Express MCP 处理程序

express-mcp-处理程序

用于将模型上下文协议 (MCP)与 Express 应用程序集成的中间件，实现 LLM 和工具之间的无缝通信。

什么是模型上下文协议（MCP）？

模型上下文协议 (MCP)是一个用于集成大型语言模型 (LLM) 与外部数据源和工具的开放协议。它使 AI 助手能够通过标准化接口访问实时数据、执行操作并与各种服务交互。

特征

有状态处理程序：可以处理一次性请求或使用会话 ID 和服务器发送事件 (SSE) 维护长期会话。
无状态处理程序：完全隔离地处理每个请求，以实现简单的一次性交互。
SSE 处理程序：使用专用的 GET 和 POST 端点处理服务器发送事件 (SSE) 上的模型上下文协议 (MCP)。
类型安全 API ：使用 TypeScript 构建，可实现可靠集成。
灵活的配置：可定制的错误处理、会话管理和生命周期挂钩。
Express 集成：使用中间件模式直接插入 Express 路由。

安装

通过 npm 安装：

npm install express-mcp-handler

或纱线：

yarn add express-mcp-handler

或者 pnpm：

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通过服务器发送事件 (SSE) 处理模型上下文协议 (MCP)，非常适合实时流响应：

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-session-id查询参数通过 SSE 传输发送 MCP 消息

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`	返回唯一会话 ID 的函数
`options.onSessionInitialized`	`(sessionId: string) => void`	（可选）使用新会话 ID 调用的回调
`options.onSessionClosed`	`(sessionId: string) => void`	（可选）会话关闭时调用的回调
`options.onError`	`(error: Error, sessionId?: string) => void`	（可选）发生错误时调用的回调
`options.onInvalidSession`	`(req: express.Request) => void`	（可选）访问无效会话时调用的回调

无状态处理程序

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`	（可选）覆盖传输会话 ID 生成
`options.onClose`	`(req: express.Request, res: express.Response) => void`	（可选）请求/响应周期结束时触发的回调
`options.onError`	`(error: Error) => void`	（可选）处理过程中发生错误时触发的回调

sse处理程序

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

范围	类型	描述
`serverFactory`	`ServerFactory`	为每个 SSE 连接返回一个新的`McpServer`的工厂函数
`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 进行持续集成。每次推送到主分支和拉取请求都会：

运行 Lint 检查
构建项目
运行覆盖测试
将覆盖率报告上传到Codecov

您可以在此 README 顶部的徽章中或 GitHub 存储库的“操作”选项卡中查看当前 CI 状态。

执照

MIT 许可证

发布到 npm

如果尚未登录，请登录 npm：

npm login

将包发布到 npm（将运行您的 prepublishOnly 构建）：

npm publish

要提升、标记和推送新版本：

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

处理程序类型一览

处理程序	设想	会议	流媒体
无状态处理程序	一次性或无服务器工作负载	不	不
statefulHandler	多轮互动	是的	是的
sse处理程序	实时 SSE 流	是的	是的

故障排除

缺少mcp-session-id标头
确保客户端包含初始请求上返回的mcp-session-id标头。

交通连接提前关闭
验证网络连接并确保客户端正确处理 SSE 事件。

变更日志

该项目所有值得注意的变化都记录在CHANGELOG.md中。

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

将模型上下文协议 (MCP) 集成到 Express 应用程序中的实用程序，提供有状态会话管理和无状态请求处理选项。

Related MCP Servers

MCP Server
la-rebelion
-
security
A
license
-
quality
MCP Server simplifies the implementation of the Model Context Protocol by providing a user-friendly API to create custom tools and manage server workflows efficiently.
Last updated -
4
3
TypeScript
MIT License
MCP Server
agentico-dev
-
security
A
license
-
quality
MCP Server provides a simpler API to interact with the Model Context Protocol by allowing users to define custom tools and services to streamline workflows and processes.
Last updated -
13
2
TypeScript
MIT License
Todo List MCP Server
RegiByte
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides tools for managing todo items, including creation, updating, completion, deletion, searching, and summarizing tasks.
Last updated -
10
4
TypeScript
MIT License
Sleep MCP Server
Garoth
A
security
F
license
A
quality
A Model Context Protocol (MCP) server that provides a simple sleep/wait tool, useful for adding delays between operations such as waiting between API calls or testing eventually consistent systems.
Last updated -
1
6
7
JavaScript

View all related MCP servers

Express MCP Handler