97 lines
5.5 KiB
Markdown
97 lines
5.5 KiB
Markdown
---
|
||
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) |