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

137 lines
5.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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()`:
```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.