Chakudya MCP Server

Un servidor MCP (Model Context Protocol) que expone la API de Chakudya Nutrition Registry (CNR) como un conjunto de herramientas MCP, de modo que cualquier cliente compatible con MCP (Claude, Claude Code, otros agentes LLM) pueda buscar datos de alimentos de Malaui, realizar consultas de nutrición clínica y consultar la base de conocimiento RAG directamente.

Esta es una capa nueva y separada. No reemplaza ni modifica el Chakudya Worker. Es un pequeño servicio HTTP de Node/TypeScript que se sitúa delante de tu API existente y traduce las llamadas a herramientas MCP en solicitudes HTTP simples contra las rutas que tu Worker ya sirve.

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

Por qué un servidor separado, no un Worker

El StreamableHTTPServerTransport del SDK oficial de MCP TypeScript está construido para http.IncomingMessage/ServerResponse de Node. Cloudflare Workers usa la Fetch API en su lugar, y la variante estándar web del SDK (WebStandardStreamableHTTPServerTransport) es más nueva y menos probada en batalla para la gestión de sesiones en producción. Ejecutar esto como un servicio Node simple (Docker, Render, Fly.io, un VPS, etc.) es la ruta más estándar y mejor documentada hoy en día, y mantiene esta preocupación completamente desacoplada del ciclo de despliegue de tu Worker. Nada te impide portarlo al transporte estándar web en Workers más adelante si quieres un despliegue de plataforma única: la lógica de herramientas en src/tools/* no le importa qué transporte lo envuelve.

Related MCP server: mealie-mcp

Herramientas

Las 31 herramientas o bien llaman a tu Chakudya Worker existente a través de HTTPS, o son cálculos puros en proceso / búsquedas en tablas: ninguna de ellas toca Supabase, Cohere o Groq directamente, y ninguna necesita ADMIN_API_KEY (todas las rutas que usan son públicas).

disease_information y medicine_information siempre devuelven un descargo de responsabilidad educativo junto con la respuesta y están programadas para evitar lenguaje de diagnóstico/prescripción, pero siguen siendo texto generado por LLM basado en lo que haya en tu base de conocimiento RAG, no una referencia médica verificada. Trátalas como un punto de partida para un aprendiz, igual que el resto de las herramientas respaldadas por RAG.

Las herramientas pediatric_* (fuente: BND 415 Clinical Nutrition — Paediatric Medicine Resources) y iom_dri_eer_calculator/met_activity_energy_calculator/alcohol_kcal_calculator/respiratory_quotient_interpreter (fuente: Nelms/Ireton-Jones, Nutrition Therapy and Pathophysiology, cap. 2) son herramientas puras de cálculo/consulta: sin llamada de red, sin dependencia de datos CNR. Se aplica la misma advertencia de solo estimación: no sustituyen una evaluación clínica individualizada ni una calorimetría indirecta medida.

Estructura del proyecto

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

Variables de entorno

Copia .env.example a .env y complétalo:

Consideraciones de seguridad

• La autenticación es obligatoria en producción. env.ts termina el proceso al arrancar si NODE_ENV=production y MCP_AUTH_TOKEN no está definida; esto es una comprobación deliberada de fallo cerrado, no solo una advertencia.

• Este servidor se sitúa delante de tus rutas RAG con límite de velocidad. /rag/ask en tu Worker tiene un tope de 15 req/min por IP, pero eso es por IP de cliente tal como la ve el Worker, que una vez desplegado sería la IP de este servidor, compartida por todos los que lo usen. El limitador de velocidad a nivel de MCP (MCP_RATE_LIMIT_PER_MIN) existe para que un cliente MCP con mal comportamiento no pueda agotar silenciosamente ese presupuesto para los demás. Redúcelo si esperas varios clientes MCP concurrentes.

• No se incrusta ni se requiere ninguna clave de administrador. Cada herramienta llama a una ruta CNR pública. Si más adelante añades una herramienta con acceso restringido a administradores, mantén CHAKUDYA_ADMIN_API_KEY solo en el lado del servidor; nunca la expongas al cliente MCP.

• El estado de sesión está en memoria, por proceso. Perfecto para una instancia única. Si alguna vez escalas a varias instancias detrás de un balanceador de carga, habilita sesiones persistentes (enrutando por Mcp-Session-Id) o cambia el mapa transports en src/index.ts por un almacén compartido.

• CORS está desactivado por defecto. Activa MCP_ALLOWED_ORIGINS solo si tienes un cliente MCP específico basado en navegador; los clientes MCP de servidor a servidor (Claude Desktop, Claude Code, etc.) no lo necesitan.

Ejecutar localmente

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

O para desarrollo iterativo con recarga automática:

npm run dev

Comprobación de estado: curl http://localhost:8787/health

Conexión de un cliente MCP

Apunta cualquier cliente MCP compatible con Streamable-HTTP a:

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

Para Claude Desktop / Claude Code, añádelo como un servidor MCP remoto que apunte a esa URL con el mismo bearer token. Consulta la documentación actual de Anthropic para conocer la sintaxis exacta del archivo de configuración, ya que ha cambiado con el tiempo; comprueba https://docs.claude.com para ver el formato más reciente de servidor remoto mcpServers.

Despliegue: Render (recomendado — gratis, sin tarjeta de crédito)

Este repositorio incluye render.yaml, por lo que la función Blueprint de Render lo despliega sin necesidad de configuración manual en el panel.

1. Sube este repositorio a GitHub (comandos más abajo).

2. En el panel de Render: Nuevo → Blueprint, conecta tu cuenta de GitHub y elige el repositorio chakudya-mcp-server. Render lee render.yaml automáticamente.

3. Render aprovisiona el servicio en el plan Free y genera automáticamente un MCP_AUTH_TOKEN aleatorio (mediante generateValue: true). Tras el primer despliegue, ve a la pestaña Environment del servicio para copiar ese token generado; lo necesitarás en la configuración de tu cliente MCP.

4. Despliega. Tu endpoint MCP será https://<your-service-name>.onrender.com/mcp (consulta el panel de Render para ver tu URL generada real; puede incluir un sufijo aleatorio si el nombre que hayas elegido ya está ocupado).

El problema de la suspensión del plan gratuito y su solución

Los servicios web gratuitos de Render se suspenden tras 15 minutos sin tráfico y luego tardan entre 30 y 60 segundos en reactivarse con la siguiente solicitud. Eso está bien para una comprobación de estado, pero puede interrumpir una sesión MCP en curso (el estado de sesión vive en memoria; ver src/index.ts) si el cliente permanece en silencio a mitad de una conversación durante demasiado tiempo.

Solución: mantenlo activo con un monitor de disponibilidad gratuito que haga ping a /health cada 5-10 minutos.

1. Regístrate en uptimerobot.com (plan gratuito, sin tarjeta).

2. Añade un nuevo monitor HTTP(s):

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

   • Intervalo: 5 minutos

3. Guarda. /health no requiere autenticación por diseño, precisamente para que este monitor no necesite tu MCP_AUTH_TOKEN.

Esto mantiene el servicio activo 24/7 dentro de las 750 h/mes del plan gratuito (muy por debajo del límite para un servicio al que se le hace ping de esta manera).

Actualización tras un cambio de código

Render vuelve a desplegar automáticamente en cada push a tu rama conectada; no se necesita ningún paso adicional:

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

Observa el despliegue en la pestaña Events del panel de Render; normalmente tarda entre 1 y 2 minutos en un proyecto de este tamaño.

Otras opciones de despliegue

Docker en cualquier lugar

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 básico con un gestor de procesos

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

Ponlo detrás de Nginx/Caddy para la terminación TLS si no tienes ya algo delante que gestione HTTPS.

Actualización mediante la línea de comandos

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

Después, vuelve a desplegarlo en la plataforma que hayas elegido (Render/Railway/Fly se redespliegan automáticamente al hacer push si has conectado el repositorio de GitHub; si no, activa un redespliegue manual o vuelve a ejecutar los comandos de Docker/pm2 anteriores en tu host).