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()

初始化期间运行适配器认证钩子。当认证按路由强制执行时，官方适配器可以将其实现为无操作。

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()

通过注册所有中间件和路由来初始化服务器。

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 规范的端点。

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()：创建自定义路由