godotty-mcp 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/CHANGELOG.md +53 -0
  2. package/LICENSE +21 -0
  3. package/README.md +180 -2
  4. package/addon/godotty_mcp/editor/godotty_editor_commands.gd +406 -0
  5. package/addon/godotty_mcp/editor/godotty_editor_commands.gd.uid +1 -0
  6. package/addon/godotty_mcp/plugin.cfg +7 -0
  7. package/addon/godotty_mcp/plugin.gd +93 -0
  8. package/addon/godotty_mcp/plugin.gd.uid +1 -0
  9. package/addon/godotty_mcp/runtime/godotty_bridge_client.gd +147 -0
  10. package/addon/godotty_mcp/runtime/godotty_bridge_client.gd.uid +1 -0
  11. package/addon/godotty_mcp/runtime/godotty_commands.gd +448 -0
  12. package/addon/godotty_mcp/runtime/godotty_commands.gd.uid +1 -0
  13. package/addon/godotty_mcp/runtime/godotty_error_logger.gd +67 -0
  14. package/addon/godotty_mcp/runtime/godotty_error_logger.gd.uid +1 -0
  15. package/addon/godotty_mcp/runtime/godotty_eval.gd +88 -0
  16. package/addon/godotty_mcp/runtime/godotty_eval.gd.uid +1 -0
  17. package/addon/godotty_mcp/runtime/godotty_input.gd +146 -0
  18. package/addon/godotty_mcp/runtime/godotty_input.gd.uid +1 -0
  19. package/addon/godotty_mcp/runtime/godotty_runtime.gd +77 -0
  20. package/addon/godotty_mcp/runtime/godotty_runtime.gd.uid +1 -0
  21. package/dist/bridge/bridge-server.js +265 -0
  22. package/dist/bridge/peer-client.js +80 -0
  23. package/dist/bridge/protocol.js +60 -0
  24. package/dist/bridge/runtime-client.js +29 -0
  25. package/dist/bridge/session-file.js +37 -0
  26. package/dist/config.js +74 -0
  27. package/dist/godot/docs/bbcode.js +65 -0
  28. package/dist/godot/docs/class-xml.js +144 -0
  29. package/dist/godot/docs/docs-store.js +165 -0
  30. package/dist/godot/docs/lookup.js +130 -0
  31. package/dist/godot/executable.js +141 -0
  32. package/dist/godot/game.js +255 -0
  33. package/dist/godot/godot-log.js +118 -0
  34. package/dist/godot/input-names.js +247 -0
  35. package/dist/godot/lsp-client.js +155 -0
  36. package/dist/godot/output-buffer.js +63 -0
  37. package/dist/godot/process-guard.js +46 -0
  38. package/dist/godot/project-file.js +95 -0
  39. package/dist/godot/runtime-injection.js +99 -0
  40. package/dist/godot/scene-file.js +190 -0
  41. package/dist/godot/script-checker.js +276 -0
  42. package/dist/godot/section-file.js +145 -0
  43. package/dist/godot/tests/junit.js +86 -0
  44. package/dist/godot/tests/test-runner.js +145 -0
  45. package/dist/godot/variant.js +297 -0
  46. package/dist/index.js +37 -0
  47. package/dist/install-addon.js +60 -0
  48. package/dist/server.js +13 -0
  49. package/dist/services.js +66 -0
  50. package/dist/tools/diagnostics.js +133 -0
  51. package/dist/tools/docs.js +233 -0
  52. package/dist/tools/editor.js +145 -0
  53. package/dist/tools/eval.js +43 -0
  54. package/dist/tools/index.js +44 -0
  55. package/dist/tools/project.js +168 -0
  56. package/dist/tools/registry.js +40 -0
  57. package/dist/tools/run.js +134 -0
  58. package/dist/tools/runtime.js +324 -0
  59. package/dist/tools/tests.js +134 -0
  60. package/dist/util/errors.js +40 -0
  61. package/dist/util/files.js +101 -0
  62. package/dist/util/literals.js +20 -0
  63. package/dist/util/paginate.js +33 -0
  64. package/dist/util/sandbox.js +59 -0
  65. package/dist/util/state-dir.js +41 -0
  66. package/dist/version.js +7 -0
  67. package/package.json +59 -4
