DevCDP

# DevCDP

Real Chrome DevTools access for an AI assistant, over MCP. Your assistant reads the
console, watches the network, queries the DOM, resolves source maps, sets
breakpoints and inspects live variables — so it can tell you *why* something broke
instead of guessing from a pasted error.

Works with any assistant that speaks MCP, and with any web app: nothing about a
particular framework, product or company is built in.

**74 tools** — see [docs/TOOLS.md](docs/TOOLS.md) for the full reference, generated
from the server itself, and [docs/PERFORMANCE.md](docs/PERFORMANCE.md) for measured
token costs and how to lower them.

---

## What it does

| | |
|---|---|
| **Console** | Logs, warnings and uncaught exceptions with file, 1-based line and stack. |
| **Network** | Every request from the moment it attaches — method, status, timing, size, initiator, and response bodies on request. |
| **DOM** | Selector queries with real visibility and geometry, named computed styles, mutation history, iframe support, and structural dialog detection. |
| **Sources** | Loaded scripts, plus original pre-bundling files recovered from source maps — including external `.map` files behind authentication. Full-text search across both. |
| **Debugger** | Breakpoints on original files by original line, stepping, and scope inspection that expands nested objects instead of printing `Object`. |
| **Discovery** | Asks the app what it is: framework, routing, working selectors for its buttons and fields, its backend API surface, and your project's own docs. |
| **Collaboration** | You can take over at any time; what you click, choose and type is recorded and readable by the assistant. |

### Four things it is careful about

**It never fakes success.** A breakpoint that cannot bind says `bound: false` and
explains why. A body Chrome has discarded says so. A capture from a pause that has
already resumed is marked stale. Every failure is `{ok: false, code, message, hint}`
with the next action named.

**It tells you where its knowledge ends.** Chrome cannot replay console history to
a debugger that attaches later, so attaching reports exactly that rather than
presenting an empty buffer as "no errors".

**It cannot be stranded.** Every call into the page is bounded on *our* side —
`Runtime.evaluate`'s own timeout is enforced by the renderer, which is useless when
the renderer is what is stuck. A page wedged in an infinite loop fails in seconds
with the recovery path named, and DevCDP will abort the runaway script and retry by
itself.

**It never leaves your app frozen.** Breakpoints capture what you need and then
resume on their own. A pause held deliberately is still released after
`maxPauseMs`, and everything is cleaned up on disconnect.

---

## Install

**Requirements:** Node 18+, Chrome, and an MCP-capable assistant.

Pick whichever fits your client. All of them run the same server on your machine; nothing
is hosted.

**Any MCP client, from npm.** Add to the client's MCP config:

```json
{ "mcpServers": { "devcdp": { "command": "npx", "args": ["-y", "devcdp"] } } }
```

On native Windows some clients need `"command": "cmd", "args": ["/c", "npx", "-y", "devcdp"]`.

**Claude Code, as a plugin** (server plus a skill that tells Claude when to reach for which tool):

```
/plugin marketplace add Dayananda-D/DevCDP
/plugin install devcdp@devcdp
```

**Cursor:** [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=devcdp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsImRldmNkcCJdfQ==),
or add the JSON above to `~/.cursor/mcp.json`.

**Gemini CLI**, as an extension that also carries the usage guidance:

```
gemini extensions install https://github.com/Dayananda-D/DevCDP
```

**opencode:** `opencode mcp add`, or in `opencode.json`:

```json
{ "mcp": { "devcdp": { "type": "local", "command": ["npx", "-y", "devcdp"], "enabled": true } } }
```

**Codex** (CLI, desktop, VS Code extension), as a plugin:

```
codex plugin marketplace add Dayananda-D/DevCDP
```

