rinkplanner/docs/findings-2026-11-01-godot-ai-bridge.md
torsten 53c8498bc5 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
2026-11-01 14:15:16 +01:00

5.2 KiB
Raw Permalink Blame History

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 <repo>/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():

 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:

    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:

    /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.