From 53c8498bc56f5f553dc78f096adf378b59711b4e Mon Sep 17 00:00:00 2001 From: torsten Date: Sun, 1 Nov 2026 14:15:16 +0100 Subject: [PATCH] docs: Godot AI Bridge und MCP-Setup festhalten - neues Findings-Dokument beschreibt Aufbau (Node, godot-mcp, Bridge), Live-Editor-Anbindung, Sicherheit und das Vorgehen beim Addon-Update - der lokale Patch am vendored Addon ist inklusive Diff dokumentiert, damit ein Neukopieren aus /opt/godot-mcp die Leak-Warnung nicht zurueckbringt - AGENTS.md verweist fuer Agenten auf den Patch und die Blender-Gegenstelle - architecture.md: letzte Session aktualisiert --- AGENTS.md | 12 ++ docs/architecture.md | 4 +- docs/findings-2026-11-01-godot-ai-bridge.md | 137 ++++++++++++++++++++ 3 files changed, 151 insertions(+), 2 deletions(-) create mode 100644 docs/findings-2026-11-01-godot-ai-bridge.md diff --git a/AGENTS.md b/AGENTS.md index daa2e2c..2278436 100755 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,3 +10,15 @@ Beim Hochladen eines macOS-Builds auf den Webspace (programmschmiede.de): und verlinkt. (Stand 2026-10-31 so vom Nutzer gewünscht.) - Download-Links relativ zur `index.html` setzen, z. B. `rinkplanner/download/rinkplanner.zip`. + +## MCP-Werkzeuge + +- **Godot:** `godot-mcp` steuert das Projekt über `--project rinkplanner/rinkplanner`. + Die Live-Editor-Werkzeuge brauchen das Addon `rinkplanner/addons/godot_ai_bridge` + (Port 6550, startet mit dem Editor). +- `godot_ai_bridge` ist eine Kopie aus `/opt/godot-mcp` **mit lokalem Patch**. + Beim Neukopieren den Patch aus `docs/findings-2026-11-01-godot-ai-bridge.md` + erneut anwenden, sonst meldet jeder `--import`-Lauf + „6 ObjectDB instances leaked at exit". +- **Blender:** `mcp-for-blender` über `uvx`, Addon in + `~/.config/blender/5.2/scripts/addons/blender_mcp.py` (Port 9876). diff --git a/docs/architecture.md b/docs/architecture.md index ac7ae8d..85764f6 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -3,8 +3,8 @@ Stand: 2026-11-01 Grundlage: `rinkplanner/rinkplanner_definition_agent_guidelines.md` Übergeordnete Reihenfolge: `docs/roadmap.md` -Letzte Session: `docs/findings-2026-10-31-arm-gewichte.md` -(Session davor: `docs/findings-2026-10-31-kamera-rueckwaerts.md`) +Letzte Session: `docs/findings-2026-11-01-godot-ai-bridge.md` +(Session davor: `docs/findings-2026-10-31-arm-gewichte.md`) ## 1. Leitentscheidung diff --git a/docs/findings-2026-11-01-godot-ai-bridge.md b/docs/findings-2026-11-01-godot-ai-bridge.md new file mode 100644 index 0000000..5c4a9c2 --- /dev/null +++ b/docs/findings-2026-11-01-godot-ai-bridge.md @@ -0,0 +1,137 @@ +# Findings 2026-11-01 – Godot AI Bridge und MCP-Werkzeuge + +## Ziel + +`godot-mcp` in OpenCode nutzbar machen, inklusive der Live-Editor-Werkzeuge, +die das Addon **Godot AI Bridge** im Projekt brauchen. + +## Aufbau + +| Komponente | Ort | Zweck | +| :--- | :--- | :--- | +| Node.js 24.22.2 LTS | `/opt/node` → `/opt/node-v24.22.2-linux-x64`, Symlinks in `~/.local/bin` | Laufzeit für den MCP-Server (war vorher nicht installiert) | +| godot-mcp 0.2.0 | `/opt/godot-mcp`, Start über `dist/index.js` | MCP-Server, 90 Werkzeuge in 13 Kategorien | +| OpenCode-Eintrag | `~/.config/opencode/opencode.jsonc`, `mcp.servers.godot-mcp` | `node /opt/godot-mcp/dist/index.js --project /rinkplanner/rinkplanner` | +| Godot AI Bridge | `rinkplanner/addons/godot_ai_bridge` | WebSocket-Server im Editor, Port 6550 | + +Der MCP-Eintrag läuft global, der `--project`-Pfad zeigt aber fest auf dieses +Projekt. Für andere Godot-Projekte braucht es dort eine eigene +`.opencode/opencode.jsonc` mit passendem `--project`. + +Ohne laufenden Editor arbeiten die dateibasierten Werkzeuge (Szenen, Skripte, +Shader, Ressourcen, Input-Map, Audio, Animation) direkt auf dem Projekt. + +## Live-Editor-Anbindung + +- Der Editor lauscht nur auf `127.0.0.1:6550`. +- Die Paarung läuft über ein Token in `res://.godot/godot-ai-bridge.json`. +- Der Autoload `GodotAIBridgeRuntime` (`addons/godot_ai_bridge/runtime_bridge.gd`) + ist in `project.godot` eingetragen, wird aber nur aktiv, wenn + `EngineDebugger.is_active()` gilt – also beim Start aus dem Editor. In + Exporten öffnet sich kein Port. + +## Lokaler Patch am Addon + +Das Addon ist eine Kopie aus `/opt/godot-mcp/addons/godot_ai_bridge` (0.1.0) +und enthält **eine lokale Änderung**, die beim Neukopieren verloren geht. + +**Symptom** – jeder `--import`-Lauf meldete: + +``` +WARNING: 6 ObjectDB instances were leaked at exit +Leaked instance: GDScriptNativeClass … +Leaked instance: GDScript … +Leaked instance: RefCounted … +Leaked instance: EditorDebuggerPlugin … +Resource still in use: res://addons/godot_ai_bridge/message_handler.gd +``` + +**Ursache** + +- `MessageHandler` und `AIBridgeDebuggerPlugin` halten sich gegenseitig als + `RefCounted` (`message_handler.debugger_plugin` / + `debugger_plugin.message_handler`). Der Zyklus wird nie freigegeben. +- Der WebSocket-Server wurde in `_exit_tree()` mit `queue_free()` freigegeben. + Beim Beenden läuft kein Deferred-Call mehr, der Server blieb also stehen. + +**Lösung** in `godot_ai_bridge.gd`, `_exit_tree()`: + +```diff + if _debugger_plugin: + remove_debugger_plugin(_debugger_plugin) +- _debugger_plugin = null ++ # Lokaler Patch: MessageHandler und DebuggerPlugin halten sich gegenseitig ++ # als RefCounted, der Zyklus wird beim Beenden sonst nie freigegeben ++ # ("ObjectDB instances leaked at exit"). ++ _debugger_plugin.message_handler = null ++ _debugger_plugin = null + if _ws_server: + _ws_server.stop() +- _ws_server.queue_free() ++ _ws_server.free() + _ws_server = null ++if _message_handler: ++ _message_handler.debugger_plugin = null ++ _message_handler.editor_interface = null ++ _message_handler.undo_redo = null + _message_handler = null +``` + +### Addon aktualisieren + +1. Neu kopieren und Rechte setzen: + + ```bash + cp -r /opt/godot-mcp/addons/godot_ai_bridge rinkplanner/addons/ + chmod 644 rinkplanner/addons/godot_ai_bridge/* + ``` + +2. Den Patch oben erneut in `godot_ai_bridge.gd` anwenden. + +3. Prüfen, dass der Import wieder still ist: + + ```bash + /opt/godot/Godot_v4.7.2-stable_linux.x86_64 --headless \ + --path rinkplanner --import 2>&1 | grep -iE 'leaked|still in use' + ``` + + Erwartung: keine Ausgabe. + +4. `./tools/test.sh` laufen lassen (16 Suiten, 1193 Assertions). + +Der Patch ist upstream noch nicht gemeldet; ein `update` des MCP-Servers +(`uvx mcp-for-blender update` betrifft nur Blender) überschreibt die Kopie +nicht, ein erneutes Kopieren aus `/opt/godot-mcp` schon. + +## Verifikation (Stand 2026-11-01) + +| Prüfung | Ergebnis | +| :--- | :--- | +| `opencode mcp list` | `godot-mcp connected` | +| `godot_help` | 90 Werkzeuge, 13 Kategorien | +| `godot_list_scene_nodes` auf `scenes/whiteboard/whiteboard.tscn` | 163 Nodes gelesen | +| `godot_connect` bei laufendem Editor | `success: true`, `ws://127.0.0.1:6550` | +| `godot_editor_get_project_info` | `Rinkplanner`, `4.7.2-stable (official)` | +| `--headless --import` | keine Warnungen, keine Errors | +| `./tools/test.sh` | 16 Suiten, 1193 Assertions grün | + +## Sicherheit + +- Der Server bindet nur an `127.0.0.1` und verlangt ein Paarungstoken. +- Die Editor-Werkzeuge schreiben direkt in Projektdateien (Szenen, Skripte, + `.tres`); vor größeren Umbauten committen. +- Das Blender-Gegenstück (`mcp-for-blender`) führt dagegen beliebigen + Python-Code in Blender aus; dort optional `BLENDER_MCP_SAFE_MODE=1` setzen. + +## Verwandt: Blender MCP + +Für die Rotoscoping-Werkbank ist zusätzlich `mcp-for-blender` eingerichtet: + +| Komponente | Ort | +| :--- | :--- | +| `uv` / `uvx` 0.13.6 | `~/.local/bin` | +| MCP-Server | `uvx mcp-for-blender` (PyPI-Paket `mcp-for-blender`, früher `blender-mcp`) | +| Blender-Addon 1.8 | `~/.config/blender/5.2/scripts/addons/blender_mcp.py`, in Blender aktiviert | +| OpenCode-Eintrag | `~/.config/opencode/opencode.jsonc`, `mcp.servers.blender-mcp` | + +Der Blender-Addon-Server läuft auf Port 9876 und startet mit Blender.