package/CHANGELOG.md ADDED
@@ -0,0 +1,53 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
5
+ [Semantic Versioning](https://semver.org/).
6
+
7
+ ## [Unreleased]
8
+
9
+ ### Fixed
10
+
11
+ - A game or headless editor no longer keeps running after the MCP server is killed hard (SIGKILL):
12
+ a small guard process stops it (macOS, Linux). Run info now shows Godot's own pid.
13
+
14
+ ## [0.1.0] - 2026-11-20
15
+
16
+ First public release.
17
+
18
+ ### Added
19
+
20
+ - Project named **Godotty** (npm package `godotty-mcp`, addon `addons/godotty_mcp`).
21
+ - `godotty-mcp install-addon` copies the editor plugin into a project; the npm package ships the
22
+ addon, and `scripts/package-addon.sh` builds the addon zip for releases.
23
+ - README (quick start for Claude Code, Claude Desktop, Cursor; tool reference; safety;
24
+ troubleshooting), CONTRIBUTING, docs/ARCHITECTURE.md, docs/RELEASING.md, issue/PR templates.
25
+ - Repository skeleton: MCP server package (TypeScript, stdio), editor addon stub, demo project, CI.
26
+ - `eval_gdscript` (opt-in via `--allow-eval`): run GDScript in the game or editor, with parse and
27
+ runtime errors reported by line. Godot refuses eval unless the server enabled it.
28
+ - Security hardening after an independent review; see docs/SECURITY.md (safety model and limits).
29
+ - Godot editor plugin (`addons/godotty_mcp`) and editor tools: `open_scene` (or create),
30
+ `add_node` (class or scene instance), `remove_node`, `update_node` (properties, rename, reparent,
31
+ script), `save_scene` — each one undoable step in the editor. `inspect_scene_tree` and
32
+ `get_node_properties` take `target: editor` to see the edited scene, unsaved changes included.
33
+ - See and play the running game: `screenshot` (images, frame sequences), `send_input` (actions,
34
+ keys, mouse, holds, waits; optional screenshot after), `wait` (frames, seconds, or a node/property
35
+ condition), `inspect_scene_tree`, `get_node_properties`, `set_node_property` — over a
36
+ token-authenticated loopback bridge to the runtime helper. Headless runs refuse screenshots
37
+ instead of hanging.
38
+ - `run_tests`: GUT and gdUnit4 (auto-detected), headless with JUnit results — totals, failures with
39
+ file:line, skipped tests, warnings for tests that never reported, and test scripts that failed
40
+ to load (which both frameworks skip silently).
41
+ - `godot_docs`: class reference of the installed Godot version — exact signatures from the local
42
+ binary, descriptions from the matching engine release (cached, `--offline` supported), class
43
+ overviews, members via inheritance, enums, ranked search.
44
+ - Tools: `project_info`, `list_files`, `read_scene`, `check_scripts` (Godot language server,
45
+ headless fallback), `run_game`, `stop_game`, `get_output`, `get_errors` (structured errors with
46
+ backtraces via the runtime helper's Logger).
47
+ - Runtime helper autoload, injected per launch without modifying the project.
48
+ - Integration tests against real Godot; CI integration job for Godot 4.5.2 and 4.7.2.
49
+ - Server core: config (`--project`, `--godot`, `--allow-eval`), project-root path sandbox,
50
+ pagination/truncation helpers, tool registry with actionable error results.
51
+
52
+ [Unreleased]: https://github.com/Arjein/godotty-mcp/compare/v0.1.0...HEAD
53
+ [0.1.0]: https://github.com/Arjein/godotty-mcp/releases/tag/v0.1.0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mert Arcan and godotty-mcp contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,181 @@
1
- # Temporary Holding Version
1
+ # Godotty
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ **An MCP server that lets AI coding agents play-test your Godot 4 game — not just edit it.**
4
+
5
+ Godotty (`godotty-mcp`) connects Claude Code, Claude Desktop, Cursor and other MCP clients to a
6
+ Godot 4 project. Besides reading and editing, the agent can **run the game, see it, play it and
7
+ debug it**: take screenshots, press keys and InputMap actions with real timing, wait for
8
+ conditions, inspect and tweak live nodes, read runtime errors with backtraces, look up the class
9
+ reference _of your installed Godot version_, and run your GUT or gdUnit4 tests.
10
+
11
+ <!-- Demo GIF placeholder: a recording of an agent play-testing examples/demo-project goes here,
12
+ e.g. ![Godotty play-testing the demo project](https://github.com/Arjein/godotty-mcp/blob/main/docs/media/demo.gif) -->
13
+
14
+ > Status: **0.1.0** — first public release. Tool names and inputs may still change before 1.0.
15
+
16
+ ## What makes it different
17
+
18
+ - **It sees and plays the game.** `screenshot` returns real frames (sequences too), `send_input`
19
+ drives actions, keys and the mouse through Godot's input pipeline, `wait` blocks until
20
+ `Player.position:y < 1`, and `get_node_properties` confirms what happened.
21
+ - **Diagnostics from Godot itself.** `check_scripts` uses Godot's own GDScript language server
22
+ (errors _and_ warnings with line and column); `get_errors` captures runtime errors with full
23
+ GDScript backtraces through Godot's Logger API, not by scraping logs.
24
+ - **Docs that match your Godot.** `godot_docs` serves signatures from your installed binary and
25
+ descriptions from that exact engine release, so agents stop mixing up Godot 3 and 4 APIs.
26
+ - **Structured test results** for GUT and gdUnit4, including the cases both frameworks silently
27
+ hide (test files that fail to load, tests that never reported).
28
+ - **Undoable editor edits.** With the editor plugin, every scene edit is one Ctrl/Cmd+Z step.
29
+ - **Safe by default.** Paths are confined to the project, the bridge to Godot is loopback-only and
30
+ mutually authenticated, and no tool runs arbitrary code unless you start it with `--allow-eval`.
31
+ See [the safety model](https://github.com/Arjein/godotty-mcp/blob/main/docs/SECURITY.md).
32
+ - **Small and cheap.** 21 tools (about 6K tokens of tool definitions), compact text outputs,
33
+ pagination and actionable errors.
34
+
35
+ ## Requirements
36
+
37
+ - Godot **4.5 or newer** (4.x), the standard editor build. Tested on 4.5.2 and 4.7.2.
38
+ - Node.js **20 or newer**.
39
+ - macOS, Linux or Windows. Screenshots need a display (on headless Linux use Xvfb).
40
+
41
+ ## Quick start
42
+
43
+ Point Godotty at your project folder (the one containing `project.godot`) and your Godot
44
+ executable. If `godot` is on your `PATH` you can leave out `--godot`.
45
+
46
+ ### Claude Code
47
+
48
+ ```bash
49
+ claude mcp add godotty -- npx -y godotty-mcp --project /path/to/your/game --godot /path/to/Godot
50
+ ```
51
+
52
+ On macOS the executable is usually `/Applications/Godot.app/Contents/MacOS/Godot`.
53
+
54
+ ### Claude Desktop
55
+
56
+ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
57
+
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "godotty": {
62
+ "command": "npx",
63
+ "args": ["-y", "godotty-mcp", "--project", "/path/to/your/game", "--godot", "/path/to/Godot"]
64
+ }
65
+ }
66
+ }
67
+ ```
68
+
69
+ ### Cursor
70
+
71
+ Add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):
72
+
73
+ ```json
74
+ {
75
+ "mcpServers": {
76
+ "godotty": {
77
+ "command": "npx",
78
+ "args": ["-y", "godotty-mcp", "--project", "/path/to/your/game", "--godot", "/path/to/Godot"]
79
+ }
80
+ }
81
+ }
82
+ ```
83
+
84
+ ### Editor tools (optional)
85
+
86
+ The editing tools talk to the open Godot editor through a small plugin. Install it into your
87
+ project and enable it:
88
+
89
+ ```bash
90
+ npx godotty-mcp install-addon --project /path/to/your/game
91
+ ```
92
+
93
+ Then in Godot: **Project → Project Settings → Plugins → Godotty → Enable**. Everything else works
94
+ without the editor open.
95
+
96
+ ### Try it
97
+
98
+ Ask your agent things like:
99
+
100
+ - "What's in this project? Show me the main scene."
101
+ - "Run the game, take a screenshot, hold right for a second and show me again."
102
+ - "Check all scripts for errors, then run the tests."
103
+ - "Add a Marker3D called Spawn at (2, 0, -3) to the main scene and save it."
104
+ - "How do I make a CharacterBody3D jump? Use godot_docs."
105
+
106
+ The repository's [demo project](https://github.com/Arjein/godotty-mcp/blob/main/examples/demo-project) is a ready-made playground.
107
+
108
+ ## Options
109
+
110
+ | Flag | Environment variable | Meaning |
111
+ | ------------------- | ---------------------- | ------------------------------------------------------------------------ |
112
+ | `--project <dir>` | `GODOT_PROJECT_PATH` | Godot project root (default: current directory). |
113
+ | `--godot <path>` | `GODOT_PATH` | Godot 4 executable (default: `godot` on `PATH`). |
114
+ | `--lsp-port <port>` | `GODOT_LSP_PORT` | Port of the editor's GDScript language server (default 6005). |
115
+ | `--offline` | `GODOTTY_OFFLINE=1` | No network: `godot_docs` shows signatures only. |
116
+ | `--allow-eval` | `GODOTTY_ALLOW_EVAL=1` | Adds `eval_gdscript`, which runs arbitrary GDScript. **Off by default.** |
117
+
118
+ ## Tools
119
+
120
+ | Tool | What it does |
121
+ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
122
+ | **Project** | |
123
+ | `project_info` | Godot version, main scene, autoloads, input map with bindings, plugins, game/editor status |
124
+ | `list_files` | Project files as `res://` paths, filtered by type and glob, paginated |
125
+ | `read_scene` | Compact node tree of a `.tscn` with saved properties and signal connections |
126
+ | **Docs & diagnostics** | |
127
+ | `godot_docs` | Class reference of your installed Godot: class overviews, members (through inheritance), enums, search |
128
+ | `check_scripts` | GDScript errors and warnings with line:column from Godot's language server |
129
+ | `get_errors` | Runtime errors and warnings of the last run, de-duplicated, with GDScript backtraces |
130
+ | **Run** | |
131
+ | `run_game` | Start the main scene or another scene (windowed or headless), with the runtime helper injected for that run only |
132
+ | `stop_game` | Stop the game and summarize how it ended |
133
+ | `get_output` | Console output with levels, a cursor for new lines, and level/text filters |
134
+ | **See & play** (running game) | |
135
+ | `screenshot` | Rendered frame(s) as images, scaled to a maximum size |
136
+ | `send_input` | Actions, keys, mouse buttons/motion, holds and waits, in order with real timing |
137
+ | `wait` | Frames, seconds, or until a node exists / a property meets a condition |
138
+ | `inspect_scene_tree` | Live node tree of the game — or of the scene open in the editor (`target: editor`) |
139
+ | `get_node_properties` | Property values of a live node (game or editor) |
140
+ | `set_node_property` | Change live properties in the running game (not saved) |
141
+ | **Editor** (needs the plugin) | |
142
+ | `open_scene` | Open a scene in the editor, or create a new one |
143
+ | `add_node` | Add a node by class or as a scene instance, with properties — undoable |
144
+ | `remove_node` | Remove a node — undoable |
145
+ | `update_node` | Properties, rename, reparent, attach/detach script in one undoable step |
146
+ | `save_scene` | Save the edited scene (or save as) |
147
+ | **Tests** | |
148
+ | `run_tests` | Run GUT or gdUnit4 headless; totals, failures with file:line, skipped and missing tests |
149
+ | **Opt-in** | |
150
+ | `eval_gdscript` | Run GDScript in the game or editor (only with `--allow-eval`) |
151
+
152
+ ## Safety
153
+
154
+ Godotty confines file access to the project, keeps its connection to Godot on `127.0.0.1` with
155
+ per-session tokens and a server proof, refuses value literals that could load and run scripts, and
156
+ only offers code execution when you pass `--allow-eval`. Editor edits are undoable.
157
+
158
+ Running or testing a project runs that project's code, as it would in the editor. Read
159
+ [docs/SECURITY.md](https://github.com/Arjein/godotty-mcp/blob/main/docs/SECURITY.md) for the full model and its limits.
160
+
161
+ ## Troubleshooting
162
+
163
+ | Problem | Fix |
164
+ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
165
+ | `GODOT_NOT_FOUND` | Pass `--godot` with the full path to the Godot executable (inside `Godot.app/Contents/MacOS/` on macOS). |
166
+ | "not supported; godotty-mcp needs 4.5" | Install Godot 4.5 or newer. |
167
+ | `EDITOR_NOT_CONNECTED` | Open the project in Godot, install the plugin (`npx godotty-mcp install-addon`) and enable it under Project Settings → Plugins. |
168
+ | Screenshot says the game runs headless | Run with `run_game` `headless: false`; on a headless Linux machine start the client under Xvfb. |
169
+ | The first `check_scripts` is slow | Godot imports the project the first time; later calls reuse a warm language server. |
170
+ | `run_tests` finds no framework | Install GUT (`addons/gut`) or gdUnit4 (`addons/gdUnit4`) from the Asset Library. |
171
+ | `godot_docs` has no descriptions | You are offline or using a build without published docs; signatures are still exact. |
172
+ | The game window grabs focus | Expected for windowed runs; use `headless: true` when you don't need screenshots. |
173
+
174
+ ## Contributing
175
+
176
+ Contributions are welcome — see [CONTRIBUTING.md](https://github.com/Arjein/godotty-mcp/blob/main/CONTRIBUTING.md) and
177
+ [docs/ARCHITECTURE.md](https://github.com/Arjein/godotty-mcp/blob/main/docs/ARCHITECTURE.md) (components, bridge protocol, how to add a tool).
178
+
179
+ ## License
180
+
181
+ [MIT](https://github.com/Arjein/godotty-mcp/blob/main/LICENSE)
@@ -0,0 +1,406 @@
1
+ @tool
2
+ extends "res://addons/godotty_mcp/runtime/godotty_commands.gd"
3
+ ## Editor-side bridge commands: open/create scenes and make undoable edits to the edited scene.
4
+ ##
5
+ ## Every edit is validated completely first, then applied as ONE EditorUndoRedoManager action
6
+ ## named "Godotty: ...", so Ctrl+Z in the editor reverts it. Node paths are relative to the edited
7
+ ## scene root ("." = root). Shares tree/property code with the runtime commands.
8
+
9
+ const ACTION_PREFIX: String = "Godotty: "
10
+ const INVALID_NAME_CHARS: Array[String] = [".", ":", "@", "/", '"', "%"]
11
+ const SCENE_EXTENSIONS: Array[String] = ["tscn", "scn"]
12
+ const EDITOR_METHODS: Array[String] = [
13
+ "open_scene",
14
+ "add_node",
15
+ "remove_node",
16
+ "update_node",
17
+ "save_scene",
18
+ "tree",
19
+ "get_props",
20
+ "undo",
21
+ "redo",
22
+ "eval",
23
+ ]
24
+
25
+ var _undo_redo: EditorUndoRedoManager
26
+ ## res:// paths of scenes Godotty edited since they were last saved.
27
+ var _unsaved: Dictionary = {}
28
+
29
+
30
+ func _init(host: Node, undo_redo: EditorUndoRedoManager) -> void:
31
+ super(host)
32
+ _undo_redo = undo_redo
33
+
34
+
35
+ ## Only editor commands are available here (no screenshots/input in the editor).
36
+ func run(method: String, params: Dictionary) -> Dictionary:
37
+ if not method in EDITOR_METHODS:
38
+ return _error("UNKNOWN_METHOD", "Unknown editor method '%s'." % method)
39
+ return await super.run(method, params)
40
+
41
+
42
+ func _root() -> Node:
43
+ return EditorInterface.get_edited_scene_root()
44
+
45
+
46
+ func _eval_scene() -> Node:
47
+ return _root()
48
+
49
+
50
+ func _tree_start(path: String) -> Node:
51
+ return _resolve(path)
52
+
53
+
54
+ func _current_scene_label() -> String:
55
+ var root: Node = _root()
56
+ return root.scene_file_path if root != null else ""
57
+
58
+
59
+ func _display_path(node: Node) -> String:
60
+ var root: Node = _root()
61
+ if root == null or not (node == root or root.is_ancestor_of(node)):
62
+ return str(node.get_path())
63
+ return "." if node == root else str(root.get_path_to(node))
64
+
65
+
66
+ func _resolve(path: String) -> Node:
67
+ var root: Node = _root()
68
+ if root == null:
69
+ return null
70
+ return root if path == "" or path == "." else root.get_node_or_null(NodePath(path))
71
+
72
+
73
+ func _no_scene() -> Dictionary:
74
+ return _error("NO_SCENE", "No scene is open in the editor.")
75
+
76
+
77
+ func _cmd_open_scene(params: Dictionary) -> Dictionary:
78
+ var path: String = str(params.get("path", ""))
79
+ if not path.get_extension() in SCENE_EXTENSIONS:
80
+ return _error("INVALID_OPERATION", "'%s' is not a scene file (.tscn/.scn)." % path)
81
+ var type: String = str(params.get("create_root_type", ""))
82
+ if type != "":
83
+ var problem: Dictionary = _create_scene(path, type, str(params.get("root_name", "")))
84
+ if not problem.is_empty():
85
+ return problem
86
+ elif not ResourceLoader.exists(path):
87
+ return _error("FILE_NOT_FOUND", "Scene '%s' does not exist." % path)
88
+ EditorInterface.open_scene_from_path(path)
89
+ await _host.get_tree().process_frame
90
+ var root: Node = _root()
91
+ if root == null or root.scene_file_path != path:
92
+ return _error("INVALID_OPERATION", "The editor did not open '%s'." % path)
93
+ return _ok(_scene_info())
94
+
95
+
96
+ ## Writes a new scene with a single root node; returns {} or an error.
97
+ func _create_scene(path: String, type: String, root_name: String) -> Dictionary:
98
+ if ResourceLoader.exists(path) or FileAccess.file_exists(path):
99
+ return _error("FILE_EXISTS", "'%s' already exists." % path)
100
+ if not _is_node_class(type):
101
+ return _error("INVALID_TYPE", "'%s' is not an instantiable Node class." % type)
102
+ var node: Node = ClassDB.instantiate(type)
103
+ node.name = root_name if root_name != "" else path.get_file().get_basename().to_pascal_case()
104
+ var packed: PackedScene = PackedScene.new()
105
+ packed.pack(node)
106
+ node.free()
107
+ DirAccess.make_dir_recursive_absolute(ProjectSettings.globalize_path(path.get_base_dir()))
108
+ var error: Error = ResourceSaver.save(packed, path)
109
+ if error != OK:
110
+ return _error("SAVE_FAILED", "Could not write '%s' (%s)." % [path, error_string(error)])
111
+ EditorInterface.get_resource_filesystem().update_file(path)
112
+ return {}
113
+
114
+
115
+ func _cmd_add_node(params: Dictionary) -> Dictionary:
116
+ var root: Node = _root()
117
+ if root == null:
118
+ return _no_scene()
119
+ var parent: Node = _resolve(str(params.get("parent", ".")))
120
+ if parent == null:
121
+ return _error("NODE_NOT_FOUND", "No node at '%s'." % params.get("parent", "."))
122
+ var name: String = str(params.get("name", ""))
123
+ var name_problem: String = _name_problem(name, parent, null)
124
+ if name_problem != "":
125
+ return _error("INVALID_NAME", name_problem)
126
+ var made: Variant = _instantiate(params)
127
+ if made is Dictionary:
128
+ return made
129
+ var node: Node = made
130
+ node.name = name
131
+ var parsed: Dictionary = {}
132
+ var values: Dictionary = params.get("properties", {})
133
+ for key: Variant in values:
134
+ var problem: String = _parse_assignment(node, str(key), str(values[key]), parsed)
135
+ if problem != "":
136
+ node.free()
137
+ return _error("INVALID_VALUE", problem)
138
+ for key: Variant in parsed:
139
+ node.set_indexed(NodePath(str(key)), parsed[key])
140
+ var action: String = ACTION_PREFIX + "add " + name
141
+ _undo_redo.create_action(action, UndoRedo.MERGE_DISABLE, root)
142
+ _undo_redo.add_do_method(parent, "add_child", node, true)
143
+ _undo_redo.add_do_method(node, "set_owner", root)
144
+ _undo_redo.add_do_reference(node)
145
+ _undo_redo.add_undo_method(parent, "remove_child", node)
146
+ _undo_redo.commit_action()
147
+ var changes: Array[String] = []
148
+ for key: Variant in parsed:
149
+ changes.append("%s = %s" % [key, _format(parsed[key])])
150
+ return _edit_result(_display_path(node), action, changes)
151
+
152
+
153
+ ## A new node from "type" or an instance of "scene"; an error Dictionary on failure.
154
+ func _instantiate(params: Dictionary) -> Variant:
155
+ var scene: String = str(params.get("scene", ""))
156
+ if scene != "":
157
+ if not ResourceLoader.exists(scene):
158
+ return _error("FILE_NOT_FOUND", "Scene '%s' does not exist." % scene)
159
+ var packed: PackedScene = load(scene) as PackedScene
160
+ if packed == null:
161
+ return _error("INVALID_TYPE", "'%s' is not a scene." % scene)
162
+ return packed.instantiate(PackedScene.GEN_EDIT_STATE_INSTANCE)
163
+ var type: String = str(params.get("type", ""))
164
+ if not _is_node_class(type):
165
+ return _error("INVALID_TYPE", "'%s' is not an instantiable Node class." % type)
166
+ return ClassDB.instantiate(type)
167
+
168
+
169
+ func _cmd_remove_node(params: Dictionary) -> Dictionary:
170
+ var root: Node = _root()
171
+ if root == null:
172
+ return _no_scene()
173
+ var node: Node = _resolve(str(params.get("node", "")))
174
+ if node == null:
175
+ return _error("NODE_NOT_FOUND", "No node at '%s'." % params.get("node", ""))
176
+ if node == root:
177
+ return _error("INVALID_OPERATION", "The scene root cannot be removed.")
178
+ var path: String = _display_path(node)
179
+ var parent: Node = node.get_parent()
180
+ var action: String = ACTION_PREFIX + "remove " + str(node.name)
181
+ _undo_redo.create_action(action, UndoRedo.MERGE_DISABLE, root)
182
+ _undo_redo.add_do_method(parent, "remove_child", node)
183
+ _undo_redo.add_undo_method(parent, "add_child", node, true)
184
+ _undo_redo.add_undo_method(parent, "move_child", node, node.get_index())
185
+ # Restore ownership so the node is saved with the scene again after an undo.
186
+ for owned: Node in _owned_subtree(node):
187
+ _undo_redo.add_undo_method(owned, "set_owner", owned.owner)
188
+ _undo_redo.add_undo_reference(node)
189
+ _undo_redo.commit_action()
190
+ return _edit_result(path, action, ["removed %s" % path])
191
+
192
+
193
+ func _owned_subtree(node: Node) -> Array[Node]:
194
+ var nodes: Array[Node] = [node]
195
+ for child: Node in node.get_children():
196
+ nodes.append_array(_owned_subtree(child))
197
+ return nodes.filter(func(n: Node) -> bool: return n.owner != null)
198
+
199
+
200
+ func _cmd_update_node(params: Dictionary) -> Dictionary:
201
+ var root: Node = _root()
202
+ if root == null:
203
+ return _no_scene()
204
+ var node: Node = _resolve(str(params.get("node", "")))
205
+ if node == null:
206
+ return _error("NODE_NOT_FOUND", "No node at '%s'." % params.get("node", ""))
207
+ var plan: Array[Dictionary] = []
208
+ var problem: Dictionary = _plan_update(node, root, params, plan)
209
+ if not problem.is_empty():
210
+ return problem
211
+ if plan.is_empty():
212
+ return _error(
213
+ "BAD_PARAMS", "Nothing to update: pass properties, rename, reparent or script."
214
+ )
215
+ var action: String = ACTION_PREFIX + "update " + str(node.name)
216
+ _undo_redo.create_action(action, UndoRedo.MERGE_DISABLE, root)
217
+ var changes: Array[String] = []
218
+ for step: Dictionary in plan:
219
+ for call: Array in step["do"]:
220
+ _undo_redo.callv("add_do_method", call)
221
+ for call: Array in step["undo"]:
222
+ _undo_redo.callv("add_undo_method", call)
223
+ changes.append(step["change"])
224
+ _undo_redo.commit_action()
225
+ return _edit_result(_display_path(node), action, changes)
226
+
227
+
228
+ ## Validates every requested change and fills `plan` with do/undo calls; returns {} or an error.
229
+ func _plan_update(
230
+ node: Node, root: Node, params: Dictionary, plan: Array[Dictionary]
231
+ ) -> Dictionary:
232
+ if params.has("script"):
233
+ var script_step: Dictionary = _plan_script(node, str(params["script"]))
234
+ if script_step.has("error"):
235
+ return script_step
236
+ plan.append(script_step)
237
+ var parsed: Dictionary = {}
238
+ var values: Dictionary = params.get("properties", {})
239
+ for key: Variant in values:
240
+ var problem: String = _parse_assignment(node, str(key), str(values[key]), parsed)
241
+ if problem != "":
242
+ return _error("INVALID_VALUE", problem)
243
+ for key: Variant in parsed:
244
+ var path: NodePath = NodePath(str(key))
245
+ (
246
+ plan
247
+ . append(
248
+ {
249
+ "do": [[node, "set_indexed", path, parsed[key]]],
250
+ "undo": [[node, "set_indexed", path, node.get_indexed(path)]],
251
+ "change": "%s = %s" % [key, _format(parsed[key])],
252
+ }
253
+ )
254
+ )
255
+ if params.has("rename"):
256
+ var name: String = str(params["rename"])
257
+ var name_problem: String = _name_problem(name, node.get_parent(), node)
258
+ if name_problem != "":
259
+ return _error("INVALID_NAME", name_problem)
260
+ (
261
+ plan
262
+ . append(
263
+ {
264
+ "do": [[node, "set_name", name]],
265
+ "undo": [[node, "set_name", node.name]],
266
+ "change": "renamed %s → %s" % [node.name, name],
267
+ }
268
+ )
269
+ )
270
+ if params.has("reparent"):
271
+ var step: Dictionary = _plan_reparent(node, root, str(params["reparent"]))
272
+ if step.has("error"):
273
+ return step
274
+ plan.append(step)
275
+ return {}
276
+
277
+
278
+ func _plan_script(node: Node, path: String) -> Dictionary:
279
+ var old: Variant = node.get_script()
280
+ if path == "":
281
+ return {
282
+ "do": [[node, "set_script", null]],
283
+ "undo": [[node, "set_script", old]],
284
+ "change": "script detached"
285
+ }
286
+ if not ResourceLoader.exists(path):
287
+ return _error("FILE_NOT_FOUND", "Script '%s' does not exist." % path)
288
+ var script: Script = load(path) as Script
289
+ if script == null:
290
+ return _error("INVALID_TYPE", "'%s' is not a script." % path)
291
+ var base: String = script.get_instance_base_type()
292
+ if base != "" and not ClassDB.is_parent_class(node.get_class(), base):
293
+ return _error(
294
+ "INVALID_TYPE",
295
+ "%s extends %s; it can't be attached to a %s." % [path, base, node.get_class()]
296
+ )
297
+ return {
298
+ "do": [[node, "set_script", script]],
299
+ "undo": [[node, "set_script", old]],
300
+ "change": "script = %s" % path
301
+ }
302
+
303
+
304
+ func _plan_reparent(node: Node, root: Node, target_path: String) -> Dictionary:
305
+ var target: Node = _resolve(target_path)
306
+ if target == null:
307
+ return _error("NODE_NOT_FOUND", "No node at '%s'." % target_path)
308
+ if node == root:
309
+ return _error("INVALID_OPERATION", "The scene root cannot be reparented.")
310
+ if target == node or node.is_ancestor_of(target):
311
+ return _error("INVALID_OPERATION", "A node cannot be moved under itself.")
312
+ var name_problem: String = _name_problem(str(node.name), target, node)
313
+ if name_problem != "":
314
+ return _error("INVALID_NAME", name_problem)
315
+ var parent: Node = node.get_parent()
316
+ return {
317
+ "do": [[node, "reparent", target]],
318
+ "undo": [[node, "reparent", parent], [parent, "move_child", node, node.get_index()]],
319
+ "change": "moved under %s" % _display_path(target),
320
+ }
321
+
322
+
323
+ func _cmd_save_scene(params: Dictionary) -> Dictionary:
324
+ var root: Node = _root()
325
+ if root == null:
326
+ return _no_scene()
327
+ var path: String = str(params.get("path", ""))
328
+ if path != "":
329
+ if not path.get_extension() in SCENE_EXTENSIONS:
330
+ return _error("INVALID_OPERATION", "'%s' is not a scene file (.tscn/.scn)." % path)
331
+ EditorInterface.save_scene_as(path, false)
332
+ elif root.scene_file_path == "":
333
+ return _error("SAVE_FAILED", "This scene has never been saved; pass a path.")
334
+ else:
335
+ var error: Error = EditorInterface.save_scene()
336
+ if error != OK:
337
+ return _error("SAVE_FAILED", "Saving failed (%s)." % error_string(error))
338
+ _unsaved.erase(root.scene_file_path)
339
+ return _ok(_scene_info())
340
+
341
+
342
+ func _cmd_undo(_params: Dictionary) -> Dictionary:
343
+ return _step_history(true)
344
+
345
+
346
+ func _cmd_redo(_params: Dictionary) -> Dictionary:
347
+ return _step_history(false)
348
+
349
+
350
+ func _step_history(undo: bool) -> Dictionary:
351
+ var root: Node = _root()
352
+ if root == null:
353
+ return _no_scene()
354
+ var history: UndoRedo = _undo_redo.get_history_undo_redo(_undo_redo.get_object_history_id(root))
355
+ # The current action is the one an undo would revert; after a redo it's the one redone.
356
+ var name: String = history.get_current_action_name() if undo else ""
357
+ var done: bool = history.undo() if undo else history.redo()
358
+ if not done:
359
+ return _error("INVALID_OPERATION", "Nothing to %s." % ("undo" if undo else "redo"))
360
+ if not undo:
361
+ name = history.get_current_action_name()
362
+ return _ok(_scene_info().merged({"action": name}))
363
+
364
+
365
+ func _edit_result(path: String, action: String, changes: Array[String]) -> Dictionary:
366
+ _unsaved[_root().scene_file_path] = true
367
+ return _ok(_scene_info().merged({"node": path, "action": action, "changes": changes}))
368
+
369
+
370
+ func _scene_info() -> Dictionary:
371
+ var root: Node = _root()
372
+ return {
373
+ "scene": root.scene_file_path,
374
+ "root": str(root.name),
375
+ "class": root.get_class(),
376
+ "nodes": _count(root),
377
+ "unsaved": _unsaved.has(root.scene_file_path),
378
+ }
379
+
380
+
381
+ func _count(node: Node) -> int:
382
+ var total: int = 1
383
+ for child: Node in node.get_children():
384
+ total += _count(child)
385
+ return total
386
+
387
+
388
+ ## "" when `name` is a valid, unique child name under `parent` (ignoring `node` itself).
389
+ func _name_problem(name: String, parent: Node, node: Node) -> String:
390
+ if name.strip_edges() == "":
391
+ return "The name is empty."
392
+ for character: String in INVALID_NAME_CHARS:
393
+ if name.contains(character):
394
+ return "'%s' contains '%s', which node names cannot use." % [name, character]
395
+ var existing: Node = parent.get_node_or_null(NodePath(name))
396
+ if existing != null and existing != node:
397
+ return "%s already has a child named '%s'." % [_display_path(parent), name]
398
+ return ""
399
+
400
+
401
+ func _is_node_class(type: String) -> bool:
402
+ return (
403
+ ClassDB.class_exists(type)
404
+ and ClassDB.can_instantiate(type)
405
+ and (type == "Node" or ClassDB.is_parent_class(type, "Node"))
406
+ )
@@ -0,0 +1 @@
1
+ uid://vuv344q0e4l8
@@ -0,0 +1,7 @@
1
+ [plugin]
2
+
3
+ name="Godotty"
4
+ description="Editor bridge for the godotty-mcp server: lets AI agents make undoable scene edits."
5
+ author="godotty-mcp contributors"
6
+ version="0.1.0"
7
+ script="plugin.gd"