Initial: Mesh-Skills, Configs, Scripts

2026-09-02 23:49:07 +02:00
commit 26c7980750
783 changed files with 145393 additions and 0 deletions
@@ -0,0 +1,78 @@
+---
+name: coros-mcp-integration
+description: "Use when: COROS-Sportuhr-Daten in PersoEnt anbinden."
+version: 1.0.0
+author: mehlzoerwer
+platforms: [linux]
+models:
+  default: mimo-v2-flash
+license: MIT
+related_skills: [content-creator, pocketbase-deployment]
+---
+
+# COROS-MCP — Sportuhr-Daten in PersoEnt
+
+Nutze diesen Skill, wenn PersoEnt (oder ein anderes Projekt) **echte COROS-Sportuhr-Gesundheitsdaten** anbinden soll: Schlaf, HRV, Stress, Ruhe-Herzfrequenz, Training, Erholung, VO2max.
+
+## Status (2026-08-10)
+- **Installiert** global: `npm install -g coros-mcp` (OFFIZIELLES Paket von `coros_openplatform`, ~0.1.1)
+- **Eingeloggt** — Token gecacht in `/root/.coros-mcp-skill-gateway-ts/<region>/token.json`
+- **22 MCP-Tools** verfügbar, Endpoint `mcp.coros.com` (Europa: `mcpeu.coros.com`)
+
+## CLI-Syntax (WICHTIG — Flags, nicht Positional)
+
+Das Paket nutzt Flags, NICHT Positionsargumente:
+```bash
+coros-mcp list-tools                                   # alle Tools + Schema
+coros-mcp describe-tool --tool <NAME>                  # Schema eines Tools
+coros-mcp call-tool --tool <NAME> --arguments-json '{}' # Tool aufrufen
+```
+- `call-tool --tool X queryDailyHealthData` (ohne `--tool`) → **Fehler "unknown argument"**
+- `--args '{}'` / `--name X` / `--tool` mit Positional → **alles falsch** (richtig: `--tool NAME --arguments-json JSON`)
+
+## Login-Flow (einmalig, nur Nutzerkonto)
+```bash
+coros-mcp login-start      # erzeugt Browser-Login-Link (mcpeu.coros.com/cli/login/...)
+# Nutzer oeffnet Link + meldet sich mit COROS-Konto an
+coros-mcp login-finish     # bestaetigt Session -> 'login ok'
+coros-mcp login-status     # 'no pending login session' = sauber/fertig
+```
+Login-Link ist region-/sessiongebunden. Andere COROS-Region → `--issuer`/`--mcp-url` anpassen.
+
+## Wichtigste Tools (Daten fuer PersoEnt-Gesundheitsdetektiv)
+
+| Tool | Daten |
+|------|-------|
+| `queryDailyHealthData` | 7 Tage: Schritte, Kalorien, Stress, Schlaf (Tief/Leicht/REM), Schlaf-HR |
+| `querySleepHrv` | taegl. HRV + Baseline + Normbereich |
+| `queryRestingHeartRate` / `queryAvgHeartRate` | Ruhe-/durchschnittl. HF |
+| `queryStressLevel` / `queryStressTimeSeries` | Stress (avg/roh) |
+| `querySportRecords` | Workout-Protokoll (+ labelId, sportType) |
+| `getActivityDetail` / `queryActivityLapData` | Activity-Details inkl. HR |
+| `queryRecoveryStatus` | Erholung % + Level |
+| `queryFitnessAssessmentOverview` | VO2max, Threshold-Pace |
+| `querySleepData` | Schlafscore, Dauer, Stufen |
+| `queryDevices` / `queryUserInfo` | Geraete / Profil |
+
+## Integration in PersoEnt (Architektur-Vorgabe)
+- **Server-seitig auf VPS** (Master): Poller ruft `coros-mcp call-tool` auf → Daten nach **PocketBase** (`health_records`-ahnliche Struktur) → PersoEnt-Dashboard/Detektiv liest von dort.
+- HRV + Schlaf + Stress + Erholung = ideale **Kausal-Merkmale** fuer den Gesundheitsdetektiv (besser als Google-Health-Fit).
+- Gleiche Basis-Assets (ein COROS-Konto) fuer mehrere Kanaele/Personas.
+
+## Edge Cases
+- **Daten brauchen echten Login** — ohne `login-finish` kein Token, `call-tool` schlaegt fehl.
+- Zeitfenster-Tools (`queryCustomActivityLapData`) brauchen `startTimestamp`/`endTimestamp` in Unix-Sekunden.
+- Sport-Records-Details brauchen `labelId` + `sportType` aus der Records-Liste.
+
+## Verifizierte Daten-Shapes
+Siehe `references/coros-mcp-data-shapes.md` — echte Antwort-Formate (queryDailyHealthData = ein String mit `--- JJJJMMTT ---`-Tag-Abschnitten, Sport-Records mit labelId/sportType), Token-Sicherheit (root-only Cache + age-Backup, NIE die Klartext-token.json verschluesseln) und der PersoEnt-Write-Hinweis (kein datum-Feld).
+
+## 🔥 Robustes Parsen der 7-Tage-Helth-Antwort (verifiziert 2026-08-15)
+
+`queryDailyHealthData` liefert EINEN String mit 7 `--- 20260815 ---`-Tagbloecken. Naive Extraktion (erstes "Steps" finden) ist FEHLERHAFT — es erwischt das Datum oder einen alten Tag. Robust:
+- **Letzten Tages-Block nehmen**, nicht den ersten: `re.split(r'--- (\d{8}) ---', text)` → nimm das letzte (date, body)-Paar.
+- **`Stress: Avg 22`** hat "Avg" zwischen Label und Zahl → Regex `re.escape(label) + r'[^\d]*?([\d.,]+)'` (Ueberspringt Zwischenwoerter).
+- **Puls zuverlaessig aus `Sleep HR: Avg 51 bpm`** im Health-Block (AVG HR-Call `queryAvgHeartRate` hat anderes/leeres Block-Format — nicht darauf stuetzen).
+- **Schlaf** = `Total: 7h 46min` → `(\d+)h (\d+)min` → 7.77h.
+- COROS-Werte kommen mit **Tausender-Komma** (z.B. `9,304`) → `,` entfernen.
+- Nach jedem Fix: **real gegen die Live-Antwort testen** (echten `call-tool`-String parsen), nie von Schema raten — Daten-Shapes weichen ab.