controlador express-mcp

Un middleware para integrar el Protocolo de Contexto de Modelo (MCP) con aplicaciones Express, lo que permite una comunicación fluida entre LLM y herramientas.

versión npm Descargas de npm Licencia: MIT Versión de Node.js Mecanografiado código decodificador

¿Qué es el Protocolo de Contexto Modelo (MCP)?

El Protocolo de Contexto de Modelo (MCP) es un protocolo abierto para integrar grandes modelos de lenguaje (LLM) con fuentes de datos y herramientas externas. Permite a los asistentes de IA acceder a datos en tiempo real, ejecutar operaciones e interactuar con diversos servicios a través de una interfaz estandarizada.

Related MCP server: Memory Cache Server

Características

Manejador con estado : puede manejar solicitudes únicas o mantener sesiones de larga duración con identificadores de sesión y eventos enviados por el servidor (SSE).
Manejador sin estado : maneja cada solicitud de manera completamente aislada para interacciones simples y únicas.
Manejador SSE : maneja el Protocolo de contexto de modelo (MCP) sobre eventos enviados por el servidor (SSE) con puntos finales GET y POST dedicados.
API de tipo seguro : desarrollada con TypeScript para una integración confiable.
Configuración flexible : manejo de errores personalizables, administración de sesiones y ganchos de ciclo de vida.
Integración Express : se conecta directamente a las rutas Express con patrón de middleware.

Instalación

Instalar mediante npm:

npm install express-mcp-handler

O hilo:

yarn add express-mcp-handler

O pnpm:

pnpm add express-mcp-handler

Dependencias entre pares

Este paquete requiere las siguientes dependencias de pares:

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

Instálalos si aún no lo has hecho:

npm install express @modelcontextprotocol/sdk zod

Inicio rápido

He aquí un ejemplo básico para empezar:

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');
});

Uso

Express-mcp-handler proporciona tres tipos de controladores para adaptarse a diferentes casos de uso:

Modo con estado

Utilice statefulHandler para establecer sesiones reutilizables entre el cliente y el servidor, ideal para mantener el contexto en múltiples interacciones:

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');
});

El controlador con estado:

Inicializa una nueva sesión en la primera solicitud (sin encabezado mcp-session-id )
Devuelve un encabezado mcp-session-id que los clientes deben incluir en las solicitudes posteriores
Administra eventos enviados por el servidor (SSE) para enviar mensajes desde el servidor al cliente
Limpia automáticamente las sesiones cuando se cierran

Modo sin estado

Utilice statelessHandler para el manejo de solicitudes únicas sin administración de sesiones, perfecto para entornos sin servidor o solicitudes simples:

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');
});

Cada solicitud sin estado:

Crea una nueva instancia de transporte y servidor
Garantiza un aislamiento completo sin seguimiento de sesiones.
Es adecuado para entornos simples o sin servidor.

Modo SSE

Utilice sseHandlers para manejar el Protocolo de contexto de modelo (MCP) sobre eventos enviados por el servidor (SSE), ideal para respuestas de transmisión en tiempo real:

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');
});

Los controladores de SSE proporcionan:

GET /sse : establece la secuencia SSE y devuelve un encabezado mcp-session-id
POST /messages : envía mensajes MCP a través del transporte SSE utilizando el parámetro de consulta mcp-session-id

Referencia de API

manejador con estado

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;

Parámetro	Tipo	Descripción
`server`	`McpServer`	Instancia de `McpServer` para manejar la lógica del protocolo
`options.sessionIdGenerator`	`() => string`	Función que devuelve un ID de sesión único
`options.onSessionInitialized`	`(sessionId: string) => void`	(opcional) Devolución de llamada invocada con el nuevo ID de sesión
`options.onSessionClosed`	`(sessionId: string) => void`	(opcional) Devolución de llamada invocada cuando se cierra una sesión
`options.onError`	`(error: Error, sessionId?: string) => void`	(opcional) Devolución de llamada invocada en caso de errores
`options.onInvalidSession`	`(req: express.Request) => void`	(opcional) Se invoca una devolución de llamada cuando se accede a una sesión no válida

manejador sin estado

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

Parámetro	Tipo	Descripción
`serverFactory`	`() => McpServer`	Función que devuelve una nueva instancia de servidor para cada solicitud
`options.sessionIdGenerator`	`() => string`	(opcional) Anular la generación de ID de sesión de transporte
`options.onClose`	`(req: express.Request, res: express.Response) => void`	(opcional) La devolución de llamada se activa cuando finaliza el ciclo de solicitud/respuesta
`options.onError`	`(error: Error) => void`	(opcional) Devolución de llamada activada en caso de errores durante el manejo

Manejadores sse

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

Parámetro	Tipo	Descripción
`serverFactory`	`ServerFactory`	Función de fábrica que devuelve un `McpServer` nuevo para cada conexión SSE
`options.onError`	`(error: Error, sessionId?: string) => void`	(opcional) Se invoca una devolución de llamada en caso de errores, recibe `error` y `sessionId` opcional.
`options.onClose`	`(sessionId: string) => void`	(opcional) Se invoca una devolución de llamada cuando se cierra una sesión SSE y recibe `sessionId`

Manejo de errores

Todos los tipos de controladores admiten el manejo de errores personalizado a través de sus opciones:

// 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 }
    });
  }
};

Compatibilidad con TypeScript

Este paquete está escrito en TypeScript y proporciona definiciones de tipos para todas las exportaciones. Al usar TypeScript, obtendrá IntelliSense completo y comprobación de tipos.

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));

Desarrollo

Para contribuir a este proyecto:

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

Cobertura de la prueba

El proyecto tiene una sólida cobertura de pruebas y promete mantenerla.

Todos los cambios se verifican a través de nuestro pipeline CI/CD usando Jest para pruebas y Codecov para informes de cobertura.

Integración continua

Este proyecto utiliza GitHub Actions para la integración continua. Cada envío a la rama principal y cada solicitud de extracción:

Ejecutar la comprobación de pelusa
Construir el proyecto
Ejecutar pruebas con cobertura
Subir informes de cobertura a Codecov

Puede ver el estado actual de CI en la insignia en la parte superior de este README o en la pestaña Acciones del repositorio de GitHub.

Licencia

Licencia MIT

Publicación en npm

Inicie sesión en npm si aún no lo ha hecho:

npm login

Publica el paquete en npm (ejecutará tu compilación prepublishOnly):

npm publish

Para impulsar, etiquetar y enviar una nueva versión:

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

Tipos de manejadores de un vistazo

Entrenador de animales	Guión	Sesiones	Transmisión
manejador sin estado	Cargas de trabajo únicas o sin servidor	No	No
manejador con estado	Interacciones de múltiples turnos	Sí	Sí
Manejadores sse	Transmisión SSE en tiempo real	Sí	Sí

Solución de problemas

Falta el encabezado
Asegúrese de que el cliente incluya el encabezado mcp-session-id devuelto en la solicitud inicial.

Conexión de transporte cerrada prematuramente
Verifique la conectividad de la red y asegúrese de que el cliente gestione correctamente los eventos SSE.

Registro de cambios

Todos los cambios notables de este proyecto están documentados en CHANGELOG.md .

Express MCP Handler