> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# MastraServer

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

## 导入

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

## 类型参数

```typescript
MastraServer<TApp, TRequest, TResponse>
```

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

## 构造函数

```typescript
constructor(options: MastraServerOptions<TApp>)
```

### 选项

**app** (`TApp`): 框架应用实例

**mastra** (`Mastra`): Mastra 实例

**prefix** (`string`): 路由路径前缀（例如 /api/v2） (Default: `''`)

**openapiPath** (`string`): 提供 OpenAPI 规范的路径 (Default: `''`)

**bodyLimitOptions** (`BodyLimitOptions`): 请求体大小限制

**streamOptions** (`StreamOptions`): 流脱敏配置 (Default: `{ redact: true }`)

**customRouteAuthConfig** (`Map<string, boolean>`): 按路由设置的认证覆盖项

**tools** (`Record<string, Tool>`): 服务器可用的 Tool

**taskStore** (`InMemoryTaskStore`): 用于 A2A（Agent-to-Agent）操作的任务存储

**mcpOptions** (`MCPOptions`): 适用于无服务器环境的 MCP 传输选项

## 抽象方法

适配器必须实现以下方法：

### `registerContextMiddleware()`

为每个请求附加 Mastra 上下文。

```typescript
abstract registerContextMiddleware(): void
```

**要附加的上下文：**

- `mastra` - Mastra 实例
- `requestContext` - 请求范围的上下文
- `tools` - 可用的 Tool
- `abortSignal` - 请求取消信号

### `registerAuthMiddleware()`

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

```typescript
abstract registerAuthMiddleware(): void
```

### `registerRoute()`

向框架注册单个路由。

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

### `getParams()`

从请求中提取参数。

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

### `sendResponse()`

根据路由类型发送响应。

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

### `stream()`

处理流式响应。

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

## 实例方法

### `init()`

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

```typescript
async init(): Promise<void>
```

按以下顺序调用：

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

### `registerRoutes()`

注册所有 Mastra 路由。

```typescript
async registerRoutes(): Promise<void>
```

### `getApp()`

获取框架应用实例。

```typescript
getApp<T = TApp>(): T
```

### `parsePathParams()`

使用该路由的 Zod schema 验证路径参数。

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

### `parseQueryParams()`

使用该路由的 Zod schema 验证查询参数。

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

### `parseBody()`

使用该路由的 Zod schema 验证请求体。

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

### `registerOpenAPIRoute()`

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

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

## 受保护的方法

### `mergeRequestContext()`

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

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

## 类型

### `BodyLimitOptions`

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

### `StreamOptions`

```typescript
interface StreamOptions {
  redact?: boolean
}
```

### MCPOptions

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

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

## 示例

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

## 相关内容

- [服务器适配器](https://mastra.zisheng.pro/docs/server/server-adapters)：使用适配器
- [自定义适配器](https://mastra.zisheng.pro/docs/server/custom-adapters)：创建自定义适配器
- [createRoute()](https://mastra.zisheng.pro/reference/server/create-route)：创建自定义路由