Projekt-Spezifikation für StarCraft-Kampagnen-MCP-Server in README festhalten

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NaZBZofC1on2gkSMb5UWZy

README.md

@@ -1 +1,155 @@
-# Star-Edit
+# Star-Edit — StarCraft-Kampagnen-MCP-Server ("Missions-Baumeister")
+
+> **Status:** Planung / Spezifikation. Dieses Dokument hält den kompletten Auftrag
+> fest, bevor Code gebaut wird. Es dient als verbindliche Vorlage für die Umsetzung.
+
+## Ziel in einem Satz
+
+Ein **MCP-Server**, der Claude in die Lage versetzt, aus der Kreativ-Seite einer
+StarCraft-Brood-War-Kampagne (Story, Dialoge, Voiceover, Sounds, Missionsablauf)
+echte, spielbare `.scm`/`.scx`-Missionsdateien zu bauen — also komplette
+Missions-Logik, Texte und Sound-Einbettung.
+
+**Wichtig:** Das **Gelände wird nicht generiert**. Jede Mission startet von einer
+vorhandenen Basis-Karte als Leinwand; der Server bearbeitet nur die Daten-/Logik-
+Sektionen darin.
+
+## Rollenverteilung
+
+- **Ich (Auftraggeber):** liefere die Kreativ-Seite — Story, Dialoge, Voiceover,
+  Sounds, Missionsablauf. Null Programmierkenntnisse. Will am Ende **einen Befehl**
+  ausführen und eine **URL** in Claude eintragen.
+- **Claude + MCP-Server:** setzt die Kreativ-Vorlage in echte Missionsdateien um.
+
+## Technische Basis
+
+- **Karten-Manipulation:** Python-Bibliothek **RichChk** (PyPI: `richchk`).
+  - `pip install richchk` funktioniert; bringt StormLib mit, läuft auf Linux
+    (getestet — `StarCraftMpqIoHelper.create_mpq_io()` startet ohne Fehler).
+- **Bestätigte Einstiegspunkte** (Signaturen vor dem Coden per Introspektion final
+  prüfen, da sie je nach Version leicht abweichen):
+
+  Lesen/Schreiben von Karten (MPQ-Container):
+  ```python
+  from richchk.io.mpq.starcraft_mpq_io_helper import StarCraftMpqIoHelper
+  mpq_io = StarCraftMpqIoHelper.create_mpq_io()
+  rich_chk = mpq_io.read_chk_from_mpq("/pfad/map.scx")          # -> RichChk-Modell
+  mpq_io.save_chk_to_mpq(rich_chk, "/pfad/basis.scx", "/pfad/out.scx")
+  ```
+
+  Bearbeiten:
+  ```python
+  from richchk.editor.richchk.rich_chk_editor import RichChkEditor
+  new_chk = RichChkEditor().replace_chk_section(neue_sektion, rich_chk)
+  rich_chk.get_sections_by_name(...)   # vorhandene Sektionen abfragen
+  rich_chk.chk_sections                # alle Sektionen
+  ```
+
+- **Fertige Editoren** unter `richchk.editor.richchk.*`:
+  **trig** (Trigger), **mrgn** (Locations), **unis/unix** (Einheiten-Werte),
+  **forc** (Forces/Fraktionen), **ownr** (Owner), **side** (Rassen),
+  **swnm** (Switches), **uprp** (Unit Properties), **wav** (Sounds).
+- **Rich-Modelle** (Trigger, Conditions, Actions, Locations, …) unter
+  `richchk.model.richchk.*`.
+
+**Herzstück = Trigger.** Fast die gesamte Kampagnen-Logik wird über Trigger
+abgebildet: Gegnerwellen, Verstärkungen, Einheiten spawnen, Story-Text einblenden,
+Funksprüche mit Portrait, WAV-Sounds abspielen, Missionsziele, Sieg/Niederlage,
+Timer, AI-Skripte starten. Das Trigger-Tool muss ausdrucksstark und gut
+dokumentiert sein (unterstützte Condition-/Action-Typen in der Tool-Beschreibung).
+
+### Erster Arbeitsschritt (vor dem Tool-Coding)
+
+1. `richchk` installieren.
+2. README/Quellen des GitHub-Repos "richchk" lesen.
+3. Installiertes Paket per Introspektion inspizieren, um die echten Klassen für
+   Trigger (Conditions/Actions), Locations, Forces etc. zu lernen.
+4. **Keine erratenen Methodennamen** schreiben.
+
+## Stack & Architektur
+
+| Aspekt        | Wahl |
+|---------------|------|
+| Sprache       | Python 3.12 |
+| MCP-Framework | FastMCP (offizielles `mcp`-SDK, `pip install "mcp[cli]"`) |
+| Transport     | stdio (lokaler Test) + **Streamable HTTP** (Dauerbetrieb VPS) |
+| Betrieb       | Docker-Container, eingebunden ins bestehende docker-compose Setup |
+| Reverse-Proxy | Caddy (läuft bereits) → TLS-Subdomain, z.B. `sc-mcp.pixel-by-design.de` |
+| Karten-Volume | gemountetes Volume (z.B. `/data/maps`) für Basis-Karten, WAVs, Missionen |
+
+## Tools (Prefix `sc_`)
+
+| Tool | Zweck | Hints |
+|------|-------|-------|
+| `sc_list_maps` | listet `.scm`/`.scx`-Dateien im Karten-Verzeichnis | readOnly |
+| `sc_describe_map` | menschenlesbare Übersicht: Tileset, Größe, Forces/Player-Setup, Rassen, Locations, Trigger-Zusammenfassung | readOnly |
+| `sc_list_locations` | Locations (MRGN) auflisten | readOnly |
+| `sc_create_location` | Location anlegen | — |
+| `sc_rename_location` | Location umbenennen | — |
+| `sc_set_player_setup` | Forces (forc), Owner (ownr), Rassen (side) setzen | — |
+| `sc_add_trigger` | **Kern-Tool.** Trigger mit Conditions + Actions + betroffenen Playern hinzufügen | — |
+| `sc_list_triggers` | Trigger auflisten | readOnly |
+| `sc_remove_trigger` | einzelnen Trigger entfernen | destructive |
+| `sc_clear_triggers` | alle Trigger entfernen | destructive |
+| `sc_embed_wav` | WAV-Datei einbetten und referenzierbar machen (wav-Editor) | — |
+| `sc_save_map` | bearbeitetes Modell als neue `.scm`/`.scx` schreiben (`save_chk_to_mpq`, Basis-Karte als Vorlage) | — |
+| `sc_set_briefing` | **optional / experimentell.** Mission-Briefing (MBRF). Falls kein High-Level-Editor: als TODO markieren, kein Blocker | — |
+
+### `sc_add_trigger` — Mindest-Abdeckung
+
+Strukturierte Eingabe (Liste von Conditions, Liste von Actions, betroffene Player).
+Muss u.a. abdecken:
+- Einheiten erzeugen an Location
+- Text einblenden (Display Text Message)
+- Transmission mit Portrait + WAV
+- Play WAV
+- Sieg-/Niederlagebedingungen
+- Timer
+- AI-Skript ausführen
+
+### Anforderungen pro Tool
+
+- Klare Beschreibung.
+- Sinnvolle **Pydantic**-Eingabeschemas mit Feldbeschreibungen.
+- Hilfreiche Fehlermeldungen, z.B.
+  `"Location 'Basis' existiert nicht – verfügbar: …"`.
+- `readOnlyHint`/`destructiveHint`-Annotationen passend gesetzt.
+
+## Definition of Done — Selbsttest
+
+Ein kurzer Selbsttest beweist die ganze Pipeline:
+
+1. Basis-Karte aus `/data/maps` laden.
+2. Eine Location anlegen.
+3. Per Trigger hinzufügen: bei Spielstart eine Texteinblendung
+   `"Mission 1 – Start"` **und** das Erzeugen von ein paar Einheiten an der Location.
+4. Als neue `.scx` speichern.
+5. Neue Datei erneut laden und bestätigen, dass Trigger + Location wirklich drin sind.
+
+Läuft das durch, steht das Fundament.
+
+## Liefergegenstände
+
+- [ ] Server läuft als Docker-Service, erreichbar über die TLS-Subdomain.
+- [ ] **Ein** Start-/Neustart-Befehl.
+- [ ] Die Connector-URL für Claude (Custom Connector).
+- [ ] Beispiel-Basis-Karte liegt bereits in `/data/maps`.
+- [ ] `README.md` mit Startbefehl, Subdomain-URL und Anleitung für den Custom
+      Connector in Claude.
+
+## Defaults / Entscheidungen
+
+> Hier werden während der Umsetzung die getroffenen Default-Entscheidungen
+> dokumentiert, damit am Ende klar ist, was gewählt wurde (keine technischen
+> Rückfragen, wo selbst entscheidbar).
+
+- _(wird ergänzt)_
+
+## Offene TODOs
+
+- [ ] `richchk` installieren & per Introspektion echte Klassen verifizieren.
+- [ ] Projektstruktur (FastMCP-Server, Pydantic-Schemas, Tool-Module) anlegen.
+- [ ] Self-Test-Skript schreiben.
+- [ ] Dockerfile + docker-compose-Service + Caddy-Reverse-Proxy-Eintrag.
+- [ ] Beispiel-Basis-Karte bereitstellen.
+- [ ] `sc_set_briefing` (MBRF) als best-effort prüfen.