devharness

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.

Skill

Bundled Agent Skill at 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/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.

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