# Task 6 Report: CORS-Tür + MCP-Endpoint

**Status:** DONE
**Datum:** 2026-10-18
**Basis:** 24ceff3 (Tasks 1–5 verifiziert) → HEAD `30bd535`
**Commits (feat/v1, kein Push, .scratch/ unberührt):**

1. `cef6e6b` feat(config): CORS-Erlaubnisliste server.allowed_origins (TALK_ALLOWED_ORIGINS)
2. `156c20d` feat(api): CORS-Tür für POST /speak — OPTIONS-Preflight und ACAO aus Config
3. `a577597` feat(api): MCP-Endpoint POST /mcp — schlankes eigenes JSON-RPC-Subset mit speak-Tool
4. `150c374` test: Prozessgrenzen-Tests für CORS-Tür und MCP-Handshake
5. `30bd535` docs(readme): CORS-Konfiguration und MCP-Endpoint mit curl-Handshake dokumentiert

## Was geliefert wurde

### 1. CORS-Tür (nur POST /speak)

- **`internal/api/cors.go`** (neu): `OPTIONS /speak` beantwortet Browser-Preflights mit
  `204 No Content` + `Access-Control-Allow-Origin` (exakt gematchte Origin bzw. literales
  `*` bei Wildcard-Konfiguration), `Access-Control-Allow-Methods: POST, OPTIONS`,
  `Access-Control-Allow-Headers: Content-Type`, `Access-Control-Max-Age: 600`.
  Echte (non-preflight) `POST /speak`-Antworten tragen ACAO, wenn die Anfrage-Origin
  gelistet ist. `Vary: Origin` steht immer auf /speak (Cache-Korrektheit).
- **Ungelistete Origin:** sauberer 204/202 **ohne** jegliche CORS-Header — die Blockade
  macht der Browser; HTTP bleibt für Nicht-Browser-Clients sauber erreichbar.
- **Leere Liste (Default):** gar keine CORS-Header — Tür zu, bis konfiguriert.
- **Nur /speak:** `OPTIONS /status` → 405 (kein Preflight-Support), `GET /status` ohne
  ACAO; kein anderer Endpunkt sendet CORS-Header (Prozessgrenzen-Test `TestCORSNurAufSpeak`).
- **`internal/config`:** `server.allowed_origins` (TOML-Liste) + Env-Override
  `TALK_ALLOWED_ORIGINS` (kommagetrennt, Whitespace toleriert; `off` leert die Liste).
  Wildcard `*` ist explizit erlaubt, NICHT Default. Leere Einträge → klarer Fehler.
  Unit-Tests: `TestLoadAllowedOrigins` (Defaults, TOML, Env schlägt Datei, off,
  Wildcard, Fehlerfälle).
- **`GET /status`:** additives Feld `cors: [origins]` — immer vorhanden, `[]` (nicht
  `null`) bei geschlossener Tür (Compat-Anforderung des Briefs; Test `TestStatusCorsFeld`).

### 2. MCP-Endpoint (Streamable HTTP)

- **`internal/api/mcp.go`** (neu): `POST /mcp` — **eigene schlanke Implementierung des
  JSON-RPC-2.0-Subsets, kein SDK-Dependency** (bindende Decision des Briefs; es wurde
  auch keins in Betracht gezogen — der benötigte Umfang sind ~370 Zeilen inkl. Doku,
  ein SDK wäre schwerer als der Payload). Methoden: `initialize`,
  `notifications/initialized`, `ping`, `tools/list`, `tools/call`.
- **Ein Tool `speak`:** Input-Schema exakt nach Brief — `{text: string, priority?,
  provider?, lang?, now?}`, `required: ["text"]`, enums für priority/lang (Test prüft
  Exactly-those-5-Properties).
- **`tools/call` = `POST /speak`:** Beide Türen fahren denselben Aufnahme-Pfad
  `admitSpeak` (Refactoring in `internal/api/server.go`): Validierung → Mute-Check →
  Enqueue inkl. Gesetz (Rate-Limit-Budget, Ruhezeit; Rangordnung mute > now > quiet >
  rate aus Task 05 bleibt unverändert in `internal/queue`). Kein Contract-Drift möglich.
