devharness

npm version license

MCP server. Your agent runs the app, sees what happened, and redoes none of it by hand.

npx devharness@latest

Was cdp-tools-mcp. That name described the transport. CDP is now one of three things this does. Migrating.

Why

Three things burn a debugging session, and only the first is about seeing.

You are the eyes. You start the app, click the thing, paste the stack trace back into chat, reload and report whether it worked.

Everything gets re-driven by hand. Relaunch the browser, log in again, refill the form, click back to the screen where the bug lives — every iteration. Slow, and the retyped arguments drift from what actually ran.

One failure stalls the whole session. A dead dev server, a missing parameter, a wedged tool: the agent stops and waits for you.

devharness closes all three. Real execution instead of guesses. Every call it has already made is replayable by index. Failures have recovery paths the agent takes itself.

What it does

24 tool modules. 802 tests across 57 files, ~7s.

See — pause real execution and read the real frame: breakpoints (line, conditional, logpoint, DOM mutation, event, XHR), call stack and scope, source maps so TypeScript breakpoints hit TypeScript lines. Chrome and Node.js (node --inspect), both at once. Console, network, storage, DOM. content verify reports dead buttons, dead links, small touch targets, and overflow clipping from CDP facts, not heuristics.

Repeat — every tool response carries its own history index:

**Repeat:** replay({ action: 'repeat', indices: [58] })

indices takes a list, so four steps re-run in one call. Whatever the agent already did, it redoes by reference rather than by retyping. Worth keeping? replay({ action: 'create', ... }) promotes it to a named sequence, exportable as a Playwright or Puppeteer test.

Recover — a call that fails validation comes back with a continuationToken and the list of what was missing; the retry sends only the missing field. A validated call blocked by a guard is already recorded, so acknowledging the block and replaying resumes the exact call. If the server itself wedges, config({ action: 'restart' }) respawns it and replays the MCP handshake, so the host session never reconnects.

Prove — dev servers run under management (npm, flask, docker, compose) with port monitoring. Issues bind a bug to its reproduction: workOn navigates back to the failing state, resolve replays the sequence against the fix.

Design decisions

  • A dead server blocks tools rather than warning. An agent clicking away at a dead server produces a long, confident, entirely fictional debugging session. Configurable: inform, error, block.
  • Closing an issue needs a human click. resolve waits on a browser overlay no agent can dismiss. Recording findings is automated; declaring something actually fixed stays a human judgement.
  • Repeat is on every response, not just failures. Recovery and ordinary re-running are the same mechanism, so there's nothing extra to reach for when the session gets long.
  • getVariables degrades, never errors. full → reduced depth → names → counts. A truncated answer that says it truncated beats a tool error.
  • Connections are named. Every tool takes connectionReason, so nested agents each drive their own tab in one Chrome without fighting over "the current page".
  • Text beats screenshots. extractText costs a fraction of an image and answers most page questions. Screenshot when the question is genuinely visual.

Setup

Claude Code:

claude mcp add devharness -- npx devharness@latest

Claude Desktop:

{
  "mcpServers": {
    "devharness": {
      "command": "npx",
      "args": ["-y", "devharness@latest"]
    }
  }
}

Other clients — npx devharness@latest over stdio.

As a Claude Code plugin — this registers the server for you:

/plugin marketplace add InDate/indate-tools
/plugin install devharness@indate-tools

The plugin pins an exact server version rather than tracking @latest, so what you installed is what runs until you update it.

Skill

Bundled Agent Skill at plugin/skills/devharness/. Same guidance as docs/instructions.md, split for progressive disclosure: name and description at session start, full catalogue only when debugging starts.

mkdir -p .claude/skills
ln -s ../../node_modules/devharness/plugin/skills/devharness .claude/skills/devharness

Installing as a Claude Code plugin does this for you.

Example

Node service:

1. node --inspect=9229 app.js
2. connectDebugger({ reference: "api", port: 9229 })
3. breakpoint({ action: 'set', connectionReason: "api", file: "user.ts", line: 42 })
4. Trigger the request.
5. inspect({ action: 'getVariables', connectionReason: "api" })
   → real frame: what userId and userRole actually were

Browser fix:

1. launchChrome({ reference: "app" })   # launches and connects
2. Record the five clicks that reproduce it.
3. Fix the code.
4. Replay → pass or fail, against the real app

docs/GUIDE.md for depth, docs/instructions.md for the tool reference. examples/test-app ships eight seeded bugs to exercise it against known-wrong code.

vs Chrome DevTools MCP

Chrome DevTools MCP is better at performance tracing, device emulation, advanced browser automation.

devharness adds breakpoint debugging with variable inspection, Node.js targets, simultaneous connections, logpoints, server lifecycle, and — the part that compounds over a long session — replayable call history and self-service recovery.

Browser-only and performance-shaped → theirs. Backend code, stepping execution, long sessions where the agent keeps re-driving the same setup → this.

Migrating

cdp-tools-mcp is deprecated on npm and points here. Tools unchanged. Package, repo, and skill renamed.

-"args": ["-y", "cdp-tools-mcp@latest"]
+"args": ["-y", "devharness@latest"]

Your MCP server name (cdp-tools, or whatever you called it) is yours and keeps working. Renaming it is cosmetic — but tools are addressed as mcp__<server-name>__<tool>, so update project docs if you do.

State moved .cdp-tools/ → .devharness/ in 0.9.0. Migrates itself on first run; profiles, config, sequences, and issues carry over. DEVHARNESS_DIR supersedes CDP_TOOLS_DIR, which still works.

From source

git clone https://github.com/InDate/devharness.git
cd devharness
npm install && npm run build && npm test

Contributing

Issues and PRs welcome. Reporting a bug? Attach a recorded reproduction sequence.

License

MIT