MastraServer

MastraServer abstract class 是所有 server adapter 的基礎。擴充此 class 可為 Hono 或 Express 以外的 framework 建立 adapter。

匯入

import { MastraServer } from '@mastra/server/server-adapter'

Type 參數

MastraServer<TApp, TRequest, TResponse>

參數	說明
TApp	Framework app 類型（例如 Hono、Application）
TRequest	Framework request 類型
TResponse	Framework response/context 類型

Constructor

constructor(options: MastraServerOptions<TApp>)

選項

app:

TApp

Framework app instance

mastra:

Mastra

Mastra instance

prefix?:

string

= ''

Route 路徑前綴（例如 /api/v2）

openapiPath?:

string

= ''

提供 OpenAPI 規格的路徑

bodyLimitOptions?:

BodyLimitOptions

Request body 大小限制

streamOptions?:

StreamOptions

= { redact: true }

Stream 遮蔽設定

customRouteAuthConfig?:

Map<string, boolean>

各 route 的 auth 覆寫設定

tools?:

Record<string, Tool>

Server 可用的 Tool

taskStore?:

InMemoryTaskStore

A2A（Agent-to-Agent）操作的 task store

mcpOptions?:

MCPOptions

Serverless 環境的 MCP transport 選項

Abstract method

Adapter 必須實作以下 method：

registerContextMiddleware()

將 Mastra context 附加至每個 request。

abstract registerContextMiddleware(): void

要附加的 context：

• mastra - Mastra instance
• requestContext - Request scope context
• tools - 可用的 Tool
• abortSignal - Request 取消訊號

registerAuthMiddleware()

在初始化期間運行 adapter auth hook。當 auth 按 route 強制執行時，官方 adapter 可將其實作為 no-op。

abstract registerAuthMiddleware(): void

registerRoute()

向 framework 註冊單一 route。

abstract registerRoute(
  app: TApp,
  route: ServerRoute,
  options: { prefix?: string }
): Promise<void>

getParams()

從 request 擷取參數。

abstract getParams(
  route: ServerRoute,
  request: TRequest
): Promise<{
  urlParams: Record<string, string>;
  queryParams: Record<string, string>;
  body: unknown;
}>

sendResponse()

根據 route 類型傳送 response。

abstract sendResponse(
  route: ServerRoute,
  response: TResponse,
  result: unknown
): Promise<unknown>

stream()

處理 streaming response。

abstract stream(
  route: ServerRoute,
  response: TResponse,
  result: unknown
): Promise<unknown>

Instance method

init()

透過註冊所有 middleware 及 route 初始化 server。

async init(): Promise<void>

按以下順序呼叫：

1. registerContextMiddleware()
2. registerAuthMiddleware()
3. registerRoutes()

registerRoutes()

註冊所有 Mastra route。

async registerRoutes(): Promise<void>

getApp()

取得 framework app instance。

getApp<T = TApp>(): T

parsePathParams()

使用 route 的 Zod schema 驗證路徑參數。

async parsePathParams(
  route: ServerRoute,
  params: Record<string, string>
): Promise<Record<string, unknown>>

parseQueryParams()

使用 route 的 Zod schema 驗證 query 參數。

async parseQueryParams(
  route: ServerRoute,
  params: Record<string, string>
): Promise<Record<string, unknown>>

parseBody()

使用 route 的 Zod schema 驗證 request body。

async parseBody(
  route: ServerRoute,
  body: unknown
): Promise<unknown>

registerOpenAPIRoute()

註冊提供 OpenAPI 規格的 endpoint。

async registerOpenAPIRoute(
  app: TApp,
  config: OpenAPIConfig,
  options: { prefix?: string }
): Promise<void>

Protected method

mergeRequestContext()

合併來自多個來源（query 參數及 body）的 request context。

protected mergeRequestContext(options: {
  paramsRequestContext?: Record<string, any>;
  bodyRequestContext?: Record<string, any>;
}): RequestContext

類型

BodyLimitOptions

interface BodyLimitOptions {
  maxSize: number
  onError: (error: unknown) => unknown
}

StreamOptions

interface StreamOptions {
  redact?: boolean
}

MCPOptions

interface MCPOptions {
  serverless?: boolean
  sessionIdGenerator?: () => string
}

Property	說明
serverless	設為 true 時，MCP 會以無狀態模式運行，不使用 session 管理。適用於 Cloudflare Workers 或 Vercel Edge 等 serverless 環境。
sessionIdGenerator	用於產生 session ID 的自訂 function。

範例

import { MastraServer, ServerRoute } from '@mastra/server/server-adapter'
import type { Mastra } from '@mastra/core'

export class MyServer extends MastraServer<MyApp, MyRequest, MyResponse> {
  registerContextMiddleware(): void {
    this.app.use('*', (req, res, next) => {
      res.locals.mastra = this.mastra
      next()
    })
  }

  registerAuthMiddleware(): void {
    const auth = this.mastra.getServer()?.auth
    if (!auth) return
    // Register global auth middleware, or leave this empty and
    // enforce auth when routes are registered.
  }

  async registerRoute(app, route, { prefix }) {
    // Implement route registration
  }

  async getParams(route, request) {
    return {
      urlParams: request.params,
      queryParams: request.query,
      body: request.body,
    }
  }

  async sendResponse(route, response, result) {
    return response.json(result)
  }

  async stream(route, response, result) {
    // Implement streaming
  }
}

相關內容

• Server adapter：使用 adapter
• 自訂 adapter：建立自訂 adapter
• createRoute()：建立自訂 route