NestJS 어댑터

그만큼@mastra/nestjs패키지는 Express 기반 NestJS 플랫폼으로 Mastra를 실행하기 위한 NestJS 모듈을 제공합니다.

v1은 의도적으로 Express만 지원합니다. Nest가 다른 HTTP 어댑터로 부트스트랩되면 MastraModule은 부분적인 통합을 시도하지 않고 시작 중에 오류를 발생시킵니다. 일반적인 어댑터 개념은 서버 어댑터를 참조하세요.

설치

NestJS 어댑터를 설치하고 앱이 Express 플랫폼을 사용하는지 확인하세요.

npm

npm install @mastra/nestjs@latest

pnpm

pnpm add @mastra/nestjs@latest

Yarn

yarn add @mastra/nestjs@latest

Bun

bun add @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('*'))를 등록합니다. 애플리케이션 모듈보다 먼저 가져오면 관련 없는 경로를 가로채 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 추적 구성

contextOptions?:

{ strict?: boolean; logWarnings?: boolean }

요청 컨텍스트 구문 분석 구성

customRouteAuthConfig?:

Map<string, boolean>

경로별 인증 재정의입니다. 키는 METHOD:PATH 형식입니다.

tools?:

Record<string, Tool>

서버에 등록된 Tool

taskStore?:

InMemoryTaskStore

A2A(Agent-to-Agent) 작업용 작업 저장소

mcpOptions?:

{ serverless?: boolean; sessionIdGenerator?: () => string }

MCP 전송 옵션

auth?:

{ enabled?: boolean; allowQueryApiKey?: boolean }

= `{ enabled: false }`

Mastra 토큰 인증을 활성화합니다. 기본적으로 비활성화되어 있습니다. 대부분의 NestJS 애플리케이션은 자체 인증 가드를 사용합니다. 이전 버전과의 호환성을 위한 쿼리 문자열 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 토큰 또는 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 엔드포인트는 API 접두사 아래에 노출됩니다.

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

건강 경로

인프라 호환성을 위해 운영 엔드포인트는 의도적으로 접두어가 붙지 않은 상태로 유지됩니다.

• GET /health
• GET /ready
• GET /info

관련된

• 서버 어댑터
• Mastra서버 참조