Módulo de servidor MCP de NestJS

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!

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: