@csmodding/gameface-devtools-mcp 0.2.0 → 1.0.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 (3) hide show
  1. package/README.md +43 -32
  2. package/dist/server.mjs +1750 -463
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -125,54 +125,65 @@ Or in `.vscode/mcp.json` (note the `servers` key, not `mcpServers`):
125
125
 
126
126
  ## Tools
127
127
 
128
- | Tool | What it does | Under the hood |
129
- | ----------------- | ------------------------------------------------------------------------------- | ----------------------------------- |
130
- | `game_status` | Reachability + page target + engine info. Run first when things fail. | `/json/list` + `/json/version` |
131
- | `game_eval` | Evaluate a JS expression in the Gameface UI, returns the value as JSON. | `Runtime.evaluate` (returnByValue) |
132
- | `game_screenshot` | Screenshot the viewport (or a selector's box) as an inline image. | `Page.captureScreenshot` (+ `clip`) |
133
- | `game_dom` | DOM details (tag, classes, attributes, rect, outerHTML) for a CSS selector. | `Runtime.evaluate` |
134
- | `game_wait` | Wait until a selector matches (optionally visible) or a JS predicate is truthy. | polled `Runtime.evaluate` |
135
- | `game_click` | Click an element by dispatching real bubbling DOM events. | `Runtime.evaluate` (see note) |
136
- | `game_fill` | Set an input/textarea/contenteditable value. | `Runtime.evaluate` (see note) |
137
- | `game_type` | Type text key by key (real KeyboardEvents + value sync). | `Runtime.evaluate` (see note) |
138
- | `game_hover` | Hover an element (over/enter/move sequence) to trigger tooltips/hover state. | `Runtime.evaluate` (see note) |
139
- | `game_console` | Recent `console.*`, log entries, and uncaught exceptions from the Gameface UI. | `Log` + `Runtime.consoleAPICalled` |
140
-
128
+ | Tool | What it does | Under the hood |
129
+ | --- | --- | --- |
130
+ | `game_status` | Reachability + page target + engine info + view-reload tracking (count, last reload, context id). Run first when things fail. | `/json/list` + `/json/version` + `Runtime.executionContextCreated` |
131
+ | `game_eval` | Evaluate a JS expression in the Gameface UI, returns the value as JSON. | `Runtime.evaluate` (returnByValue) |
132
+ | `game_screenshot` | Screenshot the viewport (or a selector's box) as an inline image. | `Page.captureScreenshot` (+ `clip`) |
133
+ | `game_dom` | DOM details (tag, classes, attributes, rect, outerHTML) for a CSS selector. | `Runtime.evaluate` |
134
+ | `game_query` | Find elements by selector and/or text; returns rect + optional attributes and handles. | `Runtime.evaluate` |
135
+ | `game_wait` | Wait for a view reload and/or until a selector matches (optionally visible) or a JS predicate is truthy. | polled `Runtime.evaluate` + `Runtime.executionContextCreated` |
136
+ | `game_click` | Click an element by dispatching real bubbling DOM events. | `Runtime.evaluate` (see note) |
137
+ | `game_fill` | Set an input/textarea/contenteditable value. | `Runtime.evaluate` (see note) |
138
+ | `game_type` | Type text key by key (real KeyboardEvents + value sync). | `Runtime.evaluate` (see note) |
139
+ | `game_key` | Press a named key (Escape/Enter/arrows/…) as bubbling keydown+keyup, with modifiers/repeats. | `Runtime.evaluate` (see note) |
140
+ | `game_hover` | Hover an element (over/enter/move sequence) to trigger tooltips/hover state. | `Runtime.evaluate` (see note) |
141
+ | `game_console` | Recent `console.*`, log entries, and uncaught exceptions from the Gameface UI, timestamped, with object arguments expanded to their real values and re-readable deeper. | `Log` + `Runtime.consoleAPICalled` + `Runtime.exceptionThrown` + `Runtime.callFunctionOn` |
142
+
143
+ > [!IMPORTANT]
141
144
  > **Input is done via DOM events, not CDP `Input`.** Gameface accepts `Input.dispatchMouseEvent` /
142
145
  > `dispatchKeyEvent` but never delivers them to the UI. So `game_click`, `game_fill`, `game_type`,
143
- > and `game_hover` dispatch real DOM events in the page.
146
+ > `game_key`, and `game_hover` dispatch real DOM events in the page. These reach the UI's own JS
147
+ > handlers, but not any input the game routes at the native/engine level (e.g. Escape-to-close is
148
+ > often handled natively and will not respond to a dispatched key).
144
149
 
145
150
  ### JS debugger tools
146
151
 
147
152
  The Gameface UI's V8 `Debugger` domain is fully supported, so these drive a real source-level
148
153
  debugger.
149
154
 
150
- | Tool | What it does |
151
- | ------------------------------ | ------------------------------------------------------------------------------------------------------------- |
152
- | `game_debug_status` | Debugger state: paused?/where, pause-on-exceptions, breakpoints, script count. Also sets pause-on-exceptions. |
153
- | `game_debug_scripts` | List parsed UI scripts (scriptId + url), filterable by url substring. |
154
- | `game_debug_source` | Get a script's source (by scriptId) with line numbers, optionally a line range. |
155
- | `game_debug_set_breakpoint` | Break at url-substring + line (1-based), with an optional JS condition. |
156
- | `game_debug_remove_breakpoint` | Remove a breakpoint by id, or `all`. |
157
- | `game_debug_pause_state` | When paused: the call stack, optionally with each frame's local/closure variables. |
158
- | `game_debug_evaluate` | Evaluate in the paused frame's scope (read locals), or globally when running. |
159
- | `game_debug_step` | `resume` / `over` / `into` / `out` / `pause`. |
155
+ | Tool | What it does |
156
+ | --- | --- |
157
+ | `game_debug_status` | Debugger state: paused?/where, pause-on-exceptions, breakpoints, script count. Also sets pause-on-exceptions. |
158
+ | `game_debug_scripts` | List parsed UI scripts (scriptId + url), filterable by url substring. |
159
+ | `game_debug_source` | Get a script's source (by scriptId) with line numbers, optionally a line range. |
160
+ | `game_debug_search_source` | Find a literal string across the parsed sources; returns url + line + column (1-based) and a snippet per hit. |
161
+ | `game_debug_set_breakpoint` | Break at url-substring + line, optionally column (both 1-based), with an optional JS condition. Reports where the engine bound it. |
162
+ | `game_debug_remove_breakpoint` | Remove a breakpoint by id, or `all`. |
163
+ | `game_debug_pause_state` | When paused: the call stack, optionally with each frame's local/closure variables. |
164
+ | `game_debug_evaluate` | Evaluate in the paused frame's scope (read locals), or globally when running. |
165
+ | `game_debug_step` | `resume` / `over` / `into` / `out` / `pause`. |
160
166
 
161
167
  > **Hitting a breakpoint or pausing FREEZES the UI thread until you resume** (`game_debug_step`
162
168
  > with `resume`). Prefer conditional breakpoints to limit freezes, and while paused inspect with
163
169
  > `game_debug_evaluate` rather than `game_eval`. Safety net: if the server's connection drops while
164
170
  > paused, the engine auto-resumes.
165
171
 
172
+ > **The debugger only sees scripts parsed since it attached**: Gameface does not replay
173
+ > `scriptParsed`, so a late attach lists nothing until a view reload re-parses everything.
174
+ > Breakpoints, on the other hand, survive a reload: the engine re-binds its own registrations to the
175
+ > re-parsed script.
176
+
166
177
  ## Configuration
167
178
 
168
179
  All are optional, read by the server from the environment:
169
180
 
170
- | Variable | Default | Purpose |
171
- | ----------------------------- | ----------- | ---------------------------------------- |
172
- | `GAMEFACE_HOST` | `localhost` | Host of the Gameface CDP endpoint. |
173
- | `GAMEFACE_PORT` | `9444` | Port of the Gameface CDP endpoint. |
174
- | `GAMEFACE_CONNECT_TIMEOUT_MS` | `5000` | HTTP discovery / WebSocket open timeout. |
175
- | `GAMEFACE_CALL_TIMEOUT_MS` | `15000` | Per-command reply timeout. |
181
+ | Variable | Default | Purpose |
182
+ | --- | --- | --- |
183
+ | `GAMEFACE_HOST` | `localhost` | Host of the Gameface CDP endpoint. |
184
+ | `GAMEFACE_PORT` | `9444` | Port of the Gameface CDP endpoint. |
185
+ | `GAMEFACE_CONNECT_TIMEOUT_MS` | `5000` | HTTP discovery / WebSocket open timeout. |
186
+ | `GAMEFACE_CALL_TIMEOUT_MS` | `15000` | Per-command reply timeout. |
176
187
 
177
188
  ## Troubleshooting
178
189
 
@@ -187,5 +198,5 @@ All are optional, read by the server from the environment:
187
198
  The server is developed in the
188
199
  [agents-plugins](https://github.com/CitiesSkylinesModding/agents-plugins)
189
200
  repository, where this package lives as the `plugins/coherent-gameface/mcp/` workspace. See the
190
- repository README for the development setup, and its `AGENTS.md` for the verified Gameface CDP
191
- behavior matrix.
201
+ repository README for the development setup, and the plugin's `AGENTS.md`
202
+ (`plugins/coherent-gameface/AGENTS.md`) for the verified Gameface CDP behavior matrix.