chakudya-mcp-server

Chakudya MCP サーバー

MCP（Model Context Protocol）サーバーです。Chakudya Nutrition Registry（CNR） API を MCP ツールのセットとして公開するため、MCP 互換クライアント（Claude、Claude Code、その他の LLM エージェント）から、マラウイの食品データの検索、臨床栄養の照会、RAG ナレッジベースへの直接問い合わせを行えます。

**これは新たに追加する独立したレイヤーであり、Chakudya Worker を置き換えたり変更したりするものではありません。**既存の API の前段で動作し、MCP ツールの呼び出しを、Worker がすでに提供しているルートへの通常の HTTP リクエストに変換する、小規模な Node/TypeScript 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/* のツールロジックは、どのトランスポートでラップされているかに依存しません。

ツール

31 個のツールはすべて、既存の Chakudya Worker を HTTPS 経由で呼び出すか、プロセス内で計算やテーブル参照のみを行います。いずれも 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 g あたりの値をスケーリング
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 Table 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 に設定します

セキュリティに関する考慮事項

• 本番環境では認証が必須です。 env.ts は、NODE_ENV=production で MCP_AUTH_TOKEN が未設定の場合、起動時にプロセスを終了します。これは警告にとどまらず、意図的にフェイルクローズするチェックです。
• このサーバーは、レート制限のある RAG ルートの前段に配置されます。 Worker の /rag/ask には IP ごとに 15 req/min の上限があります。ただし、これは Worker から見た クライアント の 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 クライアントを、次の URL に接続します。

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

Claude Desktop／Claude Code では、この URL と同じ Bearer トークンを使用するリモート MCP サーバーとして追加します。正確な設定ファイルの構文は時間とともに変更されているため、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 は、接続済みのブランチへの push ごとに自動で再デプロイするため、追加の手順は不要です。

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 は push 時に自動で再デプロイします。接続していない場合は、手動で再デプロイするか、ホスト上で上記の Docker/pm2 コマンドを再実行してください）。