Express-MCP-Handler

Eine Middleware zur Integration des Model Context Protocol (MCP) mit Express-Anwendungen, die eine nahtlose Kommunikation zwischen LLMs und Tools ermöglicht.

Was ist das Model Context Protocol (MCP)?

Model Context Protocol (MCP) ist ein offenes Protokoll zur Integration großer Sprachmodelle (LLMs) mit externen Datenquellen und Tools. Es ermöglicht KI-Assistenten den Zugriff auf Echtzeitdaten, die Ausführung von Operationen und die Interaktion mit verschiedenen Diensten über eine standardisierte Schnittstelle.

Merkmale

Stateful Handler : Kann einmalige Anfragen verarbeiten oder langlebige Sitzungen mit Sitzungs-IDs und Server-Sent Events (SSE) aufrechterhalten.
Stateless Handler : Behandelt jede Anfrage vollständig isoliert für einfache, einmalige Interaktionen.
SSE-Handler : Verarbeitet Model Context Protocol (MCP) über Server-Sent Events (SSE) mit dedizierten GET- und POST-Endpunkten.
Typsichere API : Erstellt mit TypeScript für zuverlässige Integration.
Flexible Konfiguration : Anpassbare Fehlerbehandlung, Sitzungsverwaltung und Lebenszyklus-Hooks.
Express-Integration : Lässt sich mit Middleware-Muster direkt in Express-Routen einbinden.

Installation

Über npm installieren:

npm install express-mcp-handler

Oder Garn:

yarn add express-mcp-handler

Oder pnpm:

pnpm add express-mcp-handler

Peer-Abhängigkeiten

Dieses Paket erfordert die folgenden Peer-Abhängigkeiten:

express >= 4.0.0
@modelcontextprotocol/sdk >= 1.10.2
zod >= 3.0.0

Installieren Sie sie, falls Sie dies noch nicht getan haben:

npm install express @modelcontextprotocol/sdk zod

Schnellstart

Hier ist ein einfaches Beispiel für den Einstieg:

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { statelessHandler } from 'express-mcp-handler';

const app = express();
app.use(express.json());

// Create a factory function that returns a new McpServer instance for each request
const serverFactory = () => new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// Mount the stateless handler
app.post('/mcp', statelessHandler(serverFactory));

app.listen(3000, () => {
  console.log('Express MCP server running on port 3000');
});

Verwendung

Express-mcp-handler bietet drei Handlertypen für unterschiedliche Anwendungsfälle:

Stateful-Modus

Verwenden Sie statefulHandler , um wiederverwendbare Sitzungen zwischen Client und Server einzurichten. Dies ist ideal, um den Kontext über mehrere Interaktionen hinweg aufrechtzuerhalten:

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { statefulHandler } from 'express-mcp-handler';
import { randomUUID } from 'node:crypto';

const app = express();
app.use(express.json());

// Create an MCP server instance
const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
});

// Configure handler options
const handlerOptions = {
  sessionIdGenerator: randomUUID, // Function to generate unique session IDs
  onSessionInitialized: (sessionId: string) => {
    console.log(`Session initialized: ${sessionId}`);
    // You could store session metadata or initialize resources here
  },
  onSessionClosed: (sessionId: string) => {
    console.log(`Session closed: ${sessionId}`);
    // Perform cleanup logic here
  },
  onError: (error: Error, sessionId?: string) => {
    console.error(`Error in session ${sessionId}:`, error);
    // Handle errors for monitoring or logging
  }
};

// Mount the handlers for different HTTP methods
app.post('/mcp', statefulHandler(server, handlerOptions));
app.get('/mcp', statefulHandler(server, handlerOptions));
app.delete('/mcp', statefulHandler(server, handlerOptions));

app.listen(3000, () => {
  console.log('Express MCP server running on port 3000');
});

Der Stateful-Handler:

Initialisiert eine neue Sitzung bei der ersten Anfrage (ohne mcp-session-id Header)
Gibt einen mcp-session-id Header zurück, den Clients in nachfolgende Anfragen einschließen müssen
Verwaltet Server-Sent Events (SSE), um Nachrichten vom Server an den Client zu senden
Bereinigt Sitzungen automatisch, wenn sie geschlossen werden

Zustandsloser Modus

