Chakudya MCP Server
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: MCP Task Assistant
工具
全部 31 个工具要么通过 HTTPS 调用您现有的 Chakudya Worker,要么是纯进程内计算/表查询——它们都不直接接触 Supabase、Cohere 或 Groq,也都不需要 ADMIN_API_KEY(它们使用的每条路由都是公开的)。
工具 | 使用的 Chakudya 路由 |
|
|
|
|
|
|
| 同上,在多个项目间循环并求和 |
|
|
|
|
|
|
|
|
|
|
| 无 — 纯 BMI/BMR(Mifflin-St Jeor)/TDEE 计算 |
|
|
|
|
|
|
|
|
|
|
| 无 — 纯 Holliday-Segar 计算 |
| 无 — 纯 Schofield/WHO BMR + DRI/FAO 2004 + DRI/IOM 2006 计算 |
| 无 — 纯 IOM 2005 / ASPEN 患病儿童 / 早产儿表查询 |
| 无 — 纯 ASPEN 手册生长速度表查询 |
| 无 — 纯肠内喂养方案表查询 |
| 无 — 纯 IOM/DRI(2002/2005)EER 预测方程计算,涵盖所有生命阶段 |
| 无 — 纯 MET × 体重 × 时长计算 |
| 无 — 纯体积 × 酒精度计算 |
| 无 — 纯 RQ 参考值解读 |
| 无 — 纯早产儿液体/能量表查询 |
| 无 — 纯 DRI 宏量营养素百分比范围表查询 |
| 无 — 纯 REE × 活动带乘数计算 |
| 无 — 纯发热 REE 调整计算 |
| 无 — 纯 Atwater 系数(4/9/4/7)计算 |
| 无 — 纯 DRI 表 2.2 参考表查询 |
| 无 — 纯 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 并填写:
变量 | 必填 | 说明 |
| 否(默认使用维护者自己的 Worker) | 如果你 fork 此仓库来代理你自己的 CNR 实例,请将其设置为你自己的 Worker URL,而不是依赖默认值 |
| 否 | 当前没有任何工具使用;仅在你之后添加需要管理员权限的工具时才需要 |
| 否(默认 | |
| 生产环境中必填 | MCP 客户端必须发送的 Bearer token。没有它,服务器在生产环境中拒绝启动 |
| 否 | 逗号分隔的 CORS 来源;留空以禁用浏览器访问 |
| 否(默认 | 此服务器自身 |
| 否(默认 | 部署时设置为 |
安全注意事项
认证在生产环境中是强制性的。 如果
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中的transportsmap 替换为共享存储。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 功能无需任何手动仪表盘配置即可部署它。
将此仓库推送到 GitHub(命令如下)。
在 Render 仪表盘中:新建 → Blueprint,连接你的 GitHub 账户,选择
chakudya-mcp-server仓库。Render 会自动读取render.yaml。Render 会按照 Free(免费)计划配置该服务,并自动生成随机的
MCP_AUTH_TOKEN(通过generateValue: true)。首次部署后,请转到服务的 Environment 选项卡以复制生成的 token——你的 MCP 客户端配置中会需要它。部署。你的 MCP 端点将是
https://<your-service-name>.onrender.com/mcp(查看 Render 仪表盘以获取实际生成的 URL——如果你选择的名称已被占用,它可能包含随机后缀)。
免费套餐的休眠问题及解决方案
Render 的免费 Web 服务在 15 分钟没有流量后会休眠,然后在下一个请求到来时需要 30-60 秒才能唤醒。这对健康检查来说没问题,但如果客户端在对话中途静默太久,它可能会丢弃正在进行中的 MCP 会话(会话状态保存在内存中——参见 src/index.ts)。
解决方案:使用免费的在线状态监控器每 5-10 分钟 ping 一次 /health,让它保持活跃。
在 uptimerobot.com 注册(免费计划,无需信用卡)。
添加一个新的 HTTP(s) 监控器:
URL:
https://<your-service>.onrender.com/health间隔:5 分钟
保存。
/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 命令)。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Read-only MCP tools for AI agent discovery, structured resources, and NIULAI information.
A registry of AI agent tools — MCP servers, APIs, CLIs, SDKs — kept current by automated ingestion.
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes retrieval capabilities of two RAG systems as authenticated MCP tools, allowing any MCP client to perform graph-augmented and hybrid retrieval with JWT auth.1-
- FlicenseNot gradedqualityDmaintenanceExposes task management (add, list, complete tasks) and document search (RAG) as MCP tools for AI agents.-
- FlicenseNot gradedqualityDmaintenanceExposes an existing RAG API as MCP tools, enabling health checks and document-based question answering with source evidence.-
- FlicenseAqualityDmaintenanceMCP bridge to a multimodal RAG service, enabling hybrid search and Q&A over documents with tools for knowledge base queries and health checks.4-