chakudya-mcp-server

Chakudya MCP 服务

一个 MCP（Model Context Protocol）服务，将 Chakudya Nutrition Registry (CNR) API 封装为一组 MCP 工具，让任何兼容 MCP 的客户端（Claude、Claude Code、 其他大模型 Agent）都能搜索马拉维食品数据、查询临床营养信息，并直接查询 RAG 知识库。

这是一个全新的独立层，不会替代或修改 Chakudya Worker。 它是一个小型 Node/TypeScript HTTP 服务，位于现有 API 前端，将 MCP 工具调用转换为针对 Worker 当前提供的路由的 普通 HTTP 请求。

MCP Client (Claude, etc.)
        │  Streamable HTTP (JSON-RPC over HTTP + SSE)
        ▼
Chakudya MCP Server  (this project)
        │  plain HTTPS fetch()
        ▼
Chakudya Worker API  (unchanged) → Supabase / Cohere / Groq / USDA / OFF / FatSecret

为什么使用独立服务，而不是 Worker

官方 MCP TypeScript SDK 的 StreamableHTTPServerTransport 是为 Node 的 http.IncomingMessage/ServerResponse 构建的。Cloudflare Workers 使用 Fetch API，而 SDK 的 Web 标准版本（WebStandardStreamableHTTPServerTransport）较新，在生产环境的会话管理方面尚未经过充分验证。如今，将其作为普通 Node 服务运行（Docker、Render、Fly.io、VPS 等）是更常见、文档更完善的方案，也能让这一部分与 Worker 的部署周期完全解耦。如果你想要在单一平台部署，也可以稍后将其移植到 Workers 上，使用 Web 标准传输方式——src/tools/* 中的工具逻辑并不关心外层使用的是哪种 传输方式。

工具

全部 31 个工具要么通过 HTTPS 调用你现有的 Chakudya Worker，要么是在进程内进行纯计算／表格查找——没有任何工具会直接访问 Supabase、Cohere 或 Groq，也都不需要 ADMIN_API_KEY （它们使用的所有路由都是公开的）。

工具	使用的 Chakudya 路由
search_food	GET /foods → 失败时回退到 GET /foods/lookup
get_food_details	GET /foods/:id
calculate_nutrients	GET /foods 或 /foods/:id，然后在进程内按比例缩放每 100 克的数值
analyze_meal	同上，循环处理多个条目并汇总
barcode_lookup	GET /packaged?barcode= → 失败时回退到 GET /foods/lookup?barcode=
packaged_food_search	GET /packaged 和／或 GET /products
diabetes_exchange_lookup	GET /exchange
renal_exchange_lookup	GET /renal
enteral_formula_lookup	GET /formulas
nutrition_calculator	无——纯 BMI/BMR（Mifflin-St Jeor）/TDEE 计算
rag_retrieve	POST /rag/retrieve
search_guidelines	POST /rag/ask（context: "clinical"）
retrieve_evidence	POST /rag/ask（context: "both"，较高的 top_k）
disease_information	POST /rag/ask，查询内容设定为疾病教育概览
medicine_information	POST /rag/ask，明确要求排除剂量和处方建议
pediatric_fluid_requirements	无——纯 Holliday-Segar 计算
pediatric_energy_requirements	无——纯 Schofield/WHO BMR + DRI/FAO 2004 + DRI/IOM 2006 计算
pediatric_protein_requirements	无——纯 IOM 2005 / ASPEN 患病儿童 / 早产儿表格查找
pediatric_growth_velocity	无——纯 ASPEN 手册生长速度表格查找
pediatric_enteral_feed_advancement	无——纯肠内喂养方案表格查找
iom_dri_eer_calculator	无——纯 IOM/DRI（2002/2005）EER 预测方程计算，适用于所有生命阶段
met_activity_energy_calculator	无——纯 MET × 体重 × 时长计算
alcohol_kcal_calculator	无——纯体积 × 酒精度计算
respiratory_quotient_interpreter	无——纯 RQ 参考值解读
preterm_fluid_energy_requirements	无——纯早产儿液体／能量表格查找
macronutrient_distribution_check	无——纯 DRI 宏量营养素百分比范围表格查找
tee_activity_band_estimator	无——纯 REE × 活动等级乘数计算
fever_stress_ree_adjustment	无——纯发热时的 REE 调整计算
atwater_food_energy_calculator	无——纯 Atwater 系数（4/9/4/7）计算
dri_eer_reference_lookup	无——纯 DRI 表 2.2 参考表查找
who_growth_zscore	无——纯 WHO 生长参考 LMS z 分数／百分位计算（年龄别体重、年龄别身高、0-5 岁年龄别 BMI、5-19 岁年龄别 BMI、年龄别头围、身长别体重、身高别体重）

disease_information 和 medicine_information 总会在答案中附带教育用途免责声明，并且提示词要求避免使用诊断／处方用语——但它们仍是基于 RAG 知识库中现有内容生成的 LLM 文本，并非经验证的医学参考资料。请将它们视为学习者的起点，与其他由 RAG 支持的工具一样。

pediatric_* 工具（来源：BND 415 Clinical Nutrition — Paediatric Medicine Resources）以及 iom_dri_eer_calculator/met_activity_energy_calculator/alcohol_kcal_calculator/ respiratory_quotient_interpreter（来源：Nelms/Ireton-Jones，Nutrition Therapy and Pathophysiology， 第 2 章）都是纯计算／查找工具——不进行网络调用，也不依赖 CNR 数据。同样需要注意，这些结果仅为估算，不能替代个体化临床评估或实测间接量热法。

项目结构

src/
├── index.ts                 Express app, Streamable HTTP session wiring, graceful shutdown
├── config/env.ts            Zod-validated environment config, loaded once at startup
├── clients/chakudyaClient.ts  Fetch wrapper for the Chakudya Worker (GET/POST, error normalization)
├── server/
│   ├── createServer.ts      Builds one McpServer instance and registers all tool modules
│   └── security.ts          Bearer auth + per-IP rate limiting for this server's /mcp endpoint
├── tools/
│   ├── foodTools.ts
│   ├── clinicalTools.ts
│   ├── ragTools.ts
│   ├── educationTools.ts
│   ├── pediatricTools.ts        Pediatric fluid/energy/protein/growth/enteral-feed calculators
│   └── energyExpenditureTools.ts  IOM/DRI EER, MET activity, alcohol kcal, RQ interpreter
│   └── whoGrowthTools.ts        WHO Child Growth Standards z-score/percentile calculator (LMS)
├── data/
│   └── who/                     WHO Child Growth Standards LMS tables (JSON, per standard+sex)
└── utils/
    ├── logger.ts             Structured JSON logging
    └── toolResult.ts         Consistent success/error shaping for every tool handler

环境变量

将 .env.example 复制为 .env 并填写：

变量	必填	说明
CHAKUDYA_API_BASE_URL	否（默认使用维护者自己的 Worker）	如果你复刻此仓库来为自己的 CNR 实例提供前端服务，请将其设为自己的 Worker URL，而不要依赖默认值
CHAKUDYA_ADMIN_API_KEY	否	当前没有任何工具使用此变量；只有在之后添加受管理员权限控制的工具时才需要
PORT	否（默认值为 8787）
MCP_AUTH_TOKEN	生产环境中必填	MCP 客户端必须发送的 Bearer 令牌。生产环境中如果未设置此变量，服务将拒绝启动
MCP_ALLOWED_ORIGINS	否	以逗号分隔的 CORS 来源；留空则禁用浏览器访问
MCP_RATE_LIMIT_PER_MIN	否（默认值为 60）	此服务自身 /mcp 端点的每 IP 请求上限
NODE_ENV	否（默认值为 development）	部署时设为 production

安全注意事项

• 生产环境中必须启用身份验证。 如果 NODE_ENV=production 且未设置 MCP_AUTH_TOKEN，env.ts 会在启动时退出进程——这是有意设置的失败关闭检查，而不仅仅是警告。
• 此服务位于受速率限制的 RAG 路由前。 你的 Worker 上的 /rag/ask 每个 IP 每分钟最多允许 15 个请求——但这是按 Worker 所见的客户端 IP 计算的。部署后，该 IP 会是此服务的 IP，所有使用者将共用它。MCP 级别的速率限制器（MCP_RATE_LIMIT_PER_MIN）用于防止某个行为异常的 MCP 客户端悄悄耗尽其他所有客户端的请求额度。如果预计会有多个 MCP 客户端同时连接，请调低此值。
• 不内置或要求管理员密钥。 每个工具都会调用公开的 CNR 路由。如果之后添加受管理员权限控制的工具，请仅将 CHAKUDYA_ADMIN_API_KEY 保留在服务端——切勿将其暴露给 MCP 客户端。
• 会话状态保存在内存中，且按进程隔离。 对于单个实例，这没有问题。如果将来需要在负载均衡器后扩展到多个实例，请启用粘性会话（按 Mcp-Session-Id 路由），或将 src/index.ts 中的 transports 映射替换为共享存储。
• 默认禁用 CORS。 只有在使用特定的基于浏览器的 MCP 客户端时才启用 MCP_ALLOWED_ORIGINS；服务到服务的 MCP 客户端（Claude Desktop、Claude Code 等）不需要此设置。

本地运行

cd ~
git clone https://github.com/edisontaimu9-ui/chakudya-mcp-server.git
cd chakudya-mcp-server
cp .env.example .env
# edit .env: set MCP_AUTH_TOKEN to a long random string
npm install
npm run build
npm start

或者使用自动重新加载进行迭代开发：

npm run dev

健康检查：curl http://localhost:8787/health

连接 MCP 客户端

将支持 Streamable-HTTP 的 MCP 客户端指向：

POST/GET/DELETE  https://<your-deployed-host>/mcp
Header: Authorization: Bearer <MCP_AUTH_TOKEN>

对于 Claude Desktop / Claude Code，将其添加为远程 MCP 服务，指向该 URL 并使用相同的 Bearer 令牌。具体配置文件语法可能随时间发生变化，请查阅 Anthropic 的最新文档——访问 https://docs.claude.com 查看最新的 mcpServers 远程服务格式。

部署：Render（推荐——免费，无需信用卡）

此仓库包含 render.yaml，因此 Render 的 Blueprint 功能无需手动配置控制面板即可完成部署。

1. 将此仓库推送到 GitHub（命令见下文）。
2. 在 Render 控制面板中：选择 New → Blueprint，连接你的 GitHub 账户，然后选择 chakudya-mcp-server 仓库。Render 会自动读取 render.yaml。
3. Render 会使用 Free 计划创建服务，并自动生成随机的 MCP_AUTH_TOKEN（通过 generateValue: true）。首次部署后，前往服务的 Environment 选项卡，复制生成的令牌——你需要在 MCP 客户端配置中使用它。
4. 部署。你的 MCP 端点将为 https://<your-service-name>.onrender.com/mcp（请在 Render 控制面板中查看实际生成的 URL——如果你选择的名称已被占用，URL 可能会包含随机后缀）。

免费套餐的休眠问题及解决方法

Render 的免费 Web 服务在 15 分钟没有流量后会休眠，收到下一个请求时需要 30-60 秒才能唤醒。健康检查这样做没问题，但如果客户端在对话过程中长时间没有活动，可能会导致进行中的 MCP 会话中断（会话状态保存在内存中，参见 src/index.ts）。

解决方法：使用免费的运行时间监控服务，每隔 5-10 分钟 ping 一次 /health，让服务保持运行。

1. 在 uptimerobot.com 注册（免费套餐，无需银行卡）。
2. 添加新的 HTTP(s) 监控：
   • URL：https://<your-service>.onrender.com/health
   • 间隔：5 分钟
3. 保存。/health 按设计无需身份验证，专门用于让此监控无需使用你的 MCP_AUTH_TOKEN。

这样可以在免费套餐每月 750 小时的限额内，让服务全天候保持运行（以这种方式 ping 一个服务，远低于限额）。

代码更改后的更新

Render 会在每次推送到已连接的分支时自动重新部署——无需额外操作：

git add .
git commit -m "Update MCP server"
git push

在 Render 控制面板的 Events 选项卡中查看部署情况；这种规模的项目通常会在 1-2 分钟内完成。

其他部署选项

随处使用 Docker

docker build -t chakudya-mcp-server .
docker run -d -p 8787:8787 \
  -e NODE_ENV=production \
  -e MCP_AUTH_TOKEN=<long-random-string> \
  -e CHAKUDYA_API_BASE_URL=<your-chakudya-worker-url> \
  --name chakudya-mcp chakudya-mcp-server

使用进程管理器的普通 VPS

npm install --omit=dev
npm run build
npx pm2 start dist/index.js --name chakudya-mcp

如果前面还没有使用可处理 HTTPS 的服务，请将其置于 Nginx/Caddy 后方，以终止 TLS。

通过命令行更新

cd ~
# first time only:
git clone https://github.com/edisontaimu9-ui/chakudya-mcp-server.git
cd chakudya-mcp-server

# after any file update:
cp <path-to-updated-file>.ts src/<path>/<updated-file>.ts
git add .
git commit -m "Update MCP server"
git push

然后在你选择的平台上重新部署（如果已连接 GitHub 仓库，Render/Railway/Fly 会在推送时自动重新部署；否则，请手动触发重新部署，或在主机上重新运行上述 Docker/pm2 命令）。