habitica-mcp

Un servidor MCP para una instancia de Habitica autoalojada, servido a través de HTTP Streamable para que pueda ejecutarse como un servicio de red normal en lugar de un subproceso stdio por cliente.

Por qué existe

El servidor comunitario existente (iBreaker/habitica-mcp-server) fija https://habitica.com/api/v3, es solo stdio y no ha recibido mantenimiento desde tres días después de su creación. Nada de eso funciona para una instancia autoalojada detrás de un ingress.

Aquí, HABITICA_BASE_URL es obligatorio sin valor predeterminado — apuntar a la instancia equivocada se hace imposible en lugar de simplemente desaconsejarse.

Related MCP server: habitca-mcp

Herramientas

Configuración

Endpoints: POST/GET/DELETE /mcp, y GET /healthz.

Notas de diseño

Cuatro decisiones que son críticas y no obvias:

Proyección de respuesta, no paginación. El GET /tasks/user de Habitica devuelve history: [{date, value}] en cada hábito y tarea diaria — una entrada por evento de puntuación durante toda la vida de la cuenta, y está activado por defecto. La API no ofrece límite/desplazamiento, así que la solución es la proyección: este servidor siempre envía history=false y además proyecta cada tarea a un conjunto fijo de campos, de modo que un cambio en el esquema ascendente no pueda reintroducir silenciosamente cientos de KB en el contexto de un modelo. get_user_stats usa ?userFields= por la misma razón.

El filtro de lista es plural e irregular. GET /tasks/user?type= acepta habits | dailys | todos | rewards | completedTodos (nótese dailys), mientras que el cuerpo de creación toma el singular habit | daily | todo | reward. Las herramientas exponen la forma singular y la mapean internamente; pasar la forma singular al endpoint de lista devuelve 400.

La validación de host está limitada a /mcp, nunca a toda la aplicación. createMcpExpressApp la aplica globalmente, lo que rompería tanto las sondas de kubelet (una sonda httpGet envía Host: <podIP>, y las IPs de los pods no pueden estar en la lista de permitidos) como la monitorización blackbox (que envía Host: <svc>.<ns>.svc). Por lo tanto, /healthz queda fuera de la protección; no expone nada, y la protección contra el rebinding de DNS solo importa para la superficie JSON-RPC.

/healthz informa solo de la vivacidad del proceso — nunca de la accesibilidad de Habitica. Una comprobación de conectividad convertiría un reinicio de Habitica en un CrashLoopBackOff aquí, y la sonda de vivacidad seguiría matando un proceso que está perfectamente sano y simplemente no tiene con quién hablar. Las caídas de Habitica se manifiestan como errores JSON-RPC limpios por herramienta.

Transporte

Streamable HTTP sin estado (sessionIdGenerator: undefined), construido sobre @modelcontextprotocol/server v2 — la versión estable actual, cuyo transporte HTTP vive en los adaptadores separados @modelcontextprotocol/express / @modelcontextprotocol/node. La versión de protocolo negociada es 2025-11-25 (LATEST_PROTOCOL_VERSION en el SDK); v1.x es ahora solo de seguridad y corrección de errores.

Se crea un McpServer + transporte nuevo por petición, y se destruye en el evento close de la respuesta. La construcción por petición es necesaria, no una cuestión de orden: el SDK v1 lanza un error directo al reutilizar el transporte sin estado ("Stateless transport cannot be reused across requests"), porque la reutilización causa colisiones de ID de mensaje entre clientes concurrentes.

El coste es real y conviene conocerlo: cada petición reconstruye 11 conversiones zod→JSON-Schema, que se midieron en aproximadamente 0,5 MB de basura por llamada. Se recupera bajo presión del GC (1500 llamadas secuenciales se estabilizaron en ~193 MiB con un límite de heap de 96 MB) en lugar de filtrarse, pero es por lo que el despliegue solicita más memoria de la que sugiere la huella en reposo.

GET /mcp devuelve 405 con Allow: POST. Esto es legal según la especificación (un servidor puede rechazar el stream independiente) y es exactamente lo que el cliente MCP espera — trata el 405 como "no hay stream de servidor aquí" y se detiene.

Una versión anterior intentaba ser complaciente devolviendo un stream SSE vacío. Eso causaba un bucle de reconexión infinito: el cliente trata un stream que termina limpiamente sin llevar respuesta como una conexión caída y lo reprograma, pero su contador de reintentos solo avanza en fallo, así que un stream vacío exitoso no reiniciaba nada. Se midió a ~1 req/s para siempre — 1 → 4 → 8 → 12 GETs en 12s de inactividad, aproximadamente 86k peticiones/día por cliente conectado, sin que apareciera ningún error. Devolver 405 lo mantiene en exactamente 1.

El estado sin estado tiene un coste real, no solo ventajas: los viajes de ida y vuelta servidor→cliente (sampling, elicitation) y las notificaciones no solicitadas *ListChanged no pueden funcionar, porque la respuesta del cliente llega como una nueva petición HTTP que aterriza en una instancia de servidor nueva sin memoria de la llamada pendiente. Las notificaciones de progreso sí funcionan — viajan en el propio stream de la petición original. Nada de eso importa para una superficie de herramientas CRUD, pero no construyas sobre esas capacidades aquí.

Seguridad

El endpoint /mcp es no autenticado. La credencial de Habitica vive en el lado del servidor, así que cualquiera que pueda alcanzar el endpoint puede leer y escribir toda la lista de tareas de la cuenta. Esto es deliberado — un proxy de autenticación delante de un endpoint MCP rompe los clientes MCP — y es por lo que el despliegue está restringido a una red privada y una sola réplica.

El token de API es una credencial de Habitica a nivel de usuario (almacenada en texto plano por la propia Habitica), así que filtrarlo es un compromiso total de la cuenta. Todo el registro de salida pasa por un logger que redacta, con una prueba que verifica que el token nunca aparece en ninguna línea emitida.

Desarrollo

npm ci
npm test
npm run lint && npm run typecheck
npm run build && node dist/index.js

Licencia

MIT