> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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()`

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

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

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

```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 規格的 endpoint。

```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/zh-TW/docs/server/server-adapters)：使用轉接器
- [自訂轉接器](https://mastra.zisheng.pro/zh-TW/docs/server/custom-adapters)：建立自訂轉接器
- [createRoute()](https://mastra.zisheng.pro/zh-TW/reference/server/create-route)：建立自訂路由