# Golem MCP

MCP open-source pour connecter **Claude Code** à **Godot 4.x**.

```
Claude Code ←stdio/MCP→ golem_mcp.py (FastMCP) ←TCP/JSON→ GolemServer (GDScript @tool)
```

## Installation

### Quick install (recommended)

```bash
uvx golem-mcp install /path/to/your/godot-project
```

This copies the plugin, skills, and generates `.mcp.json` automatically.

Then enable the plugin in **Godot > Project Settings > Plugins > Golem MCP**.

### Options

```bash
# Force overwrite existing install
uvx golem-mcp install /path/to/project --force

# Use a local clone instead of uvx (for development)
uvx golem-mcp install /path/to/project --local /path/to/golem-mcp

# Skip skills installation
uvx golem-mcp install /path/to/project --skip-skills
```

### Manual installation

<details>
<summary>If you prefer to install manually</summary>

#### 1. Plugin Godot

Copier le dossier `godot-plugin/` dans ton projet Godot :

```
ton-projet/addons/golem-mcp/ ← contenu de godot-plugin/
```

Activer le plugin : **Project > Project Settings > Plugins > Golem MCP**

#### 2. Serveur MCP Python

```bash
cd golem-mcp
uv sync
```

#### 3. Configuration Claude Code

Créer un `.mcp.json` à la racine de ton projet Godot :

```json
{
  "mcpServers": {
    "godot": {
      "type": "stdio",
      "command": "uvx",
      "args": ["golem-mcp"]
    }
  }
}
```

</details>

### Auto-updates

The plugin checks for updates every 24h via GitHub Releases. When a new version is available, you'll get a dialog in the Godot editor to update in one click.

## Tools disponibles

### Phase 1 — Core
| Tool | Description |
|------|-------------|
| `godot_get_scene_tree` | Arbre de scène hiérarchique |
| `godot_inspect_node` | Propriétés d'un node |
| `godot_get_editor_screenshot` | Capture éditeur |
| `godot_get_game_screenshot` | Capture jeu en cours |
| `godot_play_scene` | Lancer une scène |
| `godot_stop_scene` | Stopper la scène |
| `godot_get_errors` | Récupérer erreurs |
| `godot_clear_logs` | Vider les logs |
| `godot_execute_script` | Exécuter GDScript dans l'éditeur |
| `godot_view_script` | Lire un script |

### Phase 2 — Manipulation
| Tool | Description |
|------|-------------|
| `godot_add_node` | Créer un node |
| `godot_delete_node` | Supprimer un node |
| `godot_update_property` | Modifier une propriété |
| `godot_move_node` | Déplacer dans l'arbre |
| `godot_duplicate_node` | Dupliquer un node |

### Phase 3 — Avancé
| Tool | Description |
|------|-------------|
| `godot_get_input_map` | Lire les actions input |
| `godot_project_settings` | Lire/modifier settings projet |
| `godot_save_scene` | Sauvegarder la scène |

### Phase 3 — Avancé (suite)
| Tool | Description |
|------|-------------|
| `godot_write_script` | Écrire un fichier .gd |
| `godot_attach_script` | Attacher un script à un node |
| `godot_get_logs` | Logs jeu + engine |
| `godot_create_scene` | Créer une nouvelle scène |
| `godot_open_scene` | Ouvrir une scène existante |
| `godot_add_nodes` | Batch: créer une hiérarchie entière |

## Skills (slash commands)

Copier `.claude/commands/*.md` dans `.claude/commands/` de ton projet Godot.

### Workflow Commands

| Skill | Rôle |
|-------|------|
| `/init` | **Bootstrap projet** — vision, gameplay loop, livrables, structure (nouveau projet ou reprise) |
| `/golem-dev` | **Mode MCP** — switch contexte pour travailler sur Golem MCP lui-même |
| `/deliverable <nom>` | **Focus livrable** — implémenter UN livrable jusqu'à complétion |
| `/checkpoint` | **Snapshot état** — scanner le projet, générer CHECKPOINT.md |
| `/references` | **Patterns projet** — voir/éditer les conventions réutilisables |

### Core Skills

| Skill | Rôle |
|-------|------|
| `/godot` | **Routeur principal** — analyse l'intention, scanne le projet, dispatche vers le bon skill |
| `/godot-plan` | Interroger l'idée, produire un mini-PRD + plan séquencé avant toute construction |
| `/godot-architecture` | Architecture modulaire pseudo-ECS : Core, Entities, Mechanics, Data |
| `/godot-scene` | Construire une scène Godot à partir d'une description |
| `/godot-composition` | Structure UI : tokens, rôles, containers, patterns, torture tests |
| `/godot-behavior` | Système nerveux UI : états 3 canaux, tweens, FX, son, fallback perf |
| `/godot-theme` | Design tokens via Theme resource : palette, fonts, spacing, StyleBox |
| `/godot-debug` | Diagnostic séquentiel en 5 étapes + table des bugs courants |
| `/godot-design-audit` | Audit UX via screenshots + inspection, rapport phasé d'améliorations |
| `/godot-status` | Scan projet, DEVLOG.md, progress.txt, suggestions d'amélioration |

## Hooks

Golem MCP fournit 4 hooks Claude Code dans `hooks/` (Python, cross-platform) :

| Hook | Event | Rôle |
|------|-------|------|
| `check_connection.py` | PreToolUse (godot_*) | Vérifie la connexion TCP avant chaque appel MCP |
| `gdscript_lint.py` | PostToolUse (godot_write_script) | Lint basique GDScript après écriture |
| `copy_skills.py` | PostToolUse (Edit/Write) | Auto-copie les skills modifiés vers le projet test (dev) |
| `check_project_sync.py` | PostToolUse (Edit/Write) | Sync livrables, checkpoint, références |

