Polar MCP

Este repositorio implementa los límites definidos en ADR 0001: un núcleo Polar de Python reutilizable, con adaptadores finos de solo lectura para MCP local y el Claude Agent SDK.

La implementación es deliberadamente v4-first. Proporciona:

• actualización automática de tokens AccessLink v4;

• clientes v4 aislados y v3 complementarios;

• rangos de fechas acotados con extremo exclusivo y fragmentación automática de solicitudes v4;

• envoltorios de respuesta normalizados con procedencia de API y unidades;

• redacción recursiva de credenciales, identificadores de usuario/dispositivo y ubicación precisa;

• series temporales anidadas acotadas y resultados de nivel superior;

• una caché TTL en memoria que nunca persiste datos de salud;

• herramientas MCP y del Agent SDK que solo pueden leer datos saneados;

• una CLI de autenticación separada con un archivo de token local de solo propietario.

Instalación

Se requiere Python 3.11 o posterior.

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

Registra una aplicación en Polar AccessLink y luego establece las credenciales del lado del servidor. No pongas estos valores en un archivo de configuración de MCP que un modelo pueda leer.

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

Genera una URL de autorización con un valor de estado que tu callback verifique:

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

Después de aprobar el acceso, intercambia el código devuelto. Al omitir --code, se lee sin mostrarlo en pantalla ni colocarlo en el historial del shell.

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

Los tokens se guardan por defecto en el directorio de configuración de la plataforma y se rechazan si su archivo es legible por cualquier persona excepto su propietario. Anula la ubicación con POLAR_TOKEN_FILE.

Related MCP server: health-mcp

Ejecutar MCP local

polar-mcp

El servidor usa stdio; no abre un listener de red. Expone únicamente:

• polar_get_activity

• polar_get_sleep

• polar_get_recovery

• polar_get_training_sessions

• polar_get_heart_rate

Todos los valores de end_date son exclusivos. Los esquemas de las herramientas no incluyen deliberadamente indicadores de datos brutos ni de ubicación. El código fuera de un agente puede usar PolarService.query con una DisclosureGrant explícita, pero la concesión requiere una confirmación del usuario registrada por separado y las respuestas permanecen acotadas en tamaño.

Pruebas

Las pruebas usan únicamente el ejecutor de pruebas de la biblioteca estándar y transportes HTTP simulados:

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

Ninguna prueba requiere credenciales de Polar ni envía datos de salud por la red.

Estado de validación actual

Este código implementa la arquitectura duradera, pero no afirma la prueba de concepto con dispositivo real necesaria para aceptar el ADR 0001. El ADR permanece en Proposed hasta que se completen las comprobaciones documentadas en vivo con Polar Pacer.