@vkse/sse-mcp-skill 1.0.1

package/README.md

@@ -0,0 +1,185 @@
+# sse-mcp-skill
+
+一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 **SSE（Server-Sent Events）传输模式** 示例服务器，使用 Node.js + Express 实现。该服务器对外暴露 `query_user_database` 工具，模拟远程数据库查询场景，供 AI 客户端（如 Claude Desktop、Cursor 等）在对话中调用。
+
+## 与 Stdio 模式的核心差异
+
+| 特性     | Stdio 模式         | SSE 模式（本项目）               |
+| -------- | ------------------ | -------------------------------- |
+| 通信方式 | 标准输入/输出      | HTTP + Server-Sent Events        |
+| 网络能力 | 仅限本地进程       | 支持远程 / 跨网络连接            |
+| 端口监听 | 无                 | 默认监听 `3000` 端口             |
+| 连接建立 | 客户端直接启动进程 | 客户端先 `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. 安装依赖
+
+```bash
+cd sse-mcp-skill
+npm install
+```
+
+### 2. 运行服务
+
+```bash
+npm start
+# 或
+node server.js
+```
+
+启动后，服务监听 `http://localhost:3000`，终端将输出：
+
+```
+🚀 HTTP/SSE MCP Server 正在运行，请让 AI 客户端连接: http://localhost:3000/sse
+```
+
+## 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](https://modelcontextprotocol.io/docs/tools/inspector) 是官方提供的可视化调试工具：
+
+```bash
+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 连接（保持终端窗口打开）：**
+
+```bash
+curl -N http://localhost:3000/sse
+```
+
+**② 在另一个终端发送初始化请求：**
+
+```bash
+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 等）中添加如下配置：
+
+```json
+{
+  "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` 处理器中注册工具描述：**
+
+```javascript
+{
+  name: "your_tool_name",
+  description: "工具描述（写给 AI 看，决定调用时机）",
+  inputSchema: {
+    type: "object",
+    properties: {
+      param1: { type: "string", description: "参数说明" },
+    },
+    required: ["param1"],
+  },
+}
+```
+
+**② 在 `CallToolRequestSchema` 处理器中实现工具逻辑：**
+
+```javascript
+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`，如有冲突可在 `server.js` 底部修改 `PORT` 常量
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@vkse/sse-mcp-skill",
+  "version": "1.0.1",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "publish:npm": "npm publish --access public",
+    "release": "npm version patch && npm publish --access public",
+    "release:minor": "npm version minor && npm publish --access public",
+    "release:major": "npm version major && npm publish --access public"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "module",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "cors": "^2.8.6",
+    "express": "^5.2.1"
+  }
+}

package/server.js

@@ -0,0 +1,87 @@
+import express from "express";
+import cors from "cors";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const app = express();
+// 必须配置 CORS，因为 AI 客户端（如浏览器内的环境）可能会跨域请求
+app.use(cors()); 
+
+// 1. 初始化 MCP Server
+const mcpServer = new Server(
+  { name: "remote-database-skill", version: "1.0.0" },
+  { capabilities: { tools: {} } }
+);
+
+// 2. 注册工具 (例如：一个模拟的远程数据库查询工具)
+mcpServer.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "query_user_database",
+        description: "根据用户 ID 查询远程数据库中的核心数据",
+        inputSchema: {
+          type: "object",
+          properties: {
+            userId: { type: "number", description: "需要查询的用户 ID" },
+          },
+          required: ["userId"],
+        },
+      },
+    ],
+  };
+});
+
+// 3. 处理调用指令
+mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name === "query_user_database") {
+    const { userId } = request.params.arguments;
+    // 这里可以接入真实的 PostgreSQL 或 CockroachDB 查询逻辑
+    const mockData = { id: userId, status: "active", plan: "premium" };
+    
+    return {
+      content: [{ type: "text", text: `查询成功，数据为: ${JSON.stringify(mockData)}` }],
+    };
+  }
+  throw new Error(`Tool not found: ${request.params.name}`);
+});
+
+// === 核心差异：网络路由与 Transport 绑定 ===
+
+let transport; // 维护全局/会话级别的 transport 实例
+
+// 接口 1：客户端发起的 SSE 握手连接
+app.get("/sse", async (req, res) => {
+  console.log("收到新的客户端连接请求...");
+  
+  // 创建 SSE Transport，并告知客户端未来发消息要用哪个相对路径（/messages）
+  transport = new SSEServerTransport("/messages", res);
+  
+  // 将 Transport 绑定到 MCP Server
+  await mcpServer.connect(transport);
+  
+  // 此时长连接已建立，客户端会一直保持 pending 状态接收数据
+  console.log("SSE 连接已建立！");
+});
+
+// 接口 2：客户端用来发送指令的 POST 接口
+app.post("/messages", async (req, res) => {
+  if (!transport) {
+    return res.status(400).send("请先访问 /sse 建立连接");
+  }
+  
+  // 将原生的 HTTP 请求/响应对象交给 SDK 内部去解析 JSON-RPC
+  // SDK 拿到指令后，会触发上面定义的 CallToolRequestSchema，
+  // 然后通过绑定的 SSE 长连接把结果推回给客户端
+  await transport.handlePostMessage(req, res);
+});
+
+// 启动 Express 服务
+const PORT = 3000;
+app.listen(PORT, () => {
+  console.log(`🚀 HTTP/SSE MCP Server 正在运行，请让 AI 客户端连接: http://localhost:${PORT}/sse`);
+});