{"_id":"godot-hands","name":"godot-hands","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"godot-hands","version":"1.0.0","description":"Give your AI assistant hands on the Godot editor — 10 MCP tools, a live catalog of 210 addon methods, zero tool-spray","type":"module","main":"dist/index.js","bin":{"godot-hands":"dist/index.js"},"engines":{"node":">=18"},"scripts":{"build":"tsc","start":"node dist/index.js","prepublishOnly":"npm run build && npm test","test":"vitest run","test:godot":"node scripts/run-godot-tests.mjs","contract":"node scripts/contract-check.mjs","token-cost":"node scripts/token-cost.mjs"},"repository":{"type":"git","url":"git+https://github.com/WindSeries83/godot-mcp.git"},"homepage":"https://github.com/WindSeries83/godot-mcp#readme","bugs":{"url":"https://github.com/WindSeries83/godot-mcp/issues"},"keywords":["godot","mcp","modelcontextprotocol","ai","gamedev","editor"],"dependencies":{"@modelcontextprotocol/sdk":"^1.9.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0","vitest":"^4.1.10"},"license":"MIT","gitHead":"d9ea1be3967ab7b10ca570d0845385cf7a5e5a3d","_id":"godot-hands@1.0.0","_nodeVersion":"24.19.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-GUxDlpXu11J+kvnmriuBryZJmDWMqkBqY80OMjJiA8jdb4Yehv9l8+TcaKH+jp7iE6y7q+Ge14SYEBEKvSM5Bg==","shasum":"374694f923b12a2a87664692167f5692ba9db0b3","tarball":"https://registry.npmjs.org/godot-hands/-/godot-hands-1.0.0.tgz","fileCount":49,"unpackedSize":890632,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHz28W5p06bihIHRo4r/tsCy2m1rnTrEI8VWa7Sm3HaoAiEAkevbyHQMskRTKvfbeCjFhW8Q7vtOYypvw9VJ15eoiOQ="}]},"_npmUser":{"name":"windseries","email":"corentinb.series@gmail.com"},"directories":{},"maintainers":[{"name":"windseries","email":"corentinb.series@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/godot-hands_1.0.0_1787526221518_0.41555300597689704"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-23T23:03:41.447Z","1.0.0":"2026-08-23T23:03:41.673Z","modified":"2026-08-23T23:03:41.919Z"},"maintainers":[{"name":"windseries","email":"corentinb.series@gmail.com"}],"description":"Give your AI assistant hands on the Godot editor — 10 MCP tools, a live catalog of 210 addon methods, zero tool-spray","homepage":"https://github.com/WindSeries83/godot-mcp#readme","keywords":["godot","mcp","modelcontextprotocol","ai","gamedev","editor"],"repository":{"type":"git","url":"git+https://github.com/WindSeries83/godot-mcp.git"},"bugs":{"url":"https://github.com/WindSeries83/godot-mcp/issues"},"license":"MIT","readme":"[🇫🇷 Français](#fr) · [🇬🇧 English](#en)\n\n![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)\n[![npm](https://img.shields.io/npm/v/godot-hands.svg)](https://www.npmjs.com/package/godot-hands)\n![Godot 4.3+](https://img.shields.io/badge/Godot-4.3%2B-478cbf.svg)\n![Node >=18](https://img.shields.io/badge/Node-%3E%3D18-339933.svg)\n![Zero runtime deps](https://img.shields.io/badge/runtime%20deps-MCP%20SDK%20only-informational.svg)\n\n---\n\n# <a id=\"fr\"></a>godot-hands\n\n**Donnez les mains à votre assistant IA sur l'éditeur Godot — avec 10 outils au lieu de 100.**\n\n```\nAssistant IA <---stdio/MCP---> godot-hands <---WebSocket:6505---> Plugin Godot\n```\n\n## Pourquoi celui-ci\n\nLa plupart des serveurs MCP Godot exposent chaque méthode de l'addon comme\nun *tool* MCP séparé — 50, 80, parfois plus de 100 entrées dans le catalogue\nque le modèle doit lire et trier avant chaque appel. Plus la surface est\nlarge, moins un LLM choisit le bon outil de façon fiable, et plus chaque\nrequête coûte cher en tokens rien que pour décrire les outils disponibles.\n\ngodot-hands prend le pari inverse : **10 outils**, dont un seul (`godot_call`)\ndonne accès à un catalogue de **210 méthodes** réparties en ~25 catégories\n(scène, nodes, 3D, physique, animation, shaders, tilemap, particules, audio,\nnavigation, export Android, tests…), découvert **en direct** auprès de\nl'éditeur connecté plutôt que figé dans ce dépôt. Le modèle demande le\nschéma dont il a besoin (`godot_describe`) au lieu de tout charger d'un\ncoup. Résultat mesuré (`npm run token-cost`) : **~1460 tokens** pour toute\nla surface d'outils.\n\nLe reste tient en une phrase : **zéro dépendance runtime** en dehors du SDK\nMCP, **aucun service externe**, le plugin Godot est un simple client\nWebSocket — vous savez exactement ce qui tourne et où.\n\n### Ce qui distingue ce pont d'un simple exécuteur de commandes\n\n- **Garde-fous, pas juste des fonctions.** Les opérations destructrices\n  (suppression de fichier, édition de script, code arbitraire) exigent\n  `confirm: true` ; les éditions de script portent un garde optimiste par\n  SHA-256 pour ne pas écraser silencieusement un changement fait entre-temps\n  dans l'éditeur ; les mutations de scène passent par\n  `EditorUndoRedoManager` — un Ctrl-Z suffit toujours à annuler.\n- **Multi-éditeur.** Plusieurs projets Godot peuvent se connecter en même\n  temps ; `godot_status {\"select\": \"...\"}` épingle celui qui doit recevoir\n  les appels au lieu de tomber sur le premier connecté par hasard.\n- **Les opérations longues ne timeout plus.** `godot_call {\"async\": true}`\n  rend la main immédiatement avec un `job_id` à relire via `godot_job` —\n  un stress test de 60s ne meurt plus au bout de 30.\n- **Compatibilité de version fine.** Chaque méthode déclare la version\n  Godot minimale qu'elle requiert ; sur un moteur plus ancien, seules ces\n  méthodes-là disparaissent du catalogue au lieu de faire échouer tout\n  l'addon.\n- **Capture d'erreurs structurée**, pas du scraping d'UI : les erreurs\n  runtime sont interceptées via le signal `debug_data` du debugger Godot.\n- **Playtesting déterministe** : seed RNG fixée, tick de simulation fixe,\n  snapshots d'état, avance frame-par-frame (`step_frames`) ou jusqu'à\n  condition (`wait_for_condition`) — pour reproduire un bug plutôt que le\n  chasser à l'aveugle.\n- **Perception 3D** : modes de rendu debug (wireframe, overdraw, éclairage\n  seul…) sur les captures d'écran, détection d'objets qui se chevauchent ou\n  flottent, test de frustum caméra, couverture des lumières — un lint\n  spatial pour repérer ce qu'un screenshot seul ne montre pas.\n- **Assets CC0 intégrés** : recherche, prévisualisation et import direct\n  depuis Poly Haven et ambientCG, sans quitter la conversation.\n\n## Installation\n\nDeux commandes, zéro build, pas de clone de dépôt :\n\n```bash\n# 1. Pose l'addon Godot dans votre projet (addons/godot_mcp/)\nnpx godot-hands install ./mon-jeu\n```\n\nActivez-le : **Projet → Paramètres du projet → Plugins → godot-hands → Activer**\n\n```json\n{\n  \"mcpServers\": {\n    \"godot-hands\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"godot-hands\"]\n    }\n  }\n}\n```\n\nPréférez installer une bonne fois pour toutes ? `npm install -g godot-hands`,\npuis `\"command\": \"godot-hands\"` dans la config. Le paquet npm embarque le\nplugin Godot : la sous-commande `install` le copie depuis `node_modules`\n(ou copiez manuellement `node_modules/godot-hands/plugin/` vers\n`addons/godot_mcp/`, c'est équivalent).\n\n## Outils\n\n| Outil | Description |\n|-------|-------------|\n| `godot_call` | Appelle n'importe quelle méthode du catalogue (`async: true` pour les appels longs) |\n| `godot_list_methods` | Liste les méthodes par catégorie (en direct depuis l'éditeur connecté) |\n| `godot_describe` | Schéma complet (paramètres, types, annotations) d'une ou plusieurs méthodes |\n| `godot_info` | Infos projet |\n| `godot_screenshot` | Capture éditeur en PNG |\n| `godot_execute` | Exécute du GDScript |\n| `godot_status` | Vérifie la connexion, épingle un éditeur (`select`) si plusieurs sont connectés |\n| `godot_job` | Relit le résultat d'un appel `async: true` |\n| `godot_doctor` | Diagnostic complet : port, connexion, auth, contrat addon/serveur, binaire Godot |\n| `godot_assets` | Recherche/prévisualise/importe des assets CC0 (Poly Haven, ambientCG) |\n\n> **Confirmation obligatoire (`confirm: true`)** : les méthodes qui écrivent\n> ou suppriment un fichier sur disque, modifient `project.godot`, ou exécutent\n> du code arbitraire dans le process éditeur/jeu (`create_scene`,\n> `delete_scene`, `edit_script`, `execute_editor_script`, `set_project_setting`,\n> etc.) refusent l'appel avec l'erreur `-32009` tant que `params.confirm` n'est\n> pas `true`. `godot_describe` liste ce paramètre dans le schéma de chaque\n> méthode concernée. Les mutations de la **scène éditée** (ajout/suppression\n> de nodes, changement de propriétés, CSG, scatter…) ne sont **pas** gatées :\n> elles passent par `EditorUndoRedoManager` et un simple Ctrl-Z suffit à les\n> annuler.\n>\n> **`godot_assets`** effectue des requêtes réseau sortantes vers `polyhaven.com`\n> et `ambientcg.com`. `import` écrit les fichiers dans\n> `<projet>/assets/<provider>/<id>/` (chemin obtenu via `get_project_info`)\n> puis déclenche un rescan du projet. Sources CC0 uniquement (domaine\n> public, aucune attribution légalement requise) ; une note `NOTICE.txt`\n> est écrite à côté de chaque asset importé.\n\n> **Chemins de nodes** : les paramètres `parent_path` et `node_path` de\n> `godot_call` (ex. `add_node`, `update_property`, `delete_node`) sont\n> **toujours relatifs à la racine de la scène actuellement éditée** (`\".\"` =\n> racine de la scène). Les chemins absolus Godot (`\"/root\"`, `\"../...\"`) sont\n> rejetés — ils cibleraient l'arbre interne de l'éditeur au lieu de la scène.\n>\n> **Handles de session** : tout paramètre `node_path` accepte aussi un\n> handle (chaîne `\"@id:<n>\"`, renvoyée sous `\"handle\"` par `get_scene_tree`,\n> `add_node`, `rename_node`, etc.) à la place d'un chemin. Un handle continue\n> de désigner le même node après un renommage ou un déplacement dans la\n> scène, contrairement à un chemin qui casse dès que l'un des deux se\n> produit — utile pour enchaîner plusieurs appels sur le node qu'on vient de\n> créer/modifier. Un handle expire si la scène est rechargée/refermée ;\n> rappelez `get_scene_tree` pour en obtenir un nouveau.\n>\n> **`godot_screenshot`** nécessite un éditeur avec rendu actif : il ne\n> fonctionne pas en mode `--headless` (erreur \"Could not get image from\n> viewport\").\n\n## Ressources et prompts MCP\n\nEn plus des outils, le serveur expose l'état du projet en **ressources**\n(gratuites en tokens tant qu'elles ne sont pas lues, contrairement aux\noutils) : `godot://scene/current`, `godot://project/info`,\n`godot://project/settings`, `godot://logs/recent`, et le template\n`godot://class/{name}` (réflexion ClassDB, mise en cache 5 min — les classes\ndu moteur ne changent pas en cours de session).\n\nQuatre **prompts** réutilisables guident les workflows pour lesquels ce\nserveur a été conçu : `blockout-3d-level`, `diagnose-crash`,\n`audit-scene-perf`, `asset-strategy`.\n\n`godot_assets {action: \"import\"}` envoie des notifications de progression\n(`notifications/progress`) si le client fournit un `progressToken` — le\ntéléchargement peut prendre du temps sur une connexion lente.\n\n## Arborescence\n\n```\ngodot-hands/\n├── plugin/              ← Plugin Godot (embarqué dans le paquet npm)\n├── src/index.ts         ← Serveur MCP (Node.js)\n├── src/assets/          ← Sourcing d'assets CC0 (Poly Haven, ambientCG)\n├── package.json\n├── tsconfig.json\n├── README.md\n└── LICENSE              ← MIT\n```\n\n## Développement\n\n```bash\nnpm test           # tests unitaires (vitest), y compris le contract-check addon/serveur\nnpm run contract    # contract-check seul : get_commands()/get_command_schemas() alignés, modules enregistrés\nnpm run test:godot  # tests GDScript en --headless (nécessite `godot`/`godot4` sur le PATH ou GODOT_BIN)\nnpm run token-cost  # mesure le poids en tokens de la surface d'outils (et le contrefactuel si un éditeur est connecté)\n```\n\n## Licence\n\nMIT\n\nCe plugin Godot dérive de [godot-mcp-pro](https://github.com/youichi-uda/godot-mcp-pro) (Youichi Uda, MIT).\n\n---\n\n# <a id=\"en\"></a>godot-hands\n\n**Give your AI assistant real control of the Godot editor — with 10 tools instead of 100.**\n\n```\nAI Assistant <---stdio/MCP---> godot-hands <---WebSocket:6505---> Godot Plugin\n```\n\n## Why this one\n\nMost Godot MCP servers expose every addon method as its own MCP tool — 50,\n80, sometimes 100+ entries the model has to read and sort through before\nevery single call. The bigger that surface gets, the less reliably an LLM\npicks the right tool, and the more tokens get burned on tool descriptions\nbefore the conversation even starts.\n\ngodot-hands takes the opposite bet: **10 tools**, one of which (`godot_call`)\nopens onto a catalog of **210 methods** across ~25 categories (scene,\nnodes, 3D, physics, animation, shaders, tilemaps, particles, audio,\nnavigation, Android export, testing…), discovered **live** from the\nconnected editor instead of hardcoded in this repo. The model asks for the\nschema it actually needs (`godot_describe`) instead of loading everything\nup front. Measured result (`npm run token-cost`): **~1460 tokens** for the\nwhole tool surface.\n\nEverything else fits in one sentence: **zero runtime dependencies** beyond\nthe MCP SDK, **no external services**, the Godot plugin is a plain\nWebSocket client — you know exactly what's running and where.\n\n### What sets this apart from a plain command runner\n\n- **Guardrails, not just functions.** Destructive operations (deleting a\n  file, editing a script, running arbitrary code) require `confirm: true`;\n  script edits carry an optimistic SHA-256 guard so they can't silently\n  clobber a change made in the editor in the meantime; scene mutations go\n  through `EditorUndoRedoManager` — a plain Ctrl-Z always undoes them.\n- **Multi-editor aware.** Several Godot projects can stay connected at\n  once; `godot_status {\"select\": \"...\"}` pins which one receives calls\n  instead of falling back to whichever connected first.\n- **Long operations stop timing out.** `godot_call {\"async\": true}` returns\n  a `job_id` immediately, polled via `godot_job` — a 60-second stress test\n  no longer dies at the 30-second mark.\n- **Fine-grained version compatibility.** Every method declares the\n  minimum Godot version it needs; on an older engine, only those specific\n  methods drop out of the catalog instead of the whole addon failing to\n  load.\n- **Structured error capture**, not UI scraping: runtime errors are\n  intercepted through Godot's debugger `debug_data` signal.\n- **Deterministic playtesting**: fixed RNG seed, fixed simulation tick,\n  state snapshots, frame-by-frame stepping (`step_frames`) or stepping\n  until a condition holds (`wait_for_condition`) — reproduce a bug instead\n  of hunting it blind.\n- **3D perception**: debug render modes (wireframe, overdraw, lighting\n  only…) on screenshots, overlapping/floating object detection, camera\n  frustum testing, light coverage — a spatial lint for what a single\n  screenshot won't show you.\n- **Built-in CC0 assets**: search, preview, and import directly from Poly\n  Haven and ambientCG without leaving the conversation.\n\n## Setup\n\nTwo commands, zero build, no repo clone:\n\n```bash\n# 1. Drops the Godot addon into your project (addons/godot_mcp/)\nnpx godot-hands install ./my-game\n```\n\nEnable it: **Project → Project Settings → Plugins → godot-hands → Enable**\n\n```json\n{\n  \"mcpServers\": {\n    \"godot-hands\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"godot-hands\"]\n    }\n  }\n}\n```\n\nPrefer a permanent install? `npm install -g godot-hands`, then use\n`\"command\": \"godot-hands\"` in the config. The npm package ships the Godot\nplugin itself: the `install` subcommand copies it out of `node_modules`\n(or manually copy `node_modules/godot-hands/plugin/` to `addons/godot_mcp/`\n— same thing).\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `godot_call` | Call any method in the catalog (`async: true` for long-running calls) |\n| `godot_list_methods` | List methods by category (live from the connected editor) |\n| `godot_describe` | Full schema (params, types, annotations) for one or more methods |\n| `godot_info` | Project info |\n| `godot_screenshot` | Editor screenshot in PNG |\n| `godot_execute` | Run GDScript |\n| `godot_status` | Check connection, pin an editor (`select`) when several are connected |\n| `godot_job` | Poll the result of an `async: true` call |\n| `godot_doctor` | End-to-end diagnostic: port, connection, auth, addon/server contract, Godot binary |\n| `godot_assets` | Search/preview/import CC0 assets (Poly Haven, ambientCG) |\n\n> **Confirmation required (`confirm: true`)**: methods that write to or\n> delete a file on disk, modify `project.godot`, or run arbitrary code in the\n> editor/game process (`create_scene`, `delete_scene`, `edit_script`,\n> `execute_editor_script`, `set_project_setting`, etc.) refuse the call with a\n> `-32009` error until `params.confirm` is `true`. `godot_describe` lists this\n> parameter in the schema of every gated method. Mutations to the **edited\n> scene** (adding/removing nodes, property changes, CSG, scatter…) are **not**\n> gated: they go through `EditorUndoRedoManager`, so a plain Ctrl-Z undoes\n> them.\n>\n> **`godot_assets`** makes outbound network requests to `polyhaven.com` and\n> `ambientcg.com`. `import` writes files under\n> `<project>/assets/<provider>/<id>/` (path learned via `get_project_info`)\n> and then triggers a project rescan. CC0 sources only (public domain, no\n> attribution legally required); a `NOTICE.txt` is written next to each\n> imported asset regardless.\n\n> **Node paths**: `parent_path` and `node_path` parameters of `godot_call`\n> (e.g. `add_node`, `update_property`, `delete_node`) are **always relative to\n> the root of the currently edited scene** (`\".\"` = scene root). Absolute\n> Godot paths (`\"/root\"`, `\"../...\"`) are rejected — they would target the\n> editor's internal tree instead of the scene.\n>\n> **Session handles**: any `node_path` parameter also accepts a handle (an\n> `\"@id:<n>\"` string, returned as `\"handle\"` by `get_scene_tree`, `add_node`,\n> `rename_node`, etc.) instead of a path. A handle keeps addressing the same\n> node across a rename or reparent, where a path would break — useful for\n> chaining several calls against the node you just created/modified. A\n> handle goes stale when the scene is reloaded/reopened; call\n> `get_scene_tree` again for a fresh one.\n>\n> **`godot_screenshot`** requires an editor with active rendering: it does not\n> work in `--headless` mode (\"Could not get image from viewport\" error).\n\n## MCP resources and prompts\n\nBesides tools, the server exposes project state as **resources** (free in\ntokens until actually read, unlike tools): `godot://scene/current`,\n`godot://project/info`, `godot://project/settings`, `godot://logs/recent`,\nand the template `godot://class/{name}` (ClassDB reflection, cached for 5\nminutes — engine classes don't change mid-session).\n\nFour reusable **prompts** guide the workflows this server was built for:\n`blockout-3d-level`, `diagnose-crash`, `audit-scene-perf`, `asset-strategy`.\n\n`godot_assets {action: \"import\"}` sends `notifications/progress` updates if\nthe client supplies a `progressToken` — the download can take a while on a\nslow connection.\n\n## Development\n\n```bash\nnpm test           # unit tests (vitest), including the addon/server contract-check\nnpm run contract    # contract-check alone: get_commands()/get_command_schemas() agree, every module registered\nnpm run test:godot  # headless GDScript tests (needs `godot`/`godot4` on PATH or GODOT_BIN)\nnpm run token-cost  # measures the tool surface's token weight (and the counterfactual if an editor is connected)\n```\n\n## Structure\n\n```\ngodot-hands/\n├── plugin/              ← Godot plugin (bundled in the npm package)\n├── src/index.ts         ← MCP server (Node.js)\n├── src/assets/          ← CC0 asset sourcing (Poly Haven, ambientCG)\n├── test/                ← vitest suite + headless GDScript fixture project\n├── package.json\n├── tsconfig.json\n├── README.md\n└── LICENSE              ← MIT\n```\n\n## License\n\nMIT\n\nThis Godot plugin is derived from [godot-mcp-pro](https://github.com/youichi-uda/godot-mcp-pro) (Youichi Uda, MIT).\n","readmeFilename":"README.md","_rev":"1-24512a3810bbe2932412dc886bd54378"}