---
name: wearable-health-mcp
description: "Use when: Wearables-Daten (COROS) ueber MCP-CLI integrieren."
version: 1.0.0
author: mehlzoerwer
platforms: [linux]
models:
  default: mimo-v2-flash
license: MIT
related_skills: [pocketbase-deployment, content-creator]
---

# Wearable-Health-MCP (COROS u.a.)

## When to Use

Nutze diesen Skill, wenn Wearable-/Gesundheitsdaten (z.B. **COROS-Sportuhr**) über einen **MCP-Gateway-CLI** abgefragt und in eine App/Backend (z.B. PersoEnt) integriert werden sollen — um korrekte CLI-Flag-Syntax, Browser-Login und Token-Sicherheit zu kennen, ohne sie neu zu erkunden.

> **Use when:** Gesundheits-/Trainingsdaten eines Wearables (Sportuhr) über einen MCP-Gateway-CLI abziehen und in eine App/Backend integrieren. Derzeit konkret: **COROS → PersoEnt** über das offizielle `coros-mcp`-Paket.

## Was es ist

`coros-mcp` (npm, **offiziell von COROS**: maintainer `coros_openplatform`) ist eine TypeScript-CLI zum MCP-Gateway `https://mcp.coros.com` (Europa: `https://mcpeu.coros.com`). Login + MCP-Tool-Aufrufe. **Kein zusätzlicher Cloud-Fremdkostenpflicht-Call nötig innerhalb des Rahmenbudgets — der Hersteller stellt es gratis.**

## Installation

```bash
npm install -g coros-mcp        # installiert bin /usr/local/bin/coros-mcp
```

## Login (Browser-Auth, 1x)

```bash
coros-mcp login-start            # gibt Link: https://mcpeu.coros.com/cli/login/<token>
# Nutzer öffnet Link im Browser, loggt sich ins COROS-Konto ein
coros-mcp login-finish            # → "login ok", Token gecacht
coros-mcp login-status            # "no pending login session" wenn fertig
coros-mcp logout                  # Cache leeren
```
Der Login ist ein OAuth-ähnlicher browser flow; nur das echte COROS-Konto kann ihn abschließen (Client-ID/Secret werden NICHT manuell konfiguriert).

## 🔥 CLI-Flag-Syntax (VERIFIZIERT 2026-08-15 — häufigste Fehlerquelle)

**Beachte exakt diese Flags — ANDERE Varianten scheitern mit `unknown argument`:**

```bash
# Tools auflisten (JSON-Array mit name/description/inputSchema)
coros-mcp list-tools

# Ein Tool-Schema anzeigen:
coros-mcp describe-tool --tool <NAME>

# Tool AUFRUFEN — Argumente als --arguments-json (WICHTIG: nicht --args!) :
coros-mcp call-tool --tool <NAME> --arguments-json '<json>'
```

**Getestete Fehlversuche (real aufgetreten):** `--args`, `--name`, `--tool`-ohne-`--arguments-json`, reine Positionsargumente → alle `error: unknown argument`. Das `--help` auf Unterbefehle zeigt nur die HAUPT-Hilfe (nicht die Flag-Struktur). **Verlässliche Quelle bei Unklarheit: Packagedatei lesen** `grep -n "call-tool|--tool|--arguments-json" $(npm root -g)/coros-mcp/dist/*.js` — dort steht die echte Sub-Kommando-Logik.

## Verifizierte Tools (22, Stand 2026-08-15)

| Gruppe | Tools (Beispiele) |
|--------|-------------------|
| Schlaf | `querySleepData` (Score/Dauer/Phasen), `querySleepHrv` (avg+Range+Baseline) |
| Herz | `queryAvgHeartRate`, `queryRestingHeartRate` |
| Stress | `queryStressLevel`, `queryStressTimeSeries` |
| Gesundheit | `queryDailyHealthData` (Schritte/Kalorien/Exercise), `queryHealthCheckTimeSeries` (Roh-HR+HRV+Stress+Atmung) |
| Sport | `querySportRecords`, `getActivityDetail`, `queryActivityLapData`, `queryCustomActivityLapData`, `analyzeActivityDetail` (Coach-Style), `downloadActivityFitFiles`, `queryActivityFitFileDownloadUrls` |
| Fitness | `queryFitnessAssessmentOverview` (VO2max/Threshold-Pace), `queryTrainingLoadAssessment`, `queryRecoveryStatus` (%), `queryTrainingSchedule` |
| Profil/Geräte | `queryUserInfo` (Größe/Gewicht/Geburt/Geschlecht), `queryDevices`, `queryMenstruationCycles` |

**Detektiv-Priorität für Kausal-Analyse (Team-Review 2026-08-15):** P0=HRV + Schlaf, P1=Stress + Erholung, P2=Ruhe-HR + VO2max, P3=Sport/FIT.

## 🔒 Token-Sicherheit (Team-Auflage 2026-08-15)

- Token liegt in `<cache-root>/<region>/token.json` (d.h. `/root/.coros-mcp-skill-gateway-ts/eu/token.json`) — **im Klartext**.
- Die CLI LIEST es selbst aus diesem Cache → **nicht verschlüsseln an Ort**, sonst bricht die CLI. Stattdessen:
  - `chmod 600` token.json UND `chmod 700` Cache-Verzeichnisse (root-only)
  - **Verschlüsselte Sicherungskopie** anlegen: `age` installieren, `age-keygen -o /root/.coros-age-key.txt`, dann
    `age -r <PUBKEY> -o /root/.coros-token.json.age <token.json>` → Datei beginnt mit `age-encryption.org/v1`.
  - **Niemals Token in Logs/env** — nur zur Laufzeit vom Cache einlesen.
- Single-User-PersoEnt = kleine Angriffsfläche (kein Multi-User-Token-Management nötig).

## Architektur-Empfehlung (Team-Review 2026-08-15)

Für Uhren-Health (= tagesbasiert, nicht Echtzeit) **Cron-Poller 1×/Tag (03:00)** → Daten in PocketBase/Backend schreiben; **Live-UI liest NUR aus Backend**, nie Live-COROS (Entkopplung + Rate-Limit + Offline-Fähigkeit). Upsert pro (Datum, Datentyp).

⚠️ **Noch NICHT umgesetzt (Stand 2026-08-15):** der eigentliche Poller-Skript (COROS→PocketBase Write) war zum Sitzungsende noch nie fertig — die PocketBase-Auth-Token-Abfrage blockierte auf Nutzer-Freigabe. Vorgehen siehe nächster Abschnitt.

## Nächster Schritt (noch offen)

1. PersoEnt PocketBase-Login (Auth-Token holen) — **erfordert Nutzer-Freigabe** (sensible Login-Lösung)
2. Collection `health_records`-Schema prüfen (Felder: weight, blood_pressure, pulse, user_id lt. pocketbase-deployment)
3. Poller-Skript: `coros-mcp call-tool --tool querySleepHrv --arguments-json '{}'` je Tag → upsert in PocketBase
4. PersoEnt-Dashboard/Detektiv liest daraus

## Referenzen
- `references/coros-tools-inventory.md` — vollständige 22-Tool-Beschreibungen (Detaildichte)