Экспресс-обработчик MCP

express-mcp-обработчик

Промежуточное программное обеспечение для интеграции протокола контекста модели (MCP) с приложениями Express, обеспечивающее бесперебойную связь между LLM и инструментами.

Что такое протокол контекста модели (MCP)?

Model Context Protocol (MCP) — открытый протокол для интеграции больших языковых моделей (LLM) с внешними источниками данных и инструментами. Он позволяет помощникам ИИ получать доступ к данным в реальном времени, выполнять операции и взаимодействовать с различными службами через стандартизированный интерфейс.

Функции

Обработчик с отслеживанием состояния : может обрабатывать разовые запросы или поддерживать долгосрочные сеансы с идентификаторами сеансов и событиями, отправленными сервером (SSE).
Обработчик без сохранения состояния : обрабатывает каждый запрос в полной изоляции для простых одноразовых взаимодействий.
Обработчик SSE : обрабатывает протокол контекста модели (MCP) через события, отправленные сервером (SSE), с выделенными конечными точками GET и POST.
Type-Safe API : создан на основе TypeScript для надежной интеграции.
Гибкая конфигурация : настраиваемая обработка ошибок, управление сеансами и хуки жизненного цикла.
Интеграция Express : подключается напрямую к маршрутам Express с помощью шаблона промежуточного программного обеспечения.

Установка

Установить через npm:

npm install express-mcp-handler

Или пряжа:

yarn add express-mcp-handler

Или пнпм:

pnpm add express-mcp-handler

Зависимости от сверстников

Для этого пакета требуются следующие одноранговые зависимости:

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

Установите их, если вы еще этого не сделали:

npm install express @modelcontextprotocol/sdk zod

Быстрый старт

Вот простой пример, с которого можно начать:

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

Использование

Express-mcp-handler предоставляет три типа обработчиков для различных вариантов использования:

Режим с отслеживанием состояния

Используйте statefulHandler для создания многоразовых сеансов между клиентом и сервером, что идеально подходит для сохранения контекста при множественных взаимодействиях:

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

Обработчик с отслеживанием состояния:

Инициализирует новый сеанс по первому запросу (без заголовка mcp-session-id )
Возвращает заголовок mcp-session-id , который клиенты должны включать в последующие запросы.
Управляет событиями, отправленными сервером (SSE), для передачи сообщений с сервера клиенту
Автоматически очищает сеансы при закрытии

Режим без сохранения состояния

Используйте statelessHandler для обработки одноразовых запросов без управления сеансами, что идеально подходит для сред без сервера или простых запросов:

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

Каждый запрос без указания состояния:

Создает новый транспорт и экземпляр сервера
Обеспечивает полную изоляцию без отслеживания сеанса
Подходит для простых или бессерверных сред.

Режим SSE

Используйте sseHandlers для обработки протокола контекста модели (MCP) через события, отправленные сервером (SSE), что идеально подходит для потоковых ответов в реальном времени:

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 предоставляют:

GET /sse : устанавливает поток SSE и возвращает заголовок mcp-session-id
POST /messages : отправляет сообщения MCP через транспорт SSE, используя параметр запроса mcp-session-id

Ссылка на API

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;

Параметр	Тип	Описание
`server`	`McpServer`	Экземпляр `McpServer` для обработки логики протокола
`options.sessionIdGenerator`	`() => string`	Функция, возвращающая уникальный идентификатор сеанса
`options.onSessionInitialized`	`(sessionId: string) => void`	(необязательно) Обратный вызов с новым идентификатором сеанса
`options.onSessionClosed`	`(sessionId: string) => void`	(необязательно) Обратный вызов, вызываемый при закрытии сеанса
`options.onError`	`(error: Error, sessionId?: string) => void`	(необязательно) Обратный вызов при возникновении ошибок
`options.onInvalidSession`	`(req: express.Request) => void`	(необязательно) Обратный вызов, вызываемый при доступе к недействительному сеансу

statelessHandler

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

Параметр	Тип	Описание
`serverFactory`	`() => McpServer`	Функция, которая возвращает новый экземпляр сервера для каждого запроса
`options.sessionIdGenerator`	`() => string`	(необязательно) Переопределить генерацию идентификатора сеанса транспорта
`options.onClose`	`(req: express.Request, res: express.Response) => void`	(необязательно) Обратный вызов запускается по завершении цикла запрос/ответ
`options.onError`	`(error: Error) => void`	(необязательно) Обратный вызов, срабатывающий при возникновении ошибок во время обработки

sseHandlers

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

Параметр	Тип	Описание
`serverFactory`	`ServerFactory`	Фабричная функция, которая возвращает новый `McpServer` для каждого SSE-подключения
`options.onError`	`(error: Error, sessionId?: string) => void`	(необязательно) Обратный вызов, вызываемый при ошибках, получает `error` и необязательный `sessionId`
`options.onClose`	`(sessionId: string) => void`	(необязательно) Обратный вызов, вызываемый при закрытии сеанса SSE, получает `sessionId`

Обработка ошибок

Все типы обработчиков поддерживают индивидуальную обработку ошибок с помощью своих параметров:

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

Этот пакет написан на TypeScript и предоставляет определения типов для всех экспортов. При использовании TypeScript вы получите полный IntelliSense и проверку типов.

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

Разработка

Чтобы внести свой вклад в этот проект:

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

Тестовое покрытие

Проект имеет солидное тестовое покрытие и обещает его поддерживать.

Все изменения проверяются через наш конвейер CI/CD с использованием Jest для тестирования и Codecov для составления отчетов о покрытии.

Непрерывная интеграция

Этот проект использует GitHub Actions для непрерывной интеграции. Каждый push в основную ветку и pull request будут:

Запустите проверку ворса
Построить проект
Проведите тесты с покрытием
Загрузить отчеты о покрытии в Codecov

Текущий статус CI можно просмотреть на значке в верхней части этого файла README или на вкладке «Действия» репозитория GitHub.

Лицензия

Лицензия Массачусетского технологического института

Публикация в npm

Войдите в npm, если вы еще этого не сделали:

npm login

Опубликуйте пакет в npm (запустится ваша сборка prepublishOnly):

npm publish

Чтобы добавить, пометить и выложить новую версию:

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

Краткий обзор типов обработчиков

Обработчик	Сценарий	Сессии	Потоковое вещание
statelessHandler	Разовые или бессерверные рабочие нагрузки	Нет	Нет
statefulHandler	Многооборотные взаимодействия	Да	Да
sseHandlers	Потоковая передача SSE в реальном времени	Да	Да

Поиск неисправностей

Отсутствует заголовок mcp-session-id
Убедитесь, что клиент включает заголовок mcp-session-id возвращенный в первоначальном запросе.

Транспортное сообщение закрыто преждевременно
Проверьте сетевое подключение и убедитесь, что клиент правильно обрабатывает события SSE.

Журнал изменений

Все существенные изменения в этом проекте задокументированы в CHANGELOG.md .

Express MCP Handler

Integrations