Verwenden Sie statelessHandler für die einmalige Anforderungsverarbeitung ohne Sitzungsverwaltung, perfekt für serverlose Umgebungen oder einfache Anforderungen:

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { statelessHandler } from 'express-mcp-handler';

const app = express();
app.use(express.json());

// Function that creates a fresh McpServer for each request
const serverFactory = () => new McpServer({
  name: 'stateless-mcp-server',
  version: '1.0.0',
});

// Configure with custom error handling
const options = {
  onError: (error: Error) => {
    console.error('MCP error:', error);
    // Add custom error reporting logic here
  }
};

app.post('/mcp', statelessHandler(serverFactory, options));

app.listen(3000, () => {
  console.log('Express Stateless MCP server running on port 3000');
});

Jede zustandslose Anfrage:

Erstellt eine neue Transport- und Serverinstanz
Gewährleistet vollständige Isolierung ohne Sitzungsverfolgung
Ist für einfache oder serverlose Umgebungen geeignet

SSE-Modus

Verwenden Sie sseHandlers , um Model Context Protocol (MCP) über Server-Sent Events (SSE) zu verarbeiten, ideal für Streaming-Antworten in Echtzeit:

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { sseHandlers } from 'express-mcp-handler';

const app = express();
app.use(express.json());

// Provide a factory function that returns a fresh McpServer for each SSE connection
const serverFactory = () => new McpServer({
  name: 'sse-mcp-server',
  version: '1.0.0',
});

// Configure SSE handlers
const handlers = sseHandlers(serverFactory, {
  onError: (error: Error, sessionId?: string) => {
    console.error(`[SSE][${sessionId || 'unknown'}]`, error);
  },
  onClose: (sessionId: string) => {
    console.log(`[SSE] transport closed: ${sessionId}`);
    // Clean up any session resources
  },
});

// Mount the SSE endpoints
app.get('/sse', handlers.getHandler);
app.post('/messages', handlers.postHandler);

app.listen(3002, () => {
  console.log('Express MCP SSE server running on port 3002');
});

SSE-Handler bieten:

GET /sse : Erstellt den SSE-Stream und gibt einen mcp-session-id Header zurück
POST /messages : Sendet MCP-Nachrichten über den SSE-Transport unter Verwendung des Abfrageparameters mcp-session-id

API-Referenz

StatefulHandler

function statefulHandler(
  server: McpServer,
  options: {
    sessionIdGenerator: () => string;
    onSessionInitialized?: (sessionId: string) => void;
    onSessionClosed?: (sessionId: string) => void;
    onError?: (error: Error, sessionId?: string) => void;
    onInvalidSession?: (req: express.Request) => void;
  }
): express.RequestHandler;

Parameter	Typ	Beschreibung
`server`	`McpServer`	Instanz von `McpServer` zur Handhabung der Protokolllogik
`options.sessionIdGenerator`	`() => string`	Funktion, die eine eindeutige Sitzungs-ID zurückgibt
`options.onSessionInitialized`	`(sessionId: string) => void`	(optional) Rückruf mit der neuen Sitzungs-ID
`options.onSessionClosed`	`(sessionId: string) => void`	(optional) Rückruf, der beim Schließen einer Sitzung aufgerufen wird
`options.onError`	`(error: Error, sessionId?: string) => void`	(optional) Rückruf bei Fehlern
`options.onInvalidSession`	`(req: express.Request) => void`	(optional) Rückruf, der beim Zugriff auf eine ungültige Sitzung aufgerufen wird

zustandsloser Handler

function statelessHandler(
  serverFactory: () => McpServer,
  options?: {
    sessionIdGenerator?: () => string;
    onClose?: (req: express.Request, res: express.Response) => void;
    onError?: (error: Error) => void;
  }
): express.RequestHandler;

Parameter	Typ	Beschreibung
`serverFactory`	`() => McpServer`	Funktion, die für jede Anfrage eine neue Serverinstanz zurückgibt
`options.sessionIdGenerator`	`() => string`	(optional) Generierung der Transportsitzungs-ID überschreiben
`options.onClose`	`(req: express.Request, res: express.Response) => void`	(optional) Rückruf wird ausgelöst, wenn der Anfrage-/Antwortzyklus endet
`options.onError`	`(error: Error) => void`	(optional) Rückruf, der bei Fehlern während der Verarbeitung ausgelöst wird

