# 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. 安装依赖
```bash
cd E:\work\icbc_mcp
npm install
```

### 2. 开发模式运行
```bash
npm run dev
```
服务器将在 `http://localhost:3000` 启动。

### 3. 生产模式
```bash
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` 中添加：

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

### 直接 HTTP 调用示例
```bash
# 初始化
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 服务端：

```bash
npm run dev
```

或者：

```bash
npm run build
npm start
```

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

### 2. 启动客户端

使用默认地址连接：

```bash
npm run client
```

连接指定地址：

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

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

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

### 3. 交互模式命令

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

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

示例：

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

### 4. 非交互模式

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

列出工具：

```bash
npm run client -- list
```

调用 `match_openapi_interfaces`：

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

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

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

### 5. 参数格式说明

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

正确示例：

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

错误示例：

```bash
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 示例：

```bash
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 镜像**：
   ```bash
   docker build -t icbc-mcp-demo .
   ```

2. **运行 Docker 容器**：
   ```bash
   docker run -d -p 3000:3000 --name mcp-server icbc-mcp-demo
   ```

3. **使用 Client 验证**：
   容器启动后，在宿主机上使用内置的 MCP Client 连接并测试工具：
   ```bash
   # 列出工具
   npm run client -- http://localhost:3000/mcp list

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

4. **停止并删除容器**（测试完毕后）：
   ```bash
   docker stop mcp-server
   docker rm mcp-server
   ```

### 传统方式部署到生产
- 使用 `npm run build` 编译
- 使用 PM2 等工具管理进程
- 配置反向代理（如 Nginx）处理 HTTPS 和负载均衡

## 许可证

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