MastraServer

MastraServer 抽象类是所有服务器适配器的基类。扩展此类可以为 Hono 或 Express 以外的框架创建适配器。

🌐 The MastraServer abstract class is the base for all server adapters. Extend this class to create adapters for frameworks other than Hono or Express.

导入

🌐 Import

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

类型参数

🌐 Type parameters

MastraServer<TApp, TRequest, TResponse>

参数	描述
TApp	框架应用类型（例如，Hono，Application）
TRequest	框架请求类型
TResponse	框架响应/上下文类型

构造函数

🌐 Constructor

constructor(options: MastraServerOptions<TApp>)

选项

🌐 Options

app:

TApp

Framework app instance

mastra:

Mastra

Mastra instance

prefix?:

string

= ''

Route path prefix (e.g., `/api/v2`)

openapiPath?:

string

= ''

Path to serve OpenAPI spec

bodyLimitOptions?:

BodyLimitOptions

Request body size limits

streamOptions?:

StreamOptions

= { redact: true }

Stream redaction config

customRouteAuthConfig?:

Map<string, boolean>

Per-route auth overrides

tools?:

Record<string, Tool>

Available tools for the server

taskStore?:

InMemoryTaskStore

Task store for A2A (Agent-to-Agent) operations

mcpOptions?:

MCPOptions

MCP transport options for serverless environments

抽象方法

🌐 Abstract methods

这些方法必须由适配器实现：

🌐 These methods must be implemented by adapters:

registerContextMiddleware()

将Mastra上下文附加到每个请求中。

🌐 Attach Mastra context to every request.

abstract registerContextMiddleware(): void

要附加的上下文：

• mastra - Mastra 实例
• requestContext - 请求范围上下文
• tools - 可用工具
• abortSignal - 请求取消信号

registerAuthMiddleware()

注册身份验证和授权中间件。

🌐 Register authentication and authorization middleware.

abstract registerAuthMiddleware(): void

registerRoute()

在框架中注册一个路由。

🌐 Register a single route with the framework.

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

getParams()

从请求中提取参数。

🌐 Extract parameters from the request.

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

sendResponse()

根据路线类型发送响应。

🌐 Send response based on route type.

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

stream()

处理流式响应。

🌐 Handle streaming responses.

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

实例方法

🌐 Instance methods

init()

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

🌐 Initialize the server by registering all middleware and routes.

async init(): Promise<void>

按顺序调用：

🌐 Calls in order:

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

registerRoutes()

注册所有Mastra路线。

🌐 Register all Mastra routes.

async registerRoutes(): Promise<void>

getApp()

获取框架应用实例。

🌐 Get the framework app instance.

getApp<T = TApp>(): T

parsePathParams()

使用路由的 Zod 模式验证路径参数。

🌐 Validate path parameters with the route's Zod schema.

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

parseQueryParams()

使用路由的 Zod 模式验证查询参数。

🌐 Validate query parameters with the route's Zod schema.

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

parseBody()

使用路由的 Zod 模式验证请求体。

🌐 Validate request body with the route's Zod schema.

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

registerOpenAPIRoute()

注册一个提供 OpenAPI 规范的端点。

🌐 Register an endpoint that serves the OpenAPI specification.

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

受保护的方法

🌐 Protected methods

mergeRequestContext()

合并来自多个来源的请求上下文（查询参数和请求体）。

🌐 Merge request context from multiple sources (query params and body).

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

类型

🌐 Types

BodyLimitOptions

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

StreamOptions

interface StreamOptions {
  redact?: boolean;
}

MCP选项

🌐 MCPOptions

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

属性	描述
serverless	当 true 时，以无状态模式运行 MCP，不管理会话。适用于无服务器环境，如 Cloudflare Workers 或 Vercel Edge。
sessionIdGenerator	用于生成会话 ID 的自定义函数。

示例

🌐 Example

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;
    // Implement auth
  }

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

相关

🌐 Related

• 服务器适配器 - 使用适配器
• 自定义适配器 - 创建自定义适配器
• createRoute() - 创建自定义路由