Polar MCP

Dieses Repository implementiert die Grenzen aus ADR 0001: einen wiederverwendbaren Python-Polar-Kern mit schlanken Nur-Lese-Adaptern für lokales MCP und das Claude Agent SDK.

Die Implementierung ist bewusst v4-orientiert. Sie bietet:

• automatische Aktualisierung von AccessLink-v4-Tokens;

• isolierte v4- und ergänzende v3-Clients;

• begrenzte Datumsbereiche mit exklusivem Ende und automatisches v4-Request-Chunking;

• normalisierte Antwort-Envelopes mit API-Herkunft und Einheiten;

• rekursive Schwärzung von Anmeldedaten, Benutzer-/Gerätekennungen und präzisen Standorten;

• begrenzte verschachtelte Zeitreihen und Top-Level-Ergebnisse;

• einen In-Memory-TTL-Cache, der niemals Gesundheitsdaten persistiert;

• MCP- und Agent-SDK-Tools, die nur bereinigte Daten lesen können;

• eine separate Authentifizierungs-CLI mit einer lokalen Token-Datei, die nur der Eigentümer lesen kann.

Installation

Python 3.11 oder höher ist erforderlich.

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

Registrieren Sie eine Anwendung in Polar AccessLink und setzen Sie dann serverseitige Anmeldedaten. Legen Sie diese Werte nicht in einer MCP-Konfigurationsdatei ab, die ein Modell lesen kann.

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

Generieren Sie eine Autorisierungs-URL mit einem State-Wert, den Ihr Callback verifiziert:

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

Nachdem Sie den Zugriff genehmigt haben, tauschen Sie den zurückgegebenen Code ein. Wenn Sie --code weglassen, wird er eingelesen, ohne angezeigt oder in der Shell-Historie abgelegt zu werden.

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

Tokens werden standardmäßig im Plattform-Konfigurationsverzeichnis gespeichert und abgelehnt, wenn ihre Datei von irgendjemandem außer dem Eigentümer gelesen werden kann. Überschreiben Sie den Speicherort mit POLAR_TOKEN_FILE.

Related MCP server: health-mcp

Lokales MCP ausführen

polar-mcp

Der Server verwendet stdio; er öffnet keinen Netzwerk-Listener. Er stellt nur Folgendes bereit:

• polar_get_activity

• polar_get_sleep

• polar_get_recovery

• polar_get_training_sessions

• polar_get_heart_rate

Alle end_date-Werte sind exklusiv. Die Tool-Schemas haben bewusst keine Rohdaten- oder Standort- Flags. Code außerhalb eines Agents kann PolarService.query mit einer expliziten DisclosureGrant verwenden, aber die Freigabe erfordert eine separat aufgezeichnete Benutzerbestätigung, und Antworten bleiben größenbegrenzt.

Testen

Die Tests verwenden nur den Test-Runner der Standardbibliothek und simulierte HTTP-Transports:

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

Kein Test erfordert Polar-Anmeldedaten oder sendet Gesundheitsdaten über das Netzwerk.

Aktueller Validierungsstatus

Dieser Code implementiert die dauerhafte Architektur, erhebt aber nicht den Anspruch, den für die Annahme von ADR 0001 erforderlichen Proof of Concept mit echten Geräten zu erbringen. Die ADR bleibt Proposed, bis die dokumentierten Live-Prüfungen mit Polar Pacer abgeschlossen sind.