巢mcp
 ](https://www.npmjs.com/package/@nest-mcp/server) ](https://www.npmjs.com/package/@nest-mcp/server)  
构建 模型上下文协议（MCP） 使用您已经知道的NestJS生态系统的服务器、客户端和网关：装饰器、依赖注入、模块和保护，而无需学习新的框架。
包裹
| 包装 | 描述 |
|---|---|
@nest-mcp/server | 构建具有装饰器、身份验证、弹性和多传输支持的MCP服务器 |
@nest-mcp/client | 通过键入注入和健康检查连接并使用MCP服务器 |
@nest-mcp/gateway | 在一个统一的MCP端点后聚合多个上游服务器 |
@nest-mcp/common | 共享类型和实用程序（对等依赖） |
建筑
┌─────────────────────────────────────────────┐
│ AI Client (LLM host) │
└──────────────────────┬──────────────────────┘
│ MCP (Streamable HTTP / SSE / STDIO)
┌────────────▼────────────┐
│ @nest-mcp/gateway │ ← optional aggregation layer
│ (NestJS application) │
└──┬──────────────┬───────┘
│ │ upstream MCP connections (@nest-mcp/client)
┌──────────▼──┐ ┌──────▼──────┐
│ @nest-mcp/ │ │ @nest-mcp/ │ ← MCP servers built with @nest-mcp/server,
│ server A │ │ server B │ or any other MCP-compatible server
└─────────────┘ └─────────────┘@nest-mcp/server内部体系结构
HTTP / SSE / STDIO
│
▼
┌─────────────────────────────────────────────────────────┐
│ Transport Layer │
│ (StreamableHttpService / SseService / │
│ StdioService) │
└──────────────────────┬──────────────────────────────────┘
│ MCP request (tool/resource/prompt)
▼
┌─────────────────────────────────────────────────────────┐
│ Execution Pipeline │
│ │
│ ContextFactory → McpExecutionContext │
│ │ │
│ ▼ │
│ Auth Guards (@Public / @Scopes / @Roles / @Guards) │
│ │ │
│ ▼ │
│ Middleware (@UseMiddleware → McpMiddleware chain) │
│ │ │
│ ▼ │
│ Resilience (@RateLimit → @CircuitBreaker → @Retry │
│ → @Timeout) │
│ │ │
│ ▼ │
│ ExecutorService → @Tool / @Resource / @Prompt / │
│ @ResourceTemplate / @Completion │
└─────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌────────────────────┐
│ Session / │ │ Dynamic Builders │
│ Subscription│ │ McpToolBuilder / │
│ / Task │ │ McpResourceBuilder │
│ Managers │ │ McpPromptBuilder │
└─────────────┘ └────────────────────┘@嵌套mcp/客户端——内部架构
McpClientModule.forRoot({ connections: [...] })
│
▼
┌─────────────────────────────────────────────────────────┐
│ McpClientsService │
│ (registry of named McpClient instances) │
└──────┬─────────────────────┬────────────────────────────┘
│ │
▼ ▼
┌─────────────┐ ┌───────────────┐
│ McpClient │ │ McpClient │ (one per connection)
│ "server-a" │ │ "server-b" │
│ │ │ │
│ Transport │ │ Transport │
│ (SSE / │ │ (Streamable │
│ Streamable │ │ HTTP / │
│ HTTP / │ │ STDIO) │
│ STDIO) │ │ │
│ + auth │ │ + reconnect │
│ headers │ │ backoff │
└──────┬──────┘ └───────────────┘
│
├── @InjectMcpClient('server-a') → injected into any service
│
├── @OnMcpNotification(method) → notification handler registry
│
└── McpClientHealthIndicator → health check (ping-based)@嵌套mcp/gateway——内部架构
AI Client
│ MCP request
▼
┌──────────────────────────────────────────────────────────┐
│ McpGatewayModule │
│ │
│ RouterService (aggregated tool/resource/prompt list) │
│ ├── ToolAggregatorService prefix: weather_* │
│ ├── ResourceAggregatorService prefix: weather://... │
│ ├── PromptAggregatorService prefix: weather_* │
│ └── ResourceTemplateAggregator │
│ │
│ On tool call: │
│ PolicyEngineService (allow / deny / require_approval) │
│ │ │
│ RequestTransformService (custom hooks) │
│ │ │
│ ResponseCacheService (TTL cache check) │
│ │ cache miss │
│ ▼ │
│ UpstreamManagerService ──────────────────────────┐ │
│ (resolves prefix → upstream connection) │ │
│ │ │ │
│ ResponseTransformService (custom hooks) │ │
│ │ │ │
│ ResponseCacheService (store result) │ │
└─────────────────────────────────────────────────────┼────┘
│
┌──────────────────────┬─────────────────────┐ │
▼ ▼ ▼ │
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Upstream A │ │ Upstream B │ │ Upstream C │
│ (weather) │ │ (search) │ │ (...) │
│ McpClient │ │ McpClient │ │ McpClient │
└─────────────┘ └──────────────┘ └──────────────┘
↕ health ping ↕ health ping
HealthCheckerService (periodic ping per upstream)
TaskAggregatorService (tasks proxied with upstream prefix)安装
# Server — expose tools/resources to AI clients
npm install @nest-mcp/server @modelcontextprotocol/sdk zod@^4
# Client — call tools on a remote MCP server
npm install @nest-mcp/client @modelcontextprotocol/sdk zod@^4
# Gateway — aggregate multiple servers into one
npm install @nest-mcp/gateway @modelcontextprotocol/sdk zod@^4NestJS对等依赖（如果尚未安装）：
npm install @nestjs/common @nestjs/core reflect-metadata rxjs快速开始
服务器
使用装饰器定义工具并注册模块：
// tools.service.ts
import { Injectable } from '@nestjs/common';
import { Tool } from '@nest-mcp/server';
import { z } from 'zod';
@Injectable()
export class ToolsService {
@Tool({
name: 'greet',
description: 'Greet a user by name',
schema: z.object({ name: z.string() }),
})
async greet({ name }: { name: string }) {
return `Hello, ${name}!`;
}
}// app.module.ts
import { Module } from '@nestjs/common';
import { McpModule, McpTransportType } from '@nest-mcp/server';
import { ToolsService } from './tools.service';
@Module({
imports: [
McpModule.forRoot({
name: 'my-server',
version: '1.0.0',
transports: [{ type: McpTransportType.STREAMABLE_HTTP }],
}),
],
providers: [ToolsService],
})
export class AppModule {}客户
连接到服务器并注入客户端：
// app.module.ts
import { Module } from '@nestjs/common';
import { McpClientModule, McpTransportType } from '@nest-mcp/client';
@Module({
imports: [
McpClientModule.forRoot({
connections: [
{
name: 'my-server',
transport: {
type: McpTransportType.STREAMABLE_HTTP,
url: 'http://localhost:3000/mcp',
},
},
],
}),
],
})
export class AppModule {}// my.service.ts
import { Injectable } from '@nestjs/common';
import { InjectMcpClient, McpClient } from '@nest-mcp/client';
@Injectable()
export class MyService {
constructor(@InjectMcpClient('my-server') private client: McpClient) {}
async greet(name: string) {
return this.client.callTool({ name: 'greet', arguments: { name } });
}
}网关
在一个端点后聚合两个上游服务器：
// app.module.ts
import { Module } from '@nestjs/common';
import { McpGatewayModule, McpTransportType } from '@nest-mcp/gateway';
@Module({
imports: [
McpGatewayModule.forRoot({
name: 'my-gateway',
version: '1.0.0',
upstreams: [
{
name: 'weather',
transport: { type: McpTransportType.STREAMABLE_HTTP, url: 'http://weather-service/mcp' },
},
{
name: 'search',
transport: { type: McpTransportType.STREAMABLE_HTTP, url: 'http://search-service/mcp' },
},
],
}),
],
})
export class AppModule {}来自上游服务器的工具以前缀显示(weather_forecast, search_query).下游客户端看到一个统一的服务器。
文档
完整的文档保存在 docs/ 文件夹。
例子
工作实例在 apps/ 目录：
| 应用程序 | 描述 |
|---|---|
example-sse-server | 使用SSE传输的MCP服务器 |
example-client | NestJS客户端使用远程MCP服务器 |
example-gateway | 网关聚合多个上游服务器 |
example-stdio | 使用STDIO传输的MCP服务器 |
example-browser-mcp | 基于浏览器的MCP集成 |
example-postgres-mcp | MCP服务器公开PostgreSQL工具 |
发展
这是一个由Turborepo管理的pnpm monorepo。
# Install dependencies
pnpm install
# Build all packages
pnpm build
# Run all tests
pnpm test
# Lint
pnpm lint
# Type check
pnpm typecheck要求： Node.js>=20，pnpm>=9。
贡献
- 分叉存储库并从中创建分支
main - 通过测试进行更改
- 跑
pnpm test和pnpm lint验证 - 打开拉取请求
对已发布包的更改需要 变更集:
pnpm changeset许可证
BSD-3条款