Chakudya MCP Server

Ein MCP (Model Context Protocol) Server, der die API der Chakudya Nutrition Registry (CNR) als eine Reihe von MCP-Tools bereitstellt, sodass jeder MCP-kompatible Client (Claude, Claude Code, andere LLM-Agenten) direkt malawische Lebensmitteldaten durchsuchen, klinische Ernährungs-Lookups ausführen und die RAG-Wissensdatenbank abfragen kann.

Dies ist eine neue, separate Schicht. Sie ersetzt oder modifiziert den Chakudya Worker nicht. Es ist ein kleiner Node/TypeScript-HTTP-Dienst, der vor deiner bestehenden API sitzt und MCP-Tool-Aufrufe in einfache HTTP-Anfragen an die Routen übersetzt, die dein Worker bereits bedient.

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

Warum ein separater Server und kein Worker

Der offizielle StreamableHTTPServerTransport des MCP TypeScript SDK ist für die http.IncomingMessage/ServerResponse von Node gebaut. Cloudflare Workers nutzen stattdessen die Fetch API, und die Web-Standard-Variante des SDK (WebStandardStreamableHTTPServerTransport) ist neuer und für das Sitzungsmanagement in der Produktion weniger ausgereift. Dies als einfachen Node-Dienst zu betreiben (Docker, Render, Fly.io, eine VPS usw.) ist heute der üblichere, besser dokumentierte Weg, und es hält dieses Anliegen vollständig vom Deploy-Zyklus deines Workers entkoppelt. Nichts hindert dich daran, es später auf den Web-Standard-Transport auf Workers zu portieren, wenn du ein Deployment auf einer einzigen Plattform möchtest — die Tool-Logik in src/tools/* kümmert sich nicht darum, welcher Transport sie umhüllt.

Related MCP server: mealie-mcp

Tools

Alle 31 Tools rufen entweder deinen bestehenden Chakudya Worker per HTTPS auf oder sind reine In-Process-Berechnungs-/Tabellen-Lookups — keines davon greift direkt auf Supabase, Cohere oder Groq zu, und keines benötigt ADMIN_API_KEY (jede verwendete Route ist öffentlich).

disease_information und medicine_information geben neben der Antwort immer einen edukativen Haftungsausschluss zurück und sind per Prompt angewiesen, Diagnose-/Verschreibungssprache zu vermeiden — aber es handelt sich weiterhin um LLM-generierten Text, der auf dem basiert, was in deiner RAG-Wissensdatenbank steht, nicht um eine verifizierte medizinische Referenz. Behandle sie als Ausgangspunkt für Lernende, genau wie die übrigen RAG-gestützten Tools.

Die pediatric_*-Tools (Quelle: BND 415 Clinical Nutrition — Paediatric Medicine Resources) und iom_dri_eer_calculator/met_activity_energy_calculator/alcohol_kcal_calculator/respiratory_quotient_interpreter (Quelle: Nelms/Ireton-Jones, Nutrition Therapy and Pathophysiology, Kap. 2) sind reine Berechnungs-/Lookup-Tools — kein Netzwerkaufruf, keine CNR-Datenabhängigkeit. Es gilt weiterhin der Vorbehalt, dass es sich nur um Schätzungen handelt: kein Ersatz für eine individuelle klinische Beurteilung oder gemessene indirekte Kalorimetrie.

Projektstruktur

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

Umgebungsvariablen

Kopiere .env.example zu .env und fülle die Datei aus:

Sicherheitsaspekte

• Authentifizierung ist in Produktion Pflicht. env.ts beendet den Prozess beim Start, wenn NODE_ENV=production gesetzt ist und MCP_AUTH_TOKEN fehlt – eine bewusste Fail-Closed-Prüfung, keine bloße Warnung.

• Dieser Server ist deinen rate-limitierten RAG-Routen vorgeschaltet. /rag/ask auf deinem Worker ist auf 15 req/min pro IP begrenzt – aber diese Begrenzung gilt pro Client-IP, wie sie der Worker sieht, und das wäre nach dem Deployment die IP dieses Servers, die sich alle Nutzer teilen. Der Rate-Limiter auf MCP-Ebene (MCP_RATE_LIMIT_PER_MIN) existiert, damit ein einzelner MCP-Client mit Fehlverhalten dieses Budget nicht lautlos für alle anderen aufbrauchen kann. Setze ihn niedriger an, wenn du mit mehreren gleichzeitigen MCP-Clients rechnest.

• Es ist kein Admin-Schlüssel eingebettet und keiner erforderlich. Jedes Tool ruft eine öffentliche CNR-Route auf. Wenn du später ein Tool hinzufügst, das nur Administratoren verwenden dürfen, behalte CHAKUDYA_ADMIN_API_KEY ausschließlich serverseitig – gib ihn niemals an den MCP-Client weiter.

• Der Sitzungszustand liegt im Speicher, pro Prozess. Das ist für eine einzelne Instanz in Ordnung. Wenn du jemals hinter einem Load-Balancer auf mehrere Instanzen skalierst, aktiviere entweder Sticky Sessions (Routing über Mcp-Session-Id) oder tausche die transports-Map in src/index.ts gegen einen gemeinsamen Store aus.

• CORS ist standardmäßig deaktiviert. Aktiviere MCP_ALLOWED_ORIGINS nur, wenn du einen konkreten browserbasierten MCP-Client hast; Server-zu-Server-MCP-Clients (Claude Desktop, Claude Code usw.) benötigen es nicht.

Lokal ausführen

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

Oder für iterative Entwicklung mit automatischem Neuladen:

npm run dev

Health-Check: curl http://localhost:8787/health

Verbinden eines MCP-Clients

Richte einen beliebigen Streamable-HTTP-fähigen MCP-Client auf Folgendes aus:

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

Für Claude Desktop / Claude Code fügst du ihn als Remote-MCP-Server hinzu, der auf diese URL mit demselben Bearer-Token zeigt. Die genaue Syntax der Konfigurationsdatei findest du in der aktuellen Dokumentation von Anthropic, da sich diese im Laufe der Zeit geändert hat – prüfe unter https://docs.claude.com das aktuelle mcpServers-Format für Remote-Server.

Deployment: Render (empfohlen – kostenlos, keine Kreditkarte)

Dieses Repo enthält render.yaml, sodass die Blueprint-Funktion von Render das Deployment ohne manuelle Dashboard-Konfiguration übernimmt.

1. Pushe dieses Repo auf GitHub (Befehle unten).

2. Verbinde im Render-Dashboard unter New → Blueprint dein GitHub-Konto und wähle das Repo chakudya-mcp-server aus. Render liest render.yaml automatisch.

3. Render stellt den Dienst im Free-Tarif bereit und generiert automatisch ein zufälliges MCP_AUTH_TOKEN (über generateValue: true). Gehe nach dem ersten Deployment zum Tab Environment des Dienstes, um das generierte Token zu kopieren – du brauchst es in deiner MCP-Client-Konfiguration.

4. Führe das Deployment aus. Dein MCP-Endpunkt wird https://<your-service-name>.onrender.com/mcp sein (prüfe im Render-Dashboard die tatsächlich generierte URL – sie kann ein zufälliges Suffix enthalten, wenn dein gewählter Name bereits vergeben ist).

Das Sleep-Problem im Free-Tarif und die Lösung

Die kostenlosen Webdienste von Render werden nach 15 Minuten ohne Datenverkehr heruntergefahren und benötigen dann 30–60 Sekunden, um beim nächsten Request wieder aufzuwachen. Das ist für einen Health-Check in Ordnung, kann aber eine laufende MCP-Sitzung beenden (der Sitzungszustand liegt im Speicher – siehe src/index.ts), wenn der Client mitten in einer Unterhaltung zu lange schweigt.

Lösung: Halte den Dienst mit einem kostenlosen Uptime-Monitor warm, der /health alle 5–10 Minuten anpingt.

1. Melde dich bei uptimerobot.com an (kostenloser Tarif, keine Kreditkarte).

2. Füge einen neuen HTTP(s)-Monitor hinzu:

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

   • Intervall: 5 Minuten

3. Speichern. /health ist bewusst ohne Authentifizierung erreichbar, genau damit dieser Monitor dein MCP_AUTH_TOKEN nicht benötigt.

Dadurch bleibt der Dienst im Rahmen der 750 Stunden/Monat des kostenlosen Tarifs rund um die Uhr warm (deutlich unter dem Limit für einen auf diese Weise angepingten Dienst).

Aktualisieren nach einer Codeänderung

Render deployt bei jedem Push in deinen verbundenen Branch automatisch neu – kein zusätzlicher Schritt nötig:

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

Beobachte das Deployment im Tab Events des Render-Dashboards; bei einem Projekt dieser Größe ist es in der Regel nach 1–2 Minuten abgeschlossen.

Weitere Deployment-Optionen

Docker überall

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

Einfacher VPS mit Prozessmanager

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

Platziere den Dienst hinter Nginx/Caddy für die TLS-Terminierung, falls du nicht bereits etwas vorgeschaltet hast, das HTTPS übernimmt.

Aktualisieren über die Befehlszeile

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

Deploye anschließend auf der Plattform deiner Wahl neu (Render/Railway/Fly deployen bei Push automatisch neu, wenn du das GitHub-Repo verbunden hast; andernfalls stoße ein manuelles Deployment an oder führe die Docker/pm2-Befehle von oben auf deinem Host erneut aus).