diff --git a/ANLEITUNG.md b/ANLEITUNG.md new file mode 100644 index 0000000..1ba0660 --- /dev/null +++ b/ANLEITUNG.md @@ -0,0 +1,258 @@ +# Anleitung: StarCraft-Kampagnen-MCP-Server einrichten & benutzen + +Diese Anleitung ist für **null Programmierkenntnisse** gedacht. Du tippst nur die +fettgedruckten Befehle ab. Wenn etwas von *deinem* Setup abhängt, steht ausdrücklich +dabei „**das musst du anpassen**". + +--- + +## 0. Was du brauchst (Checkliste) + +- [ ] **Zugang zu deinem Hetzner-VPS** (per SSH – also das schwarze Terminal-Fenster, + mit dem du dich auf den Server einloggst). +- [ ] Auf dem VPS sind **Docker** und **Caddy** installiert und laufen bereits + (hast du). Caddy ist dein „Türsteher", der die Webadresse + das Sicherheitsschloss + (TLS/https) bereitstellt. +- [ ] Eine **Subdomain**, z.B. `sc-mcp.pixel-by-design.de`, deren DNS-Eintrag auf die + IP-Adresse deines VPS zeigt. (Einstellung beim Anbieter, wo deine Domain liegt.) +- [ ] Ein **Claude-Bezahl-Account** (Pro, Max, Team oder Enterprise). Nur diese können + eigene „Custom Connectors" hinzufügen – im Gratis-Account fehlt die Funktion. +- [ ] **Basis-Karten** (`.scx`/`.scm`) und optionale **WAV-Sounddateien**, aus denen + Claude Missionen bauen soll. Eine Beispiel-Karte liegt schon dabei. + +> **Begriffe in einem Satz:** +> *MCP-Server* = das Programm, das Karten lesen/schreiben kann. +> *Connector* = die Verbindung, über die Claude dieses Programm benutzt. +> *Docker* = verpackt das Programm so, dass es überall gleich startet. +> *Caddy* = stellt die https-Webadresse bereit. + +--- + +## Teil A — Einmalig einrichten (ca. 15 Minuten) + +### A1. Auf den Server einloggen + +Öffne ein Terminal auf deinem Computer und logge dich auf dem VPS ein (Adresse/Benutzer +hast du von Hetzner): + +```bash +ssh dein-benutzer@deine-server-ip +``` + +Alle weiteren Befehle tippst du **auf dem Server** (im eingeloggten Fenster). + +### A2. Das Projekt auf den Server holen + +```bash +git clone https://github.com/Kenearos/Star-Edit.git +cd Star-Edit +``` + +Falls du das Projekt schon mal geholt hast, hol nur die neueste Version: + +```bash +cd Star-Edit +git pull origin main +``` + +### A3. Das Docker-Netzwerk von Caddy herausfinden — **das musst du anpassen** + +Damit Caddy mit unserem Server reden kann, müssen beide im selben Docker-Netzwerk sein. +Zeig dir die vorhandenen Netzwerke an: + +```bash +docker network ls +``` + +Suche den Namen, den **dein Caddy** benutzt (oft `caddy`, manchmal `web`, `proxy` o.ä.). +Trage diesen Namen in die Datei `docker-compose.yml` ein – ganz unten steht: + +```yaml +networks: + web: + external: true + name: caddy # <-- hier den echten Netzwerknamen eintragen +``` + +Bearbeiten kannst du die Datei z.B. mit dem Editor `nano`: + +```bash +nano docker-compose.yml +``` + +(Ändern, dann mit `Strg+O`, `Enter` speichern und `Strg+X` schließen.) + +> Wenn du dir unsicher bist, welches Netzwerk Caddy nutzt: +> `docker inspect | grep -i network` zeigt es an. + +### A4. Subdomain auf den Server zeigen lassen (DNS) — **das musst du anpassen** + +Beim Anbieter deiner Domain legst du einen **A-Record** an: + +| Typ | Name (Host) | Wert (Ziel) | +|-----|-------------|-------------| +| A | `sc-mcp` | *die IP-Adresse deines VPS* | + +Damit wird `sc-mcp.pixel-by-design.de` auf deinen Server gezeigt. (Kann ein paar Minuten +bis Stunden dauern, bis es überall aktiv ist.) + +### A5. Caddy für die Subdomain konfigurieren + +Öffne deine bestehende Caddy-Konfiguration (deine `Caddyfile`) und füge diesen Block +hinzu – er steht auch in der mitgelieferten Datei [`Caddyfile`](./Caddyfile): + +```caddy +sc-mcp.pixel-by-design.de { + reverse_proxy sc-mcp:8000 +} +``` + +Das heißt: „Alles, was an `sc-mcp.pixel-by-design.de` ankommt, leite an unseren Server +weiter." Caddy holt das https-Zertifikat automatisch. + +Danach Caddy neu laden (je nach deinem Setup einer dieser Befehle): + +```bash +docker exec -w /etc/caddy caddy reload +# oder, falls Caddy nicht in Docker läuft: +sudo systemctl reload caddy +``` + +> Falls du die Subdomain im selben Reverse-Proxy noch nicht hattest: `` +> findest du mit `docker ps` (Spalte NAMES). + +### A6. Den Server starten (der eine Befehl) + +```bash +./run.sh +``` + +Das baut beim ersten Mal das Programm (dauert 1–2 Minuten) und startet es. Fertig sieht +so aus, dass kein Fehler erscheint und der Server läuft. + +Prüfen, ob er läuft: + +```bash +./run.sh logs +``` + +(Mit `Strg+C` schließt du die Log-Ansicht wieder – der Server läuft weiter.) + +**Schnelltest, ob alles greift** (baut testweise eine Mini-Mission): + +```bash +./run.sh selftest +``` + +Wenn am Ende **„SELBSTTEST BESTANDEN"** steht, ist das Fundament in Ordnung. + +### A7. In Claude als Connector eintragen + +1. Claude öffnen (Web oder App) → **Einstellungen** → **Connectors** (bzw. + „Connectors verwalten"). +2. **Custom Connector hinzufügen** wählen. +3. Als Adresse/URL eintragen: + + ``` + https://sc-mcp.pixel-by-design.de/mcp + ``` + + (Wichtig: das `/mcp` am Ende gehört dazu.) +4. Speichern. Ab jetzt darf Claude im Chat die `sc_`-Werkzeuge benutzen. + +--- + +## Teil B — Eine Mission bauen (so läuft es im Alltag) + +### B1. Karten & Sounds bereitstellen + +Lege deine Dateien auf dem Server in den Ordner `Star-Edit/data/maps/`: + +- Basis-Karten: `.scx` oder `.scm` +- Sounds/Voiceover: `.wav` + +Hochladen z.B. vom eigenen Rechner aus (in einem **neuen** Terminal, *nicht* eingeloggt +auf dem Server): + +```bash +scp meine-karte.scx funk1.wav dein-benutzer@deine-server-ip:~/Star-Edit/data/maps/ +``` + +Eine Beispiel-Karte (`base-map.scx`) liegt bereits drin – du kannst sofort loslegen. + +### B2. Mit Claude im Chat arbeiten + +Schreib Claude einfach, was du willst – auf Deutsch. Claude ruft dann selbst die +Werkzeuge auf. Beispiele: + +> „Zeig mir die vorhandenen Karten." +> → Claude nutzt `sc_list_maps`. + +> „Beschreib mir die Karte `base-map.scx`." +> → Claude nutzt `sc_describe_map` (Größe, Spieler, Locations, Trigger). + +> „Erstelle auf `base-map.scx` bei Spielstart eine Texteinblendung ‚Mission 1 – Start' +> und spawne 4 Marines für Spieler 1 an einer neuen Location ‚Basis' in der Kartenmitte. +> Speichere das Ergebnis als `mission1.scx`." +> → Claude legt die Location an (`sc_create_location`), baut den Trigger +> (`sc_add_trigger`) und speichert (`sc_save_map`). + +Für **Voiceover/Funksprüche**: + +> „Bette `funk1.wav` ein und spiel es bei Sekunde 30 zusammen mit dem Text +> ‚Achtung, Feindkontakt!' ab." +> → Claude nutzt `sc_embed_wav` + `sc_add_trigger` (play_wav + display_text). + +### B3. Ergebnis abholen + +Die fertige Mission liegt danach in `Star-Edit/data/maps/` (z.B. `mission1.scx`). Auf den +eigenen Rechner herunterladen: + +```bash +scp dein-benutzer@deine-server-ip:~/Star-Edit/data/maps/mission1.scx . +``` + +Diese Datei kannst du in StarCraft laden und spielen. + +--- + +## Teil C — Befehls-Spickzettel (auf dem Server, im Ordner `Star-Edit`) + +| Was du willst | Befehl | +|---------------|--------| +| Server starten / neu starten | `./run.sh` | +| Logs ansehen (beenden mit Strg+C) | `./run.sh logs` | +| Selbsttest laufen lassen | `./run.sh selftest` | +| Server stoppen | `./run.sh stop` | +| Neueste Programmversion holen | `git pull origin main` danach `./run.sh` | + +--- + +## Teil D — Wenn etwas klemmt + +- **Claude sagt, der Connector ist nicht erreichbar.** + 1. Läuft der Server? `./run.sh logs` ansehen. + 2. Zeigt die Subdomain schon auf den Server? Im Browser `https://sc-mcp.pixel-by-design.de/mcp` + öffnen – kommt *irgendeine* Antwort (kein „Server nicht gefunden"), passt das Grundsätzliche. + 3. Sind Caddy und der `sc-mcp`-Container im **selben** Docker-Netzwerk (Schritt A3)? + +- **„network caddy not found" o.ä. beim Start.** + Der Netzwerkname in `docker-compose.yml` stimmt nicht mit deinem Caddy-Netzwerk + überein → Schritt A3 wiederholen (`docker network ls`). + +- **Claude findet eine Location/Einheit nicht.** + Die Fehlermeldung listet die verfügbaren Namen auf – einfach einen davon nehmen oder + die Location vorher anlegen lassen. + +- **Ich will den Server ohne Caddy nur kurz lokal testen.** + In `docker-compose.yml` die zwei `ports:`-Zeilen einkommentieren (`# ports:` und + `# - "8000:8000"`), dann `./run.sh`. Endpunkt: `http://deine-server-ip:8000/mcp`. + +--- + +## Sicherheitshinweis + +Der Server hat **kein Passwort**: Wer die URL `https://sc-mcp.pixel-by-design.de/mcp` +kennt, kann ihn benutzen. Für ein privates Werkzeug ist das meist okay – halte die URL +aber für dich. Wenn du später einen Zugriffsschutz möchtest, sag Bescheid, dann bauen wir +einen (z.B. ein Token in Caddy) ein.