README.md•4.41 kB
## MCP Server Demo
一个最小可用的 Model Context Protocol (MCP) 演示项目：
- `server.js` 通过 stdio 方式启动 MCP Server，并注册工具
- `client.js` 作为 HTTP API 网关，内部与 MCP Server 建立长连接，将工具暴露为 HTTP 接口
- `tools/` 目录下包含三个示例工具：`helloTool`、`weatherTool`、`networkTool`
### 运行环境
- Node.js 18+（推荐 20+）
### 安装依赖
```bash
npm install
```
### 启动 HTTP API（会自动启动 MCP Server）
```bash
node client.js
```
启动后控制台会看到：
- MCP server 已通过 stdio 启动并连接
- HTTP API 监听在 `http://localhost:3000`
### 健康检查
```bash
curl http://localhost:3000/health
```
### 列出可用工具
```bash
curl http://localhost:3000/tools
```
### 调用工具（通用）
HTTP 方法：`POST`
路径：`/tools/:name`
请求体：工具所需参数（JSON）
---
## 工具列表与用法
### helloTool
- 描述：输出问候语
- 参数：
- `name` (string)：要问候的名字
示例：
```bash
curl -X POST http://localhost:3000/tools/helloTool \
-H "Content-Type: application/json" \
-d '{"name":"Han"}'
```
---
### weatherTool
- 描述：查询城市天气（示例内置了几座城市，未命中则返回默认值）
- 参数：
- `city` (string)：城市名
示例：
```bash
curl -X POST http://localhost:3000/tools/weatherTool \
-H "Content-Type: application/json" \
-d '{"city":"Beijing"}'
```
---
### networkTool
- 描述：请求指定 URL，返回 HTTP 状态、耗时、以及响应摘要/完整内容
- 参数：
- `url` (string, url)：目标地址
- `method` ("GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE"，默认 "GET")
- `timeoutMs` (number, 默认 8000)：超时时间毫秒
- `fullBody` (boolean, 默认 true)：是否返回完整 body（若为 JSON 将尝试解析）
- `maxBodyBytes` (number, 默认 262144)：非 JSON 响应在 `fullBody` 下返回的最大字节数，超过即截断
- `headers` (record<string,string>，可选)：请求头
- `query` (record<string,string|number|boolean>，可选)：追加到 URL 的查询参数
- `body` (any，可选)：请求体（仅非 GET/HEAD 有效）
- `bodyType` ("json" | "text" | "form"，默认 "json")：请求体序列化方式
返回字段（核心）：
- `status`、`ok`、`latencyMs`
- `contentType`、`isJson`
- `bodyJson`（当响应为 JSON 且解析成功）
- `body`（非 JSON 文本，可能被截断）
- `bodySnippet`（未开启 `fullBody` 或 JSON 解析失败时的片段）
- `truncated`（是否发生截断）
- `headers`（响应头）
- `request`（回显请求信息，含 `url/method/headers/bodyPreview`）
示例：
- GET 带查询参数
```bash
curl -X POST http://localhost:3000/tools/networkTool \
-H "Content-Type: application/json" \
-d '{
"url":"https://httpbin.org/get",
"query": {"q":"hello","page":2},
"headers": {"X-Debug":"1"}
}'
```
- POST JSON
```bash
curl -X POST http://localhost:3000/tools/networkTool \
-H "Content-Type: application/json" \
-d '{
"url":"https://httpbin.org/post",
"method":"POST",
"bodyType":"json",
"body": {"foo":"bar"}
}'
```
- POST 表单
```bash
curl -X POST http://localhost:3000/tools/networkTool \
-H "Content-Type: application/json" \
-d '{
"url":"https://httpbin.org/post",
"method":"POST",
"bodyType":"form",
"body": {"a":1,"b":"x"}
}'
```
- 发送纯文本
```bash
curl -X POST http://localhost:3000/tools/networkTool \
-H "Content-Type: application/json" \
-d '{
"url":"https://httpbin.org/post",
"method":"POST",
"bodyType":"text",
"body":"raw text"
}'
```
---
## 目录结构
```
.
├─ client.js # HTTP 网关，连接 MCP Server 并暴露 /tools/*
├─ server.js # MCP Server，注册工具并通过 stdio 提供服务
├─ tools/
│ ├─ helloTool.js
│ ├─ weatherTool.js
│ └─ networkTool.js
├─ package.json
└─ README.md
```
### 关闭与清理
`client.js` 支持 Ctrl+C 优雅退出，会尝试关闭与 MCP 的连接及 HTTP 服务器。
### 常见问题
- 无法联网：检查本机代理/防火墙；`networkTool` 默认 8s 超时，可调整 `timeoutMs`
- 返回体太大：可通过 `maxBodyBytes` 控制非 JSON 响应的最大返回字节
- 需要仅看片段：将 `fullBody` 设为 `false`，仅返回 `bodySnippet`