Chakudya MCP Server

一个 MCP（模型上下文协议）服务器，将 Chakudya Nutrition Registry (CNR) API 暴露为一组 MCP 工具，使任何兼容 MCP 的客户端（Claude、Claude Code、其他 LLM 代理）都能直接搜索马拉维食品数据、执行临床营养查询，并查询 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/* 中的工具逻辑并不关心由哪种传输层包装它。

Related MCP server: mealie-mcp

工具

全部 31 个工具要么通过 HTTPS 调用您现有的 Chakudya Worker，要么是纯进程内计算/表查询——它们都不直接接触 Supabase、Cohere 或 Groq，也都不需要 ADMIN_API_KEY（它们使用的每条路由都是公开的）。

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 并填写：

安全注意事项

• 认证在生产环境中是强制性的。 如果 NODE_ENV=production 且 MCP_AUTH_TOKEN 未设置，env.ts 会在启动时退出进程——这是有意为之的故障关闭（fail-closed）检查，而不只是警告。

• 此服务器位于你受速率限制的 RAG 路由之前。 你 Worker 上的 /rag/ask 限制为每 IP 15 req/min——但那是按 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 map 替换为共享存储。

• 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，将其添加为指向该 URL 的远程 MCP 服务器，并使用相同的 bearer token。有关确切的配置文件语法，请查阅 Anthropic 当前的文档，因为该语法随时间变化——请查看 https://docs.claude.com 了解最新的 mcpServers 远程服务器格式。

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

此仓库包含 render.yaml，因此 Render 的 Blueprint 功能无需任何手动仪表盘配置即可部署它。

1. 将此仓库推送到 GitHub（命令如下）。

2. 在 Render 仪表盘中：新建 → Blueprint，连接你的 GitHub 账户，选择 chakudya-mcp-server 仓库。Render 会自动读取 render.yaml。

3. Render 会按照 Free（免费）计划配置该服务，并自动生成随机的 MCP_AUTH_TOKEN（通过 generateValue: true）。首次部署后，请转到服务的 Environment 选项卡以复制生成的 token——你的 MCP 客户端配置中会需要它。

4. 部署。你的 MCP 端点将是 https://<your-service-name>.onrender.com/mcp（查看 Render 仪表盘以获取实际生成的 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 小时的限额内 24/7 保持活跃（对于以这种方式 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 命令）。