Controlador MCP Express

controlador express-mcp

Una utilidad para integrar el Protocolo de Contexto de Modelo (MCP) en sus aplicaciones Express.

Características

Manejador con estado : mantiene 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 flexible y fácil de usar que se conecta directamente a las rutas Express.

Instalación

Instalar mediante npm:

npm install express-mcp-handler

O hilo:

yarn add express-mcp-handler

Dependencias entre pares

express >= 4.x
@modelcontextprotocol/sdk

Uso

Importa los controladores del paquete y móntalos en tu aplicación Express:

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

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

Modo con estado

Utilice statefulHandler para establecer sesiones reutilizables entre el cliente y el servidor.

import { randomUUID } from 'node:crypto';

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

const handlerOptions = {
  sessionIdGenerator: randomUUID,
  onSessionInitialized: (sessionId: string) => {
    console.log(`Session initialized: ${sessionId}`);
  },
  onSessionClosed: (sessionId: string) => {
    console.log(`Session closed: ${sessionId}`);
    // perform cleanup logic here
  },
  onError: (error: Error, sessionId?: string) => {
    console.error(`Error in session ${sessionId}:`, error);
  }
};

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 manejador se encargará de:

Inicializar 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 solicitudes posteriores.
Administrar eventos enviados por el servidor (SSE) para enviar mensajes desde el servidor al cliente.
Limpiar sesiones automáticamente al cerrarlas.

Modo sin estado

Utilice statelessHandler para el manejo de solicitudes únicas sin administración de sesiones:

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

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

Cada solicitud:

Crea una nueva instancia de transporte y servidor.
Garantiza el aislamiento y la ausencia de seguimiento de sesiones.
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).

import { sseHandlers } from 'express-mcp-handler';

// Provide a factory function that returns a fresh McpServer for each SSE connection
const handlers = sseHandlers(serverFactory, {
  onError: (error: Error, sessionId?: string) => {
    console.error(`[SSE][${sessionId || 'unknown'}]`, error);
  },
  onClose: (sessionId: string) => {
    console.log(`[SSE] transport closed: ${sessionId}`);
  },
});

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

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

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;

servidor : instancia de McpServer para manejar la lógica del protocolo.
options.sessionIdGenerator : Función que devuelve un ID de sesión único.
options.onSessionInitialized (opcional) : devolución de llamada invocada con el nuevo ID de sesión.
options.onSessionClosed (opcional) : devolución de llamada invocada cuando se cierra una sesión.
options.onError (opcional) : devolución de llamada invocada en caso de errores.
options.onInvalidSession (opcional) : devolución de llamada invocada 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;

serverFactory : Función que devuelve una nueva instancia de servidor.
options.sessionIdGenerator (opcional) : anula la generación de ID de sesión de transporte.
options.onClose (opcional) : Se activa una devolución de llamada cuando finaliza el ciclo de solicitud/respuesta.
options.onError (opcional) : devolución de llamada que se activa en caso de errores durante el manejo.

Manejadores sse

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

serverFactory : función de fábrica que devuelve un McpServer nuevo para cada conexión SSE.
options.onError (opcional) : Se invoca una devolución de llamada en caso de errores, recibe error y sessionId opcional.
options.onClose (opcional) : Se invoca una devolución de llamada cuando se cierra una sesión SSE y recibe sessionId .

Desarrollo

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 ahora ha mejorado significativamente la cobertura de pruebas:

Declaraciones: 86,06%
Sucursales: 79,06%
Funciones: 88,88%
Líneas: 85,71%

Hemos agregado pruebas integrales para todos los tipos de controladores:

Manipuladores sin estado: cobertura del 100%
Manipuladores de SSE: cobertura del 97,29 %
Controladores con estado: cobertura del 67,34 % (con mejoras en curso)

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

Express MCP Handler

Integrations