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 スキーマを使用してパスパラメーターを検証します。

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

parseQueryParams()

ルートの Zod スキーマを使用してクエリパラメーターを検証します。

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

parseBody()

ルートの Zod スキーマを使用してリクエストボディを検証します。

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

registerOpenAPIRoute()

OpenAPI 仕様を配信するエンドポイントを登録します。

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

protected メソッド

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()：カスタムルートの作成