AI_Health 经络穴位 MCP 服务使用指南

概述

acupoint-health-tool 是一个连接 AI_Health 经络穴位养生 MCP 服务（https://health.geeyo.com）的 Agent 技能，让任何 MCP 客户端一句话即可获得有古籍依据的中医穴位按摩建议。

核心价值：

• 有据可查的中医咨询：回答严格出自《玉龙歌》《玉龙赋》《百症赋》《马丹阳天星十二穴治杂病歌》四部针灸古籍，每条穴位推荐附出处与选穴原理，拒绝无来源的养生泛谈
• 开箱即用，零门槛接入：同时支持 Streamable HTTP 与旧版 SSE 双传输，新老 MCP 客户端一个 URL 即连，无需部署任何本地组件
• 免注册的身份体系：基于本机数字指纹派生客户端 ID——无需账号密码，同一台机器的咨询历史自动归属同一身份，且只上送哈希、不泄露原始指纹，隐私安全
• 智能多轮澄清：描述不清时服务端主动追问（部位/性质/诱因，最多 3 轮），本技能内置完整流程指引，按图索骥即可跑通对话，避免答非所问
• 咨询结果可分享：一键生成分享链接，把完整问答过程发给家人朋友查看

适用场景：头痛失眠、颈肩腰腿不适等日常病痛的穴位按摩自助咨询；健康类 Agent 产品快速集成中医穴位能力。

本技能指导三件事：如何连接该服务、如何完成基于本地数字指纹的自动"注册"、如何正确走多轮澄清对话流程。

连接方式

服务与网站同端口同进程，生产地址为 https://health.geeyo.com（本地开发时替换为 http://localhost:3000）。支持两种传输，优先使用 Streamable HTTP：

MCP 客户端配置示例：

{ "mcpServers": { "ai-health": { "url": "https://health.geeyo.com/mcp" } } }

老客户端只支持 SSE 时改用 https://health.geeyo.com/mcp/sse。

握手/请求的原始 JSON-RPC 与 curl 示例见 references/protocol_examples.md（仅在需要手工调试 HTTP 层时加载）。

自动注册：基于本地数字指纹生成唯一 ID

该服务没有账号注册接口。客户端身份由 Agent 自行生成：根据本机数字指纹派生一个稳定且唯一的客户端 ID，作为业务会话 sessionId 的前缀，使同一台机器的咨询历史可以归属到同一"账号"。

生成规则（必须遵循）：

1. 采集本机指纹源（按平台取其一，再拼接 hostname 与用户名增强唯一性）：
   • Windows：注册表 HKLM\SOFTWARE\Microsoft\Cryptography 的 MachineGuid （reg query "HKLM\SOFTWARE\Microsoft\Cryptography" /v MachineGuid）
   • Linux：/etc/machine-id
   • macOS：ioreg -rd1 -c IOPlatformExpertDevice 中的 IOPlatformUUID
2. 计算 SHA-256(machineId + "|" + hostname + "|" + username)，取十六进制前 32 位作为 clientId。
3. 业务会话 ID 用 "{clientId}-{短随机串}" 格式；每个新咨询话题换一个随机串，clientId 部分保持不变。
4. 隐私约束：只上送哈希结果，绝不发送原始 MachineGuid、MAC 地址、用户名等明文指纹；不落盘缓存原始指纹，只可缓存派生出的 clientId。

Node 一行式示例：

node -e "const c=require('crypto'),os=require('os'),{execSync}=require('child_process');const mid=execSync('reg query \"HKLM\\\\SOFTWARE\\\\Microsoft\\\\Cryptography\" /v MachineGuid').toString().match(/\{[0-9a-f-]+\}/i)[0];console.log(c.createHash('sha256').update(mid+'|'+os.hostname()+'|'+os.userInfo().username).digest('hex').slice(0,32))"

注意：MCP 传输层自身的会话（mcp-session-id 头 / SSE sessionId）由服务器生成，与上述业务 sessionId 是两回事，不要混用。

工具清单与使用要点

1. acupoint_consult — 穴位咨询（核心工具，多轮流程）

入参：message（病痛描述，必填）、sessionId（可选，多轮时必传）。 返回 JSON 字段：reply、isFinal、sessionId，可能有 rejected、followupCount。

多轮流程（必须按此处理）：

1. 首次调用：sessionId 传 "{clientId}-{随机串}"；message 尽量一次给全三要素——部位、疼痛性质、诱因/伴随症状（如"前额胀痛，受凉后加重，伴轻微恶心"），可显著减少追问轮数。
2. isFinal=false 且无 rejected：reply 是追问。回答追问内容后携带同一 sessionId 再次调用，直到 isFinal=true。最多追问 3 轮，超限服务端自动强制作答。
3. isFinal=true：reply 为最终 Markdown 回答（推荐穴位/定位/手法/选穴原理/古籍出处/免责声明），直接呈现给用户，不要删减免责声明。
4. rejected=true：问题与中医穴位无关被拒。不要重试同一问题；如确属健康问题，改写为身体不适描述再试。
5. 最终回答生成后该会话即完结；新话题必须换新的随机串生成新 sessionId，不要复用已完结会话。

注意：最终回答由 LLM 生成，单次调用可能需要 30–120 秒，设置足够的客户端超时。

2. share_create / share_get — 分享读写

• share_create：入参 messages（[{role: "user"|"assistant", content}]，至少 1 条）、title（可选，缺省取首条用户消息前 40 字）。返回 shareId。分享页地址为 {BASE_URL}/?share={shareId}（注意：参数名为 share 而非 id，路径为站点根 / 而非 /share.html；前端 app.js 仅读取 ?share= 参数，用错格式会回退成初始提问页）。
• share_get：入参 shareId，返回 {title, messages, createdAt}；不存在时返回 isError。服务端最多保留 200 条分享，旧的会被淘汰，shareId 不保证永久有效。

3. list_reference_books — 列出参考古籍

无入参。返回本服务回答所依据的古籍名列表。用户质疑答案依据时先调用它说明知识边界；古籍未覆盖的病症，回答中会声明"选择最接近的"。

错误处理