MCP 接入说明
将 ResAPI 接入 Cursor 等 MCP 客户端：远程 /mcp 与本地 stdio 配置、Tool 清单与故障排查
ResAPI MCP 接入说明
将 ResAPI 作为 MCP（Model Context Protocol） 工具接入 Cursor、Claude Desktop、WorkBuddy 等 AI 客户端。接入后，AI 可直接调用中国节假日、区划、高校、手机号段、邮编、非遗等 12 个结构化查询能力。
无需 API Key，按 IP 计数限流；只读 GET，用户查询参数不缓存。
快速选择接入方式
| 方式 | 适合谁 | 需要安装 | 连接地址 |
|---|---|---|---|
| 远程 MCP（推荐） | 大多数用户、生产环境 | 否 | https://www.resapi.cn/mcp |
| 本地 stdio | 离线开发、自定义 API 地址 | 是（resapi-mcp 二进制） |
本地进程 |
不确定用哪种？优先用远程 MCP——配置最少，与线上一致。
方式一：远程 MCP（推荐）
ResAPI 主服务已内置 Streamable HTTP MCP 端点，客户端填 URL 即可，无需下载或编译 resapi-mcp。
端点
https://www.resapi.cn/mcp
传输协议：streamable-http（MCP 2025-03-26 起推荐的标准 HTTP 传输）。
域名说明：生产环境请使用与
config.yaml中site.base_url一致的域名（当前为https://www.resapi.cn）。裸域https://resapi.cn会 301 跳转到www，部分 MCP 客户端在 POST 跳转时可能丢失请求体导致连接失败；API 与 MCP 请统一用www或查看/agent.json里的mcp.http.url。
Cursor 配置
- 打开 Cursor Settings → MCP（或编辑
~/.cursor/mcp.json/ 项目.cursor/mcp.json） - 添加远程服务（字段名因 Cursor 版本略有差异，以下为常见写法）：
{
"mcpServers": {
"resapi": {
"url": "https://www.resapi.cn/mcp"
}
}
}
（若 site.base_url 为其他地址，以 /agent.json 中 mcp.http.url 为准。）
若你的 Cursor 版本仍只支持 command 方式，请改用下方 方式二：本地 stdio。
- 保存后重启 Cursor，或在 MCP 面板点击刷新
- 在对话中尝试：「帮我查 2026 年 10 月 1 日是否放假」——应自动调用
holidays_check
自托管 / 本地调试
本地启动服务后，URL 改为：
http://127.0.0.1:8080/mcp
config.yaml 默认开启 MCP HTTP：
agent:
mcp_http_enabled: true # false 可关闭
mcp_http_path: /mcp
方式二：本地 stdio
适用于 Cursor 旧版、Claude Desktop，或需要指向非 resapi.cn 的 API 地址。
1. 获取二进制
从部署包（已含 resapi-mcp）：
chmod +x resapi-mcp
自行编译：
go build -o resapi-mcp ./cmd/mcp-server
2. Cursor / Claude Desktop 配置
编辑 MCP 配置文件：
| 客户端 | 配置文件路径 |
|---|---|
| Cursor（全局） | ~/.cursor/mcp.json |
| Cursor（项目） | .cursor/mcp.json |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） |
生产环境：
{
"mcpServers": {
"resapi": {
"command": "/绝对路径/resapi-mcp",
"args": ["-api-base", "https://resapi.cn"]
}
}
}
本地调试：
{
"mcpServers": {
"resapi": {
"command": "/绝对路径/resapi-mcp",
"args": ["-api-base", "http://127.0.0.1:8080"]
}
}
}
-api-base必须可访问；MCP 进程会通过 HTTP 代理调用 ResAPI，本身不连接数据库。
3. 命令行参数
| 参数 | 默认值 | 说明 |
|---|---|---|
-api-base |
https://resapi.cn |
ResAPI 根地址，勿带末尾 / |
提供的 Tool（12 个）
MCP 暴露的是粗粒度工具（非 60+ 原始端点），便于 AI 准确选型：
| Tool ID | 用途 | 必填参数 | 示例 |
|---|---|---|---|
holidays_check |
某日是否放假/调休 | date |
2026-10-01 |
holidays_lunar |
农历、节气、生肖 | date |
2026-02-04 |
regions_search |
省市区搜索 | q |
海淀 |
regions_ancestors |
区划层级路径 | code |
110108 |
phone_lookup |
手机号/号段归属 | number |
13213000000 |
validate_idcard |
身份证校验 | number |
18 位号码 |
validate_bank_card |
银行卡 Luhn 校验 | number |
卡号 |
zipcode_lookup |
邮编查地名 | zip |
100020 |
zipcode_search |
地名查邮编 | q |
朝阳区 |
ich_search_projects |
非遗项目搜索 | q |
黄梅戏 |
colleges_search |
高校搜索 | q |
浙江大学 |
address_parse |
自由文本地址解析 | text |
完整地址 |
完整定义（含 when_to_use、参数说明）：
curl -s https://www.resapi.cn/agent.json
聚合接口（减少 AI 多次调用）
除 MCP Tool 外，HTTP 层提供聚合接口；MCP 内部仍走 /v1/*，你也可以在 Skill / 自定义 Agent 里直接调：
| 路径 | 合并能力 |
|---|---|
GET /v1/agent/day?date= |
工作日判断 + 农历 |
GET /v1/agent/address?text= |
地址解析 + 区划层级 |
GET /v1/agent/phone?number= |
号段归属 + 省级区划 |
GET /v1/agent/zipcode?q= |
邮编/地名智能互查 |
GET /v1/agent/suggest?q= |
意图路由，推荐 Tool |
所有 /v1/* 成功 JSON 响应会附带 agent_hint，提示更合适的下一步接口。
验证接入是否成功
1. 检查 API 可达
curl -s https://www.resapi.cn/health
curl -s https://www.resapi.cn/agent.json | head -c 200
2. 检查 MCP HTTP 端点（POST）
Streamable HTTP 使用 POST 握手，curl -I（HEAD）可能返回 404，不代表服务不可用。请用下面的 POST initialize 验证：
curl -sS -X POST "https://www.resapi.cn/mcp" \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": { "name": "curl-test", "version": "1.0" }
}
}'
成功时返回 JSON，且 result.serverInfo.name 为 resapi（版本如 1.13.0）。
可选：列出 12 个 Tool：
curl -sS -X POST "https://www.resapi.cn/mcp" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
3. 在 Cursor 中测试
对 AI 说：
- 「2026 年国庆节放几天假？」
- 「132 开头的手机号是哪里？」
- 「解析地址：北京市海淀区中关村大街 1 号」
若 MCP 正常，AI 会调用对应 Tool 并返回 JSON 结果。
服务发现与其他文档
| 端点 / 文档 | 说明 |
|---|---|
GET /agent.json |
工具清单、聚合接口、MCP 地址 |
GET /catalog.json |
API 目录（含 agent_summary） |
GET /openapi.json |
OpenAPI 3.0（含 x-agent-when-to-use） |
| WorkBuddy 接入 | 腾讯 WorkBuddy Skill 配置 |
| Skill 包 | 意图路由表，可导入 Agent 中台 |
| 升级计划 | Agent 能力路线图 |
使用原则
| 原则 | 说明 |
|---|---|
| 只读 | 全部 Tool 对应 GET，无写入与数据托管 |
| 不缓存用户输入 | 手机号、地址、证件等查询不入库、不进 Redis |
| 免 Key | 当前无需 API Key；请遵守限流（响应头 X-RateLimit-*） |
| 仅供参考 | 数据用于技术验证；重要决策请以官方口径为准 |
故障排查
| 现象 | 处理 |
|---|---|
curl -I /mcp 返回 404 |
正常；MCP 走 POST，请用上方 initialize 命令验证 |
配 resapi.cn/mcp 连不上 |
改用 www.resapi.cn/mcp，避免 301 导致 POST body 丢失 |
| Cursor 看不到 resapi 工具 | 检查 MCP 配置 JSON 语法；重启 Cursor；stdio 方式确认二进制路径为绝对路径 |
| Tool 调用报 HTTP 4xx/5xx | 检查 -api-base 或远程 URL；curl -s https://www.resapi.cn/health |
远程 /mcp 连接失败 |
确认 agent.mcp_http_enabled: true；Nginx 需放行 /mcp 长连接（见下） |
| stdio 无日志 | MCP 日志在 stderr，不要重定向 stdout（会破坏 JSON-RPC） |
| 日期/邮编参数错误 | 日期 YYYY-MM-DD；邮编 6 位数字 |
| 429 限流 | 降低调用频率；响应头查看 X-RateLimit-Remaining |
无需单独启动
resapi-mcp：远程 MCP 只跑主进程./resapi即可；stdio 方式由 Cursor 自动拉起子进程。
Nginx 反代提示
若 resapi.cn 前有 Nginx，需为 /mcp 关闭缓冲并允许长连接，例如：
location /mcp {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_read_timeout 86400s;
}
相关链接
- MCP 协议：https://modelcontextprotocol.io/
- ResAPI 首页：https://www.resapi.cn
- Agent 接入总览：UPGRADE.md