**VS Code:** [Install in VS Code](https://vscode.dev/redirect/mcp/install?name=devcdp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22devcdp%22%5D%7D), or run *MCP: Add Server*, choose *NPM Package*,
and enter `devcdp`. **Copilot CLI:** `/mcp add` with command `npx -y devcdp`. DevCDP is in
the [official MCP Registry](https://registry.modelcontextprotocol.io/?q=devcdp); the picker
inside VS Code shows GitHub's curated subset of that registry, which is a separate listing.

**From source**, with the setup wizard that also writes usage guidance into your
assistant's instructions file: see Setup, next.

Then launch Chrome with remote debugging (`debug-chrome.bat`, or
`chrome --remote-debugging-port=9222 --user-data-dir=<a separate profile>`), open your
app, and describe the bug.

---

## Setup

```
1. node initialize_MCP.js      (or double-click initialize_MCP.bat)
2. Fully quit and reopen your assistant
3. Double-click debug-chrome.bat, open your app
4. Describe the bug
```

The wizard detects installed editors, writes the right config shape for each, and
drops a launcher. It **never** overwrites a config file it cannot parse — it prints
the snippet to paste instead — every write is atomic with one timestamped backup,
and duplicate registrations from older installs are removed. That path is covered
by 23 tests, because getting it wrong damages your machine rather than just failing.

---

## Settings

Everything is optional. Ask the assistant to run `devcdp_settings` to see the
effective values and where each came from, or `devcdp_settings_init` to write an
annotated file you can edit.

Files are merged, later winning, so an install-wide baseline can be overridden per
project:

```
<install>/devcdp.settings.json   or  <install>/settings.json
<cwd>/.devcdp/settings.json
<cwd>/devcdp.settings.json
```

then `DEVCDP_*` environment variables, then tool arguments. Comments and trailing
commas are tolerated.

| Setting | Default | |
|---|---|---|
| `toasts` | `true` | show live status messages |
| `toastMs` · `toastOpacity` · `toastMaxVisible` | `3500` · `0.78` · `3` | how long, how visible, how many |
| `badge` · `badgeCorner` · `edgePulse` | `true` · `"tc"` · `true` | the tab indicator and its breathing border |
| `badgeCorner` positions | `tc` · `bc` · `tl` · `tr` · `bl` · `br` | where the overlay parks. Drag the chip to move it anywhere; that position is remembered per origin. Messages travel with it, so `toastCorner` follows `badgeCorner` |
| `showCursor` · `highlightInspected` | `true` · `true` | show where interaction happens, and what was inspected |
| `ownerTimeoutMs` | `45000` | how long an indicator stays up without hearing from its session, before removing itself |
| `followNewTabs` | `true` | mark and hold tabs the app opens for itself, so a popup is never an unmarked blind spot |
| `chromeProfile` | `"isolated"` | or `"default"` to reuse your signed-in Chrome, or a path |
| `disableWebSecurity` | `false` | leave off: it hides the CORS bugs you would be debugging |
| `chromeFlags` | `[]` | extra Chrome flags |
| `evalTimeoutMs` · `toolTimeoutMs` | `8000` · `30000` | liveness ceilings |
| `autoResumeDefault` · `maxPauseMs` | `true` · `30000` | autonomous pause control |
| `captureInputValues` | `false` | always-on capture of typed values |
| `docsRoot` | auto | where to read your project's README and docs |
| `sharedMemoryDir` | `null` | pool learned fixes across a team |
| `tabGroupMode` | `"session"` | one tab group per session, or `"single"` for all |

`docsRoot` and `sharedMemoryDir` are the two worth setting: the first lets the
assistant learn your domain vocabulary, the second is what makes "the team's fixes
accumulate" actually true.

---

## Multiple sessions at once

Several agents can debug on one machine safely. Each session **claims** a tab in a
registry under `~/.devcdp/registry/`, taken atomically so two processes cannot win
the same tab. A session that dies stops heartbeating and its claim is reaped, so
nothing stays wedged.

- A new session gets an unclaimed tab; if all are taken it opens its own — **on the
  page you wanted**, not blank, and it says why.
- Reloading your assistant briefly overlaps two server processes, so a short grace
  period lets the departing one release its tab and the new one simply reattaches.
- `browser: 'new'` launches a separate Chrome, own port and profile.
- `window: 'new'` gives the session its own browser window.
- `sessions_list` shows which session holds which tab.

## Knowing which tab is in use

Every claimed tab carries a **1px edge border** and a small
identity chip. The border tells you who is driving:

- **breathing blue glow** — DevCDP is working
- **still, green** — it has handed control to you
- **still, red** — something failed

Three states, three colours, and each colour means exactly one thing regardless of how
many sessions are running. Sessions are told apart by the chip text and by their own
Chrome tab group — not by hue, which would turn the border into a puzzle when the only
thing worth knowing at a glance is whether the tab is waiting for you.

**Tabs the app opens for itself** — `window.open`, `target="_blank"`, a detail screen
in its own window — are marked and held too, labelled "opened tab". `devtools_status`
lists them under `tabsAppOpened`, with the call that switches to one.

**The indicator cannot outlive the session that drew it.** A normal finish — you close
the assistant, it disconnects, the session ends — removes the border immediately. If the
server is *killed* and never gets to clean up, the overlay notices it has stopped hearing
from its session and removes itself within `ownerTimeoutMs` (45s), taking the tab out of
its group with it. Either way, a border on screen means a session is genuinely there. For
one left behind by an older build, `node scripts/sweep.mjs` clears any that no live
session owns (`--dry` to look first).