@satelliteoflove/godot-mcp 3.21.1 → 3.22.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.
- package/README.md +99 -59
- package/addon/plugin.cfg +1 -1
- package/dist/__tests__/tools/docs.test.js +9 -1
- package/dist/__tests__/tools/docs.test.js.map +1 -1
- package/dist/__tests__/tools/watch-contract.test.d.ts +2 -0
- package/dist/__tests__/tools/watch-contract.test.d.ts.map +1 -0
- package/dist/__tests__/tools/watch-contract.test.js +165 -0
- package/dist/__tests__/tools/watch-contract.test.js.map +1 -0
- package/dist/utils/usage-logger.d.ts.map +1 -1
- package/dist/utils/usage-logger.js +2 -0
- package/dist/utils/usage-logger.js.map +1 -1
- package/package.json +10 -4
package/README.md
CHANGED
|
@@ -1,20 +1,55 @@
|
|
|
1
1
|
# godot-mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@satelliteoflove/godot-mcp)
|
|
4
|
+
[](https://github.com/satelliteoflove/godot-mcp/actions/workflows/ci.yml)
|
|
5
|
+
[](https://godotengine.org)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](https://github.com/satelliteoflove/godot-mcp/blob/main/LICENSE)
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
Give your AI assistant eyes and hands in the Godot editor — and a running game it can actually playtest.
|
|
6
10
|
|
|
7
|
-
|
|
11
|
+
<!-- HERO PLACEHOLDER: short demo GIF goes here (agent running the game, stepping time, reading state). Use an absolute raw.githubusercontent.com URL so it also renders on npm. -->
|
|
8
12
|
|
|
9
|
-
|
|
13
|
+
## Why this one?
|
|
14
|
+
|
|
15
|
+
There are a few Godot MCP servers out there, and most can open a scene and poke at nodes. This one is built around a harder problem: **letting an agent verify its own work.** Run the game, drive it like a player, observe what actually happened, and prove the change did what it claimed — without you ferrying screenshots and error logs back and forth.
|
|
16
|
+
|
|
17
|
+
The pieces that make that possible, and that you won't find elsewhere:
|
|
18
|
+
|
|
19
|
+
- **Deterministic playtesting.** Freeze the game clock, step exact slices of game time (or step *until a condition holds*), with inputs riding inside the window. Observation never races the game.
|
|
20
|
+
- **Cheap observation.** Live entity state — positions, velocities, animation state, your own custom data — as structured JSON. Most "what's happening on screen?" questions get answered without spending vision tokens on a screenshot.
|
|
21
|
+
- **Real input.** Named actions with analog strength, joypad buttons and stick vectors, raw keys with modifier combos, relative mouse-look, text typing. Sequences run with precise timing and can prove they changed game state.
|
|
22
|
+
- **Scenario setup.** Run GDScript inside the running game: grant the weapon, skip to wave 3, spawn a test bot — no debug hooks baked into your game code.
|
|
23
|
+
|
|
24
|
+
Here's what that looks like when an agent tests a boss fight:
|
|
25
|
+
|
|
26
|
+
```text
|
|
27
|
+
godot_editor run frozen=true # boot with game time frozen at frame 0
|
|
28
|
+
godot_exec GameState.wave = 3 # set up the scenario worth testing
|
|
29
|
+
godot_game_time step_until "tree.get_nodes_in_group('boss').size() >= 1"
|
|
30
|
+
godot_runtime_state digest # exact positions and state — no pixels, no guessing
|
|
31
|
+
godot_game_time step 500ms + dodge input # play the moment that matters
|
|
32
|
+
godot_editor screenshot_game # and a screenshot when it's actually worth the tokens
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Less copy-paste, more creating.
|
|
10
36
|
|
|
11
37
|
## Quick Start
|
|
12
38
|
|
|
13
39
|
### 1. Configure your AI assistant
|
|
14
40
|
|
|
15
|
-
Add godot-mcp to your MCP client. See the [Installation Guide](INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more).
|
|
41
|
+
Add godot-mcp to your MCP client. See the [Installation Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/INSTALL.md) for config examples (Claude Desktop, Claude Code, VSCode/Copilot, and more). The short version:
|
|
16
42
|
|
|
17
|
-
|
|
43
|
+
```json
|
|
44
|
+
{
|
|
45
|
+
"mcpServers": {
|
|
46
|
+
"godot-mcp": {
|
|
47
|
+
"command": "npx",
|
|
48
|
+
"args": ["-y", "@satelliteoflove/godot-mcp"]
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
```
|
|
18
53
|
|
|
19
54
|
### 2. Install the Godot addon
|
|
20
55
|
|
|
@@ -22,76 +57,84 @@ While you're at it, add [minimal-godot-mcp](https://github.com/ryanmazzolini/min
|
|
|
22
57
|
npx @satelliteoflove/godot-mcp --install-addon /path/to/your/godot/project
|
|
23
58
|
```
|
|
24
59
|
|
|
25
|
-
Enable in Godot: **Project Settings > Plugins > Godot MCP**
|
|
60
|
+
Enable it in Godot: **Project > Project Settings > Plugins > Godot MCP**
|
|
26
61
|
|
|
27
|
-
### 3.
|
|
62
|
+
### 3. Start building
|
|
28
63
|
|
|
29
|
-
Open your Godot project, restart your AI assistant, and start building.
|
|
64
|
+
Open your Godot project, restart your AI assistant, and start building. If anything refuses to connect, the [Troubleshooting Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/troubleshooting.md) has you covered.
|
|
30
65
|
|
|
31
|
-
## What
|
|
66
|
+
## What's in the box
|
|
32
67
|
|
|
33
|
-
|
|
34
|
-
- **Inspect** nodes, resources, animations, tilemaps, 3D spatial data
|
|
35
|
-
- **Modify** scenes, nodes, scripts, animations, tilemaps directly
|
|
36
|
-
- **Test** by running the game and injecting input
|
|
37
|
-
- **Learn** by fetching Godot docs on demand
|
|
68
|
+
15 tools, ~90 actions, 3 MCP resources. Full API docs in the [Tools Reference](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/tools/README.md).
|
|
38
69
|
|
|
39
|
-
|
|
70
|
+
| Tool | What it does |
|
|
71
|
+
|------|--------------|
|
|
72
|
+
| `godot_scene` | Open, save, and create scenes |
|
|
73
|
+
| `godot_node` | Create, update, delete, and reparent nodes; attach scripts; connect signals |
|
|
74
|
+
| `godot_editor` | Editor state, selection, run/stop/restart, screenshots, editor error log, 2D viewport control |
|
|
75
|
+
| `godot_project` | Project info and settings |
|
|
76
|
+
| `godot_animation` | Query, play, and edit animations down to individual tracks and keyframes |
|
|
77
|
+
| `godot_tilemap` / `godot_gridmap` | Read and edit TileMapLayer and GridMap cells |
|
|
78
|
+
| `godot_resource` | Inspect resources with type-aware output: SpriteFrames, TileSet, Materials, Textures |
|
|
79
|
+
| `godot_scene3d` | 3D transforms, bounding boxes, and visibility for spatial reasoning |
|
|
80
|
+
| `godot_docs` | Fetch Godot documentation as clean markdown, version-matched to your editor |
|
|
81
|
+
| `godot_input` | Inject input into the running game: actions, joypad, raw keys, mouse-look, text |
|
|
82
|
+
| `godot_profiler` | Metric snapshots and per-frame time series with spike detection |
|
|
83
|
+
| `godot_runtime_state` | Live game state as JSON: one-shot digests, watch windows, signal timelines |
|
|
84
|
+
| `godot_game_time` | Freeze, step, and step-until on the game clock — deterministic observation |
|
|
85
|
+
| `godot_exec` | Run GDScript inside the running game for test scenario setup |
|
|
40
86
|
|
|
41
|
-
|
|
87
|
+
A note on shape: this kit deliberately stays at 15 tools rather than 90. Related operations live as actions inside one tool, so your agent's context isn't flooded with tool definitions it won't use.
|
|
42
88
|
|
|
43
|
-
|
|
89
|
+
## Things to ask for
|
|
44
90
|
|
|
45
|
-
|
|
91
|
+
A feel for what an agent can do with this, in plain prompts:
|
|
46
92
|
|
|
47
|
-
|
|
93
|
+
- *"Run the game and screenshot the title screen. Does the layout survive 1280x720?"*
|
|
94
|
+
- *"The player can clip through the east wall. Reproduce it, then check the collision shapes and tell me why."*
|
|
95
|
+
- *"Step the game until the second wave spawns and give me every enemy's position and velocity."*
|
|
96
|
+
- *"Hold the left stick at half deflection for two seconds — does the walk animation blend correctly?"*
|
|
97
|
+
- *"Profile ten seconds of gameplay and find what's causing the frame spikes."*
|
|
98
|
+
- *"Add a hit-flash animation to the Player: modulate to red and back over 0.2 seconds."*
|
|
48
99
|
|
|
49
|
-
|
|
50
|
-
- [Claude Code Setup Guide](../docs/claude-code-setup.md) - CLAUDE.md template for Godot projects
|
|
51
|
-
- [Runtime State Guide](../docs/runtime-state-guide.md) - Expose game state to agents via the `mcp_watch` group and `_mcp_state()`
|
|
52
|
-
- [Tools Reference](../docs/tools/README.md) - All 12 tools with full API docs
|
|
53
|
-
- [Resources Reference](../docs/resources.md) - MCP resources for reading project data
|
|
54
|
-
- [Contributing](../CONTRIBUTING.md) - Dev setup, adding tools, release process
|
|
55
|
-
- [Changelog](CHANGELOG.md) - Release history
|
|
100
|
+
For richer runtime observation, add key nodes to the `mcp_watch` group or give them a `_mcp_state()` method — see the [Runtime State Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/runtime-state-guide.md).
|
|
56
101
|
|
|
57
|
-
##
|
|
102
|
+
## How it works
|
|
58
103
|
|
|
104
|
+
```text
|
|
105
|
+
┌─────────────────┐ stdio ┌─────────────────┐ WebSocket ┌──────────────────┐ debugger ┌──────────────┐
|
|
106
|
+
│ MCP client │ ◄────────► │ godot-mcp │ ◄──────────► │ Bridge addon │ ◄─────────► │ Running game │
|
|
107
|
+
│ (Claude, etc.) │ │ server (Node) │ :6550 │ (Godot editor) │ wire │ (autoload) │
|
|
108
|
+
└─────────────────┘ └─────────────────┘ └──────────────────┘ └──────────────┘
|
|
59
109
|
```
|
|
60
|
-
[Claude/AI Assistant/MCP Client] <--stdio--> [MCP Server] <--WebSocket:6550--> [Godot MCP Bridge Addon]
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
WSL2 is supported (auto-detection, host IP discovery, configurable bind modes). See the [Installation Guide](INSTALL.md#wsl-support) for setup details.
|
|
64
|
-
|
|
65
|
-
## CLI smoke test (paste-ready JSON-RPC)
|
|
66
110
|
|
|
67
|
-
|
|
111
|
+
The server talks to an editor addon over a local WebSocket; the addon reaches into the running game over Godot's own debugger protocol, so the game process needs no extra ports or setup. The addon binds to `127.0.0.1` by default. WSL2 is fully supported (auto-detection, host IP discovery, configurable bind modes) — see the [Installation Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/INSTALL.md#wsl-support).
|
|
68
112
|
|
|
69
|
-
|
|
113
|
+
Curious about connection lifecycles, the single-client policy, or how frozen-time stepping works under the hood? The [Architecture Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/architecture.md) goes deep.
|
|
70
114
|
|
|
71
|
-
|
|
72
|
-
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli-test","version":"0"}}}
|
|
73
|
-
```
|
|
115
|
+
## Works well with minimal-godot-mcp
|
|
74
116
|
|
|
75
|
-
|
|
117
|
+
[minimal-godot-mcp](https://github.com/ryanmazzolini/minimal-godot-mcp) by [@ryanmazzolini](https://github.com/ryanmazzolini) covers exactly what this server doesn't: LSP diagnostics for fast static GDScript checking, and the running game's console output over DAP. This server covers everything that needs an editor bridge. No overlap, no conflict — run both, and your agent gets static analysis and the game console alongside full editor and runtime control.
|
|
76
118
|
|
|
77
|
-
|
|
78
|
-
{"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{},"resources":{},"logging":{}},"serverInfo":{"name":"godot-mcp","version":"2.11.0"}},"jsonrpc":"2.0","id":1}
|
|
79
|
-
```
|
|
119
|
+
One caveat: a Godot editor serves a single godot-mcp client at a time. Extra clients (a subagent inheriting your MCP config, say) wait their turn rather than hijacking your session — details in [Troubleshooting](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/troubleshooting.md#one-client-at-a-time).
|
|
80
120
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
```json
|
|
84
|
-
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"godot_editor","arguments":{"action":"get_state"}}}
|
|
85
|
-
```
|
|
121
|
+
## Documentation
|
|
86
122
|
|
|
87
|
-
|
|
123
|
+
- [Installation Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/INSTALL.md) — MCP client configs for Claude Desktop, Claude Code, VSCode/Copilot, and more
|
|
124
|
+
- [Troubleshooting](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/troubleshooting.md) — connection checklist, CLI smoke test, common fixes
|
|
125
|
+
- [Claude Code Setup Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/claude-code-setup.md) — CLAUDE.md template for Godot projects
|
|
126
|
+
- [Runtime State Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/runtime-state-guide.md) — expose game state to agents via `mcp_watch` and `_mcp_state()`
|
|
127
|
+
- [Tools Reference](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/tools/README.md) — all 15 tools with full API docs
|
|
128
|
+
- [Resources Reference](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/resources.md) — MCP resources for reading project data
|
|
129
|
+
- [Architecture Guide](https://github.com/satelliteoflove/godot-mcp/blob/main/docs/architecture.md) — how the server, addon, and game bridge fit together
|
|
130
|
+
- [Contributing](https://github.com/satelliteoflove/godot-mcp/blob/main/CONTRIBUTING.md) — dev setup, adding tools, release process
|
|
131
|
+
- [Changelog](https://github.com/satelliteoflove/godot-mcp/blob/main/server/CHANGELOG.md) — release history
|
|
88
132
|
|
|
89
|
-
|
|
90
|
-
{"result":{"content":[{"type":"text","text":"{\n \"current_scene\": null,\n \"godot_version\": \"4.5.1-stable (official)\",\n \"is_playing\": false,\n \"main_screen\": \"unknown\",\n \"open_scenes\": []\n}"}]},"jsonrpc":"2.0","id":2}
|
|
91
|
-
```
|
|
133
|
+
## Requirements
|
|
92
134
|
|
|
93
|
-
|
|
94
|
-
|
|
135
|
+
- **Godot 4.5+** (the addon uses the Logger class introduced in 4.5)
|
|
136
|
+
- **Node.js 20+**
|
|
137
|
+
- Any MCP client that speaks stdio
|
|
95
138
|
|
|
96
139
|
## Development
|
|
97
140
|
|
|
@@ -102,11 +145,8 @@ npm test
|
|
|
102
145
|
npm run generate-docs
|
|
103
146
|
```
|
|
104
147
|
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
- Node.js 20+
|
|
108
|
-
- Godot 4.5+
|
|
148
|
+
Contributions welcome — this project favors tools that solve real, time-wasting problems. Read [CONTRIBUTING.md](https://github.com/satelliteoflove/godot-mcp/blob/main/CONTRIBUTING.md) before building something big, or open an issue and we'll figure out the right shape together.
|
|
109
149
|
|
|
110
150
|
## License
|
|
111
151
|
|
|
112
|
-
MIT
|
|
152
|
+
[MIT](https://github.com/satelliteoflove/godot-mcp/blob/main/LICENSE)
|
package/addon/plugin.cfg
CHANGED
|
@@ -1,6 +1,14 @@
|
|
|
1
|
-
import { describe, it, expect } from 'vitest';
|
|
1
|
+
import { describe, it, expect, vi } from 'vitest';
|
|
2
2
|
import { createMockGodot, createToolContext } from '../helpers/mock-godot.js';
|
|
3
3
|
import { docs } from '../../tools/docs.js';
|
|
4
|
+
// These suites hit the LIVE Godot docs site (docs.ts does a real fetch). The tool
|
|
5
|
+
// aborts each request at FETCH_TIMEOUT_MS (15s); the heaviest test makes two
|
|
6
|
+
// sequential fetches, so on a slow CI network the total can exceed vitest's 5s
|
|
7
|
+
// default — the observed flake (a spurious red on otherwise-unrelated PRs). Raise
|
|
8
|
+
// the per-file timeout to comfortably cover ~2 live fetches plus margin. A truly
|
|
9
|
+
// unreachable docs site will still fail (by design — that is a real signal), but
|
|
10
|
+
// merely-slow responses no longer trip the clock.
|
|
11
|
+
vi.setConfig({ testTimeout: 40_000 });
|
|
4
12
|
describe('godot_docs tool', () => {
|
|
5
13
|
describe('schema validation', () => {
|
|
6
14
|
it('accepts valid version and section values', () => {
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"docs.test.js","sourceRoot":"","sources":["../../../src/__tests__/tools/docs.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;
|
|
1
|
+
{"version":3,"file":"docs.test.js","sourceRoot":"","sources":["../../../src/__tests__/tools/docs.test.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"watch-contract.test.d.ts","sourceRoot":"","sources":["../../../src/__tests__/tools/watch-contract.test.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
import { describe, it, expect, beforeEach } from 'vitest';
|
|
2
|
+
import { readFileSync } from 'node:fs';
|
|
3
|
+
import { fileURLToPath } from 'node:url';
|
|
4
|
+
import { dirname, resolve } from 'node:path';
|
|
5
|
+
import { createMockGodot, createToolContext, structuredOf, } from '../helpers/mock-godot.js';
|
|
6
|
+
import { runtimeState } from '../../tools/runtime-state.js';
|
|
7
|
+
// Cross-language wire-contract check for the watch lifecycle (#286).
|
|
8
|
+
//
|
|
9
|
+
// This pins the CONSUMER side: the TypeScript server's watch encode/decode must
|
|
10
|
+
// use exactly the key names in the shared artifact. The GDScript headless suite
|
|
11
|
+
// (godot/addons/godot_mcp/test/watch_contract_headless_test.gd) pins the PRODUCER
|
|
12
|
+
// side against the SAME file. A rename on either side now breaks its own suite
|
|
13
|
+
// instead of silently drifting (the TS `?? default` back-compat would otherwise
|
|
14
|
+
// swallow a vanished response key).
|
|
15
|
+
//
|
|
16
|
+
// The artifact is read at RUNTIME (not a static JSON import) so tsc's rootDir
|
|
17
|
+
// (src/) does not choke on a file outside it — the #287 lesson.
|
|
18
|
+
//
|
|
19
|
+
// KNOWN BOUNDARY: the request-key NAMES are pinned here on the SEND side; the
|
|
20
|
+
// editor command layer's consume of those names (runtime_state_commands.gd) and
|
|
21
|
+
// the editor->game positional decode are GDScript<->GDScript, off both suites'
|
|
22
|
+
// runtime paths. The high-value cross-language surface (response/event/sample
|
|
23
|
+
// keys) is pinned from both directions.
|
|
24
|
+
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
25
|
+
const CONTRACT_PATH = resolve(HERE, '../../../../godot/addons/godot_mcp/test/watch_contract.json');
|
|
26
|
+
function loadContract() {
|
|
27
|
+
try {
|
|
28
|
+
return JSON.parse(readFileSync(CONTRACT_PATH, 'utf8'));
|
|
29
|
+
}
|
|
30
|
+
catch (e) {
|
|
31
|
+
throw new Error(`Could not read the watch contract artifact at ${CONTRACT_PATH}. ` +
|
|
32
|
+
`It is the single source of truth shared with the GDScript headless suite; ` +
|
|
33
|
+
`if it moved, update CONTRACT_PATH here and the res:// path in the headless test. (${String(e)})`);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
const contract = loadContract();
|
|
37
|
+
// Build an object whose keys are EXACTLY the contract shape's required keys,
|
|
38
|
+
// pulling each value from `values`. Throws if the test fails to supply a value
|
|
39
|
+
// for a contract key — that forces the test fixtures to track the artifact, so a
|
|
40
|
+
// rename in the artifact surfaces here (not as a silently stale literal).
|
|
41
|
+
function objFromContract(shape, values) {
|
|
42
|
+
const def = contract[shape];
|
|
43
|
+
const out = {};
|
|
44
|
+
for (const key of def.required) {
|
|
45
|
+
if (!(key in values)) {
|
|
46
|
+
throw new Error(`test fixture for "${String(shape)}" is missing a value for contract key "${key}" — ` +
|
|
47
|
+
`update the fixture to match watch_contract.json`);
|
|
48
|
+
}
|
|
49
|
+
out[key] = values[key];
|
|
50
|
+
}
|
|
51
|
+
// Optional keys (e.g. event.args) ride along only when the test supplies them.
|
|
52
|
+
for (const key of def.optional ?? []) {
|
|
53
|
+
if (key in values)
|
|
54
|
+
out[key] = values[key];
|
|
55
|
+
}
|
|
56
|
+
return out;
|
|
57
|
+
}
|
|
58
|
+
describe('watch wire contract (#286)', () => {
|
|
59
|
+
let mock;
|
|
60
|
+
beforeEach(() => {
|
|
61
|
+
mock = createMockGodot();
|
|
62
|
+
});
|
|
63
|
+
it('the contract artifact is well-formed', () => {
|
|
64
|
+
const shapes = [
|
|
65
|
+
'watch_start_request',
|
|
66
|
+
'watch_start_response',
|
|
67
|
+
'unresolved_signal',
|
|
68
|
+
'watch_collect_response',
|
|
69
|
+
'field_sample',
|
|
70
|
+
'event',
|
|
71
|
+
];
|
|
72
|
+
for (const shape of shapes) {
|
|
73
|
+
const s = contract[shape];
|
|
74
|
+
expect(Array.isArray(s.required), shape).toBe(true);
|
|
75
|
+
expect(s.required.length, shape).toBeGreaterThan(0);
|
|
76
|
+
expect(Array.isArray(s.optional), shape).toBe(true);
|
|
77
|
+
}
|
|
78
|
+
// The editor->game positional order must name the same keys as the request.
|
|
79
|
+
expect([...contract.watch_start_request_positional].sort()).toEqual([...contract.watch_start_request.required].sort());
|
|
80
|
+
});
|
|
81
|
+
// ── Request: what the server SENDS ─────────────────────────────────────────
|
|
82
|
+
it('watch_start sends exactly the watch_start_request keys', async () => {
|
|
83
|
+
mock.mockResponse(objFromContract('watch_start_response', {
|
|
84
|
+
started: true,
|
|
85
|
+
resolved_fields: 0,
|
|
86
|
+
connected_signals: 0,
|
|
87
|
+
unresolved_signals: [],
|
|
88
|
+
}));
|
|
89
|
+
const ctx = createToolContext(mock);
|
|
90
|
+
await runtimeState.execute({ action: 'watch_start', specs: [], hz: 20, duration_ms: 1000, signals: [] }, ctx);
|
|
91
|
+
const call = mock.calls.find((c) => c.command === 'watch_start');
|
|
92
|
+
expect(call, 'watch_start command was sent').toBeDefined();
|
|
93
|
+
expect(Object.keys(call.params).sort()).toEqual([...contract.watch_start_request.required].sort());
|
|
94
|
+
});
|
|
95
|
+
// ── watch_start response: what the server READS ────────────────────────────
|
|
96
|
+
it('watch_start reads the watch_start_response / unresolved_signal keys', async () => {
|
|
97
|
+
const startResp = objFromContract('watch_start_response', {
|
|
98
|
+
started: true,
|
|
99
|
+
resolved_fields: 2,
|
|
100
|
+
connected_signals: 1,
|
|
101
|
+
unresolved_signals: [
|
|
102
|
+
objFromContract('unresolved_signal', {
|
|
103
|
+
path: '/root/Missing',
|
|
104
|
+
signal: 'fired',
|
|
105
|
+
reason: 'node_not_found',
|
|
106
|
+
}),
|
|
107
|
+
],
|
|
108
|
+
});
|
|
109
|
+
mock.mockResponse(startResp);
|
|
110
|
+
const ctx = createToolContext(mock);
|
|
111
|
+
const data = structuredOf(await runtimeState.execute({ action: 'watch_start', signals: [{ path: '/root/Missing', signal: 'fired' }] }, ctx));
|
|
112
|
+
// Each assertion proves the TS decode read a specific contract key.
|
|
113
|
+
expect(data.resolved_fields).toBe(2); // resolved_fields
|
|
114
|
+
expect(data.connected_signals).toBe(1); // connected_signals
|
|
115
|
+
expect(data.unresolved_signals).toHaveLength(1); // unresolved_signals
|
|
116
|
+
expect(data.unresolved_signals[0]).toMatchObject({
|
|
117
|
+
path: '/root/Missing', // unresolved_signal.path
|
|
118
|
+
signal: 'fired', // unresolved_signal.signal
|
|
119
|
+
reason: 'node_not_found', // unresolved_signal.reason
|
|
120
|
+
});
|
|
121
|
+
});
|
|
122
|
+
// ── watch_collect response: what the server READS ──────────────────────────
|
|
123
|
+
it('watch_collect decodes exactly the watch_collect_response / event / field_sample keys', async () => {
|
|
124
|
+
const raw = objFromContract('watch_collect_response', {
|
|
125
|
+
window_ms: 1000,
|
|
126
|
+
sample_count: 2,
|
|
127
|
+
fields: {
|
|
128
|
+
'/root/Player:hp': [
|
|
129
|
+
objFromContract('field_sample', { t_ms: 0, value: 100 }),
|
|
130
|
+
objFromContract('field_sample', { t_ms: 500, value: 80 }),
|
|
131
|
+
],
|
|
132
|
+
},
|
|
133
|
+
events: [objFromContract('event', { t_ms: 120, source: '/root/G', signal: 'hit', args: '[2]' })],
|
|
134
|
+
events_truncated: true,
|
|
135
|
+
events_dropped: 7,
|
|
136
|
+
events_dropped_by_signal: { '/root/G:hit': 7 },
|
|
137
|
+
fields_truncated: { '/root/Player:hp': true },
|
|
138
|
+
});
|
|
139
|
+
mock.mockResponse(raw);
|
|
140
|
+
const ctx = createToolContext(mock);
|
|
141
|
+
const data = structuredOf(await runtimeState.execute({ action: 'watch_collect' }, ctx));
|
|
142
|
+
// Top-level collect keys (each assertion = the TS decode read that key):
|
|
143
|
+
expect(data.window_ms).toBe(1000); // window_ms
|
|
144
|
+
expect(data.sample_count).toBe(2); // sample_count
|
|
145
|
+
expect(data.events_dropped).toBe(7); // events_dropped
|
|
146
|
+
expect(data.events_dropped_by_signal).toEqual({ '/root/G:hit': 7 }); // events_dropped_by_signal
|
|
147
|
+
expect(data.timeline_truncated).toBe(true); // events_truncated -> timeline_truncated
|
|
148
|
+
// events + event-dict keys: the signal landed in the timeline with its args.
|
|
149
|
+
const signalEntry = data.timeline.find((e) => e.kind === 'signal');
|
|
150
|
+
expect(signalEntry).toMatchObject({
|
|
151
|
+
t_ms: 120, // event.t_ms
|
|
152
|
+
source: '/root/G', // event.source
|
|
153
|
+
name: 'hit', // event.signal (renamed to `name` in the timeline entry)
|
|
154
|
+
args: '[2]', // event.args (optional)
|
|
155
|
+
});
|
|
156
|
+
// fields + field_sample keys: the field summary reflects the sampled values,
|
|
157
|
+
// and fields_truncated surfaced as samples_truncated.
|
|
158
|
+
const hp = data.fields['/root/Player:hp'];
|
|
159
|
+
expect(hp).toBeDefined(); // fields
|
|
160
|
+
expect(hp.start).toBe(100); // field_sample.t_ms/value drove the summary
|
|
161
|
+
expect(hp.end).toBe(80);
|
|
162
|
+
expect(hp.samples_truncated).toBe(true); // fields_truncated
|
|
163
|
+
});
|
|
164
|
+
});
|
|
165
|
+
//# sourceMappingURL=watch-contract.test.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"watch-contract.test.js","sourceRoot":"","sources":["../../../src/__tests__/tools/watch-contract.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EACL,eAAe,EACf,iBAAiB,EACjB,YAAY,GAEb,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAE5D,qEAAqE;AACrE,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,kFAAkF;AAClF,+EAA+E;AAC/E,gFAAgF;AAChF,oCAAoC;AACpC,EAAE;AACF,8EAA8E;AAC9E,gEAAgE;AAChE,EAAE;AACF,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,8EAA8E;AAC9E,wCAAwC;AAExC,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACrD,MAAM,aAAa,GAAG,OAAO,CAAC,IAAI,EAAE,6DAA6D,CAAC,CAAC;AAgBnG,SAAS,YAAY;IACnB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAa,CAAC;IACrE,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,iDAAiD,aAAa,IAAI;YAChE,4EAA4E;YAC5E,qFAAqF,MAAM,CAAC,CAAC,CAAC,GAAG,CACpG,CAAC;IACJ,CAAC;AACH,CAAC;AAED,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;AAEhC,6EAA6E;AAC7E,+EAA+E;AAC/E,iFAAiF;AACjF,0EAA0E;AAC1E,SAAS,eAAe,CAAC,KAAqB,EAAE,MAA+B;IAC7E,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAU,CAAC;IACrC,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,CAAC,GAAG,IAAI,MAAM,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CACb,qBAAqB,MAAM,CAAC,KAAK,CAAC,0CAA0C,GAAG,MAAM;gBACnF,iDAAiD,CACpD,CAAC;QACJ,CAAC;QACD,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IACD,+EAA+E;IAC/E,KAAK,MAAM,GAAG,IAAI,GAAG,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;QACrC,IAAI,GAAG,IAAI,MAAM;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,QAAQ,CAAC,4BAA4B,EAAE,GAAG,EAAE;IAC1C,IAAI,IAAyB,CAAC;IAE9B,UAAU,CAAC,GAAG,EAAE;QACd,IAAI,GAAG,eAAe,EAAE,CAAC;IAC3B,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,MAAM,GAAuB;YACjC,qBAAqB;YACrB,sBAAsB;YACtB,mBAAmB;YACnB,wBAAwB;YACxB,cAAc;YACd,OAAO;SACR,CAAC;QACF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAU,CAAC;YACnC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpD,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;YACpD,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;QACD,4EAA4E;QAC5E,MAAM,CAAC,CAAC,GAAG,QAAQ,CAAC,8BAA8B,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CACjE,CAAC,GAAG,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAClD,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,8EAA8E;IAE9E,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,IAAI,CAAC,YAAY,CACf,eAAe,CAAC,sBAAsB,EAAE;YACtC,OAAO,EAAE,IAAI;YACb,eAAe,EAAE,CAAC;YAClB,iBAAiB,EAAE,CAAC;YACpB,kBAAkB,EAAE,EAAE;SACvB,CAAC,CACH,CAAC;QACF,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAEpC,MAAM,YAAY,CAAC,OAAO,CACxB,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,EAC5E,GAAG,CACJ,CAAC;QAEF,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,KAAK,aAAa,CAAC,CAAC;QACjE,MAAM,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC,WAAW,EAAE,CAAC;QAC3D,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,IAAK,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,GAAG,QAAQ,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IACtG,CAAC,CAAC,CAAC;IAEH,8EAA8E;IAE9E,EAAE,CAAC,qEAAqE,EAAE,KAAK,IAAI,EAAE;QACnF,MAAM,SAAS,GAAG,eAAe,CAAC,sBAAsB,EAAE;YACxD,OAAO,EAAE,IAAI;YACb,eAAe,EAAE,CAAC;YAClB,iBAAiB,EAAE,CAAC;YACpB,kBAAkB,EAAE;gBAClB,eAAe,CAAC,mBAAmB,EAAE;oBACnC,IAAI,EAAE,eAAe;oBACrB,MAAM,EAAE,OAAO;oBACf,MAAM,EAAE,gBAAgB;iBACzB,CAAC;aACH;SACF,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,CAAC,SAAS,CAAC,CAAC;QAC7B,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAEpC,MAAM,IAAI,GAAG,YAAY,CACvB,MAAM,YAAY,CAAC,OAAO,CACxB,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,EAChF,GAAG,CACJ,CACF,CAAC;QAEF,oEAAoE;QACpE,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB;QACxD,MAAM,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,oBAAoB;QAC5D,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,qBAAqB;QACtE,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC;YAC/C,IAAI,EAAE,eAAe,EAAE,yBAAyB;YAChD,MAAM,EAAE,OAAO,EAAE,2BAA2B;YAC5C,MAAM,EAAE,gBAAgB,EAAE,2BAA2B;SACtD,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IAEH,8EAA8E;IAE9E,EAAE,CAAC,sFAAsF,EAAE,KAAK,IAAI,EAAE;QACpG,MAAM,GAAG,GAAG,eAAe,CAAC,wBAAwB,EAAE;YACpD,SAAS,EAAE,IAAI;YACf,YAAY,EAAE,CAAC;YACf,MAAM,EAAE;gBACN,iBAAiB,EAAE;oBACjB,eAAe,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;oBACxD,eAAe,CAAC,cAAc,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;iBAC1D;aACF;YACD,MAAM,EAAE,CAAC,eAAe,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;YAChG,gBAAgB,EAAE,IAAI;YACtB,cAAc,EAAE,CAAC;YACjB,wBAAwB,EAAE,EAAE,aAAa,EAAE,CAAC,EAAE;YAC9C,gBAAgB,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE;SAC9C,CAAC,CAAC;QACH,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QACvB,MAAM,GAAG,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAEpC,MAAM,IAAI,GAAG,YAAY,CAAC,MAAM,YAAY,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,eAAe,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC;QAExF,yEAAyE;QACzE,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY;QAC/C,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe;QAClD,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,iBAAiB;QACtD,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,2BAA2B;QAChG,MAAM,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,yCAAyC;QAErF,6EAA6E;QAC7E,MAAM,WAAW,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAmB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC;QACrF,MAAM,CAAC,WAAW,CAAC,CAAC,aAAa,CAAC;YAChC,IAAI,EAAE,GAAG,EAAE,aAAa;YACxB,MAAM,EAAE,SAAS,EAAE,eAAe;YAClC,IAAI,EAAE,KAAK,EAAE,yDAAyD;YACtE,IAAI,EAAE,KAAK,EAAE,wBAAwB;SACtC,CAAC,CAAC;QAEH,6EAA6E;QAC7E,sDAAsD;QACtD,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC;QAC1C,MAAM,CAAC,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC,SAAS;QACnC,MAAM,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,4CAA4C;QACxE,MAAM,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACxB,MAAM,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,mBAAmB;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"usage-logger.d.ts","sourceRoot":"","sources":["../../src/utils/usage-logger.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"usage-logger.d.ts","sourceRoot":"","sources":["../../src/utils/usage-logger.ts"],"names":[],"mappings":"AA6DA,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CAqBN;AAOD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CActD"}
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import * as fs from 'fs';
|
|
2
2
|
import * as path from 'path';
|
|
3
3
|
import * as os from 'os';
|
|
4
|
+
import { getServerVersion } from '../version.js';
|
|
4
5
|
const DEFAULT_MAX_SIZE_BYTES = 10 * 1024 * 1024; // 10MB
|
|
5
6
|
const LOG_DIR = path.join(os.homedir(), '.godot-mcp');
|
|
6
7
|
const LOG_FILE = path.join(LOG_DIR, 'usage.log');
|
|
@@ -48,6 +49,7 @@ export function logToolUsage(tool, args, success, durationMs, responseBytes, err
|
|
|
48
49
|
return;
|
|
49
50
|
const entry = {
|
|
50
51
|
ts: new Date().toISOString(),
|
|
52
|
+
mcp_version: getServerVersion(),
|
|
51
53
|
tool,
|
|
52
54
|
success,
|
|
53
55
|
duration_ms: Math.round(durationMs),
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"usage-logger.js","sourceRoot":"","sources":["../../src/utils/usage-logger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;AACzB,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAC7B,OAAO,KAAK,EAAE,MAAM,IAAI,CAAC;
|
|
1
|
+
{"version":3,"file":"usage-logger.js","sourceRoot":"","sources":["../../src/utils/usage-logger.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@satelliteoflove/godot-mcp",
|
|
3
|
-
"version": "3.
|
|
4
|
-
"description": "MCP server
|
|
3
|
+
"version": "3.22.0",
|
|
4
|
+
"description": "MCP server that gives AI assistants eyes and hands in the Godot editor: scene editing, input injection, deterministic game-time control, and live runtime state for agent-driven playtesting",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
7
7
|
"bin": {
|
|
@@ -33,12 +33,18 @@
|
|
|
33
33
|
},
|
|
34
34
|
"keywords": [
|
|
35
35
|
"godot",
|
|
36
|
+
"godot4",
|
|
36
37
|
"mcp",
|
|
38
|
+
"mcp-server",
|
|
37
39
|
"model-context-protocol",
|
|
38
40
|
"ai",
|
|
39
|
-
"
|
|
41
|
+
"ai-agents",
|
|
42
|
+
"claude",
|
|
43
|
+
"game-development",
|
|
44
|
+
"game-testing",
|
|
45
|
+
"gdscript"
|
|
40
46
|
],
|
|
41
|
-
"author": "",
|
|
47
|
+
"author": "Christopher Childress",
|
|
42
48
|
"license": "MIT",
|
|
43
49
|
"dependencies": {
|
|
44
50
|
"@modelcontextprotocol/sdk": "^1.0.0",
|