sse-mcp-skill

一个基于 Model Context Protocol (MCP) 的 SSE（Server-Sent Events）传输模式 示例服务器，使用 Node.js + Express 实现。该服务器对外暴露 query_user_database 工具，模拟远程数据库查询场景，供 AI 客户端（如 Claude Desktop、Cursor 等）在对话中调用。

与 Stdio 模式的核心差异

| 特性 | Stdio 模式 | SSE 模式（本项目） | | -------- | ------------------ | -------------------------------- | | 通信方式 | 标准输入/输出 | HTTP + Server-Sent Events | | 网络能力 | 仅限本地进程 | 支持远程 / 跨网络连接 | | 端口监听 | 无 | 默认 3000，支持 --port 自定义 | | 连接建立 | 客户端直接启动进程 | 客户端先 GET /sse 建立长连接 | | 消息发送 | 通过 stdin/stdout | 客户端 POST /messages 发送指令 | | 适用场景 | 本地工具、CLI 环境 | 远程服务、多客户端、Web 环境 |

项目结构

sse-mcp-skill/
├── server.js         # 服务器入口，Express 路由 + MCP 工具定义
├── package.json      # 项目依赖与脚本配置
└── README.md

核心依赖

| 依赖 | 版本 | 说明 | | --------------------------- | ------- | -------------------------------------------------------- | | @modelcontextprotocol/sdk | ^1.28.0 | MCP 官方 SDK，提供 Server、SSEServerTransport 等核心能力 | | express | ^5.2.1 | Web 框架，用于创建 HTTP 路由（SSE 握手 + 消息接收） | | cors | ^2.8.6 | 跨域中间件，允许浏览器内的 AI 客户端跨域请求 |

工具列表

query_user_database

根据用户 ID 查询远程数据库中的核心数据（当前为模拟数据）。

| 参数 | 类型 | 必填 | 说明 | | -------- | -------- | ---- | ----------------- | | userId | number | 是 | 需要查询的用户 ID |

返回示例：

查询成功，数据为: {"id":1,"status":"active","plan":"premium"}

快速开始

1. 安装依赖

cd sse-mcp-skill
npm install

2. 运行服务

npm start
# 或
node server.js
# 或（一键远程启动，无需克隆项目）
npx -y @vkse/sse-mcp-skill

3. 自定义端口

默认端口为 3000，可通过以下方式自定义：

方式一：命令行参数 --port（优先级最高）

node server.js --port 8080
npx -y @vkse/sse-mcp-skill --port 8080

方式二：环境变量 PORT

# Linux / macOS
PORT=8080 node server.js

# Windows PowerShell
$env:PORT=8080; node server.js

优先级：--port 参数 > 环境变量 PORT > 默认值 3000

启动后终端将输出：

🚀 HTTP/SSE MCP Server 正在运行于端口 8080
   连接地址: http://localhost:8080/sse
   自定义端口: npx @vkse/sse-mcp-skill --port <端口号>

SSE 通信流程

AI 客户端                          SSE MCP Server (Express)
    │                                      │
    │──── GET /sse ────────────────────────>│  ① 建立 SSE 长连接
    │<─── SSE stream (keep-alive) ─────────│
    │                                      │
    │──── POST /messages ──────────────────>│  ② 发送 JSON-RPC 指令
    │                                      │     （initialize / tools/list / tools/call）
    │<─── SSE 推送结果 ────────────────────│  ③ 通过长连接推回结果
    │                                      │

测试方法

方式一：使用 MCP Inspector 测试

MCP Inspector 是官方提供的可视化调试工具：

npx -y @modelcontextprotocol/inspector node server.js
# 或者
npx -y @modelcontextprotocol/inspector sse://localhost:3000/sse

启动后在浏览器中打开 Inspector 界面，可以：

• 查看工具清单（List Tools）
• 手动调用 query_user_database 工具并查看返回结果
• 调试 JSON-RPC 消息收发

方式二：使用 curl 手动测试

① 建立 SSE 连接（保持终端窗口打开）：

curl -N http://localhost:3000/sse

② 在另一个终端发送初始化请求：

curl -X POST http://localhost:3000/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

方式三：配置到 AI 客户端中测试

在支持 MCP 的 AI 客户端（如 Claude Desktop、Cursor、Cline 等）中添加如下配置：

{
  "mcpServers": {
    "remote-database-skill": {
      "url": "http://localhost:3000/sse"
    }
  }
}

配置完成后，在对话中询问"帮我查一下用户 1 的信息"等数据库相关问题，AI 将自动调用 query_user_database 工具。

使用方法

作为 MCP 技能集成

1. 启动本服务（npm start）
2. 将 SSE 端点 http://localhost:3000/sse 配置到 AI 客户端
3. AI 根据对话上下文自动判断是否调用 query_user_database
4. 工具返回结果后，AI 将查询信息整合到回答中

扩展新工具

在 server.js 中按以下模式添加新工具：

① 在 ListToolsRequestSchema 处理器中注册工具描述：

{
  name: "your_tool_name",
  description: "工具描述（写给 AI 看，决定调用时机）",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "参数说明" },
    },
    required: ["param1"],
  },
}

② 在 CallToolRequestSchema 处理器中实现工具逻辑：

if (request.params.name === "your_tool_name") {
  const { param1 } = request.params.arguments;
  // 执行业务逻辑（如调用远程 API、查询数据库等）...
  return {
    content: [{ type: "text", text: "返回结果" }],
  };
}

注意事项

• CORS 已启用：server.js 中默认配置了 cors() 中间件，允许所有来源的跨域请求
• 单客户端限制：当前实现仅维护一个全局 transport 实例，同一时间只支持一个客户端连接。如需多客户端支持，需使用 Map 按 session 管理 transport
• 端口冲突：默认端口为 3000，可通过 --port 参数或 PORT 环境变量自定义

License

ISC