# debugtron-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI agents debug
installed **Electron apps** end-to-end: discover apps, launch them with debug
ports, evaluate JavaScript in the main process and renderer pages, capture
console/IPC/network traffic, take screenshots, simulate input, profile CPU and
heap, set breakpoints, read script sources, and inspect workers.

App discovery and launch adapters are vendored from
[debugtron](https://github.com/pd4d10/debugtron) (MIT); the debugging surface
(Chrome DevTools Protocol + Node inspector) is exposed as 40+ MCP tools.

## Requirements

- Node.js >= 22
- macOS / Windows / Linux (remote Android debugging via `adb` is supported by
  the underlying adapters but currently limited to page-level CDP)

## Build

```sh
yarn install
yarn build        # outputs dist/index.js (single-file ESM bundle)
yarn typecheck    # optional
```

## Usage

Register with your MCP client over stdio. For Claude Code:

```sh
claude mcp add debugtron -- node /path/to/debugtron-mcp/dist/index.js
```

Or explore interactively with the MCP inspector:

```sh
npx @modelcontextprotocol/inspector node dist/index.js
```

### Typical agent session

1. `list_apps` — discover installed Electron apps
2. `launch_app` — launch one (by `appId` or direct `exePath`), get a `sessionId`
3. `list_pages` — find renderer windows/webviews/workers (retry until they appear)
4. `evaluate_in_main` / `evaluate_in_renderer` — run JS in either process
5. `get_console_logs` / `get_network_log` / `get_process_logs` — observe behavior
6. `get_response_body` / `get_cookies` / `get_local_storage` — inspect network/state
7. `screenshot` / `click` / `type` / `navigate` — drive the UI
8. `monitor_ipc` + `get_ipc_log` — capture IPC traffic
9. `monitor_events` + `get_event_log` — capture lifecycle/navigation/crash events
10. `list_scripts` + `get_script_source` — read app bundles for static analysis
11. `set_breakpoint` / `evaluate_on_call_frame` / `step_over` — debug at source level
12. `get_heap_snapshot` / `start_cpu_profile` — deep performance diagnostics
13. `list_workers` / `evaluate_in_worker` — debug service/shared/dedicated workers
14. `stop_session` — terminate the app and clean up

## Tools

### Sessions & discovery

| Tool | Description |
| --- | --- |
| `list_apps` | Discover installed Electron apps (`targetId?`, `refresh?`) |
| `launch_app` | Launch an app with `--inspect` + `--remote-debugging-port` (`appId?` or `exePath?`, `env?`, `cwd?`) |
| `stop_session` | Close CDP connections and terminate the app (idempotent) |
| `list_sessions` | List active sessions with status and ports |
| `list_pages` | List renderer targets: pages, webviews, workers |
| `get_process_logs` | App process stdout/stderr (works after exit) |

### Execution & observation

| Tool | Description |
| --- | --- |
| `evaluate_in_main` | Run JS in the Electron main process (Node inspector) |
| `evaluate_in_renderer` | Run JS in a renderer page (CDP `Runtime.evaluate`) |
| `get_console_logs` | Console messages + uncaught exceptions from main and pages |
| `get_network_log` | Network requests captured per page (includes `requestId`) |
| `get_response_body` | Get the response body of a captured request by `requestId` |
| `get_cookies` | Read all cookies from the browser network stack (incl HttpOnly) |
| `get_local_storage` | Read localStorage or sessionStorage entries |
| `get_app_info` | Electron/Chromium/Node versions, app paths, BrowserWindow list |
| `get_process_metrics` | Per-process CPU% and memory (app.getAppMetrics) |

### Page control & DOM

| Tool | Description |
| --- | --- |
| `navigate` / `reload` | Page navigation (waits for load event, non-fatal) |
| `screenshot` | PNG/JPEG screenshot returned as MCP image content |
| `get_dom_snapshot` | outerHTML of the document or a selector (truncatable) |
| `query_selector` | Element tag/text/attributes/bounding rect by CSS selector |
| `click` / `type` | Input simulation by selector or coordinates (unicode-safe) |
| `get_performance_metrics` | Renderer metrics: JS heap, DOM nodes, layout counts |

### Electron-specific

| Tool | Description |
| --- | --- |
| `monitor_ipc` / `get_ipc_log` | Capture IPC traffic (ipcMain send/invoke, webContents.send) |
| `monitor_events` / `get_event_log` | Capture lifecycle events (crashes, unresponsive, navigation, window creation) |

### Debugging & profiling

| Tool | Description |
| --- | --- |
| `list_scripts` | List parsed scripts (filter by URL substring) |
| `get_script_source` | Read script source by scriptId (for static analysis of app.asar bundles) |
| `set_breakpoint` / `remove_breakpoint` / `list_breakpoints` | Breakpoints by script URL or regex, main or renderer |
| `pause` / `resume` / `get_paused_state` | Execution control and paused call-stack inspection |
| `evaluate_on_call_frame` | Evaluate in a paused frame context (access local variables) |
| `step_over` / `step_into` / `step_out` | Single-step execution |
| `get_heap_snapshot` | V8 heap snapshot written to a `.heapsnapshot` file |
| `start_cpu_profile` / `stop_cpu_profile` | CPU profile to `.cpuprofile` + hottest-functions summary |

### Workers

| Tool | Description |
| --- | --- |
| `list_workers` | List service workers, shared workers, dedicated workers (Target domain) |
| `evaluate_in_worker` | Run JS in a worker target via the flatten protocol |

Heap snapshots and CPU profiles are written to files (default: system temp
dir, override with `filePath`) and can be opened in Chrome DevTools.

## Notes & limitations

- **Single-instance lock**: apps using `requestSingleInstanceLock` (e.g. VS
  Code) must be fully closed before `launch_app`; otherwise the second
  instance forwards to the running one and the debug flags are dropped. The
  tool error message tells you when this happens.
- **Pages appear asynchronously**: retry `list_pages` for a few seconds after
  launch.
- **`monitor_ipc`** captures `send` messages on `ipcMain` at any time, but
  `invoke` handlers only if they were registered *after* monitoring started
  (Electron dispatches `handle()` internally, not through the emitter).
- **Breakpoints on inline scripts** (e.g. inside `data:` URLs) don't bind;
  use them on real script files (`file://.../app.asar/...`, `http(s)://...`).
- **Workers** are discovered via the browser-level Target domain (separate from
  `/json`). Some older Electron versions may not expose all worker types.
- Diagnostics are written to stderr; stdout is reserved for the MCP protocol.

## Acknowledgements

- Target discovery/launch adapters (`src/targets/`) and the `AppInfo` type are
  vendored from [debugtron](https://github.com/pd4d10/debugtron) by Rongjian
  Zhang (MIT License).

## License

MIT