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
This commit is contained in:
torsten 2026-11-01 14:15:16 +01:00
parent 045dc57ee9
commit 53c8498bc5
3 changed files with 151 additions and 2 deletions

View file

@ -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).

View file

@ -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

View file

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