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

• 🌐 Zugriff auf HTTP-Anforderungsinformationen innerhalb von MCP-Ressourcen (Tools, Ressourcen, Eingabeaufforderungen)

Related MCP server: mcp-nestjs

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

Sie sind fertig!

[!TIP] Das obige Beispiel zeigt, wie in MCP Tools auf HTTP- Request zugegriffen wird. Dies ist nützlich, um Benutzer zu identifizieren, clientspezifische Logik hinzuzufügen und viele andere Anwendungsfälle zu ermöglichen. Weitere Beispiele finden Sie in den Authentifizierungstests .

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 (bei Konfiguration durch Schutzvorrichtungen geschützt)

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: