dap-mcp-server 0.1.10 → 0.1.12

package/README.md

@@ -24,12 +24,15 @@ Additional adapters (e.g. Node.js via js-debug) can be registered via the `confi
 
 | Tool | Description |
 |------|-------------|
-| `debug_launch` | Start a debug session (launch a program with breakpoints) |
+| `debug_inspect` | **One-shot:** launch → run to breakpoint → evaluate expressions → disconnect. Use first when you just need a value at a line. |
+| `debug_run` | **One-shot:** launch → run to completion → return all output. Combine with logpoints for printf-style debugging without editing source. |
+| `debug_launch` | Start an interactive debug session (launch a program with breakpoints) |
 | `debug_attach` | Attach to a running process |
 | `debug_restart` | Restart with the same configuration |
 | `debug_disconnect` | End a debug session |
-| `set_breakpoints` | Set/replace breakpoints in a file |
+| `set_breakpoints` | Set/replace breakpoints in a file (use `logMessage` for logpoints) |
 | `set_exception_breakpoints` | Break on exceptions |
+| `list_breakpoints` | List currently-registered breakpoints for a session |
 | `get_state` | Get threads, stack trace, scopes, and variables |
 | `evaluate` | Evaluate an expression in the debuggee context |
 | `step` | Continue, next, stepIn, stepOut, or pause |

package/SKILL.md

@@ -7,56 +7,203 @@ description: Use when debugging a program — when you need to set breakpoints,
 
 You have access to a real debugger via the `dap` MCP server. **Use it instead of adding print/log statements** whenever you need to understand runtime behavior, track down a bug, or verify a fix.
 
-## When to Use the Debugger
+## When to switch from print() to the debugger
 
-- A test fails and the cause is not obvious from the error message or stack trace
-- You need to inspect the value of variables at a specific point in execution
-- You suspect a logic error in a loop, conditional, or data transformation
-- A function returns an unexpected result and you want to trace the execution path
-- You want to verify your fix actually changes behavior at the right point
+Reach for the debugger — don't keep guessing — when any of these are true:
 
-## Quick Start
+- **Your first fix attempt was wrong.** Stop iterating on guesses. Inspect actual values.
+- **You're about to add 3+ print statements.** Use a logpoint instead (see below) — same information, no code edits.
+- **You need a value on iteration N of a loop.** Use `hitCondition: "N"` instead of conditional prints.
+- **A test fails with a non-obvious traceback.** Launch the test under the debugger; you'll see locals at the failure site.
+- **You're reasoning about state that's modified across many call sites.** A conditional breakpoint on the value beats grepping for assignments.
 
-1. Check available adapters: call `list_adapters` to see what's installed.
-2. Launch with breakpoints in a single call:
+Print debugging is fine for: trivial one-line checks, scripts you'll throw away in the next message, or when you genuinely just want to see "did this code path execute?".
+
+## Logpoints — print debugging without editing code
+
+A **logpoint** is a breakpoint that doesn't pause execution. It just emits a formatted message every time it's hit. This is the single most useful feature for AI agents.
+
+Set it via the `logMessage` field on a breakpoint:
 
 ```
