DkwtMCP CLAUDE.md

Instrucciones del proyecto — DkwtMCP

Contexto para cualquier sesión que trabaje en este repo. Léelo antes de tocar código.

Qué es

MCP local (stdio) en Python del equipo DkwtMCP que conecta Claude Desktop con Garmin y Apple Health, lectura + escritura. Uso personal, no un servicio alojado. Paquete Python: dkwt_mcp. Referencia conceptual: FitMCP (https://fitmcp.tech).

Strava se retiró del alcance por ahora (sus términos 2025 prohíben usar sus datos en IA). Si se reincorpora, seguir el patrón de providers.

Reglas de diseño (no negociables)

• Framework FastMCP (mcp[cli]). La instancia vive en app.py; los providers la importan y registran tools con @mcp.tool.
• Un tool = un workflow útil, no un envoltorio 1:1 de la API. Nombres con prefijo de plataforma: garmin_*, apple_*, más fitness_* para transversales.
• Toda tool: modelo Pydantic v2 de entrada (extra="forbid"), annotations (readOnlyHint/destructiveHint/idempotentHint/openWorldHint), docstring con Args/Returns, y salida por common.as_output (markdown|json).
• Errores siempre vía common.handle_api_error (mensajes accionables). Nunca except silencioso que oculte el fallo al agente.
• I/O de red en async. garminconnect es síncrono → envolver con asyncio.to_thread.
• Secretos solo en .env (git-ignorado). Nada de credenciales en el código.

Restricciones externas a recordar

• Garmin usa la librería no oficial python-garminconnect (>=0.3), frágil ante cambios anti-bots de Garmin. Fijar versión; si el login falla, revisar si hay versión nueva.
  • Auth: el servidor SOLO reutiliza tokens en ~/.dkwtmcp/garmin/. El primer login (con posible 2FA) se hace con scripts/garmin_login.py. El servidor nunca pide input interactivo (colgaría stdio). Si no hay tokens, las tools devuelven un error que indica ejecutar el script.
• Apple Health es solo lectura vía export XML → SQLite. No hay escritura en HealthKit.

Estado actual (Fase 3 Garmin escritura)

• Esqueleto renombrado a dkwt_mcp, servidor FastMCP "DkwtMCP", arranca y registra tools según flags.
• Garmin lectura ✅: garmin_daily_readiness, garmin_get_activities, garmin_get_activity, garmin_sleep, garmin_hrv. Probado con cuenta real (login + get_activities OK).
• Garmin escritura ✅: garmin_schedule_workout (dry_run=True por defecto, seguridad), garmin_list_workouts, garmin_delete_workout (requiere confirm=true). Payload construido con garminconnect.workout (typed); soporta targets de power (W) y heart_rate (ppm).
• Transversal ✅: fitness_planned_vs_actual (cruza programados vs. actividades reales por fecha, calcula adherencia). Parseo defensivo de get_scheduled_workouts (forma de respuesta a confirmar contra cuenta real).
• Plan de fuerza semanal ✅ (puente entre proyectos): fitness_set_week_plan (escribe) + fitness_get_week_plan (lee) sobre ~/.dkwtmcp/plan/semana.json. La fuerza se organiza en OTRO proyecto de Claude ("Pirinexus Training 2026-Noe") y cambia cada semana; como los proyectos no comparten contexto, ese proyecto vuelca la semana con fitness_set_week_plan y el brief la lee. Prioridad del brief para "planificado_hoy": entrenado hoy > Garmin programado (e-bike) > plan de fuerza semanal (archivo local) > calendario fijo del perfil (ultimo recurso). Requiere que el proyecto de planificacion tenga el MCP DkwtMCP conectado (mismo servidor, mismo archivo).
• Apple ✅ (para quien lleve Apple Watch): apple_import_export + apple_query_metric (sueño, HRV, FC reposo, pasos, energia) -> SQLite en ~/.dkwtmcp/apple/. Tambien apple_get_workouts (entrenos del Apple Watch, p.ej. fuerza, desde data.workouts). Dos formatos: export.xml/zip de la app Salud (iterparse) y Health Auto Export JSON (carpeta con .json y/o .zip, importa todo y deduplica; auto-incremental, recomendado). En Health Auto Export, Metricas y Workouts son categorias separadas: hay que exportar ambas. Detecta el formato solo. Activar con ENABLE_APPLE=true.