godotty-mcp 0.0.0-stage → 0.1.1

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 +60 -0
  2. package/LICENSE +21 -0
  3. package/README.md +190 -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,60 @@
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
+ ## [0.1.1] - 2026-11-20
10
+
11
+ ### Added
12
+
13
+ - Godotty logo and banner (`docs/media/`) and a README header with badges.
14
+
15
+ ## [0.1.0] - 2026-11-20
16
+
17
+ First public release.
18
+
19
+ ### Fixed
20
+
21
+ - A game or headless editor no longer keeps running after the MCP server is killed hard (SIGKILL):
22
+ a small guard process stops it (macOS, Linux). Run info now shows Godot's own pid.
23
+
24
+ ### Added
25
+
26
+ - Project named **Godotty** (npm package `godotty-mcp`, addon `addons/godotty_mcp`).
27
+ - `godotty-mcp install-addon` copies the editor plugin into a project; the npm package ships the
28
+ addon, and `scripts/package-addon.sh` builds the addon zip for releases.
29
+ - README (quick start for Claude Code, Claude Desktop, Cursor; tool reference; safety;
30
+ troubleshooting), CONTRIBUTING, docs/ARCHITECTURE.md, docs/RELEASING.md, issue/PR templates.
31
+ - Repository skeleton: MCP server package (TypeScript, stdio), editor addon stub, demo project, CI.
32
+ - `eval_gdscript` (opt-in via `--allow-eval`): run GDScript in the game or editor, with parse and
33
+ runtime errors reported by line. Godot refuses eval unless the server enabled it.
34
+ - Security hardening after an independent review; see docs/SECURITY.md (safety model and limits).
35
+ - Godot editor plugin (`addons/godotty_mcp`) and editor tools: `open_scene` (or create),
36
+ `add_node` (class or scene instance), `remove_node`, `update_node` (properties, rename, reparent,
37
+ script), `save_scene` — each one undoable step in the editor. `inspect_scene_tree` and
38
+ `get_node_properties` take `target: editor` to see the edited scene, unsaved changes included.
39
+ - See and play the running game: `screenshot` (images, frame sequences), `send_input` (actions,
40
+ keys, mouse, holds, waits; optional screenshot after), `wait` (frames, seconds, or a node/property
41
+ condition), `inspect_scene_tree`, `get_node_properties`, `set_node_property` — over a
42
+ token-authenticated loopback bridge to the runtime helper. Headless runs refuse screenshots
43
+ instead of hanging.
44
+ - `run_tests`: GUT and gdUnit4 (auto-detected), headless with JUnit results — totals, failures with
45
+ file:line, skipped tests, warnings for tests that never reported, and test scripts that failed
46
+ to load (which both frameworks skip silently).
47
+ - `godot_docs`: class reference of the installed Godot version — exact signatures from the local
48
+ binary, descriptions from the matching engine release (cached, `--offline` supported), class
49
+ overviews, members via inheritance, enums, ranked search.
50
+ - Tools: `project_info`, `list_files`, `read_scene`, `check_scripts` (Godot language server,
51
+ headless fallback), `run_game`, `stop_game`, `get_output`, `get_errors` (structured errors with
52
+ backtraces via the runtime helper's Logger).
53
+ - Runtime helper autoload, injected per launch without modifying the project.
54
+ - Integration tests against real Godot; CI integration job for Godot 4.5.2 and 4.7.2.
55
+ - Server core: config (`--project`, `--godot`, `--allow-eval`), project-root path sandbox,
56
+ pagination/truncation helpers, tool registry with actionable error results.
57
+
58
+ [Unreleased]: https://github.com/Arjein/godotty-mcp/compare/v0.1.1...HEAD
59
+ [0.1.1]: https://github.com/Arjein/godotty-mcp/compare/v0.1.0...v0.1.1
60
+ [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,191 @@
1
- # Temporary Holding Version
1
+ <h1 align="center">
2
+ <img src="https://raw.githubusercontent.com/Arjein/godotty-mcp/main/docs/media/godotty-banner.png" alt="Godotty: let AI agents build, run and play-test your Godot games" width="760">
3
+ </h1>
2
4
 
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.
5
+ <p align="center">
6
+ <a href="https://www.npmjs.com/package/godotty-mcp"><img src="https://img.shields.io/npm/v/godotty-mcp?color=478CBF&label=npm" alt="npm version"></a>
7
+ <a href="https://github.com/Arjein/godotty-mcp/actions/workflows/ci.yml"><img src="https://github.com/Arjein/godotty-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
8
+ <img src="https://img.shields.io/badge/Godot-4.5%2B-478CBF?logo=godotengine&logoColor=white" alt="Godot 4.5+">
9
+ <img src="https://img.shields.io/badge/MCP-server-2B2B2B" alt="MCP server">
10
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-FFB547" alt="MIT license"></a>
11
+ </p>
12
+
13
+ <p align="center"><b>An MCP server that lets AI coding agents play-test your Godot 4 game — not just edit it.</b></p>
14
+
15
+ Godotty (`godotty-mcp`) connects Claude Code, Claude Desktop, Cursor and other MCP clients to a
16
+ Godot 4 project. Besides reading and editing, the agent can **run the game, see it, play it and
17
+ debug it**: take screenshots, press keys and InputMap actions with real timing, wait for
18
+ conditions, inspect and tweak live nodes, read runtime errors with backtraces, look up the class
19
+ reference _of your installed Godot version_, and run your GUT or gdUnit4 tests.
20
+
21
+ <!-- Demo GIF placeholder: a recording of an agent play-testing examples/demo-project goes here,
22
+ e.g. ![Godotty play-testing the demo project](https://github.com/Arjein/godotty-mcp/blob/main/docs/media/demo.gif) -->
23
+
24
+ > Status: **0.1.0** — first public release. Tool names and inputs may still change before 1.0.
25
+
26
+ ## What makes it different
27
+
28
+ - **It sees and plays the game.** `screenshot` returns real frames (sequences too), `send_input`
29
+ drives actions, keys and the mouse through Godot's input pipeline, `wait` blocks until
30
+ `Player.position:y < 1`, and `get_node_properties` confirms what happened.
31
+ - **Diagnostics from Godot itself.** `check_scripts` uses Godot's own GDScript language server
32
+ (errors _and_ warnings with line and column); `get_errors` captures runtime errors with full
33
+ GDScript backtraces through Godot's Logger API, not by scraping logs.
34
+ - **Docs that match your Godot.** `godot_docs` serves signatures from your installed binary and
35
+ descriptions from that exact engine release, so agents stop mixing up Godot 3 and 4 APIs.
36
+ - **Structured test results** for GUT and gdUnit4, including the cases both frameworks silently
37
+ hide (test files that fail to load, tests that never reported).
38
+ - **Undoable editor edits.** With the editor plugin, every scene edit is one Ctrl/Cmd+Z step.
39
+ - **Safe by default.** Paths are confined to the project, the bridge to Godot is loopback-only and
40
+ mutually authenticated, and no tool runs arbitrary code unless you start it with `--allow-eval`.
41
+ See [the safety model](https://github.com/Arjein/godotty-mcp/blob/main/docs/SECURITY.md).
42
+ - **Small and cheap.** 21 tools (about 6K tokens of tool definitions), compact text outputs,
43
+ pagination and actionable errors.
44
+
45
+ ## Requirements
46
+
47
+ - Godot **4.5 or newer** (4.x), the standard editor build. Tested on 4.5.2 and 4.7.2.
48
+ - Node.js **20 or newer**.
49
+ - macOS, Linux or Windows. Screenshots need a display (on headless Linux use Xvfb).
50
+
51
+ ## Quick start
52
+
53
+ Point Godotty at your project folder (the one containing `project.godot`) and your Godot
54
+ executable. If `godot` is on your `PATH` you can leave out `--godot`.
55
+
56
+ ### Claude Code
57
+
58
+ ```bash
59
+ claude mcp add godotty -- npx -y godotty-mcp --project /path/to/your/game --godot /path/to/Godot
60
+ ```
61
+
62
+ On macOS the executable is usually `/Applications/Godot.app/Contents/MacOS/Godot`.
63
+
64
+ ### Claude Desktop
65
+
66
+ Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
67
+
68
+ ```json
69
+ {
70
+ "mcpServers": {
71
+ "godotty": {
72
+ "command": "npx",
73
+ "args": ["-y", "godotty-mcp", "--project", "/path/to/your/game", "--godot", "/path/to/Godot"]
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ ### Cursor
80
+
81
+ Add to `.cursor/mcp.json` in your project (or the global `~/.cursor/mcp.json`):
82
+
83
+ ```json
84
+ {
85
+ "mcpServers": {
86
+ "godotty": {
87
+ "command": "npx",
88
+ "args": ["-y", "godotty-mcp", "--project", "/path/to/your/game", "--godot", "/path/to/Godot"]
89
+ }
90
+ }
91
+ }
92
+ ```
93
+
94
+ ### Editor tools (optional)
95
+
96
+ The editing tools talk to the open Godot editor through a small plugin. Install it into your
97
+ project and enable it:
98
+
99
+ ```bash
100
+ npx godotty-mcp install-addon --project /path/to/your/game
101
+ ```
102
+
103
+ Then in Godot: **Project → Project Settings → Plugins → Godotty → Enable**. Everything else works
104
+ without the editor open.
105
+
106
+ ### Try it
107
+
108
+ Ask your agent things like:
109
+
110
+ - "What's in this project? Show me the main scene."
111
+ - "Run the game, take a screenshot, hold right for a second and show me again."
112
+ - "Check all scripts for errors, then run the tests."
113
+ - "Add a Marker3D called Spawn at (2, 0, -3) to the main scene and save it."
114
+ - "How do I make a CharacterBody3D jump? Use godot_docs."
115
+
116
+ The repository's [demo project](https://github.com/Arjein/godotty-mcp/blob/main/examples/demo-project) is a ready-made playground.
117
+
118
+ ## Options
119
+
120
+ | Flag | Environment variable | Meaning |
121
+ | ------------------- | ---------------------- | ------------------------------------------------------------------------ |
122
+ | `--project <dir>` | `GODOT_PROJECT_PATH` | Godot project root (default: current directory). |
123
+ | `--godot <path>` | `GODOT_PATH` | Godot 4 executable (default: `godot` on `PATH`). |
124
+ | `--lsp-port <port>` | `GODOT_LSP_PORT` | Port of the editor's GDScript language server (default 6005). |
125
+ | `--offline` | `GODOTTY_OFFLINE=1` | No network: `godot_docs` shows signatures only. |
126
+ | `--allow-eval` | `GODOTTY_ALLOW_EVAL=1` | Adds `eval_gdscript`, which runs arbitrary GDScript. **Off by default.** |
127
+
128
+ ## Tools
129
+
130
+ | Tool | What it does |
131
+ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------- |
132
+ | **Project** | |
133
+ | `project_info` | Godot version, main scene, autoloads, input map with bindings, plugins, game/editor status |
134
+ | `list_files` | Project files as `res://` paths, filtered by type and glob, paginated |
135
+ | `read_scene` | Compact node tree of a `.tscn` with saved properties and signal connections |
136
+ | **Docs & diagnostics** | |
137
+ | `godot_docs` | Class reference of your installed Godot: class overviews, members (through inheritance), enums, search |
138
+ | `check_scripts` | GDScript errors and warnings with line:column from Godot's language server |
139
+ | `get_errors` | Runtime errors and warnings of the last run, de-duplicated, with GDScript backtraces |
140
+ | **Run** | |
141
+ | `run_game` | Start the main scene or another scene (windowed or headless), with the runtime helper injected for that run only |
142
+ | `stop_game` | Stop the game and summarize how it ended |
143
+ | `get_output` | Console output with levels, a cursor for new lines, and level/text filters |
144
+ | **See & play** (running game) | |
145
+ | `screenshot` | Rendered frame(s) as images, scaled to a maximum size |
146
+ | `send_input` | Actions, keys, mouse buttons/motion, holds and waits, in order with real timing |
147
+ | `wait` | Frames, seconds, or until a node exists / a property meets a condition |
148
+ | `inspect_scene_tree` | Live node tree of the game — or of the scene open in the editor (`target: editor`) |
149
+ | `get_node_properties` | Property values of a live node (game or editor) |
150
+ | `set_node_property` | Change live properties in the running game (not saved) |
151
+ | **Editor** (needs the plugin) | |
152
+ | `open_scene` | Open a scene in the editor, or create a new one |
153
+ | `add_node` | Add a node by class or as a scene instance, with properties — undoable |
154
+ | `remove_node` | Remove a node — undoable |
155
+ | `update_node` | Properties, rename, reparent, attach/detach script in one undoable step |
156
+ | `save_scene` | Save the edited scene (or save as) |
157
+ | **Tests** | |
158
+ | `run_tests` | Run GUT or gdUnit4 headless; totals, failures with file:line, skipped and missing tests |
159
+ | **Opt-in** | |
160
+ | `eval_gdscript` | Run GDScript in the game or editor (only with `--allow-eval`) |
161
+
162
+ ## Safety
163
+
164
+ Godotty confines file access to the project, keeps its connection to Godot on `127.0.0.1` with
165
+ per-session tokens and a server proof, refuses value literals that could load and run scripts, and
166
+ only offers code execution when you pass `--allow-eval`. Editor edits are undoable.
167
+
168
+ Running or testing a project runs that project's code, as it would in the editor. Read
169
+ [docs/SECURITY.md](https://github.com/Arjein/godotty-mcp/blob/main/docs/SECURITY.md) for the full model and its limits.
170
+
171
+ ## Troubleshooting
172
+
173
+ | Problem | Fix |
174
+ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
175
+ | `GODOT_NOT_FOUND` | Pass `--godot` with the full path to the Godot executable (inside `Godot.app/Contents/MacOS/` on macOS). |
176
+ | "not supported; godotty-mcp needs 4.5" | Install Godot 4.5 or newer. |
177
+ | `EDITOR_NOT_CONNECTED` | Open the project in Godot, install the plugin (`npx godotty-mcp install-addon`) and enable it under Project Settings → Plugins. |
178
+ | Screenshot says the game runs headless | Run with `run_game` `headless: false`; on a headless Linux machine start the client under Xvfb. |
179
+ | The first `check_scripts` is slow | Godot imports the project the first time; later calls reuse a warm language server. |
180
+ | `run_tests` finds no framework | Install GUT (`addons/gut`) or gdUnit4 (`addons/gdUnit4`) from the Asset Library. |
181
+ | `godot_docs` has no descriptions | You are offline or using a build without published docs; signatures are still exact. |
182
+ | The game window grabs focus | Expected for windowed runs; use `headless: true` when you don't need screenshots. |
183
+
184
+ ## Contributing
185
+
186
+ Contributions are welcome — see [CONTRIBUTING.md](https://github.com/Arjein/godotty-mcp/blob/main/CONTRIBUTING.md) and
187
+ [docs/ARCHITECTURE.md](https://github.com/Arjein/godotty-mcp/blob/main/docs/ARCHITECTURE.md) (components, bridge protocol, how to add a tool).
188
+
189
+ ## License
190
+
191
+ [MIT](https://github.com/Arjein/godotty-mcp/blob/main/LICENSE)