- **Ergebnis-Texte:** Erfolg → `queued: <id>`; Mute → `muted: Ansage verworfen (Mute
  ist aktiv)`; Verwurf → `discarded: rate_limit …` / `discarded: quiet_hours …`
  (+ Toast-Hinweis). **Bewusst `isError: false`** bei muted/discarded (deliberate
  Decision laut Brief: dokumentiertes Aufnahme-Ergebnis, kein Protokollfehler — der
  Agent soll den Grund lesen, nicht crashen).
- **`GET /status`:** additives Feld `mcp: true` (Test `TestStatusMCPFeld`).
- Daemon-Log-Zeile nennt jetzt cors-Liste und mcp.

## MCP-Protokoll-Entscheidungen (dokumentationspflichtig)

1. **Version-Handling:** `initialize` **echot die angefragte `protocolVersion`**
   (akzeptiert sie); fehlt sie, antwortet talkd mit `2025-06-18`. Inhaltlich
   implementiert ist der 2025-06-18-Umfang: Initialize-Ergebnis mit
   `protocolVersion`, `capabilities: {tools: {}}`, `serverInfo: {name: "talkd",
   version: <daemon-version>}`; Streamable HTTP auf einem Endpoint; keine Batches
   (seit 2025-06-18 entfernt → `-32600` mit klarer Meldung). Getestet: Echo von
   `2025-06-18` und `2025-03-26`.
2. **GET /mcp:** talkd pusht nie (statische Tool-Liste, keine Server-Notifications,
   kein Sampling) — server-initiierte SSE-Streams entfallen daher komplett. `GET /mcp`
   antwortet **`405 Method Not Allowed` mit `Allow: POST, OPTIONS`** — exakt die im
   Streamable-HTTP-Transport vorgesehene Antwort für Server ohne Server-Streams.
   `DELETE /mcp` (Session-Terminierung) fällt auf den auto-405 des Routers.
3. **Content-Types:** Antworten auf Requests: `200 OK` + `application/json` — auch für
   JSON-RPC-Fehlerobjekte (der HTTP-Teil war erfolgreich; getestet in
   `TestMCPFehlerPfade`). Notifications: `202 Accepted` mit leerem Body (JSON-RPC 2.0:
   nie eine Antwort). Requests: der Daemon erzwingt kein `Content-Type` (curl-freundlich,
   strikter wäre SDK-Komfort ohne Vertragsgewinn).
4. **Zustandslos, keine Session-Enforcement:** Jeder POST ist unabhängig; `Mcp-Session-Id`
   wird ignoriert (nie gesetzt), und die Initialize-vor-allem-Regel wird NICHT erzwungen —
   ein curl kann `tools/call` direkt rufen. MCP-Clients fahren den Handshake freiwillig;
   Tests fahren ihn als volle Sequenz.
5. **JSON-RPC-Subset-Details:** Notification = `id` fehlt oder ist explizit `null`
   (→ 202; unbekannte Notifications werden still ignoriert). Fehlercodes: kaputtes
   JSON `-32700`, falsche jsonrpc-Version/Batch `-32600`, unbekannte Methode `-32601`,
   Validierung/unbekanntes Tool `-32602`, interner Fehler (enqueue, HTTP-Äquivalent
   503) `-32603`. HTTP-400-Validierung mapped also auf `-32602` + deutscher Klartext
   (identische Meldungen wie POST /speak). `id` wird roh geechot (number/string/
   null-sicher via `json.RawMessage`). `ping` → leeres Result (billig, hilft Clients).
   Body-Limit 64 KiB wie /speak.
