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 のままです。