Servidor MCP de Tyme Wear

Un servidor Model Context Protocol que conecta Claude a la plataforma de sensores de respiración Tyme Wear. Analiza tus datos ventilatorios, actividades, umbrales y zonas de entrenamiento directamente a través de Claude.

Construido sobre la misma arquitectura que trainingpeaks-mcp.

¿Qué es Tyme Wear?

Tyme Wear fabrica la banda torácica VitalPro, un sensor de respiración portátil que mide métricas ventilatorias (frecuencia respiratoria, volumen corriente, ventilación minuto) junto con la frecuencia cardíaca. Utiliza umbrales ventilatorios (VT1, VT2) para definir zonas de entrenamiento personalizadas. Utilizado por el Team Visma | Lease a Bike.

Related MCP server: Strava MCP Server

Características

• 40 herramientas MCP para perfil, actividades, datos de respiración, umbrales VE, análisis compacto por actividad, archivos/detección de actividad, planes de entrenamiento, recomendaciones de ejercicios, integraciones, suscripción/cuenta, fisiología en reposo/máxima y exportaciones

• Almacenamiento seguro de credenciales mediante llavero del sistema (macOS Keychain / Administrador de credenciales de Windows) con respaldo de archivo cifrado AES-256-GCM

• Autenticación automática con almacenamiento en caché de tokens y reautenticación automática al expirar

• Datos de respiración inteligentes con modos resumen, ventana y completo para evitar desbordamiento de contexto

• Información por actividad (tw_get_activity_insights): VT1/VT2/VO2max detectados con potencia medida en el umbral, puntuaciones de confianza, indicador de prueba truncada y tiempo/calorías por zona — en una sola llamada, sin análisis FIT

• Análisis compacto de actividad (tw_get_activity_analysis): marcas de tiempo reconciliadas, resumen etiquetado y estados de capacidad, por canal procesado/nuevo procesado/respaldo FIT, fusión determinista por segundos transcurridos y paginación

• Cargas de actividad ligeras: tw_get_activity y tw_get_activity_workout_zone_detection omiten por defecto los arrays de varios MB por segundo (se pueden incluir de nuevo con include=[...])

• Modo HTTP Streamable público con autenticación de portador estático u OAuth (conector de un clic para claude.ai), de un solo inquilino para la cuenta de Tyme Wear del operador

Inicio rápido

1. Instalar

git clone https://github.com/tkelkermans/tymewear-mcp.git
cd tymewear-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

2. Autenticarse

tymewear-mcp auth

Introduce tu correo electrónico y contraseña de Tyme Wear. Las credenciales se almacenan de forma segura en el llavero del sistema con un respaldo de archivo cifrado.

3. Configurar Claude Desktop

Añade a la configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "tymewear": {
      "command": "/path/to/tymewear-mcp/.venv/bin/tymewear-mcp",
      "args": ["serve"]
    }
  }
}

O ejecuta tymewear-mcp config para generar el fragmento con la ruta correcta.

4. Reiniciar Claude Desktop

Las herramientas de Tyme Wear aparecerán en la lista de herramientas de Claude.

Comandos CLI

Despliegue en Internet público

serve-public expone un endpoint MCP HTTP Streamable para despliegues alojados. Está autenticado y no tiene estado; no es una API pública anónima.

Servidor público

Establece la URL pública y uno o más tokens de portador MCP mediante variables de entorno. Cada token de portador debe tener al menos 32 caracteres; utiliza un secreto aleatorio generado.

export TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp"
export TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars"

tymewear-mcp serve-public \
  --host 0.0.0.0 \
  --port 8000 \
  --public-url "$TYMEWEAR_PUBLIC_URL"

El endpoint MCP es /mcp por defecto. /healthz devuelve solo {"status":"ok"} y no expone datos de clientes.

Contenedor

El Dockerfile incluido ejecuta el servidor público como un usuario no root. Inyecta los secretos en tiempo de ejecución:

docker build -t tymewear-mcp-public .

docker run --rm -p 8000:8000 \
  -e TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
  -e TYMEWEAR_PUBLIC_BEARER_TOKENS="replace-with-a-long-random-secret-of-32-plus-chars" \
  tymewear-mcp-public

Vercel

