Chakudya MCP Server

MCP（Model Context Protocol）サーバーで、Chakudya Nutrition Registry (CNR) API を一連の MCP ツールとして公開します。これにより、MCP 互換のクライアント（Claude、Claude Code、 その他の LLM エージェント）は、マラウイの食品データの検索、臨床栄養ルックアップ、RAG ナレッジベースのクエリを直接実行できます。

これは新しい独立したレイヤーです。Chakudya Worker を置き換えたり変更したりするものではありません。 既存の API の前面に配置される小さな Node/TypeScript HTTP サービスであり、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 のデプロイサイクルから完全に分離できます。後で Web 標準トランスポートに移植して Workers 上でシングルプラットフォーム展開をしたい場合は、それを妨げるものは何もありません。src/tools/* のツールロジックは、どのトランスポートがそれをラップするかに依存しないからです。

Related MCP server: mealie-mcp

ツール

31 個すべてのツールは、既存の Chakudya Worker を HTTPS 経由で呼び出すか、プロセス内の純粋な計算・テーブル ルックアップのいずれかです。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、 Ch. 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 にコピーして、以下を入力してください:

セキュリティ上の考慮事項

• 認証は本番環境では必須です。 env.tsは、NODE_ENV=productionかつMCP_AUTH_TOKENが未設定の場合、起動時にプロセスを終了します。これは単なる警告ではなく、意図的なフェイルクローズド（fail-closed）チェックです。

• このサーバーは、レート制限付きのRAGルートの前面に配置されます。 Workerの/rag/askはIPごとに毎分15リクエストに制限されていますが、これはWorkerから見たクライアントIPごとの制限であり、デプロイ後はこのサーバーのIPがそれに該当し、それを利用する全員で共有されます。MCPレベルのレートリミッター（MCP_RATE_LIMIT_PER_MIN）は、1つの問題のあるMCPクライアントが他の全員の分の予算を静かに使い果たすことを防ぐためにあります。複数の同時MCPクライアントを想定する場合は、この値を引き下げてください。

• 管理者キーは埋め込まれておらず、必要でもありません。 すべてのツールは公開CNRルートを呼び出します。後でadmin限定のツールを追加する場合は、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の場合は、そのURLを指すリモートMCPサーバーとして、同じBearerトークンを使用して追加してください。正確な設定ファイルの構文は時間とともに変更されているため、Anthropicの現在のドキュメントを参照してください。最新のmcpServersリモートサーバー形式についてはhttps://docs.claude.comを確認してください。

デプロイ: 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になります（実際に生成されたURLはRenderダッシュボードで確認してください。選択した名前が既に使用されている場合、ランダムなサフィックスが含まれることがあります）。

無料プランのスリープ問題とその対処法

Renderの無料Webサービスは、トラフィックがない状態が15分続くとスピンダウンし、次のリクエストで復帰するまでに30〜60秒かかります。ヘルスチェックには問題ありませんが、クライアントが会話の途中で長時間静かになると、進行中のMCPセッションが切断される可能性があります（セッション状態はメモリ上に保持されます — src/index.tsを参照）。

対処法: 無料のアップタイムモニターで5〜10分ごとに/healthへpingを送信し、サービスをウォーム状態に保ちます。

1. uptimerobot.comでサインアップします（無料プラン、カード不要）。

2. 新しい**HTTP(s)**モニターを追加します:

   • URL: https://<your-service>.onrender.com/health

   • 間隔: 5分

3. 保存します。/healthは設計上認証不要であり、このモニターがMCP_AUTH_TOKENを必要としないようになっています。

これにより、サービスは無料プランの月750時間の範囲内で24時間365日ウォーム状態を維持できます（この方法でpingされる1つのサービスでは、上限を大きく下回ります）。

コード変更後の更新

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を処理する何かで前面を保護していない場合は、TLS終端のためにNginx/Caddyの背後に配置してください。

コマンドラインでの更新

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コマンドをホスト上で再実行してください）。