-debug_launch({
-  adapter: "python",         // or "node", "go", "cpp"
-  program: "/absolute/path/to/file.py",
-  stopOnEntry: false,
+set_breakpoints({
+  file: "/abs/path/src/foo.py",
   breakpoints: [
-    { file: "/absolute/path/to/file.py", line: 42 }
+    { line: 42, logMessage: "x={x} y={y} state={self.state}" },
+    { line: 88, logMessage: "iteration {i}: items={len(items)}" }
   ]
 })
 ```
 
-3. When the program stops, the response already contains the full state (threads, stack, scopes, variables). Read it — no extra call needed.
-4. Step through code with `step({ action: "next" })` — the response includes the new state.
-5. Evaluate expressions with `evaluate({ expression: "len(items)" })`.
-6. When done, call `debug_disconnect`.
+Then `step({ action: "continue" })` and let the program run. Retrieve every log with `get_output`. You get the same information as inserting `print(f"x={x} y={y}")` at five places — without touching the source file, without re-running, and with the program's natural execution preserved.
+
+**When to use logpoints over breakpoints**: when you want to *observe* values across many hits rather than *interrupt* execution to inspect one. They are the right tool ~70% of the time.
+
+Expression syntax inside `{...}` depends on the adapter (debugpy: Python; node: JS). The expression is evaluated in the breakpoint's scope.
+
+## Debugging a failing test
+
+This is the dominant case. Use the test runner as the program, with the specific test as an argument.
+
+### pytest
+
+```
+debug_launch({
+  adapter: "python",
+  program: "/abs/path/.venv/bin/pytest",
+  args: ["tests/test_foo.py::test_bar", "-x", "--no-header"],
+  cwd: "/abs/path",
+  breakpoints: [{ file: "/abs/path/src/foo.py", line: 42 }],
+  stopOnEntry: false,
+})
+```
+
+For pytest, also consider setting `exceptionBreakpoints: ["raised"]` — pytest swallows exceptions before you see them, but the debugger will stop at the raise site.
+
+### vitest / jest (Node.js)
+
+Requires the `node` adapter configured (see "Node.js setup" below). Use the runner binary from `node_modules/.bin`:
+
+```
+debug_launch({
+  adapter: "node",
+  program: "${cwd}/node_modules/.bin/vitest",
+  args: ["run", "tests/foo.test.ts", "-t", "the failing test name"],
+  cwd: "/abs/path",
+  breakpoints: [{ file: "/abs/path/src/foo.ts", line: 42 }],
+  stopOnEntry: false,
+})
+```
+
+### go test
+
+```
+debug_launch({
+  adapter: "go",
+  program: "${cwd}",   // delve takes a package dir, not a binary
+  args: ["-test.run", "TestFoo", "-test.v"],
+  cwd: "/abs/path",
+  breakpoints: [{ file: "/abs/path/foo.go", line: 42 }],
+  stopOnEntry: false,
+})
+```
+
+Delve uses `dlv test` semantics under the hood when the program is a package directory containing test files.
+
+### Node.js setup
+
+If `list_adapters` shows no `node` entry, register it once (path depends on installed extension):
+
+```
+configure_adapter({
+  type: "node",
+  runtime: "node",
+  program: "/abs/path/to/js-debug/src/dapDebugServer.js",
+  args: [],
+  scope: "global",
+})
+```
+
+`js-debug-dap` ships with the VS Code Node debugger extension. Alternatively use `@vscode/js-debug` from npm.
+
+## Quick Start (single-file program)
+
+1. `list_adapters` — see what's installed.
+2. Launch with breakpoints in one call:
+
+```
+debug_launch({
+  adapter: "python",
+  program: "/abs/path/file.py",
+  stopOnEntry: false,
+  breakpoints: [{ file: "/abs/path/file.py", line: 42 }],
+})
+```
+
+3. The response already contains the full state (threads, stack, scopes, variables) when the breakpoint is hit. No follow-up `get_state` needed.
+4. Step with `step({ action: "next" })` — response includes the new state.
+5. `evaluate({ expression: "len(items)" })` for ad-hoc inspection.
+6. `debug_disconnect` when done.
+
+## Stepping strategy
+
+- **`next`** (step over) is the default choice. Use it unless you have a specific reason not to.
+- **`stepIn`** only when you suspect the bug is *inside* the function being called — not at the call site. Stepping into library code will get you lost fast.
+- **`stepOut`** to bail out of a function you stepped into by mistake.
+- **`continue`** to run to the next breakpoint. With logpoints set, this is how you collect runtime traces.
+
+If you find yourself stepping line-by-line for more than ~10 steps, you're probably doing it wrong. Set a breakpoint at the next interesting location and continue to it.
+
+## Worked example
+
+Bug: `compute_total(items)` returns `0` when items contain a tax-exempt entry.
+
+```
+# Launch under pytest with a breakpoint at the suspect line
+debug_launch({
+  adapter: "python",
+  program: "/proj/.venv/bin/pytest",
+  args: ["tests/test_billing.py::test_tax_exempt", "-x"],
+  cwd: "/proj",
+  breakpoints: [{ file: "/proj/src/billing.py", line: 57 }],
+  stopOnEntry: false,
+})
+
+# Response (paraphrased):
+# {
+#   sessionId: "s-1",
+#   status: "stopped",
+#   location: { file: ".../billing.py", line: 57, functionName: "compute_total" },
+#   scopes: [{ name: "Locals", variables: [
+#     { name: "items", value: "[{...}, {...}]", ... },
+#     { name: "subtotal", value: "100", ... },
+#     { name: "tax", value: "0", ... }
+#   ] }]
+# }
+
+# Inspect the exempt item more closely
+evaluate({ expression: "[i for i in items if i.get('tax_exempt')]" })
+# → [{name: 'book', price: 100, tax_exempt: True}]
+
+# Step over to see what compute_total actually returns
+step({ action: "next" })
+# → see that `total = subtotal + tax` returns 100, not 0. Bug is upstream.
+
+# Continue to verify nothing else changes the return
+step({ action: "continue" })
+
+debug_disconnect()
+```
+
+Fix locally, re-run the test, done.
 
 ## Key Rules
 
 - **Do NOT call `get_state` after `step`** — `step` already returns the new stopped state.
-- **Omit `sessionId`** when only one debug session is active — the server resolves it automatically.
+- **Omit `sessionId`** when only one debug session is active.
 - **Use absolute paths** for `program` and breakpoint `file` parameters.
-- **Prefer `stopOnEntry: false` with breakpoints** over `stopOnEntry: true` — it gets you directly to the interesting code.
-- **Check `get_output`** for program stdout/stderr if you need to see what the program printed.
+- **Prefer `stopOnEntry: false` with breakpoints** — it gets you directly to the interesting code.
+- **Use `get_output`** for program stdout/stderr (including logpoint output).
 
 ## Debugging Strategies
 
 ### Narrowing down a bug
-1. Set a breakpoint where you know the state is still correct.
-2. Set another breakpoint where the state is wrong.
-3. Use `step` with `action: "next"` to walk through the code between them.
-4. Use `evaluate` to check intermediate values.
+1. Set a breakpoint where state is known good.
+2. Set another where state is wrong.
+3. Use `step` with `next` to walk between them, or set intermediate logpoints.
 
 ### Understanding a crash
-1. Launch with `exceptionBreakpoints: ["uncaughtExceptions"]`.
-2. When it stops on the exception, inspect the stack and variables.
+1. Launch with `exceptionBreakpoints: ["uncaughtExceptions"]` (or `"raised"` for any raise).
+2. When stopped at the exception, inspect stack and locals.
 
 ### Verifying a fix
 1. Set a breakpoint at the fixed code.
-2. Run to it, inspect variables, confirm the new behavior.
+2. Run to it, inspect variables, confirm new behavior.
 3. Continue to verify the program completes successfully.
+
+### Observing a hot loop without stopping it
+1. Set logpoints at the relevant lines with `{i}` and any state expression.
+2. `continue`.
+3. Read the trace via `get_output`. For long-running programs, poll incrementally:
+   pass the `nextSince` value from each call as the `since` parameter of the next call
+   to receive only newly-emitted entries.

package/TODO.md

@@ -0,0 +1,32 @@
+# DAP MCP Server — Improvement TODO
+
+Findings from a self-review of how usable this MCP is for an AI agent. Ordered by priority (descending). Check items off as completed.
+
+## Tier 1 — Documentation (SKILL.md). High leverage, low risk.
+
+- [x] **P1 — Logpoints section.** `breakpoints[].logMessage` is already wired through (session.ts:138) but is invisible in SKILL.md. It is the closest thing to a drop-in replacement for `print()` debugging: no code edits, captures every hit, no execution pause. Should have its own headline section with an example.
+- [x] **P2 — "Debug a failing test" section.** Most real bugs surface inside test runners (pytest, vitest, jest, go test, cargo test). Currently zero guidance. Add a per-framework template for launching a single test under the debugger.
+- [x] **P3 — "Switch from print() to debugger" triggers.** Concrete rules an AI agent will actually follow: "if first fix attempt was wrong, stop guessing"; "if about to add 3+ prints, use logpoints"; "if reasoning about iteration N, use `hitCondition`"; "if traceback is non-obvious, launch test under debugger".
+- [x] **P4 — Stepping strategy.** Default to `next`. Use `stepIn` only when you suspect the bug is *inside* the called function. Otherwise agents get lost in library internals.
+- [x] **P5 — Full worked example.** Real bug → real `debug_launch` call → real returned state → identified fix. Replaces all the abstract advice with one concrete walkthrough.
+- [x] **P5b — Node.js adapter recipe.** Builtin was removed; add a ready-to-paste `configure_adapter` snippet for `js-debug-dap`.
+
+## Tier 2 — Code changes that materially improve UX.
+
+- [x] **P6 — `debug_inspect` macro tool.** One call: launch, run to a breakpoint, evaluate a list of expressions, disconnect. Collapses a 5–7 round-trip workflow into 1. Most likely change to make me reach for the debugger reflexively.
+- [x] **P7 — Flip `stopOnEntry` default to `false` when breakpoints are provided.** Today defaults to `true` regardless (server.ts:206). Doing the right thing automatically is better than relying on the agent reading the SKILL.md.
+- [x] **P8 — Structured deep variables.** `getVariables` with `depth > 1` flattens children into the value string (session.ts:271–278). Hard for the AI to consume. Return nested `children: [...]` instead.
+- [x] **P9 — `list_adapters` summary line + surfaced install hints.** Add `summary: "2/4 installed"` and lift `installHint` for missing adapters to the top level so it's scannable.
+- [x] **P10 — `debug_run` macro tool.** Launch, run to completion, return all stdout/stderr. Zero breakpoints, zero round-trips. For "what does this script actually print/crash with?" cases.
+
+## Tier 3 — Polish.
+
+- [x] **P11 — Better "session is not stopped" error.** Currently says "use step with action: pause" (server.ts:549) — bad advice (Python `pause` lands in arbitrary library code). Suggest "set a breakpoint where you want to inspect, then continue to it".
+- [x] **P12 — Version drift.** `McpServer` registers as `0.1.0` (server.ts:48); package.json is `0.1.10`. Read from `package.json`.
+- [x] **P13 — `list_breakpoints` tool.** After several `set_breakpoints` calls, no way to introspect what's set. Minor.
+
+## Tier 4 — Speculative.
+
+- [x] **`get_output({ since })` for incremental polling.** Smaller substitute for streaming subscriptions. Caller passes the `nextSince` value from a prior call to receive only newly-emitted entries. Useful for watching logpoint output during `continue` against long-running programs.
+- [ ] ~~Streaming output via MCP resource subscriptions.~~ AI agents don't watch streams in real time; the request/response pattern doesn't benefit. `since`-based polling covers the practical case.
+- [ ] ~~Auto-detect test runner from program path.~~ Too magic; SKILL.md recipes (P2) make the right call explicit, and silent misfires would be worse than no detection at all.

package/build/adapters/builtin.js

@@ -30,14 +30,38 @@ export const BUILTIN_ADAPTERS = [
         },
         installHint: "pip install debugpy",
     },
-    // node adapter removed — no reliable universal path to js-debug-dap.
-    // Configure via configure_adapter if needed.
     {
         type: "go",
         program: "dlv",
-        args: ["dap"],
+        args: ["dap", "--listen=127.0.0.1:0"],
+        transport: "tcp",
+        // Matches: "DAP server listening at: 127.0.0.1:38251"
+        portMatcher: "DAP server listening at:\\s*\\S+:(\\d+)",
         installHint: "go install github.com/go-delve/delve/cmd/dlv@latest",
     },
+    // node adapter: vscode-js-debug's dapDebugServer.js. The user must install
+    // it (no universal path); the registry's availability check will mark this
+    // unavailable when the program is missing.
+    {
+        type: "node",
+        runtime: "node",
+        program: "dapDebugServer.js",
+        // Bind to IPv4 explicitly; the default is IPv6 ('::1') which our client
+        // (which connects to 127.0.0.1) can't reach on systems without v4↔v6
+        // bridging.
+        args: ["0", "127.0.0.1"],
+        transport: "tcp",
+        // Matches: "Debug server listening at 127.0.0.1:38251" (vscode-js-debug)
+        portMatcher: "[Ll]istening at\\s*\\S*?:(\\d+)",
+        // vscode-js-debug requires these in the launch request; pwa-node is the
+        // "production worker agent" Node launcher.
+        launchDefaults: {
+            type: "pwa-node",
+            request: "launch",
+        },
+        installHint: "Install vscode-js-debug DAP server and set the adapter's `program` to its dapDebugServer.js path " +
+            "(e.g. via `configure_adapter`). See https://github.com/microsoft/vscode-js-debug.",
+    },
     {
         type: "cppdbg",
         program: "lldb-dap",

package/build/adapters/builtin.js.map

@@ -1 +1 @@
-{"version":3,"file":"builtin.js","sourceRoot":"","sources":["../../src/adapters/builtin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,CAAC,iBAAiB,CAAC;QACzB,cAAc,EAAE;YACd,OAAO,EAAE,iBAAiB;SAC3B;QACD,WAAW,EAAE,qBAAqB;KACnC;IACD,qEAAqE;IACrE,6CAA6C;IAC7C;QACE,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,CAAC,KAAK,CAAC;QACb,WAAW,EAAE,qDAAqD;KACnE;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,+DAA+D;KAC7E;CACF,CAAC"}
+{"version":3,"file":"builtin.js","sourceRoot":"","sources":["../../src/adapters/builtin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,MAAM,CAAC,MAAM,gBAAgB,GAAoB;IAC/C;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,SAAS;QAClB,OAAO,EAAE,IAAI;QACb,IAAI,EAAE,CAAC,iBAAiB,CAAC;QACzB,cAAc,EAAE;YACd,OAAO,EAAE,iBAAiB;SAC3B;QACD,WAAW,EAAE,qBAAqB;KACnC;IACD;QACE,IAAI,EAAE,IAAI;QACV,OAAO,EAAE,KAAK;QACd,IAAI,EAAE,CAAC,KAAK,EAAE,sBAAsB,CAAC;QACrC,SAAS,EAAE,KAAK;QAChB,sDAAsD;QACtD,WAAW,EAAE,yCAAyC;QACtD,WAAW,EAAE,qDAAqD;KACnE;IACD,2EAA2E;IAC3E,2EAA2E;IAC3E,2CAA2C;IAC3C;QACE,IAAI,EAAE,MAAM;QACZ,OAAO,EAAE,MAAM;QACf,OAAO,EAAE,mBAAmB;QAC5B,wEAAwE;QACxE,qEAAqE;QACrE,YAAY;QACZ,IAAI,EAAE,CAAC,GAAG,EAAE,WAAW,CAAC;QACxB,SAAS,EAAE,KAAK;QAChB,yEAAyE;QACzE,WAAW,EAAE,iCAAiC;QAC9C,wEAAwE;QACxE,2CAA2C;QAC3C,cAAc,EAAE;YACd,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,QAAQ;SAClB;QACD,WAAW,EACT,mGAAmG;YACnG,mFAAmF;KACtF;IACD;QACE,IAAI,EAAE,QAAQ;QACd,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,EAAE;QACR,WAAW,EAAE,+DAA+D;KAC7E;CACF,CAAC"}

package/build/dap/dap-client.d.ts

@@ -24,21 +24,88 @@ import { DebugProtocol } from "@vscode/debugprotocol";
 export declare class DAPClientError extends Error {
     constructor(message: string);
 }
+export interface DAPClientOptions {
+    /** "stdio" (default) or "tcp". */
+    transport?: "stdio" | "tcp";
+    /**
+     * Regex with one capture group that matches the TCP port the adapter is
+     * listening on. Required when transport is "tcp". The regex is applied to
+     * the cumulative adapter stdout text.
+     */
+    portMatcher?: string;
+    /** Timeout waiting for the adapter to announce its TCP port, in ms. */
+    tcpConnectTimeout?: number;
+}
 export declare class DAPClient extends EventEmitter {
     private runtime;
     private executable;
     private args;
+    private transport;
+    private portMatcher?;
+    private tcpConnectTimeout;
     private process?;
-    private parser?;
-    private seq;
-    private pending;
+    private conns;
+    /** Index into `conns` of the connection that handles user-sent requests. */
+    private activeIdx;
+    /** TCP target host (set during spawn for tcp mode). */
+    private tcpHost?;
+    /** TCP target port (set during spawn for tcp mode). */
+    private tcpPort?;
+    /**
+     * While a startDebugging handler is bootstrapping a new child session
+     * (initialize + launch), user-issued `sendRequest` calls await this so they
+     * don't race the in-progress handshake.
+     */
+    private transitionLock?;
+    /**
+     * Last setBreakpoints arguments per source path. Replayed onto new child
+     * sessions when startDebugging causes the active connection to change —
+     * adapters like vscode-js-debug spawn a child for the actual debuggee
+     * AFTER the parent has accepted setBreakpoints, so the child wouldn't know
+     * about them otherwise.
+     */
+    private bpHistory;
+    private excBpHistory?;
+    private configurationDoneSent;
     private stderrOutput;
+    private stdoutPreamble;
     private _exited;
     private _exitCode?;
-    constructor(runtime: string, executable: string, args?: string[]);
+    constructor(runtime: string, executable: string, args?: string[], options?: DAPClientOptions);
     spawn(): Promise<void>;
+    /**
+     * Record session-shaping requests so we can replay them on child sessions.
+     * `setBreakpoints` and `setExceptionBreakpoints` need to be re-sent because
+     * each DAP session has its own breakpoint state. `configurationDone` is
+     * tracked so we know whether the parent has already finished its
+     * configuration phase — if so, child sessions need the same signal.
+     */
+    private trackOutgoing;
+    /** Build a Conn around a writable/readable stream pair. */
+    private makeConn;
+    /** Open a fresh TCP connection to the adapter's DAP server. */
+    private openTcpConnection;
+    private onConnClose;
     sendRequest(command: string, args?: Record<string, unknown>, timeout?: number): Promise<DebugProtocol.Response>;
+    /** Internal: send a request on a specific connection. */
+    private sendRequestOn;
     private handleMessage;
+    /** Reply to a reverse request, on the connection that sent it. */
+    private replyToReverseRequest;
+    /**
+     * Handle a `startDebugging` reverse request from an active session.
+     *
+     * Per the DAP startDebugging protocol, the client should open a new DAP
+     * session for the supplied configuration and run the launch/attach
+     * handshake against the SAME adapter. For TCP-server adapters like
+     * vscode-js-debug, we open a fresh TCP connection to the same port, run
+     * initialize + launch (or attach) using the request's configuration, and
+     * make that new connection the active one for subsequent user requests.
+     *
+     * The `transitionLock` prevents user `sendRequest` calls from racing the
+     * handshake.
+     */
+    private handleStartDebugging;
     get exited(): boolean;
     get stderr(): string;
     dispose(): Promise<void>;