跳至主要內容

NestJS adapter

@mastra/nestjs 套件提供 NestJS module，讓 Mastra 可在以 Express 為基礎的 NestJS 平台運行。

v1 刻意只支援 Express。如 Nest 使用其他 HTTP adapter 啟動，MastraModule 會在啟動期間拋出錯誤，而不會嘗試局部整合。有關一般 adapter 概念，請參閱 Server adapter。

安裝
安裝 的直接連結

安裝 NestJS adapter，並確保 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 會註冊 catch-all controller（@All('*')）。如在 app module 之前匯入，它可能會攔截不相關的 route 並傳回 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 route 預設掛載於 /api 下。使用 prefix 可更改此設定。

Module 選項
Module 選項 的直接連結

mastra:

Mastra
Mastra instance

prefix?:

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

rateLimitOptions?:

{ enabled?: boolean; defaultLimit?: number; windowMs?: number; generateLimit?: number }
Rate limiting 設定（預設啟用）

shutdownOptions?:

{ timeoutMs?: number; notifyClients?: boolean }
Graceful shutdown 設定

bodyLimitOptions?:

{ maxSize?: number; maxFileSize?: number; tempDir?: string; allowedMimeTypes?: string[] }
Request body 大小限制

streamOptions?:

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

tracingOptions?:

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

contextOptions?:

{ strict?: boolean; logWarnings?: boolean }
Request context 解析設定

customRouteAuthConfig?:

Map<string, boolean>
各 route 的 auth 覆寫設定。Key 為 METHOD:PATH。

tools?:

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

taskStore?:

InMemoryTaskStore
A2A（Agent-to-Agent）操作的 task store

mcpOptions?:

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

auth?:

{ enabled?: boolean; allowQueryApiKey?: boolean }
= `{ enabled: false }`
啟用 Mastra token auth。預設停用——大部分 NestJS app 會使用自己的 auth guard。為保持向後兼容，query string apiKey auth 須明確啟用。

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

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 的直接連結

在 service 中使用 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 route
MCP route 的直接連結

MCP endpoint 會在 API 前綴下提供：

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

Health route
Health route 的直接連結

為兼容基礎設施，操作 endpoint 特意不加前綴：

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