---
paths:
  - "**/*.gd"
  - "godot-plugin/**"
---

# MCP Tools & TCP — Pitfalls

## Plugin / TCP

- **Godot cache les scripts @tool** — apres modification d'un .gd, recharger le projet (Project > Reload)
- **`class_name` en double** — ne jamais copier `godot-plugin/` entier dans addons
- **`put_data` TCP sur gros payloads** — screenshots base64 ~100KB+, envoi chunke en 64KB
- **`await` dans `_process`** — interdit en GDScript @tool, tout sync ou deferred
- **`user://` partage** — file-based protocol marche en local (editeur + jeu). Pas en remote debug
- **Multi-client TCP** — chaque session Claude Code = un process golem-mcp = un client TCP. MAX_CLIENTS=5, au-dela rejete. Graceful disconnect (`{"tool": "disconnect"}`) libere le slot
- **Hook PreToolUse probe TCP = connection storm** — cache TTL obligatoire pour tout hook reseau

## Tools MCP — Usage

- **`add_nodes` ne load() pas les Resources** — `"texture": "res://img.png"` → null. Assigner via `execute_script` + `load()`
- **Root node = `"."`** — `update_property(path="Main")` → Node not found. Root = `"."`, enfants = `"Player"`, petits-enfants = `"Player/Sprite"`
- **`anchors_preset` ne reset pas les offsets** — ajouter `offset_left/top/right/bottom = 0` ou `set_anchors_and_offsets_preset()`
- **`execute_script` = contexte editeur** — autoloads inaccessibles. Tester via `play_scene` + `get_logs`
- **`execute_script` code 36 sur scripts complexes** — arrays + boucles = echec. Garder simple ou .gd externe
- **`execute_script` detecte `await`** — pre-compilation scan, message d'erreur recommandant `godot_write_script`
- **`get_input_map` = actions editeur only** — lire `project.godot` section `[input]` pour les actions custom
- **Disconnected ≠ echec** — verifier `get_scene_tree()` avant retry
- **SpriteFrames = execute_script obligatoire** — `SpriteFrames.new()` + `add_animation()` + `add_frame(load(...))`
- **`unique_name_in_owner` non supporte** — activer via `execute_script` : `node.unique_name_in_owner = true`
- **`get_logs` est incremental** — chaque appel = nouvelles lignes seulement. `clear_logs` et `play_scene` remettent a zero

## Runtime & Play

- **MCP deconnecte souvent pendant play** — screenshots et get_scene_tree echouent apres `play_scene`. `get_errors` = fiable. Retry 1-2x max
- **Race condition stop → play** — `play_scene` apres `stop_scene` = "already running". Faire un call intermediaire
- **Game screenshot = best-effort, jamais retry** — JPEG+base64 = gros, TCP timeout possible. Un seul appel. Fail → `get_logs`
- **`get_game_screenshot` requiert GolemCapture** — verifier dans Project Settings > Autoload
- **`Engine.time_scale` trop bas bloque GolemCapture** — minimum safe 0.15

## Scene Editing via MCP

- **JAMAIS editer .tscn / project.godot sur disque** — Godot ecrase au prochain save. Scripts .gd = OK (auto-reload)
- **Sequence** : stop_scene → API calls → save_scene → get_scene_tree (verif) → play_scene
- **project_settings key format** — chemin complet `display/window/size/viewport_width` (pas le format fichier)
- **project_settings ne persiste pas toujours** — verifier avec `get` apres `set`
- **ext_resource orphelins** — `godot_delete_node` + `save_scene` nettoie auto
- **Scripts inline dans .tscn = indentation cassee** — fichiers .gd externes toujours
- **Instanciation scene editeur = aplatie sans `scene_file_path`** — `instantiate(PackedScene.GEN_EDIT_STATE_INSTANCE)` + `add_child()` + `.owner = scene_root` + `.scene_file_path = "res://path.tscn"`
- **Instance overrides dans parent = ignorees** — modifier la source scene, pas l'instance
- **Autoload name = classe native = masque** — prefixer (`GameLogger`, `AppState`)

## Server Modification

- **Ecrire `golem_server.gd` = kill la connexion MCP** — Godot auto-reload @tool scripts. User doit recharger le plugin. Prevenir avant
