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,97 @@
+---
+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)
@@ -0,0 +1,49 @@
+# COROS-MCP Tool-Inventory (Stand 2026-08-15, real verifiziert)
+
+Quelle: `coros-mcp list-tools` nach erfolgreichem Login. 22 MCP-Tools am COROS-Gateway. Alle Aufrufe mit korrekter Flag-Syntax:
+`coros-mcp call-tool --tool <NAME> --arguments-json '<json>'`.
+
+## Schlaf
+- `querySleepData` — Sleep-Score, Hauptdauer, Stufen (Tief/Leicht/REM), Awake. Legacy-Daily-API.
+- `querySleepHrv` — offizielles tägliches Schlaf-HRV-Assessment (avg, normal range, baseline). Datum = Wachtag (Nacht davor).
+
+## Herz
+- `queryAvgHeartRate` — tägliche durchschnittliche HK.
+- `queryRestingHeartRate` — tägliche Ruhe-HK.
+
+## Stress
+- `queryStressLevel` — täglicher avg-Stresswert.
+- `queryStressTimeSeries` — rohe Stress-Punkte (timestamp, tz).
+
+## Gesundheit / Daily
+- `queryDailyHealthData` — Breite Tages-Übersicht: Schritte, Kalorien, Exercise-Minuten, Stress, Sleep-Detail. Beispiel real: Routinesfeld ergab Schritte 627–9304, Stress avg, Sleep-HR detail.
+- `queryHealthCheckTimeSeries` — Roh-Wellness-Check: Herzrate, HRV, Stress, Atemfrequenz.
+
+## Sport / Aktivität
+- `querySportRecords` — Workout-Protokoll (Datum, Location, Duration, avg HR, Calories, LabelId, SportType). sportType-Codes: 100=running, 201=indoor cycling, 1200=hybrid fitness.
+- `getActivityDetail` — detaillierte Infos eines Trainings inkl. Herzfrequenz.
+- `analyzeActivityDetail` — Coach-Style-Zusammenfassung (holt Detail + analysiert).
+- `queryActivityLapData` — Lap-/Segment-Daten für labelId+sportType.
+- `queryCustomActivityLapData` — Custom-Fenster (z.B. letzte N Minuten, Endsegment) mit timestamp-Grenzen.
+- `downloadActivityFitFiles` — FIT-Datei(en) als Binary-Resource.
+- `queryActivityFitFileDownloadUrls` — Fallback: FIT-Download-URLs als Text.
+
+## Fitness / Assessment
+- `queryFitnessAssessmentOverview` — VO2max, Lauf-Level, Threshold-Pace, Race-Prediction.
+- `queryTrainingLoadAssessment` — Kommentar, Kurz-/Langzeit-Trainingsload.
+- `queryRecoveryStatus` — Recovery-% + Level-Verschreiben.
+- `queryTrainingSchedule` — aktuelle Woche Trainingsplan (bzw. angegeben).
+
+## Profil / Geräte
+- `queryUserInfo` — Größe, Gewicht, Geburtstag, Gender.
+- `queryDevices` — gebundene COROS-Geräte (device id, firmware type).
+- `queryMenstruationCycles` — Zyklusdaten (heute, nächste Periode, täglich).
+
+## Beispiel-Rückgabewerte (real 2026-08-15, Nutzer Thorsten)
+- `queryUserInfo`: Height 173cm, Weight 100.6kg, Birthday 1972-02-21, Male.
+- `queryRecoveryStatus`: 100 %, Level "Heavy training allowed".
+- `querySleepHrv`: HRV Ausdrücke je Tag (z.B. 55ms Normal, Baseline 61ms to 67ms).
+- `querySportRecords` (1 Woche): Indoor Cycling 1:00:14, avg HR 114, Location "Indoor Rad".
+
+## Hinweis
+Tool-Schemas: `coros-mcp describe-tool --tool <NAME>` zeigt inputSchema (Felder + erforderlichen). Viele Health-Daily-Tools brauchen `{}`-em Arguments (Default oder Sarted). Activity-Tools brauchen `labelId`+`sportType`.