ICBC MCP 示例项目

基于 Model Context Protocol (MCP) 的 Streamable HTTP Transport 示例，使用 Node.js + TypeScript 实现。该示例演示如何通过 HTTP 端点暴露 MCP 工具，供 MCP 客户端（如 Claude Desktop、Cursor 等）调用。

项目结构

icbc_mcp/
├── src/
│   ├── index.ts          // 入口文件
│   ├── server.ts         // HTTP 服务器 + MCP 端点
│   ├── client.ts         // MCP 测试客户端
│   └── tools.ts          // MCP 工具定义
├── package.json          // 依赖与脚本
├── tsconfig.json         // TypeScript 配置
└── README.md             // 本文件

快速开始

1. 安装依赖

cd E:\work\icbc_mcp
npm install

2. 开发模式运行

npm run dev

服务器将在 http://localhost:3000 启动。

3. 生产模式

npm run build  # 编译 TypeScript
npm start      # 运行编译后的 JS

可用端点

MCP 主端点

• POST http://localhost:3000/mcp
  MCP JSON-RPC 2.0 请求入口，客户端通过此端点调用工具。

• GET http://localhost:3000/mcp
  SSE（Server-Sent Events）端点，用于服务器主动推送（可选）。

健康检查

• GET http://localhost:3000/health
  返回服务器状态。

已实现的 MCP 工具

工具名	描述	参数
match_openapi_interfaces	OpenAPI 接口匹配器	match_json (string), openapi_doc (string)

Streamable HTTP Transport 说明

本示例采用 Streamable HTTP Transport，这是 MCP 协议定义的一种传输方式：

1. 客户端连接流程：

   • POST /mcp 发送 initialize 请求，建立会话
   • POST /mcp 发送 notifications/initialized 通知
   • POST /mcp 发送 tools/list 获取可用工具
   • POST /mcp 发送 tools/call 调用具体工具

2. 无状态设计：

   • 每个 HTTP 请求创建一个独立的 transport 实例
   • 适合负载均衡、无状态部署场景

3. SSE 支持：

   • GET /mcp 提供 SSE 端点，用于服务端主动推送（如资源变更通知）

客户端配置示例

Claude Desktop 配置

在 Claude Desktop 的 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "icbc-mcp-demo": {
      "command": "node",
      "args": ["E:\\work\\icbc_mcp\\dist\\index.js"],
      "env": {
        "PORT": "3000"
      }
    }
  }
}

直接 HTTP 调用示例

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

# 调用 match_openapi_interfaces 工具
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "match_openapi_interfaces",
      "arguments": {
        "match_json": "{}",
        "openapi_doc": "{}"
      }
    }
  }'

Client 使用手册

本项目内置了一个命令行 MCP 客户端，可直接连接本地或远程 MCP 服务端进行测试。

1. 启动服务端

先启动 MCP 服务端：

npm run dev

或者：

npm run build
npm start

默认服务端地址为 http://localhost:3000/mcp。

2. 启动客户端

使用默认地址连接：

npm run client

连接指定地址：

npm run client -- http://localhost:3000/mcp

也可以通过环境变量指定地址：

$env:MCP_SERVER_URL="http://localhost:3000/mcp"
npm run client

3. 交互模式命令

客户端启动后会进入交互模式，支持以下命令：

命令	说明
help	查看帮助信息
tools	列出服务端当前暴露的所有工具
ping	测试客户端是否成功连通 MCP 服务端
call <工具名> <JSON参数>	调用指定工具
exit / quit	退出客户端

示例：

call match_openapi_interfaces {"match_json":"{}","openapi_doc":"{}"}

4. 非交互模式

如果只想快速测试，也可以直接使用命令模式。

列出工具：

npm run client -- list

调用 match_openapi_interfaces：

npm run client -- call match_openapi_interfaces "{\"match_json\":\"{}\",\"openapi_doc\":\"{}\"}"

连接指定服务端后再列出工具：

npm run client -- http://localhost:3000/mcp list

5. 参数格式说明

• call 命令中的参数必须是合法的 JSON 对象
• JSON 最外层必须是 {}，不能直接传数组或普通字符串
• 如果工具没有参数，可以直接传空对象 {}

正确示例：

npm run client -- call match_openapi_interfaces "{\"match_json\":\"{}\",\"openapi_doc\":\"{}\"}"

错误示例：

npm run client -- call match_openapi_interfaces "hello"

6. 推荐测试流程

1. 启动服务端
2. 执行 npm run client -- list，确认客户端能成功连接并拿到工具列表
3. 执行 npm run client -- call match_openapi_interfaces "{\"match_json\":\"{}\",\"openapi_doc\":\"{}\"}"，确认工具调用正常
4. 执行 npm run client 进入交互模式，手工测试不同工具

7. 常见问题

连接失败

请检查：

• 服务端是否已经启动
• 地址是否正确，默认是 http://localhost:3000/mcp
• 端口是否被其他程序占用

参数解析失败

请检查：

• 传入的参数是否为合法 JSON
• Windows PowerShell 下 JSON 内部双引号是否正确转义

PowerShell 示例：

npm run client -- call match_openapi_interfaces "{\"match_json\":\"{}\",\"openapi_doc\":\"{}\"}"

技术栈

• Node.js (ESM 模块)
• TypeScript (严格模式)
• @modelcontextprotocol/sdk (MCP 官方 SDK)
• Express (HTTP 服务器)
• Zod (参数验证)

扩展指南

添加新工具

1. 在 src/tools.ts 中定义新的工具函数
2. 使用 server.tool() 注册
3. 重启服务器即可生效

添加资源能力

如需暴露资源（如文件、数据库查询），可启用 capabilities.resources 并实现相应处理器。

Docker 部署与验证

本项目已配置 Dockerfile，支持容器化部署。服务端默认监听 0.0.0.0:3000 以便在容器外访问。

1. 构建 Docker 镜像：

   docker build -t icbc-mcp-demo .
   

2. 运行 Docker 容器：

   docker run -d -p 3000:3000 --name mcp-server icbc-mcp-demo
   

3. 使用 Client 验证： 容器启动后，在宿主机上使用内置的 MCP Client 连接并测试工具：

   # 列出工具
   npm run client -- http://localhost:3000/mcp list
   
   # 调用工具
   npm run client -- http://localhost:3000/mcp call match_openapi_interfaces "{\"match_json\":\"{}\",\"openapi_doc\":\"{}\"}"
   

4. 停止并删除容器（测试完毕后）：

   docker stop mcp-server
   docker rm mcp-server
   

传统方式部署到生产

• 使用 npm run build 编译
• 使用 PM2 等工具管理进程
• 配置反向代理（如 Nginx）处理 HTTPS 和负载均衡

许可证

内部示例代码，仅供学习参考。