跳到主要内容

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 会注册一个捕获所有路由的控制器（@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 端点暴露在 API 前缀下：

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

健康检查路由
健康检查路由的直接链接

为兼容基础设施，运维端点有意不使用前缀：

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