NestJS MCP Server Module

NestJS MCP 服务模块

一个 NestJS 模块，可让你使用 Model Context Protocol (MCP)，轻松地从 NestJS 应用中为 AI 提供工具、资源和提示词。

借助 @rekog/mcp-nest，你可以用熟悉的 NestJS 方式定义工具、资源和提示词，并充分利用依赖注入的全部能力，在现有代码库的基础上构建复杂、适用于企业的 MCP 服务。

功能

• 🧩 NestJS 微服务策略：MCP 以 CustomTransportStrategy 的形式运行，因此工具／资源／提示词都是真正的 @MessagePattern 处理程序——守卫、管道、拦截器和异常过滤器均可原生应用于这些处理程序
• 🚀 多传输支持：Streamable HTTP 和 STDIO——通过 transports 数组进行选择
• 🕰️ 双时代协议支持：一个端点可并行服务于 2025 时代的协议（initialize + 会话）和无状态的 2026-07-28 修订版——无需更改工具代码
• 🔧 工具：将 NestJS 方法作为 MCP 工具公开，并支持自动发现和 Zod 验证
  • 🛠️ 引导：通过引导用户输入进行交互式工具调用
  • 🔁 多轮往返请求：在协议修订版 2026-07-28 中支持引导、采样和根目录——一个处理程序即可服务于两个时代
  • 🌐 HTTP 请求访问：在 MCP 处理程序中完整访问请求上下文
  • 🔐 单工具授权：为工具实现精细化授权
• 📁 资源：通过 MCP 资源系统提供内容和数据
• 📚 资源模板：通过参数化 URI 提供动态资源
• 💬 提示词：定义可复用的提示词模板，用于 AI 交互
• 🔐 基于守卫的身份验证：基于守卫的安全机制，并支持 OAuth
• 🏠 内置授权服务 — 使用内置授权服务，轻松完成设置。（Beta）
• 🌐 外部授权服务 — 使用外部授权服务（Keycloak、Auth0 等）保护你的 MCP 服务。
• 💉 依赖注入：在 MCP 组件中充分利用 NestJS DI 系统
• 🔍 服务变更与插桩 — 为自定义逻辑或插桩目的变更底层 MCP 服务。

你是否有兴趣构建 ChatGPT 小组件（使用 OpenAI SDK）或 MCP 应用？ 在此仓库 MCP-Nest-Samples 中了解如何使用 @rekog/MCP-Nest 构建。

提示

你可以通过 Context7 中的 chat 选项卡轻松了解此软件包。更进一步，还可以连接 Context7 MCP 服务，让你的 AI Agent 查阅文档并为你实现 MCP-Nest。

安装

npm install @rekog/mcp-nest \
  @modelcontextprotocol/server \
  @modelcontextprotocol/core \
  @modelcontextprotocol/node \
  zod@^4

可选依赖项

内置授权服务现在位于单独的软件包中。如果你要使用它，请将其与 @rekog/mcp-nest 一起安装：

npm install @rekog/mcp-nest-auth

如果你还要使用授权服务的 TypeORM 存储，请同时安装以下可选对等依赖项：

npm install @nestjs/typeorm typeorm

快速开始

MCP-Nest 以 NestJS 微服务传输策略的形式运行。工具、资源 和提示词定义在 @McpController() 类中（因此 NestJS 守卫、管道、 拦截器和异常过滤器都适用于它们），该策略通过一种或多种传输方式 （Streamable HTTP、STDIO）提供服务。

// greeting.controller.ts
import { McpController, Tool, McpContext } from '@rekog/mcp-nest';
import { Ctx, Payload } from '@nestjs/microservices';
import { z } from 'zod';

@McpController()
export class GreetingController {
  @Tool({
    name: 'greeting-tool',
    description: 'Returns a greeting with progress updates',
    parameters: z.object({ name: z.string().default('World') }),
  })
  async sayHello(
    @Payload() { name }: { name: string },
    @Ctx() ctx: McpContext,
  ) {
    await ctx.reportProgress({ progress: 50, total: 100 });
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
  }
}

// app.module.ts
import { Module } from '@nestjs/common';
import {
  McpStrategy,
  MCP_STRATEGY,
  StreamableHttpTransport,
} from '@rekog/mcp-nest';
import { GreetingController } from './greeting.controller';

// The strategy is the whole configuration — there is no McpModule.
export const mcp = new McpStrategy({
  name: 'my-mcp-server',
  version: '1.0.0',
  transports: [
    new StreamableHttpTransport(),
  ],
});

@Module({
  controllers: [GreetingController],
  // Optional: only needed if a provider injects the strategy (e.g. for
  // runtime/dynamic tool registration).
  providers: [{ provide: MCP_STRATEGY, useValue: mcp }],
})
export class AppModule {}

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

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  mcp.setHttpAdapter(app.getHttpAdapter()); // needed for HTTP transports
  app.connectMicroservice({ strategy: mcp });
  await app.startAllMicroservices(); // mounts the MCP transports
  await app.listen(3000); // also serves your normal HTTP routes
}
void bootstrap();

**调用顺序很重要：**先调用 startAllMicroservices()，再调用 listen()， 这样 MCP HTTP 路由会在服务器开始接受连接之前挂载。

/mcp 端点支持双时代协议：它可以同时通过相同的 @Tool 方法响应 2025 年版协议（initialize 握手 + 会话）和无状态的 2026-07-28 修订版。 上方的 ctx.reportProgress(...) 会原样发送给 2026-07-28 客户端——即使 请求不带会话，所有现代请求也都可以流式传回进度。2025 年版客户端需要 支持会话的传输方式才能实现此功能（new StreamableHttpTransport({ statefulMode: true }) 或 StdioTransport()）；使用旧版无状态默认设置时，此功能不起作用。请参阅 协议修订版。

对于仅使用 STDIO 的服务器，请跳过 HTTP 适配器，改用 NestFactory.createMicroservice(AppModule, { strategy: mcp })，并设置 transports: [new StdioTransport()]，同时禁用日志记录（stdout 专用于 协议）。

文档

• 迁移到策略 API - 从 McpModule.forRoot(options) 迁移到 McpStrategy + @McpController
• 协议修订版与双时代服务 - 在一个端点上同时提供 2025 年版协议和 2026-07-28
• 工具指南 - 将 NestJS 方法定义并公开为 MCP 工具
• 工具的发现与注册 - 自动发现和手动注册工具
• 动态功能指南 - 在运行时以编程方式注册工具、资源和提示词
• 资源指南 - 提供静态和动态内容
• 资源模板指南 - 创建参数化资源
• 提示词指南 - 构建可重复使用的提示词模板
• 内置授权服务器 - 使用内置 OAuth 保护 MCP 服务
• 外部授权服务器 - 使用外部授权服务器保护 MCP 服务（Keycloak、Auth0 等）
• 服务端示例 - MCP 服务示例（Streamable HTTP、HTTP 和 STDIO），以及支持 Fastify 的示例

示例

examples 目录包含涵盖所有功能的可运行示例。 详情请参阅 examples/README.md。