NestJS MCP-Servermodul

Ein NestJS-Modul zum mühelosen Bereitstellen von Tools, Ressourcen und Eingabeaufforderungen für KI aus Ihren NestJS-Anwendungen mithilfe des Model Context Protocol (MCP) .

Mit @rekog/mcp-nest definieren Sie Tools, Ressourcen und Eingabeaufforderungen auf eine Weise, die in NestJS vertraut ist, und nutzen die volle Leistungsfähigkeit der Abhängigkeitsinjektion, um Ihre vorhandene Codebasis beim Erstellen komplexer, unternehmensreifer MCP-Server zu verwenden.

Merkmale

🚀 Unterstützung für alle Transportarten:
- Streambares HTTP
- HTTP+SSE
- STDIO
🔍 Automatisches tool , resource und prompt Erkennung und Registrierung
💯 Zod-basierte Tool-Aufrufvalidierung
📊 Fortschrittsbenachrichtigungen
🔒 Guard-basierte Authentifizierung

Installation

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

Schnellstart

1. Modul importieren

// 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. Definieren Sie Tools und Ressourcen

// greeting.tool.ts
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) {
    const greeting = `Hello, ${name}!`;

    const totalSteps = 5;
    for (let i = 0; i < totalSteps; i++) {
      await new Promise((resolve) => setTimeout(resolve, 500));

      // 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',
        },
      ],
    };
  }
}

Sie sind fertig!

Schnellstart für STDIO

Der Hauptunterschied besteht darin, dass Sie beim Importieren des Moduls die transport angeben müssen.

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

Der Rest ist gleich. Sie können Tools, Ressourcen und Eingabeaufforderungen wie gewohnt definieren. Ein Beispiel für eine eigenständige NestJS-Anwendung mit STDIO-Transport ist das folgende:

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

void bootstrap();

Als Nächstes können Sie den MCP-Server mit einem MCP-Stdio-Client verwenden ( siehe Beispiel ) oder nach dem Erstellen Ihres Projekts mit der folgenden MCP-Client-Konfiguration:

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

API-Endpunkte

Der HTTP+SSE-Transport stellt zwei Endpunkte bereit:

GET /sse : SSE-Verbindungsendpunkt (durch Schutzvorrichtungen geschützt, falls konfiguriert)
POST /messages : Endpunkt der Tool-Ausführung (durch Schutzvorrichtungen geschützt, falls konfiguriert)

Der streambare HTTP-Transport stellt die folgenden Endpunkte bereit:

POST /mcp : Hauptendpunkt für alle MCP-Operationen (Toolausführung, Ressourcenzugriff usw.). Im Stateful-Modus werden Sitzungen erstellt und verwaltet.
GET /mcp : Erstellt Server-Sent Events (SSE)-Streams für Echtzeit-Updates und Fortschrittsbenachrichtigungen. Nur im Stateful-Modus verfügbar.
DELETE /mcp : Beendet MCP-Sitzungen. Nur im Stateful-Modus verfügbar.

Tipps

Es ist möglich, das Modul mit einem globalen Präfix zu verwenden, es wird jedoch empfohlen, diese Endpunkte folgendermaßen auszuschließen:

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

Authentifizierung

Sie können Ihre MCP-Endpunkte mit standardmäßigen NestJS Guards sichern.

1. Erstellen Sie eine Wache

Implementieren Sie die CanActivate Schnittstelle. Der Guard übernimmt die Anforderungsvalidierung (z. B. Überprüfung von JWTs und API-Schlüsseln) und fügt optional Benutzerinformationen an das Anforderungsobjekt an.

Nichts Besonderes, weitere Einzelheiten finden Sie in der NestJS-Dokumentation.

2. Tragen Sie den Schutz auf

Übergeben Sie Ihre Schutzmaßnahmen an die McpModule.forRoot -Konfiguration. Die Schutzmaßnahmen werden sowohl auf die Endpunkte /sse als auch /messages angewendet.

// 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 {}

Das ist alles! Der Rest ist identisch mit NestJS Guards.

Spielplatz

Das playground -Verzeichnis enthält Beispiele zum schnellen Testen von MCP- und @rekog/mcp-nest Funktionen. Weitere Informationen finden Sie in der playground/README.md .

Konfiguration

Die Methode McpModule.forRoot() akzeptiert ein McpOptions -Objekt zur Konfiguration des Servers. Folgende Optionen sind verfügbar:

Option	Beschreibung	Standard
`name`	Erforderlich. Der Name Ihres MCP-Servers.	-
`version`	Erforderlich. Die Version Ihres MCP-Servers.	-
`capabilities`	Optionale MCP-Serverfunktionen zum Ankündigen. Siehe @modelcontextprotocol/sdk .	`undefined`
`instructions`	Optionale Anweisungen für den Client zur Interaktion mit dem Server.	`undefined`
`transport`	Gibt die zu aktivierenden Transporttypen an.	`[McpTransportType.SSE, McpTransportType.STREAMABLE_HTTP, McpTransportType.STDIO]`
`sseEndpoint`	Der Endpunktpfad für die SSE-Verbindung (wird mit `SSE` Transport verwendet).	`'sse'`
`messagesEndpoint`	Der Endpunktpfad zum Senden von Nachrichten (wird mit `SSE` Transport verwendet).	`'messages'`
`mcpEndpoint`	Der Basisendpunktpfad für MCP-Operationen (wird mit `STREAMABLE_HTTP` -Transport verwendet).	`'mcp'`
`globalApiPrefix`	Ein globales Präfix für alle MCP-Endpunkte. Nützlich bei der Integration in eine vorhandene Anwendung.	`''`
`guards`	Ein Array von NestJS Guards, die zur Authentifizierung/Autorisierung auf die MCP-Endpunkte angewendet werden.	`[]`
`decorators`	Ein Array von NestJS-Klassendekoratoren, die auf die generierten MCP-Controller angewendet werden sollen.	`[]`
`sse`	Konfiguration spezifisch für den `SSE` -Transport.	`{ pingEnabled: true, pingIntervalMs: 30000 }`
`sse.pingEnabled`	Ob regelmäßige SSE-Ping-Nachrichten aktiviert werden sollen, um die Verbindung aufrechtzuerhalten.	`true`
`sse.pingIntervalMs`	Das Intervall (in Millisekunden) zum Senden von SSE-Ping-Nachrichten.	`30000`
`streamableHttp`	Konfiguration spezifisch für den `STREAMABLE_HTTP` Transport.	`{ enableJsonResponse: true, sessionIdGenerator: undefined, statelessMode: true }`
`streamableHttp.enableJsonResponse`	Wenn `true` , kann der `/mcp` -Endpunkt JSON-Antworten für Nicht-Streaming-Anfragen (wie `listTools` ) zurückgeben.	`true`
`streamableHttp.sessionIdGenerator`	Eine Funktion zum Generieren eindeutiger Sitzungs-IDs im Stateful-Modus. Erforderlich, wenn `statelessMode` `false` ist.	`undefined`
`streamableHttp.statelessMode`	Bei `true` erfolgt der `STREAMABLE_HTTP` -Transport zustandslos (keine Sitzungen). Bei `false` erfolgt der Transport zustandsbehaftet und erfordert einen `sessionIdGenerator` .	`true`

NestJS MCP Server Module

Integrations