# COROS-MCP Integration (offiziell, Wearable-Daten → PocketBase)

Muster für das Einspeisen von COROS-Sportuhr-Daten in eine PocketBase-`health_records`-Collection,
als Ergänzung zu `pocketbase-deployment/SKILL.md`. Verifiziert 2026-08-15.

## Install & Login (offizielles Paket, von COROS)

```bash
npm install -g coros-mcp            # offizielles Paket (coros_openplatform)
coros-mcp --help                     # commands: login, login-start/-finish/-status, list-tools, describe-tool, call-tool, apply-openclaw
```

**Login-Flow (nur das COROS-Konto des Nutzers kann das):**
```bash
coros-mcp login-start                # gibt einen Browser-Login-Link aus (z.B. https://mcpeu.coros.com/cli/login/...)
# Nutzer öffnet Link im Browser + meldet sich mit COROS-Konto an
coros-mcp login-finish               # "login ok" — bestätigt Session
coros-mcp list-tools                 # zeigt verfügbare Tools (JSON)
```
Token wird in `~/.coros-mcp-skill-gateway-ts/<region>/token.json` gecacht (root-only machen: `chmod 600/700`).

## 🔥 Korrekte CLI-Syntax (Nicht raten!)

`call-tool`/`describe-tool` erwarten Flags, NICHT nur den Namen als Positional:
```bash
# FALSCH (gibt "unknown argument"):
coros-mcp call-tool queryDailyHealthData
# RICHTIG (--tool + --arguments-json):
coros-mcp call-tool --tool queryDailyHealthData --arguments-json '{}'
coros-mcp describe-tool --tool queryDailyHealthData
```
Das `--help` auf Unterbefehlen zeigt nur die Haupt-Hilfe; die Flags stehen im installierten
Paket (`$(npm root -g)/coros-mcp/dist/*.js`, `call-tool requires --tool`, `--arguments-json`).

## Wertvollste Tools für Gesundheits-Detektiv

- `queryDailyHealthData` — 7-Tage-Health (Steps, Stress, Calories, Sleep-Übersicht je Tag)
- `querySleepData` / `querySleepHrv` — Schlaf + HRV (P0-Merkmale)
- `queryStressLevel` / `queryStressTimeSeries` — Stress
- `queryAvgHeartRate` / `queryRestingHeartRate` — Puls
- `querySportRecords` / `getActivityDetail` / `downloadActivityFitFiles` — Trainingsdaten
- `queryRecoveryStatus` / `queryFitnessAssessmentOverview` — Erholung % + VO2max/Threshold-Pace

## Text-Block-Parsing (wichtige Heuristik)

COROS-`call-tool`-Antworten sind **Text**, mit einem 7-Tage-Block je Datum:
```
--- 20260815 ---
Steps: 981 | Calories: 47 kcal
Stress: Avg 22
Sleep Summary: Total: 7h 46min | Deep: ... 
```
**Pitfall:** Ein simpler "nimm erste Zahl nach Label" greift das **Datum** statt Steps (→ steps=20260815).
**Robust:** `re.split(r'--- (\d{8}) ---', text)` → letzten Tagesblock nehmen, dort Werte ziehen.
Umlaute-fest: `get_num(body, "Stress")` mit `re.search(re.escape(label)+r'[^\d]*?([\d.,]+)')`
umgeht Zwischenwörter wie "Avg" (also `Stress: Avg 22` → 22).
Datum: `'20260815'` → `'2026-08-15'` formatieren.

## In PocketBase schreiben

Direkter SQLite-Write (root) umgeht das leere `createRule`-Problem — siehe SKILL.md
"Write-Schutz: leerer createRule blockt User-Writes". Beim INSERT **`PRAGMA table_info`** prüfen,
welche Spalten existieren, und nur vorhandene senden (kein `datum`/`source` annehmen).

Cron: `0 3 * * * cd /opt/persoent_api/coros && python3 coros-persoent-poller.py >> /var/log/coros-poller.log 2>&1`