MastraServer

MastraServer 抽象類是所有伺服器轉接器的基類。擴展此類可為 Hono 或 Express 以外的框架建立轉接器。

匯入

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

類型參數

MastraServer<TApp, TRequest, TResponse>

參數	描述
TApp	框架應用類型（例如 Hono、Application）
TRequest	框架請求類型
TResponse	框架回應/情境類型

建構函式

constructor(options: MastraServerOptions<TApp>)

選項

app:

TApp

框架應用程式執行個體

mastra:

Mastra

Mastra 執行個體

prefix?:

string

= ''

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

openapiPath?:

string

= ''

提供 OpenAPI 規格的路徑

bodyLimitOptions?:

BodyLimitOptions

請求主體大小限制

streamOptions?:

StreamOptions

= { redact: true }

串流遮罩設定

customRouteAuthConfig?:

Map<string, boolean>

依路由設定的認證覆寫項

tools?:

Record<string, Tool>

伺服器可用的 Tool

taskStore?:

InMemoryTaskStore

用於 A2A（Agent-to-Agent）操作的任務儲存

mcpOptions?:

MCPOptions

適用於無伺服器環境的 MCP 傳輸選項

抽象方法

轉接器必須實現以下方法：

registerContextMiddleware()

為每個請求附加 Mastra 情境。

abstract registerContextMiddleware(): void

要附加的情境：

• mastra - Mastra 執行個體
• requestContext - 請求範圍的情境
• tools - 可用的 Tool
• abortSignal - 請求取消訊號

registerAuthMiddleware()

初始化期間執行轉接器認證hook。當認證依路由強制執行時，官方轉接器可以將其實現為無操作。

abstract registerAuthMiddleware(): void

registerRoute()

向框架註冊單一路由。

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

getParams()

從請求中提取參數。

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

sendResponse()

根據路由類型傳送回應。

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

stream()

處理串流回應。

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

執行個體方法

init()

透過註冊所有 middleware 和路由來初始化伺服器。

async init(): Promise<void>

依以下順序呼叫：

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

registerRoutes()

註冊所有 Mastra 路由。

async registerRoutes(): Promise<void>

getApp()

取得框架應用程式執行個體。

getApp<T = TApp>(): T

parsePathParams()

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

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

parseQueryParams()

使用該路由的 Zod schema 驗證查詢參數。

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

parseBody()

使用該路由的 Zod schema 驗證請求主體。

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

registerOpenAPIRoute()

註冊一個提供 OpenAPI 規格的 endpoint。

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

受保護的方法

mergeRequestContext()

合併來自多個來源（查詢參數和請求主體）的請求情境。

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
}

屬性	描述
serverless	設為 true 時，會以不進行會話管理的無狀態模式執行 MCP。適用於 Cloudflare Workers 或 Vercel Edge 等無伺服器環境。
sessionIdGenerator	用於產生會話 ID 的自訂函式。

範例

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
  }
}

相關內容

• 伺服器轉接器：使用轉接器
• 自訂轉接器：建立自訂轉接器
• createRoute()：建立自訂路由