# Live-Fragebogen per MCP ausfüllen

Diese Anleitung richtet sich an KI-Agenten, die über den miovea-MCP-Server einen Live-Fragebogen gemeinsam mit ihrem Nutzer (Versicherungsmakler) ausfüllen.

## Konzept

- Ein Live-Fragebogen gehört zu einem Voranfrage-Vorgang (Risikovoranfrage für PKV oder BU) und wird über die **Vorgangs-ID** (UUID) identifiziert. Dein Nutzer gibt dir diese ID; alternativ findest du sie mit `preinquiries_list`.
- Vermittler (Plattform), Kunde (Kundenlink) und du arbeiten auf demselben Live-Stand. Jede gespeicherte Antwort erscheint **sofort** bei allen Beteiligten, ohne dass jemand neu laden muss.
- Pro Feld gilt: Der letzte Schreiber gewinnt. Es gibt keine Sperren.
- Du hast ausschließlich Zugriff auf Vorgänge des miovea-Kontos, mit dem du per OAuth verbunden bist. Fremde IDs liefern `NOT_FOUND`.

## Verbindung

- Server-URL: `https://app.miovea.com/api/mcp`
- Transport: Streamable HTTP (MCP-Standard)
- Anmeldung: OAuth 2.1 mit Dynamic Client Registration; beim ersten Verbinden öffnet sich ein Browser-Login mit dem miovea-Konto des Nutzers. API-Keys gibt es nicht.
- Beispiel Claude Code: `claude mcp add --transport http miovea https://app.miovea.com/api/mcp`

## Werkzeuge

| Tool | Zweck |
| --- | --- |
| `questionnaire_get` | Fragebogen lesen: ohne Parameter die Sektionsübersicht mit Fortschritt, mit `section_key` die aktuell sichtbaren Fragen einer Sektion samt Antworten; `search`, `unanswered_only` und `question_keys` filtern sektionsübergreifend |
| `questionnaire_answers_set` | Antworten schreiben (Batch bis 50 Stück) |
| `preinquiries_list` | Vorgänge auflisten, falls die Vorgangs-ID fehlt |

## Workflow

1. **Überblick**: `questionnaire_get` mit `preinquiry_id` ohne weitere Parameter liefert alle Sektionen mit `visible_questions`, `answered_questions` und `required_unanswered`. Das ist dein Inhaltsverzeichnis zum Durchblättern.
2. **Fragen lesen**: `questionnaire_get` mit `section_key` liefert die aktuell sichtbaren Fragen einer Sektion: `question_key`, `label`, `answer_type`, `options`, `required`, `follow_ups_on` (Antwortwerte, die Folgefragen einblenden) und die aktuelle Antwort (`value`, `last_edited_by`, `updated_at`). Fehlende Felder bedeuten false/leer/unbeantwortet.
3. **Gezielt navigieren** (statt linear durchzublättern, alle kombinierbar): `unanswered_only: true` liefert alle offenen Fragen, `search` findet Fragen per Stichwort über Label und `question_key`, `question_keys` liest einzelne Fragen direkt.
4. **Antworten schreiben**: `questionnaire_answers_set` mit einer Liste aus `{ question_key, value }`. Fasse zusammengehörige Antworten in einem Aufruf zusammen.
5. **Folgefragen**: Die Antwort enthält `newly_visible_questions` mit allen Fragen, die durch deine Werte neu sichtbar wurden (siehe `follow_ups_on`, typisch nach einem `"ja"`). Fülle sie direkt mit aus oder kläre sie mit dem Nutzer.
6. Wiederhole Schritt 2 bis 5, bis der Fragebogen vollständig ist; prüfe zum Schluss mit `unanswered_only: true`, ob noch Fragen offen sind.

## Ausfüllregeln

- **Ja/Nein-Fragen** (`answer_type: "select"` mit den Optionen ja/nein): exakt `"ja"` oder `"nein"`.
- **Auswahlfragen** (`select`, `multi_select`): nur Werte aus `options`, sonst `VALIDATION_FAILED`. Bei `multi_select` ein Array von Strings.
- **Datumsfelder** (`medical_date`): ISO-Schreibweise `JJJJ`, `JJJJ-MM` oder `JJJJ-MM-TT` — so genau, wie die Information vorliegt (z. B. `"2021"`, `"2021-03"`, `"2021-03-14"`).
- **Zeiträume** (Freitextfelder wie „Datum oder Zeitraum"): Freitext, auch mehrere oder vage Zeiträume (z. B. `"12.04.2021 bis 25.06.2021, 12.07.2021"` oder `"seit Mai 2023"`).
- **Checkboxen** (`checkbox`): `true` oder `false`.
- **Freitext**: knapp, sachlich, auf Deutsch.
- `null` löscht eine Antwort.
- **Erfinde nichts.** Gesundheitsangaben müssen vom Nutzer oder Kunden stammen. Lass Unbekanntes offen und frage nach, statt zu raten.

## Parallelität

Der Kunde kann gleichzeitig im Kundenlink tippen. Wenn du eine Antwort überschreibst, die zuletzt der Kunde bearbeitet hat, meldet `questionnaire_answers_set` das im Feld `overwrote_customer_answer` (mit dem vorherigen Wert). Lies bei längeren Pausen den Stand mit `questionnaire_get` neu, bevor du vorhandene Antworten änderst, und halte im Zweifel mit dem Nutzer Rücksprache.

## Fehler

| Code | Bedeutung | Was tun |
| --- | --- | --- |
| `NOT_FOUND` | Vorgang, Fragebogen, Sektion oder Frage existiert nicht oder gehört nicht zum verbundenen Konto | ID prüfen, ggf. `preinquiries_list` oder `questionnaire_get` ohne `section_key` aufrufen |
| `VALIDATION_FAILED` | Wert passt nicht zum Feldtyp oder zu den Optionen | Ausfüllregeln oben beachten und Wert korrigieren |
| `UNAUTHORIZED` | Verbindung nicht (mehr) angemeldet | OAuth-Verbindung neu aufbauen |

Fehler in `questionnaire_answers_set` betreffen immer nur den einzelnen Eintrag; die übrigen Antworten des Batches werden trotzdem gespeichert (siehe `results`).