guavahealth-fastmcp-app

Guava Health MCP est un serveur FastMCP open-source qui encapsule l'API développeur Guava Health pour la rendre accessible aux hôtes MCP comme Cursor, Claude et ChatGPT. Une instance hébergée est disponible à l'adresse https://guavahealth.fastmcp.app/mcp, et le projet est sous licence MIT. Il n'est pas affilié à Guava Health, Inc. Le serveur est conçu en lecture seule et ne conserve pas les données de santé ; il relaie les lectures de l'API Guava en temps réel après autorisation de l'utilisateur. La version 0.1 expose sept outils : guava_auth_status (état de connexion Guava pour l'utilisateur MCP actuel), guava_begin_connect (initie l'OAuth Guava avec PAR et PKCE et renvoie une URL d'autorisation), guava_disconnect (supprime les jetons stockés pour cet utilisateur), guava_get_me (profil/sujet), guava_search_sleep (sessions de sommeil), guava_search_activities (entraînements et activités) et guava_search_metrics (métriques filtrées par types comme les pas ou la VO2 max). Les écritures sont explicitement exclues de cette version. L'architecture utilise deux couches OAuth. L'authentification du client MCP passe par une application GitHub OAuth afin que les hôtes puissent se connecter de manière sécurisée et que plusieurs utilisateurs soient pris en charge. Le côté API Guava Health utilise une application API Guava confidentielle avec PAR, PKCE (S256) et rotation des jetons de rafraîchissement. Le flux documenté est le suivant : l'hôte MCP s'authentifie via GitHub OAuth sur guavahealth.fastmcp.app, qui communique ensuite avec api.guavahealth.com via Guava OAuth 2.1. La configuration nécessite l'enregistrement d'une application API Guava sur le portail API Guava avec l'URI de redirection exacte https://guavahealth.fastmcp.app/oauth/callback, l'activation de l'accès en arrière-plan à longue durée et des portées de lecture nécessaires, puis la fourniture de GUAVA_CLIENT_ID et GUAVA_CLIENT_SECRET. Une application GitHub OAuth est également requise, avec l'URL de la page d'accueil https://guavahealth.fastmcp.app et le rappel https://guavahealth.fastmcp.app/auth/callback, en fournissant GITHUB_CLIENT_ID et GITHUB_CLIENT_SECRET. Les variables d'environnement incluent PUBLIC_BASE_URL, GUAVA_ENV (test ou live), une option de remplacement GUAVA_API_BASE, GUAVA_TOKEN_ENCRYPTION_KEY (une clé Fernet pour le stockage des jetons au repos), un jeton porteur partagé optionnel MCP_AUTH_TOKEN pour l'automatisation, et une clé optionnelle FASTMCP_JWT_SIGNING_KEY. Le fichier README montre comment générer une clé Fernet avec le package cryptography. Les notes de déploiement mentionnent un point d'entrée Horizon main.py (ou main.py:mcp) et l'URL MCP. Pour une utilisation locale, le projet utilise uv : uv sync puis uv run python main.py, avec un service sur http://127.0.0.1:8000/mcp. Les commandes de développement sont uv sync --group dev et uv run pytest -q. Les conseils de sécurité dans le README recommandent d'utiliser des portées minimales et des outils en lecture seule en priorité, de ne jamais commettre les fichiers .env, les jetons ou les réponses de l'API de santé, de chiffrer le stockage des jetons lorsque GUAVA_TOKEN_ENCRYPTION_KEY est défini, et de reconnecter Guava après des démarrages à froid si les disques Horizon sont éphémères. Les journaux masquent les secrets clients dans la mesure du possible, et le README déconseille de vider l'intégralité des charges utiles de l'API dans le contexte du modèle lorsqu'une réponse précise suffit.