Módulo de servidor MCP de NestJS

Cobertura del código Versión NPM Descargas de NPM Licencia NPM

Un módulo NestJS para exponer sin esfuerzo herramientas, recursos y avisos para IA, desde sus aplicaciones NestJS utilizando el Protocolo de contexto de modelo (MCP) .

Con @rekog/mcp-nest define herramientas, recursos y avisos de una manera familiar en NestJS y aprovecha todo el poder de la inyección de dependencia para utilizar tu base de código existente en la creación de servidores MCP complejos y listos para la empresa.

Características

🚀 Soporte para todos los tipos de transporte:
- HTTP transmisible
- HTTP+SSE
- STDIO
🔍 tool automática, resource y descubrimiento y registro prompt
Validación de llamadas a herramientas basadas en Zod
📊 Notificaciones de progreso
Autenticación basada en guardia
🌐 Acceso a la información de solicitudes HTTP dentro de los recursos de MCP (herramientas, recursos, indicaciones)

Related MCP server: SSE MCP Server

Instalación

npm install @rekog/mcp-nest @modelcontextprotocol/sdk zod

Inicio rápido

1. Módulo de importación

// app.module.ts import { Module } from '@nestjs/common'; import { McpModule } from '@rekog/mcp-nest'; import { GreetingTool } from './greeting.tool'; @Module({ imports: [ McpModule.forRoot({ name: 'my-mcp-server', version: '1.0.0', }), ], providers: [GreetingTool], }) export class AppModule {}

2. Definir herramientas y recursos

// greeting.tool.ts import type { Request } from 'express'; import { Injectable } from '@nestjs/common'; import { Tool, Resource, Context } from '@rekog/mcp-nest'; import { z } from 'zod'; import { Progress } from '@modelcontextprotocol/sdk/types'; @Injectable() export class GreetingTool { constructor() {} @Tool({ name: 'hello-world', description: 'Returns a greeting and simulates a long operation with progress updates', parameters: z.object({ name: z.string().default('World'), }), }) async sayHello({ name }, context: Context, request: Request) { const userAgent = request.get('user-agent') || 'Unknown'; const greeting = `Hello, ${name}! Your user agent is: ${userAgent}`; const totalSteps = 5; for (let i = 0; i < totalSteps; i++) { await new Promise((resolve) => setTimeout(resolve, 100)); // Send a progress update. await context.reportProgress({ progress: (i + 1) * 20, total: 100, } as Progress); } return { content: [{ type: 'text', text: greeting }], }; } @Resource({ uri: 'mcp://hello-world/{userName}', name: 'Hello World', description: 'A simple greeting resource', mimeType: 'text/plain', }) // Different from the SDK, we put the parameters and URI in the same object. async getCurrentSchema({ uri, userName }) { return { content: [ { uri, text: `User is ${userName}`, mimeType: 'text/plain', }, ], }; } }

¡Ya estás listo!

TIP

El ejemplo anterior muestra cómo se accede a los encabezadosRequest HTTP en MCP Tools. Esto resulta útil para identificar usuarios, agregar lógica específica del cliente y muchos otros casos de uso. Para más ejemplos, consulte las Pruebas de autenticación .

Inicio rápido para STDIO

La principal diferencia es que debes proporcionar la opción transport al importar el módulo.

McpModule.forRoot({ name: 'playground-stdio-server', version: '0.0.1', transport: McpTransportType.STDIO, });

El resto es igual: puedes definir herramientas, recursos y avisos como siempre. A continuación, se muestra un ejemplo de una aplicación NestJS independiente que utiliza el transporte STDIO:

async function bootstrap() { const app = await NestFactory.createApplicationContext(AppModule, { logger: false, }); return app.close(); } void bootstrap();

A continuación, puede utilizar el servidor MCP con un cliente MCP Stdio ( ver ejemplo ) o, después de crear su proyecto, puede usarlo con la siguiente configuración de cliente MCP:

{ "mcpServers": { "greeting": { "command": "node", "args": [ "<path to dist js file>", ] } } }

Puntos finales de API

El transporte HTTP+SSE expone dos puntos finales:

GET /sse : punto final de conexión SSE (protegido por protectores si está configurado)
POST /messages : Punto final de ejecución de la herramienta (protegido por guardias si está configurado)

El transporte HTTP transmisible expone los siguientes puntos finales:

POST /mcp : Punto final principal para todas las operaciones de MCP (ejecución de herramientas, acceso a recursos, etc.). En modo con estado, crea y mantiene sesiones.
GET /mcp : Establece flujos de eventos enviados por el servidor (SSE) para actualizaciones en tiempo real y notificaciones de progreso. Solo disponible en modo con estado.
DELETE /mcp : Finaliza las sesiones MCP. Solo disponible en modo con estado.

Consejos

Es posible utilizar el módulo con prefijo global, pero la forma recomendada es excluir esos puntos finales con:

app.setGlobalPrefix('/api', { exclude: ['sse', 'messages', 'mcp'] });

Autenticación

Puede proteger sus puntos finales de MCP utilizando NestJS Guards estándar.

1. Crea un guardia

Implementar la interfaz CanActivate . El guardián debe gestionar la validación de solicitudes (p. ej., comprobar JWT y claves API) y, opcionalmente, adjuntar información del usuario al objeto de solicitud.

Nada especial, consulte la documentación de NestJS para obtener más detalles.

2. Aplicar la protección

Transfiera sus protecciones a la configuración de McpModule.forRoot . Estas se aplicarán a los puntos finales /sse y /messages .

// app.module.ts import { Module } from '@nestjs/common'; import { McpModule } from '@rekog/mcp-nest'; import { GreetingTool } from './greeting.tool'; import { AuthGuard } from './auth.guard'; @Module({ imports: [ McpModule.forRoot({ name: 'my-mcp-server', version: '1.0.0', guards: [AuthGuard], // Apply the guard here }), ], providers: [GreetingTool, AuthGuard], // Ensure the Guard is also provided }) export class AppModule {}

¡Listo! El resto es igual que con NestJS Guards.

Patio de juegos

El directorio playground contiene ejemplos para probar rápidamente las funciones de MCP y @rekog/mcp-nest . Consulte el playground/README.md para obtener más información.

Configuración

El método McpModule.forRoot() acepta un objeto McpOptions para configurar el servidor. Estas son las opciones disponibles:

Opción	Descripción	Por defecto
`name`	Obligatorio. El nombre de su servidor MCP.	-
`version`	Obligatorio. La versión de su servidor MCP.	-
`capabilities`	Funciones opcionales del servidor MCP para publicidad. Consulte @modelcontextprotocol/sdk .	`undefined`
`instructions`	Instrucciones opcionales para el cliente sobre cómo interactuar con el servidor.	`undefined`
`transport`	Especifica el tipo(s) de transporte a habilitar.	`[McpTransportType.SSE, McpTransportType.STREAMABLE_HTTP, McpTransportType.STDIO]`
`sseEndpoint`	La ruta del punto final para la conexión SSE (utilizada con el transporte `SSE` ).	`'sse'`
`messagesEndpoint`	La ruta del punto final para enviar mensajes (utilizada con el transporte `SSE` ).	`'messages'`
`mcpEndpoint`	La ruta del punto final base para las operaciones MCP (utilizada con el transporte `STREAMABLE_HTTP` ).	`'mcp'`
`globalApiPrefix`	Un prefijo global para todos los puntos finales de MCP. Útil si se integra en una aplicación existente.	`''`
`guards`	Una matriz de protectores NestJS para aplicar a los puntos finales de MCP para autenticación/autorización.	`[]`
`decorators`	Una matriz de decoradores de clase NestJS para aplicar a los controladores MCP generados.	`[]`
`sse`	Configuración específica del transporte `SSE` .	`{ pingEnabled: true, pingIntervalMs: 30000 }`
`sse.pingEnabled`	Si se deben habilitar mensajes de ping SSE periódicos para mantener la conexión activa.	`true`
`sse.pingIntervalMs`	El intervalo (en milisegundos) para enviar mensajes de ping SSE.	`30000`
`streamableHttp`	Configuración específica del transporte `STREAMABLE_HTTP` .	`{ enableJsonResponse: true, sessionIdGenerator: undefined, statelessMode: true }`
`streamableHttp.enableJsonResponse`	Si `true` , permite que el punto final `/mcp` devuelva respuestas JSON para solicitudes que no son de transmisión (como `listTools` ).	`true`
`streamableHttp.sessionIdGenerator`	Una función para generar identificadores de sesión únicos al ejecutarse en modo con estado. Obligatorio si `statelessMode` es `false` .	`undefined`
`streamableHttp.statelessMode`	Si `true` , el transporte `STREAMABLE_HTTP` funciona sin estado (sin sesiones). Si es `false` , funciona con estado, lo que requiere un `sessionIdGenerator` .	`true`

NestJS MCP Server Module