Polar MCP

이 저장소는 ADR 0001에 정의된 경계를 구현합니다: 재사용 가능한 Python Polar 코어와 로컬 MCP 및 Claude Agent SDK용 경량 읽기 전용 어댑터로 구성됩니다.

이 구현은 의도적으로 v4 우선입니다. 제공하는 기능은 다음과 같습니다:

• 자동 AccessLink v4 토큰 갱신;

• 분리된 v4 및 보완 v3 클라이언트;

• 제한된, 종료일 미포함 날짜 범위 및 자동 v4 요청 청킹;

• API 출처와 단위를 포함한 정규화된 응답 봉투;

• 재귀적 자격 증명, 사용자/기기 식별자 및 정밀 위치 정보 삭제;

• 제한된 중첩 시계열 및 최상위 결과;

• 건강 데이터를 절대 영구 저장하지 않는 인메모리 TTL 캐시;

• 비식별화된 데이터만 읽을 수 있는 MCP 및 Agent SDK 도구;

• 소유자 전용 로컬 토큰 파일을 사용하는 별도의 인증 CLI.

설치

Python 3.11 이상이 필요합니다.

python -m venv .venv
source .venv/bin/activate
pip install -e '.[mcp]'

Polar AccessLink에 애플리케이션을 등록한 다음 서버 측 자격 증명을 설정하세요. 모델이 읽을 수 있는 MCP 구성 파일에 이러한 값을 넣지 마세요.

export POLAR_CLIENT_ID='...'
export POLAR_CLIENT_SECRET='...'

콜백이 검증하는 state 값으로 인증 URL을 생성하세요:

polar-auth authorization-url \
  --redirect-uri 'http://127.0.0.1:8787/callback' \
  --state "$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

액세스를 승인한 후 반환된 코드를 교환하세요. --code를 생략하면 코드를 에코하거나 셸 기록에 남기지 않고 읽습니다.

polar-auth exchange --redirect-uri 'http://127.0.0.1:8787/callback'
polar-auth status

토큰은 기본적으로 플랫폼 구성 디렉터리를 사용하며, 해당 파일을 소유자 외의 다른 사람이 읽을 수 있으면 거부됩니다. 위치는 POLAR_TOKEN_FILE로 재정의할 수 있습니다.

Related MCP server: health-mcp

로컬 MCP 실행

polar-mcp

서버는 stdio를 사용하며 네트워크 리스너를 열지 않습니다. 다음만 노출합니다:

• polar_get_activity

• polar_get_sleep

• polar_get_recovery

• polar_get_training_sessions

• polar_get_heart_rate

모든 end_date 값은 배타적입니다. 도구 스키마에는 의도적으로 원시 데이터 또는 위치 플래그가 없습니다. 에이전트 외부의 코드는 명시적 DisclosureGrant와 함께 PolarService.query를 사용할 수 있지만, 해당 승인은 별도로 기록된 사용자 확인을 요구하며 응답은 크기 제한이 유지됩니다.

테스트

테스트는 표준 라이브러리 테스트 러너와 모의 HTTP 전송만 사용합니다:

PYTHONPATH=src python -m unittest discover -s tests -v

어떤 테스트도 Polar 자격 증명을 요구하지 않으며 네트워크를 통해 건강 데이터를 전송하지 않습니다.

현재 검증 상태

이 코드는 견고한 아키텍처를 구현하지만, ADR 0001을 수락하는 데 필요한 실기기 개념 증명을 주장하지 않습니다. 문서화된 라이브 Polar Pacer 검사가 완료될 때까지 ADR은 Proposed 상태로 유지됩니다.