6. **Kein CORS auf /mcp** (bindend: CORS nur auf POST /speak) — MCP-Clients sind keine
   Browser. Sollte später ein Browser-MCP-Client entstehen, muss die Tür explizit
   erweitert werden (bewusste Grenze, Spec: „LibreChat-Frontend-Anbindung out of scope").

## Tests (Prozessgrenze, primäre Seam — harness erweitert, nicht ersetzt)

`test/harness_test.go`: `statusBody` +`mcp`/`cors`; neue Helfer `doRequest` (rohe
HTTP-Requests mit Headern), `preflight`, `mcpPost` (literale JSON-RPC-Payloads, kein
Client-SDK), `mcpDecode`.

- **`test/cors_test.go`:** Preflight von gelisteter Origin → 204 + alle Header
  (Abnahmekriterium); ungeliste Origin → kein ACAO; echter POST mit/ohne gelistete
  Origin; leere Liste → gar keine CORS-Header (Default); Wildcard `*` → ACAO `*`;
  CORS nur auf /speak (OPTIONS /status 405, GET /status ohne ACAO); `cors`-Feld in
  /status (gelistet + `[]` bei leerer Liste).
- **`test/mcp_test.go`:** kompletter Handshake als literal JSON-RPC über HTTP —
  initialize (Version-Echo 2025-06-18 und 2025-03-26, capabilities.tools, serverInfo)
  → notifications/initialized (202, leerer Body) → tools/list (genau speak, Schema mit
  required=[text], genau die 5 Properties) → tools/call (`queued: <id>`, isError
  falsch, **Ansage am Fake-Provider sichtbar** = echte Queue-Aufnahme, Abnahmekriterium).
  Gesetze: muted → isError:false + „muted …", keine Synthese; rate_limit (30 s) →
  zweite low verworfen als „discarded: rate_limit …"; quiet_hours → „discarded:
  quiet_hours …". Fehlerpfade: text fehlt/leer, bad priority, unbekanntes Tool,
  unbekannte Methode, kaputtes JSON, falsche jsonrpc-Version, Batch — je korrekter
  Code + Meldungsanteil, Status 200; ping; GET /mcp → 405 + Allow; unbekannte
  Notification still 202. Alle Daemons auf ephemeralen Ports (TALK_PORT), isoliertes
  HOME/XDG, sink=null, Fake-Provider.

## Verifikation

- `gofmt -l .` leer; `go vet ./...` grün; `go build ./...` grün;
  `go test ./...` komplett grün (inkl. aller Tasks 1–5-Tests, keine Regressionen —
  die CLI dekodiert /status mit den additiven Feldern ohne Anpassung).
- **Cross-Compile-Smoke** (CGO_ENABLED=0): `GOOS=darwin GOARCH=amd64` und
  `GOOS=windows GOARCH=amd64` für `talk` UND `talkd` gebaut — erfolgreich.

## Self-Review (git diff 24ceff3..HEAD)

- Ein Verantwortlicher pro Datei: cors.go (CORS), mcp.go (MCP), server.go (Routing +
  admitSpeak-Refactoring), config.go (Liste + Env), Tests getrennt nach(cors|mcp).
- `admitSpeak` ist die einzige Aufnahme-Stelle — POST /speak-Verhalten unverändert
  (alle Task-04/05-Prozesstests laufen unverändert grün).
- Keine Abnahme-Lücken gegenüber dem Brief: alle vier bindenden Testszenarien
  (preflight gelistet / ungelistet / leere Liste / \*), Handshake + tools/call mit
  Fake-Beobachtung, /status-Felder, curl-Sequenz in README.

## Concerns / Grenzen

- `notifications/initialized` MIT id (falsch benutzter Client) bekommt ein leeres
  Result statt Fehler (tolerante Wahl, dokumentiert im Code).
- CORS-Preflight wird bewusst auch bei fehlendem `Origin`-Header mit 204 beantwortet
  (kein CORS-Kontext, keine Header) — harmlos, dokumentiert.
- OS-Toast in Ruhezeit bleibt wie in Task 5 eine Log-Zeile (Notification-Anbindung
  folgt später) — betrifft MCP-/CORS-Pfad nicht.