sseHandlers

function sseHandlers(
  serverFactory: ServerFactory,
  options: SSEHandlerOptions
): {
  getHandler: express.RequestHandler;
  postHandler: express.RequestHandler;
};

Parameter	Typ	Beschreibung
`serverFactory`	`ServerFactory`	Factory-Funktion, die für jede SSE-Verbindung einen neuen `McpServer` zurückgibt
`options.onError`	`(error: Error, sessionId?: string) => void`	(optional) Rückruf wird bei Fehlern aufgerufen, empfängt `error` und optionale `sessionId`
`options.onClose`	`(sessionId: string) => void`	(optional) Rückruf, der aufgerufen wird, wenn eine SSE-Sitzung geschlossen wird, empfängt `sessionId`

Fehlerbehandlung

Alle Handlertypen unterstützen die benutzerdefinierte Fehlerbehandlung über ihre Optionen:

// Example of custom error handling for stateful handler
const handlerOptions = {
  // ... other options
  onError: (error: Error, sessionId?: string) => {
    console.error(`Error in session ${sessionId}:`, error);
    // Send error to monitoring service
    Sentry.captureException(error, {
      extra: { sessionId }
    });
  }
};

TypeScript-Unterstützung

Dieses Paket ist in TypeScript geschrieben und bietet Typdefinitionen für alle Exporte. Bei Verwendung von TypeScript profitieren Sie von vollständigem IntelliSense und Typprüfung.

import { statefulHandler, StatefulHandlerOptions } from 'express-mcp-handler';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

// Type-safe options
const options: StatefulHandlerOptions = {
  sessionIdGenerator: () => Date.now().toString(),
  onError: (error, sessionId) => {
    // TypeScript knows the types of these parameters
    console.error(`Error in session ${sessionId}:`, error);
  }
};

const server = new McpServer({
  name: 'typed-server',
  version: '1.0.0',
});

// Type-safe handler
app.post('/mcp', statefulHandler(server, options));

Entwicklung

So tragen Sie zu diesem Projekt bei:

git clone https://github.com/jhgaylor/express-mcp-handler.git
cd express-mcp-handler
npm install
npm run build
npm test

Testabdeckung

Das Projekt verfügt über eine solide Testabdeckung und verspricht, diese aufrechtzuerhalten.

Alle Änderungen werden über unsere CI/CD-Pipeline überprüft, wobei Jest zum Testen und Codecov zum Berichten der Abdeckung verwendet wird.

Kontinuierliche Integration

Dieses Projekt nutzt GitHub Actions für kontinuierliche Integration. Jeder Push zum Hauptzweig und Pull Request führt zu:

Führen Sie den Lint-Check durch
Erstellen des Projekts
Führen Sie Tests mit Abdeckung durch
Abdeckungsberichte zu Codecov hochladen

Sie können den aktuellen CI-Status im Badge oben in dieser README-Datei oder auf der Registerkarte „Aktionen“ des GitHub-Repositorys anzeigen.

Lizenz

MIT-Lizenz

Veröffentlichen auf npm

Melden Sie sich bei npm an, falls Sie dies noch nicht getan haben:

npm login

Veröffentlichen Sie das Paket in npm (führt Ihren PrepublishOnly-Build aus):

npm publish

So erhöhen, markieren und pushen Sie eine neue Version:

npm version patch    # or minor, major
git push origin main --tags

Handlertypen im Überblick

Handler	Szenario	Sitzungen	Streaming
zustandsloser Handler	Einmalige oder serverlose Workloads	NEIN	NEIN
StatefulHandler	Multiturn-Interaktionen	Ja	Ja
sseHandlers	SSE-Streaming in Echtzeit	Ja	Ja

Fehlerbehebung

Fehlender mcp-session-id Header
Stellen Sie sicher, dass der Client den mcp-session-id Header einschließt, der bei der ursprünglichen Anforderung zurückgegeben wurde.

Verkehrsanbindung vorzeitig geschlossen
Überprüfen Sie die Netzwerkkonnektivität und stellen Sie sicher, dass der Client SSE-Ereignisse ordnungsgemäß verarbeitet.

Änderungsprotokoll

Alle wesentlichen Änderungen an diesem Projekt sind im CHANGELOG.md dokumentiert.

Express MCP Handler

Integrations