El repositorio también incluye un punto de entrada ASGI Python de Vercel raíz (main.py). El framework Python de Vercel enruta las solicitudes directamente a la aplicación ASGI, por lo que vercel.json no debe reescribir /mcp, /healthz o /.well-known/* a una ruta de función interna. Vincula el directorio local al proyecto de Vercel deseado, conecta ese proyecto al repositorio Git, luego configura al menos TYMEWEAR_PUBLIC_BEARER_TOKENS tanto para Producción como para Vista Previa. El punto de entrada falla de forma segura si la variable de entorno del token de portador público está ausente. Utiliza un token de portador de Vista Previa separado para limitar el alcance de las credenciales. Se recomienda TYMEWEAR_PUBLIC_URL para alias de producción, pero los despliegues de vista previa pueden derivarlo de la URL de despliegue de Vercel.

PRODUCTION_TOKEN_FILE=/path/to/generated-production-bearer-token
PREVIEW_TOKEN_FILE=/path/to/generated-preview-bearer-token
chmod 600 "$PRODUCTION_TOKEN_FILE" "$PREVIEW_TOKEN_FILE"
vercel link
vercel git connect
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE"
vercel env add TYMEWEAR_PUBLIC_BEARER_TOKENS preview --sensitive --yes < "$PREVIEW_TOKEN_FILE"

Mantén los archivos de token legibles solo por su propietario; el envoltorio de despliegue rechaza los archivos de token accesibles por grupo u otros. Usa vercel env update TYMEWEAR_PUBLIC_BEARER_TOKENS production --sensitive --yes < "$PRODUCTION_TOKEN_FILE" al rotar un token existente. No pases tokens de portador a través de vercel deploy --env, echo de shell u otros argumentos de comando que puedan terminar en el historial del shell o en listados de procesos.

La misma ruta está envuelta por scripts/deploy_public_vercel.sh para despliegues de recuperación manual. Requiere un enlace de proyecto de Vercel existente, sube el token desde un archivo, despliega en producción y ejecuta scripts/verify_public_endpoint.py contra la URL MCP desplegada:

scripts/deploy_public_vercel.sh --token-file "$PRODUCTION_TOKEN_FILE"

Establece PYTHON=/path/to/python cuando el verificador deba ejecutarse con un intérprete específico, como el entorno virtual del repositorio.

Despliegue automatizado (CI/CD)

.github/workflows/deploy.yml ejecuta el conjunto de pruebas bloqueado (ruff + mypy + pytest) en cada push y pull request. No contiene credenciales de Vercel ni despliega la aplicación.

La integración Git de Vercel vinculada crea despliegues de vista previa para ramas de características y pull requests, luego crea el despliegue de producción cuando se actualiza main. No se requiere un secreto de GitHub Actions VERCEL_TOKEN. Las variables de tiempo de ejecución como TYMEWEAR_PUBLIC_BEARER_TOKENS permanecen gestionadas en el proyecto de Vercel y persisten en los despliegues de Git.

Conector claude.ai (OAuth)

El token de portador estático funciona para clientes compatibles con cabeceras (Claude Code: claude mcp add --transport http <url> --header "Authorization: Bearer <token>"). El conector de claude.ai, en cambio, se autentica mediante OAuth, por lo que para añadir el MCP allí, el servidor funciona como un recurso protegido OAuth: valida tokens de acceso JWT de un proveedor gestionado (por ejemplo, WorkOS AuthKit o Stytch) y aplica una lista de permitidos de correos electrónicos. Sigue siendo de un solo inquilino: cada usuario autorizado lee los datos del operador mediante credenciales del lado del servidor.

Establece estas variables de entorno de Vercel (sensibles) para habilitarlo:

Configuración del proveedor (ejemplo con WorkOS AuthKit): crea una aplicación, habilita el inicio de sesión con Google/correo electrónico, habilita el Registro Dinámico de Clientes para que claude.ai pueda autorregistrarse y copia la URL del emisor en TYMEWEAR_PUBLIC_ISSUER_URL. Luego añade el conector en claude.ai → descubre el proveedor a través de /.well-known/oauth-protected-resource del servidor, se registra y ejecuta el inicio de sesión alojado; solo se admiten los correos electrónicos de la lista de permitidos.

La ruta estática TYMEWEAR_PUBLIC_BEARER_TOKENS sigue funcionando junto con OAuth (modo dual). Sin TYMEWEAR_PUBLIC_ISSUER_URL, OAuth está desactivado y solo la ruta del portador está activa.

Verificación posterior al despliegue

Después del despliegue, verifica el endpoint público sin imprimir secretos:

TYMEWEAR_PUBLIC_URL="https://mcp.example.com/mcp" \
python scripts/verify_public_endpoint.py --bearer-token-file "$TOKEN_FILE"

El verificador comprueba /healthz, el rechazo de /mcp no autenticado, initialize MCP autenticado, tools/list autenticado, las herramientas de perfil/análisis compacto requeridas y las cabeceras públicas de seguridad/sin caché. También confirma que los despliegues públicos no anuncian lecturas de actividad sin procesar ni exportaciones de disco, y que los despliegues por defecto no anuncian herramientas de mutación.

Autenticación del cliente público

El modo público es de un solo inquilino: se autentica ascendentemente con Tyme Wear utilizando las propias credenciales del operador desde TYMEWEAR_EMAIL / TYMEWEAR_PASSWORD (env del lado del servidor), por lo que cada llamante autorizado lee los datos del operador. Los clientes solo necesitan demostrar que están autorizados a conectarse; no hay un token de Tyme Wear por solicitud.

Los clientes compatibles con cabeceras (por ejemplo, Claude Code) envían el token de portador de puerta de enlace estático:

Authorization: Bearer <TYMEWEAR_PUBLIC_BEARER_TOKENS entry>

Cuando OAuth está habilitado (TYMEWEAR_PUBLIC_ISSUER_URL establecido), los clientes como el conector de claude.ai envían en su lugar un JWT emitido por el proveedor obtenido a través del inicio de sesión alojado; el servidor lo valida (firma mediante JWKS, emisor, audiencia opcional) y admite solo los correos electrónicos de la lista de permitidos. Ambas rutas funcionan a la vez (modo dual).

Las revisiones anteriores requerían un X-Tymewear-Token por solicitud. El modo de un solo inquilino lo eliminó: las credenciales ahora están en el lado del servidor.

Política de datos públicos

En modo público:

• El acceso está controlado por el token de portador estático y/o la lista de permitidos de correos electrónicos OAuth; solo se conectan las identidades de la lista de permitidos.

• Las credenciales de Tyme Wear del operador residen únicamente en el entorno del lado del servidor (mantenlas en un gestor de secretos). Se leen directamente del entorno — el modo público no toca el llavero local ni el archivo de credenciales cifrado (esos escriben en $HOME, que es de solo lectura en serverless).

• Cada resultado de herramienta y error público estable pasa a través de una proyección de privacidad recursiva no mutante antes de la serialización JSON. Elimina valores no JSON, números no finitos, correos electrónicos, UUIDs de usuario/cuenta/perfil, identificadores de dispositivo/números de serie, tokens, URL firmadas/de devolución de llamada/de descarga, rutas S3 o temporales, campos sin procesar pesados y coordenadas fuera del contrato de ubicación de análisis explícito.

• tw_get_activity_analysis es la interfaz pública compacta de muestras sin procesar. Mantiene disponibilidad etiquetada, capacidad, canal, procedencia, resumen y datos de muestra paginados. include_location debe ser el booleano literal true; solo entonces pueden sobrevivir raw_samples.data[*].position_lat/position_long y sus metadatos de canal coincidentes. Las coordenadas de inicio, genéricas y no relacionadas siempre se eliminan.

• Las respuestas públicas incluyen Cache-Control: no-store, Pragma: no-cache, X-Robots-Tag: noindex, nofollow, HSTS para URL públicas HTTPS y cabeceras de seguridad de referencia para reducir el almacenamiento en caché accidental por intermediarios, la indexación y la filtración de datos del cliente en el navegador.

• Las herramientas de mutación de perfil/actividad están ocultas y devuelven PUBLIC_MUTATIONS_DISABLED por defecto. Solo actívalas con --allow-mutations o TYMEWEAR_PUBLIC_ALLOW_MUTATIONS=true para despliegues de confianza.

• Las herramientas de exportación de archivos CSV, FIT y de correa devuelven PUBLIC_EXPORTS_DISABLED porque la implementación local escribe archivos en disco.

• tw_get_processed_data, tw_get_new_processed_data, tw_get_activity_logs y tw_get_activity_strap_files están ocultas y devuelven PUBLIC_RAW_DATA_DISABLED, incluso cuando las mutaciones están habilitadas. El modo stdio local conserva estas herramientas. La detección compacta de zonas de entrenamiento sigue siendo pública.

Los errores de herramientas públicas son estables y no reflejan el texto de excepción ascendente:

Endurecimiento de Producción

• Termine TLS en el borde y configure TYMEWEAR_PUBLIC_URL en la URL HTTPS MCP canónica.

• Mantenga la ruta de TYMEWEAR_PUBLIC_URL alineada con la ruta MCP montada (/mcp por defecto). El modo público rechaza cadenas de consulta, fragmentos y discrepancias de ruta/trayecto en el inicio.

• Inyecte TYMEWEAR_PUBLIC_BEARER_TOKENS desde un gestor de secretos, no del historial del shell ni del control de código fuente. Los tokens de menos de 32 caracteres se rechazan al inicio.

• Mantenga las implementaciones públicas como solo lectura a menos que tenga un requisito específico de cliente de confianza para mutaciones de perfil/actividad.

• Prefiera un proxy OAuth o consciente de identidad delante de serve-public para clientes no confiables; rote los tokens bearer estáticos regularmente.

• Al usar un proxy con capacidad OAuth o servidor de autorización, establezca TYMEWEAR_PUBLIC_ISSUER_URL o --issuer-url para que los clientes MCP puedan descubrir metadatos de recursos protegidos.

• Los cuerpos de solicitudes HTTP públicas tienen un límite de 1 MiB por defecto, incluidos los cuerpos fragmentados/transmitidos. Anule con TYMEWEAR_PUBLIC_MAX_BODY_BYTES o --max-body-bytes solo si una implementación de confianza necesita solicitudes JSON-RPC más grandes.

• Mantenga deshabilitado el registro del encabezado de autorización, el cuerpo de la solicitud y el cuerpo de la respuesta en el proxy inverso y la plataforma de aplicación.

• Restrinja el tráfico de salida de red a los hosts de la API de Tyme Wear donde su plataforma lo admita.

• Establezca valores explícitos de --allowed-host y --allowed-origin cuando el host de la URL pública no sea el único host/origen válido. El modo público rechaza los encabezados Host no confiables en todas las rutas, rechaza la configuración de host/origen con comodín *, requiere que los orígenes permitidos sean orígenes http(s) exactos sin rutas, y requiere que los orígenes que no sean localhost usen HTTPS.

Herramientas Disponibles

Autenticación y Perfil

Actividades

Datos de Respiración

Archivos de Actividad y Detección

Planes de Entrenamiento y Entrenamientos

Integraciones y Cuenta

Umbrales y Zonas

Valores Máximos

Exportaciones

Ejemplos de Prompts

Una vez configurado, puedes pedirle a Claude cosas como:

• "Muéstrame mis últimas 10 actividades en bicicleta"

• "Analiza los datos de respiración de mi salida de ayer: ¿cuáles fueron mi VE promedio y el tiempo en cada zona?"

• "¿Cuáles son mis umbrales actuales de VT1 y VT2 para ciclismo?"

• "Extrae la información de mi última prueba de umbral: ¿cuál es mi potencia en VT2 y alcanzó el VO2max?"

• "Exporta mi última actividad como archivo FIT"

• "Compara mis objetivos de VE entre correr y ciclismo"

• "Muéstrame mi plan de entrenamiento actual y la recomendación de entrenamiento"

• "Verifica si mi última salida tiene archivos de correa, registros o resultados de detección de zonas de entrenamiento"

• "Enumera mis integraciones conectadas y el estado de la suscripción"

Seguridad

• Las credenciales se almacenan en el llavero del sistema (recomendado) o en un archivo cifrado AES-256-GCM con derivación de clave PBKDF2 (600K iteraciones, sal específica de la máquina)

• Los tokens y credenciales nunca se devuelven en los resultados de la herramienta MCP (se sanitizan antes de llegar a Claude)

• Autenticación por variable de entorno disponible para CI/contenedores: TYMEWEAR_EMAIL + TYMEWEAR_PASSWORD

• Los permisos de archivo se establecen en 600 (solo lectura/escritura del propietario) en los archivos de credenciales cifrados

• El modo público requiere autenticación bearer u OAuth y es de un solo inquilino: la autenticación upstream de Tyme Wear usa las variables de entorno del servidor TYMEWEAR_EMAIL/TYMEWEAR_PASSWORD (nunca el llavero local ni el archivo cifrado, que son de solo lectura en serverless), cada resultado tiene privacidad protegida, y las herramientas de exportación/archivo/raw están deshabilitadas

Arquitectura

tymewear-mcp/
├── src/tymewear_mcp/
│   ├── cli.py              # CLI entry point
│   ├── server.py           # MCP server + 40 tool registrations
│   ├── public.py           # Public Streamable HTTP server + bearer/OAuth auth
│   ├── auth/               # Credential storage (keyring → encrypted → env) + OIDC verifier (oidc.py)
│   ├── client/             # Async HTTP client + Pydantic models
│   └── tools/              # Tool implementations (incl. threshold_analysis.py, _slimming.py)
└── tests/                  # 340 tests

Stack tecnológico: Python 3.10+, MCP SDK, httpx, Pydantic, keyring, cryptography, PyJWT

Desarrollo

pip install -e ".[dev]"
pytest tests/ -v          # Run tests
ruff check src tests      # Lint
mypy src/                 # Type check

Licencia

MIT