hxw-haha/mcp-server-demo

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+）

安装依赖

npm install

启动 HTTP API（会自动启动 MCP Server）

node client.js

启动后控制台会看到：

• MCP server 已通过 stdio 启动并连接
• HTTP API 监听在 http://localhost:3000

健康检查

curl http://localhost:3000/health

列出可用工具

curl http://localhost:3000/tools

调用工具（通用）

HTTP 方法：POST 路径：/tools/:name 请求体：工具所需参数（JSON）

工具列表与用法

helloTool

• 描述：输出问候语
• 参数：
  • name (string)：要问候的名字

示例：

curl -X POST http://localhost:3000/tools/helloTool \
  -H "Content-Type: application/json" \
  -d '{"name":"Han"}'

weatherTool

• 描述：查询城市天气（示例内置了几座城市，未命中则返回默认值）
• 参数：
  • city (string)：城市名

示例：

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 带查询参数

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

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 表单

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"}
  }'

• 发送纯文本

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