跳至主要內容

NestJS 轉接器

@mastra/nestjs 套件提供一個 NestJS 模組，用於透過基於 Express 的 NestJS 平台執行 Mastra。

在 v1 中它有意僅支援 Express。如果使用不同的 HTTP 轉接器引導 Nest，MastraModule 會在啟動期間擲回錯誤，而非嘗試部分整合。有關通用轉接器概念，請參閱 Server Adapters。

安裝
「安裝」的直接連結

安裝 NestJS 轉接器，並確保 app 使用 Express 平台：

npm install @mastra/nestjs@latest

使用範例
「使用範例」的直接連結

src/app.module.ts
import { Module } from '@nestjs/common'
import { MastraModule } from '@mastra/nestjs'
import { mastra } from './mastra'

@Module({
  imports: [
    MastraModule.register({
      mastra,
    }),
  ],
})
export class AppModule {}
備註

MastraModule 會註冊一個攔截所有路由的 controller（@All('*')）。如果在 app 模組之前匯入它，它可能會攔截無關路由並傳回 404。為避免衝突，請最後匯入 MastraModule，或將其掛載到專用前綴下（例如，/api/v1/mastra）。

src/main.ts
import { NestFactory } from '@nestjs/core'
import { AppModule } from './app.module'

async function bootstrap() {
  const app = await NestFactory.create(AppModule)
  await app.listen(3000)
}

bootstrap()

預設情況下，Mastra 路由掛載在 /api 下。使用 prefix 進行變更。

模組選項
「模組選項」的直接連結

mastra:

Mastra
Mastra 執行個體

prefix?:

string
= `/api`
路由路徑前綴（例如，/api/v2）

rateLimitOptions?:

{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }
速率限制設定（預設啟用）

shutdownOptions?:

{ timeoutMs?: number; notifyClients?: boolean }
優雅關閉設定

bodyLimitOptions?:

{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }
請求請求主體大小限制

streamOptions?:

{ redact?: boolean; heartbeatMs?: number }
流設定

tracingOptions?:

{ enabled?: boolean; serviceName?: string }
OpenTelemetry Trace 設定

contextOptions?:

{ strict?: boolean; logWarnings?: boolean }
請求情境解析設定

customRouteAuthConfig?:

Map<string, boolean>
依路由覆寫身分驗證。鍵為 METHOD:PATH。

tools?:

Record<string, Tool>
為 Server 註冊的 Tool

taskStore?:

InMemoryTaskStore
用於 A2A（Agent-to-Agent）操作的任務儲存

mcpOptions?:

{ serverless?: boolean; sessionIdGenerator?: () => string }
MCP 傳輸選項

auth?:

{ enabled?: boolean; allowQueryApiKey?: boolean }
= `{ enabled: false }`
啟用 Mastra token 身分驗證。預設停用——大多數 NestJS app 使用自己的身分驗證守衛。為保持回溯相容性，選擇啟用查詢字串 apiKey 身分驗證。

非同步註冊
「非同步註冊」的直接連結

src/app.module.ts
import { Module } from '@nestjs/common'
import { ConfigModule, ConfigService } from '@nestjs/config'
import { MastraModule } from '@mastra/nestjs'
import { Mastra } from '@mastra/core/mastra'

@Module({
  imports: [
    ConfigModule.forRoot(),
    MastraModule.registerAsync({
      imports: [ConfigModule],
      useFactory: (config: ConfigService) => ({
        mastra: new Mastra({
          agents: {
            greeter: {
              name: 'greeter',
              description: 'Greets the user',
              model: config.get('MASTRA_MODEL', 'openai/gpt-5-mini'),
            },
          },
        }),
        prefix: config.get('MASTRA_PREFIX', '/api'),
      }),
      inject: [ConfigService],
    }),
  ],
})
export class AppModule {}

存取 Mastra
「存取 Mastra」的直接連結

在服務中使用 MASTRA token 或 MastraService：

import { Injectable, Inject } from '@nestjs/common'
import { MASTRA, MastraService } from '@mastra/nestjs'
import type { Mastra } from '@mastra/core/mastra'

@Injectable()
export class AgentService {
  constructor(@Inject(MASTRA) private readonly mastra: Mastra) {}
}

@Injectable()
export class WorkflowService {
  constructor(private readonly mastraService: MastraService) {}
}

MCP 路由
「MCP 路由」的直接連結

MCP endpoint 會公開在 API 前綴下：

  • POST /api/mcp/:serverId/mcp
  • GET /api/mcp/:serverId/sse
  • POST /api/mcp/:serverId/messages

健康檢查路由
「健康檢查路由」的直接連結

為相容基礎設施，維運 endpoint 有意不使用前綴：

  • GET /health
  • GET /ready
  • GET /info
On this page