- 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
137 lines
5.2 KiB
Markdown
137 lines
5.2 KiB
Markdown
# 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.
|