### Installation dans ton projet Godot

Copier le template et adapter les paths :

```bash
cp hooks/settings.example.json ton-projet/.claude/settings.json
# Éditer les paths dans le fichier
```

Ou ajouter manuellement dans `.claude/settings.json` :

```json
{
  "hooks": {
    "PreToolUse": [{
      "matcher": "mcp__godot__.*",
      "hooks": [{"type": "command", "command": "python3 /chemin/vers/golem-mcp/hooks/check_connection.py", "timeout": 3}]
    }],
    "PostToolUse": [{
      "matcher": "mcp__godot__godot_write_script",
      "hooks": [{"type": "command", "command": "python3 /chemin/vers/golem-mcp/hooks/gdscript_lint.py", "timeout": 5}]
    }]
  }
}
```

## Workflow recommandé

### Nouveau projet (complet)
```
/init → /deliverable <premier> → /checkpoint → /deliverable <suivant> → ...
```

1. **`/init`** — Bootstrap complet : vision, gameplay loop, vertical slice, livrables, structure
2. **`/deliverable <nom>`** — Implémenter UN livrable jusqu'à complétion
3. **`/checkpoint`** — Snapshot état, valider les progrès
4. Répéter jusqu'au vertical slice complet

### Reprise de projet
```
/init (détecte l'état) → /checkpoint → /deliverable <en_cours>
```
`/init` détecte automatiquement les fichiers existants et propose de reprendre.

### Travailler sur Golem MCP
```
/golem-dev
```
Switch de contexte pour modifier le MCP lui-même. Revenir avec `/init` ou tout skill Godot.

### Workflow classique (sans livrables)
```
/godot-plan  →  /godot-architecture  →  /godot-scene  →  /godot-theme  →  /godot-status
```

1. **`/godot-plan`** — Définir la vision, les mécaniques, le feeling visé. Produit `GAME_PLAN.md`
2. **`/godot-architecture`** — Scaffolder Core (EventBus, GameState), structure dossiers
3. **`/godot-scene`** — Construire les scènes une par une selon le plan
4. **`/godot-theme`** — Design system si UI (palette, fonts, StyleBox)
5. **`/godot-status`** — Documenter l'état du projet (DEVLOG.md, progress.txt)

### Construire une UI
```
/godot-composition  →  /godot-theme  →  /godot-behavior
```
La **structure** (containers, tokens, rôles) AVANT le **thème** AVANT le **behavior** (animations, états).

### Debug
```
/godot-debug  →  fix  →  /godot-status
```
Route directe — pas de prérequis.

### Prototypage rapide
```
/godot-scene  (mode QUICK, sans plan ni archi)
```
Pour tester une idée vite. Transition vers le flow complet si le proto marche.

## Troubleshooting

### "Connection refused" / Port non disponible

**Symptôme** : Le hook `check_connection.py` bloque avec "Godot n'est pas connecté"

**Causes possibles** :
1. Godot n'est pas ouvert
2. Le plugin Golem MCP n'est pas activé
3. Un autre process utilise le port 3571

**Solutions** :
```bash
# Vérifier si le port est utilisé
lsof -i :3571        # macOS/Linux
netstat -ano | findstr :3571  # Windows

# Changer de port (si conflit)
export GOLEM_PORT=3572  # Avant de lancer Claude Code
```

Dans Godot : **Project > Project Settings > Plugins > Golem MCP** doit être activé (checkbox cochée).

### "No scene is currently running" (screenshot)

**Symptôme** : `godot_get_game_screenshot` retourne une erreur

**Cause** : Le jeu n'est pas lancé, ou la scène a crashé

**Solution** : Lancer le jeu avec `godot_play_scene` avant de capturer

### Screenshot vide / erreur base64

**Symptôme** : "Screenshot file was empty or corrupted" ou erreur API "image cannot be empty"

**Causes possibles** :
1. `GolemCapture` autoload non injecté dans le jeu
2. Le jeu a crashé avant la capture
3. Race condition (capture trop rapide)

**Solutions** :
1. Vérifier que `golem_capture.gd` est bien copié dans `addons/golem-mcp/`
2. Le système retry automatiquement 3 fois — si ça échoue quand même, vérifier les logs Godot
3. Utiliser `godot_get_errors` pour voir si le jeu a crashé

### Lint warnings après godot_write_script

**Symptôme** : Le hook `gdscript_lint.py` remonte des warnings

**C'est normal** — le lint est un filet de sécurité. Les warnings courants :
- `Missing 'extends'` — ajouter `extends Node` (ou le bon type)
- `print() found` — remplacer par `GolemCapture.log()` pour voir les logs via MCP
- `await inside _process` — interdit en @tool, utiliser un deferred pattern
- `Camera2D position modified` — utiliser `offset` au lieu de `position` pour le screenshake

### Ghost connections dans les logs Godot

**Symptôme** : "Condition '!is_open()' is true" répété dans les logs

**Cause** : Connexions TCP fantômes (probes de port)

**Solution** : Déjà fixé dans v0.5.1 — le serveur ignore silencieusement ces connexions. Mettre à jour le plugin.

## Protocole TCP

JSON lines sur port 3571 (configurable via `GOLEM_PORT`).

**Request :** `{"id": "uuid", "tool": "get_scene_tree", "args": {}}\n`

**Response :** `{"id": "uuid", "ok": true, "result": "...", "type": "text"}\n`

## Licence

MIT
