Sobre el proyecto

Guava Health MCP es un servidor FastMCP de código abierto que envuelve la API para desarrolladores de Guava Health y la pone a disposición de hosts MCP como Cursor, Claude y ChatGPT. Hay una instancia alojada disponible en https://guavahealth.fastmcp.app/mcp, y el proyecto tiene licencia MIT. No está afiliado a Guava Health, Inc. El servidor es de solo lectura por diseño y no persiste cargas útiles de salud; actúa como proxy de lecturas en vivo de la API de Guava después de que el usuario autoriza el acceso. La versión 0.1 expone siete herramientas: guava_auth_status (si Guava está conectado para el usuario actual de MCP), guava_begin_connect (inicia Guava OAuth con PAR y PKCE y devuelve una authorization_url), guava_disconnect (elimina los tokens almacenados de ese usuario), guava_get_me (perfil/sujeto), guava_search_sleep (sesiones de sueño), guava_search_activities (entrenamientos y actividades) y guava_search_metrics (métricas filtradas por tipos, como steps o vo2_max). Las escrituras quedan explícitamente fuera del alcance de esta versión. La arquitectura utiliza dos capas OAuth. La autenticación del cliente MCP se ejecuta a través de una GitHub OAuth App para que los hosts puedan conectarse de forma segura y se admita a varios usuarios. El lado de la API de Guava Health utiliza una aplicación confidencial de la API de Guava con PAR, PKCE (S256) y rotación de tokens de actualización. El flujo documentado es: el host MCP se autentica mediante GitHub OAuth en guavahealth.fastmcp.app, que luego se comunica con api.guavahealth.com a través de Guava OAuth 2.1. La configuración requiere registrar una aplicación de la API de Guava en el portal de la API de Guava con el URI de redireccionamiento exacto https://guavahealth.fastmcp.app/oauth/callback, habilitar el acceso en segundo plano de larga duración y los ámbitos de lectura necesarios, y luego proporcionar GUAVA_CLIENT_ID y GUAVA_CLIENT_SECRET. También se necesita una GitHub OAuth App, con la página de inicio https://guavahealth.fastmcp.app y la devolución de llamada https://guavahealth.fastmcp.app/auth/callback, proporcionando GITHUB_CLIENT_ID y GITHUB_CLIENT_SECRET. Las variables de entorno incluyen PUBLIC_BASE_URL, GUAVA_ENV (test o live), una anulación opcional GUAVA_API_BASE, GUAVA_TOKEN_ENCRYPTION_KEY (una clave Fernet para el blob de tokens en reposo), un MCP_AUTH_TOKEN opcional como token bearer compartido para automatización y un FASTMCP_JWT_SIGNING_KEY opcional. El README muestra cómo generar una clave Fernet con el paquete cryptography. Las notas de implementación mencionan un punto de entrada de Horizon en main.py (o main.py:mcp) y la URL de MCP. Para uso local, el proyecto utiliza uv: uv sync y luego uv run python main.py, sirviendo en http://127.0.0.1:8000/mcp. Los comandos de desarrollo son uv sync --group dev y uv run pytest -q. La guía de seguridad del README recomienda comenzar con ámbitos mínimos y herramientas de solo lectura, no incluir nunca en commits archivos .env, tokens ni respuestas de la API de salud, cifrar el almacén de tokens cuando se establece GUAVA_TOKEN_ENCRYPTION_KEY y volver a conectar Guava tras los arranques en frío si los discos de Horizon son efímeros. Los registros redactan los secretos de cliente siempre que es posible, y el README aconseja no volcar cargas útiles completas de la API en el contexto del modelo cuando basta con una respuesta acotada.