guavahealth-fastmcp-app

O Guava Health MCP é um servidor FastMCP de código aberto que encapsula a API de desenvolvedor da Guava Health e a disponibiliza para hosts MCP como Cursor, Claude e ChatGPT. Uma instância hospedada está acessível em https://guavahealth.fastmcp.app/mcp, e o projeto tem licença MIT. Não é afiliado à Guava Health, Inc. O servidor é somente leitura por design e não persiste cargas de dados de saúde; ele faz proxy de leituras ao vivo da API da Guava após o usuário autorizar o acesso. A versão 0.1 expõe sete ferramentas: guava_auth_status (se a Guava está conectada para o usuário atual do MCP), guava_begin_connect (inicia o OAuth da Guava com PAR e PKCE e retorna um authorization_url), guava_disconnect (remove os tokens armazenados daquele usuário), guava_get_me (perfil/identidade), guava_search_sleep (sessões de sono), guava_search_activities (treinos e atividades) e guava_search_metrics (métricas filtradas por tipos, como steps ou vo2_max). Operações de gravação estão explicitamente fora do escopo desta versão. A arquitetura usa duas camadas de OAuth. A autenticação do cliente MCP ocorre por meio de um GitHub OAuth App para que os hosts possam se conectar com segurança e vários usuários sejam suportados. O lado da API da Guava Health usa um app confidencial da API da Guava com PAR, PKCE (S256) e rotação de refresh tokens. O fluxo documentado é: o host MCP se autentica via OAuth do GitHub no guavahealth.fastmcp.app, que então se comunica com api.guavahealth.com por meio do OAuth 2.1 da Guava. A configuração exige registrar um app da API da Guava no portal da API da Guava com o URI de redirecionamento exato https://guavahealth.fastmcp.app/oauth/callback, ativar acesso de segundo plano de longa duração e os escopos de leitura necessários, e depois fornecer GUAVA_CLIENT_ID e GUAVA_CLIENT_SECRET. Também é necessário um GitHub OAuth App, com homepage https://guavahealth.fastmcp.app e callback https://guavahealth.fastmcp.app/auth/callback, fornecendo GITHUB_CLIENT_ID e GITHUB_CLIENT_SECRET. As variáveis de ambiente incluem PUBLIC_BASE_URL, GUAVA_ENV (test ou live), uma substituição opcional GUAVA_API_BASE, GUAVA_TOKEN_ENCRYPTION_KEY (uma chave Fernet para o blob de tokens em repouso), um MCP_AUTH_TOKEN opcional como bearer compartilhado para automação e um FASTMCP_JWT_SIGNING_KEY opcional. O README mostra como gerar uma chave Fernet com o pacote cryptography. As notas de implantação mencionam um entrypoint do Horizon de main.py (ou main.py:mcp) e a URL do MCP. Para uso local, o projeto usa uv: uv sync e depois uv run python main.py, servindo em http://127.0.0.1:8000/mcp. Os comandos de desenvolvimento são uv sync --group dev e uv run pytest -q. As orientações de segurança no README recomendam escopos mínimos e ferramentas somente leitura primeiro, nunca commitar arquivos .env, tokens ou respostas da API de saúde, criptografar o armazenamento de tokens quando GUAVA_TOKEN_ENCRYPTION_KEY estiver definido e reconectar a Guava após cold starts se os discos do Horizon forem efêmeros. Os logs omitem segredos de cliente sempre que possível, e o README desaconselha despejar cargas completas da API no contexto do modelo quando uma resposta específica for suficiente.