guavahealth-fastmcp-app

Guava Health MCP은 Guava Health 개발자 API를 감싸 Cursor, Claude, ChatGPT 같은 MCP 호스트에서 사용할 수 있게 만드는 오픈소스 FastMCP 서버입니다. 호스팅된 인스턴스는 https://guavahealth.fastmcp.app/mcp 에서 접근할 수 있으며 프로젝트는 MIT 라이선스입니다. Guava Health, Inc.와 제휴하지 않았습니다. 이 서버는 설계상 읽기 전용이며 건강 데이터 페이로드를 저장하지 않고, 사용자가 접근을 승인한 후 라이브 Guava API 읽기 요청을 프록시합니다. 버전 0.1은 7개 도구를 노출합니다: guava_auth_status(현재 MCP 사용자에 대해 Guava 연결 여부), guava_begin_connect(PAR 및 PKCE로 Guava OAuth를 시작하고 authorization_url을 반환), guava_disconnect(해당 사용자의 저장된 토큰 삭제), guava_get_me(프로필/주체), guava_search_sleep(수면 세션), guava_search_activities(운동 및 활동), guava_search_metrics(steps나 vo2_max 같은 유형으로 필터링된 지표). 쓰기 기능은 이 버전에서 명시적으로 범위에서 제외됩니다. 아키텍처는 두 개의 OAuth 계층을 사용합니다. MCP 클라이언트 인증은 GitHub OAuth 앱을 통해 실행되어 호스트가 안전하게 연결하고 여러 사용자를 지원할 수 있습니다. Guava Health API 쪽은 PAR, PKCE(S256), 리프레시 토큰 순환을 사용하는 기밀(confidential) Guava API 앱을 사용합니다. 문서화된 흐름은 다음과 같습니다: MCP 호스트가 GitHub OAuth를 통해 guavahealth.fastmcp.app에 인증하면, 해당 서버가 Guava OAuth 2.1을 통해 api.guavahealth.com과 통신합니다. 설치하려면 Guava API 포털에서 정확한 리디렉션 URI https://guavahealth.fastmcp.app/oauth/callback 로 Guava API 앱을 등록하고, 장기 백그라운드 액세스와 필요한 읽기 스코프를 활성화한 다음 GUAVA_CLIENT_ID와 GUAVA_CLIENT_SECRET을 제공해야 합니다. 또한 홈페이지가 https://guavahealth.fastmcp.app 이고 콜백이 https://guavahealth.fastmcp.app/auth/callback 인 GitHub OAuth 앱이 필요하며, GITHUB_CLIENT_ID와 GITHUB_CLIENT_SECRET을 제공해야 합니다. 환경 변수에는 PUBLIC_BASE_URL, GUAVA_ENV(test 또는 live), 선택적 GUAVA_API_BASE 재정의, GUAVA_TOKEN_ENCRYPTION_KEY(저장된 토큰 블롭을 위한 Fernet 키), 자동화를 위한 선택적 MCP_AUTH_TOKEN 공유 베어러, 선택적 FASTMCP_JWT_SIGNING_KEY가 포함됩니다. README에는 cryptography 패키지로 Fernet 키를 생성하는 방법이 나와 있습니다. 배포 참고 사항에는 main.py(또는 main.py:mcp) Horizon 진입점과 MCP URL이 언급되어 있습니다. 로컬 사용 시 프로젝트는 uv를 사용합니다: uv sync 후 uv run python main.py를 실행하면 http://127.0.0.1:8000/mcp 에서 제공됩니다. 개발 명령은 uv sync --group dev 와 uv run pytest -q 입니다. README의 보안 지침은 최소 스코프와 읽기 전용 도구를 우선 사용하고, .env 파일, 토큰, 건강 API 응답을 절대 커밋하지 말며, GUAVA_TOKEN_ENCRYPTION_KEY가 설정된 경우 토큰 저장소를 암호화하고, Horizon 디스크가 임시적이면 콜드 스타트 후 Guava를 다시 연결하라고 권장합니다. 로그는 가능한 경우 클라이언트 비밀을 마스킹하며, 좁은 답변으로 충분할 때는 전체 API 페이로드를 모델 컨텍스트에 덤프하지 말라고 조언합니다.