dap-mcp-server 0.1.10 → 0.1.11

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/dap/types.d.ts

@@ -20,6 +20,15 @@
  * SOFTWARE.
  */
 export type SessionState = "idle" | "configuring" | "running" | "stopped" | "terminated";
+export interface Variable {
+    name: string;
+    value: string;
+    type?: string;
+    hasChildren: boolean;
+    variablesReference: number;
+    /** Populated when getVariables is called with depth > 1 and this variable has children. */
+    children?: Variable[];
+}
 export interface StoppedState {
     status: "stopped";
     reason: string;
@@ -43,13 +52,7 @@ export interface StoppedState {
     }>;
     scopes: Array<{
         name: string;
-        variables: Array<{
-            name: string;
-            value: string;
-            type?: string;
-            hasChildren: boolean;
-            variablesReference: number;
-        }>;
+        variables: Variable[];
     }>;
     output?: string[];
 }
@@ -68,6 +71,8 @@ export interface AdapterConfig {
     installHint?: string;
 }
 export interface OutputEntry {
+    /** Monotonic per-session sequence number assigned at push time. Survives ring-buffer eviction. */
+    seq: number;
     category: string;
     text: string;
     timestamp: string;

package/build/server.js

@@ -23,10 +23,24 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import os from "node:os";
 import path from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { AdapterRegistry } from "./adapters/registry.js";
 import { SessionManager } from "./session/session-manager.js";
 import { DebugSession } from "./session/session.js";
+import { runDebugInspect } from "./session/inspect.js";
+import { runDebugRun } from "./session/run.js";
 import { checkAdapterAvailable } from "./adapters/detect.js";
+function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        const pkg = JSON.parse(readFileSync(path.join(here, "..", "package.json"), "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
 export function createServer() {
     const globalDir = path.join(os.homedir(), ".dap-mcp");
     const projectDir = path.join(process.cwd(), ".dap-mcp");
@@ -38,46 +52,49 @@ export function createServer() {
     });
     const server = new McpServer({
         name: "dap-mcp-server",
-        version: "0.1.0",
+        version: readPackageVersion(),
     }, {
         instructions: [
             "This server provides AI-driven debugging via the Debug Adapter Protocol (DAP).",
             "",
-            "## Debugging Workflow",
+            "## When to use which tool",
+            "",
+            "- **`debug_inspect`** — One-shot 'what is X at line N?'. Launches, hits a breakpoint, evaluates expressions,",
+            "  disconnects. Use this first; it collapses a multi-call workflow into a single call.",
+            "- **`debug_run`** — Run a program with no stops and collect all output. Combine with `logpoints` (breakpoints",
+            "  with `logMessage`) for printf-style debugging without modifying source.",
+            "- **`debug_launch` + step/evaluate** — Interactive multi-step session when you need to explore.",
             "",
-            "A typical session follows this sequence:",
-            "1. `list_adapters` — discover available debug adapters and check which are installed",
-            "2. `debug_launch` (or `debug_attach`) — start a debug session. This performs the full DAP handshake,",
-            "   sets initial breakpoints, and launches the program. Returns a sessionId and initial stopped state.",
-            "3. Inspect state with `get_state` — returns threads, call stack, scopes, and variables in one call.",
-            "   This is a coarse-grained tool designed to minimize round-trips; prefer it over multiple fine-grained queries.",
-            "4. `step` — control execution (continue, next, stepIn, stepOut, pause). Each step action blocks until",
-            "   the program stops again and returns the new state, so you do NOT need to call get_state after stepping.",
-            "5. `evaluate` — evaluate expressions in the context of a stopped frame (REPL, watch, or hover context).",
-            "6. `set_breakpoints` / `set_exception_breakpoints` — modify breakpoints during the session.",
-            "7. `get_output` — retrieve buffered stdout/stderr/console output (ring buffer, max 10K lines).",
-            "8. `debug_disconnect` — end the session. `debug_restart` replays the same launch config with preserved breakpoints.",
+            "## Interactive Debugging Workflow",
+            "",
+            "1. `list_adapters` — discover available adapters; the response includes a summary and install hints.",
+            "2. `debug_launch` (or `debug_attach`) — start a session. With breakpoints provided, `stopOnEntry` defaults",
+            "   to false so the program runs to the first breakpoint. Returns sessionId + initial stopped state.",
+            "3. Inspect state with `get_state` — threads + call stack + scopes + variables in one call.",
+            "4. `step` — continue, next, stepIn, stepOut, pause. Blocks until stopped; returns new state directly.",
+            "5. `evaluate` — expressions in the context of a stopped frame.",
+            "6. `set_breakpoints` / `set_exception_breakpoints` — modify breakpoints mid-session. Use `logMessage`",
+            "   on a breakpoint to make it a logpoint (emits formatted text without pausing).",
+            "7. `list_breakpoints` — see what's currently set.",
+            "8. `get_output` — retrieve stdout/stderr/console output (10K-line ring buffer).",
+            "9. `debug_disconnect` — end. `debug_restart` replays the launch config with preserved breakpoints.",
             "",
             "## Key Conventions",
             "",
-            "- **Auto-session resolution**: All tools accept an optional `sessionId`. When only one session is active,",
-            "  you can omit it — the server resolves it automatically.",
-            "- **Synchronous stepping**: `step` returns the new stopped state directly. Do not follow a step with get_state",
-            "  unless you need to change parameters like `variableDepth` or `threadId`.",
-            "- **Coarse get_state**: Fetches threads + stack frames + scopes + variables in a single call.",
-            "  Use `depth` (default 10) and `variableDepth` (default 1) to control how much data is returned.",
-            "- **Output buffering**: Program output is buffered in a 10K-line ring buffer. Oldest lines are dropped",
-            "  when the buffer is full. Use `get_output` with `clear: true` to consume and free buffer space.",
-            "- **Adapter registration**: Use `configure_adapter` to register adapters. Configs are persisted to",
-            "  `~/.dap-mcp/adapters.json` (global) or `./.dap-mcp/adapters.json` (project), with project overriding global.",
-            "- **Error handling**: All tool errors are returned as `isError: true` results with an error message.",
-            "  The session remains usable after most errors.",
+            "- **Auto-session resolution**: tools accept an optional `sessionId`; with one active session, omit it.",
+            "- **Synchronous stepping**: `step` returns the new stopped state. Don't follow it with `get_state`.",
+            "- **Variable depth**: `get_state` accepts `variableDepth` (default 1). With `> 1`, container variables",
+            "  expose their entries as a structured `children` array.",
+            "- **stopOnEntry default**: false when `debug_launch` is given breakpoints, true otherwise.",
+            "- **Adapter registration**: `configure_adapter` persists to `~/.dap-mcp/adapters.json` (global) or",
+            "  `./.dap-mcp/adapters.json` (project); project overrides global.",
+            "- **Error handling**: tool errors return `isError: true`. The session usually remains usable.",
         ].join("\n"),
     });
     // ────────────────────────────────────────────────────────────────────────────
     // 1. list_adapters
     // ────────────────────────────────────────────────────────────────────────────
-    server.tool("list_adapters", "List all known debug adapters with their availability status on this machine.", {}, async () => {
+    server.tool("list_adapters", "List all known debug adapters with their availability status on this machine. Returns a summary line, the full adapter list, and a separate 'missing' list with installation hints for adapters that aren't installed.", {}, async () => {
         try {
             const adapters = registry.listAll();
             const results = await Promise.all(adapters.map(async (a) => {
@@ -85,8 +102,20 @@ export function createServer() {
                 const available = cmd ? await checkAdapterAvailable(cmd) : false;
                 return { ...a, available };
             }));
+            const available = results.filter((r) => r.available);
+            const missing = results
+                .filter((r) => !r.available)
+                .map((r) => ({ type: r.type, installHint: r.installHint }));
+            const summary = missing.length === 0
+                ? `${available.length}/${results.length} adapters available`
+                : `${available.length}/${results.length} adapters available; missing: ${missing.map((m) => m.type).join(", ")}`;
             return {
-                content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ summary, adapters: results, missing }, null, 2),
+                    },
+                ],
             };
         }
         catch (err) {
@@ -138,7 +167,10 @@ export function createServer() {
         args: z.array(z.string()).optional().describe("Program arguments"),
         cwd: z.string().optional().describe("Working directory for the program"),
         env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
-        stopOnEntry: z.boolean().optional().describe("Stop on program entry (default: true)"),
+        stopOnEntry: z
+            .boolean()
+            .optional()
+            .describe("Stop on program entry. Defaults to false when breakpoints are provided (run to first breakpoint), true otherwise."),
         breakpoints: z
             .array(z.object({
             file: z.string().describe("Source file path"),
@@ -165,7 +197,8 @@ export function createServer() {
             .optional()
             .describe("Override adapter config inline instead of looking up from registry"),
     }, async ({ adapter, program, args, cwd, env, stopOnEntry, breakpoints, exceptionBreakpoints, adapterConfig, }) => {
-        const shouldStop = stopOnEntry !== false;
+        // Default: if breakpoints are provided, run to the first one; otherwise stop at entry.
+        const shouldStop = stopOnEntry ?? !(breakpoints !== undefined && breakpoints.length > 0);
         let session;
         try {
             const config = adapterConfig ??
@@ -463,7 +496,7 @@ export function createServer() {
                     content: [
                         {
                             type: "text",
-                            text: `Error: Session is not stopped (current state: ${session.state}). Use 'step' with action 'pause' to stop first.`,
+                            text: `Error: Session is not stopped (current state: ${session.state}). Expressions can only be evaluated at a stopped frame. Set a breakpoint where you want to inspect (set_breakpoints) and continue to it (step with action 'continue'), then retry.`,
                         },
                     ],
                     isError: true,
@@ -575,17 +608,21 @@ export function createServer() {
     // ────────────────────────────────────────────────────────────────────────────
     // 10. get_output
     // ────────────────────────────────────────────────────────────────────────────
-    server.tool("get_output", "Get buffered stdout/stderr and debug adapter output for a session.", {
+    server.tool("get_output", "Get buffered stdout/stderr and debug adapter output for a session. Pass `since` (the `nextSince` from a previous call) to get only newly-emitted entries — useful for polling logpoint output without re-reading the full buffer.", {
         sessionId: z.string().optional().describe("Session ID (omit if only one session is active)"),
         category: z
             .string()
             .optional()
             .describe("Filter by output category: 'stdout', 'stderr', 'console', etc."),
         clear: z.boolean().optional().describe("Clear the output buffer after reading (default: false)"),
-    }, async ({ sessionId, category, clear }) => {
+        since: z
+            .number()
+            .optional()
+            .describe("Return only entries with seq > since. Pass the `nextSince` value from a prior call to fetch incremental output."),
+    }, async ({ sessionId, category, clear, since }) => {
         try {
             const session = sessions.resolve(sessionId);
-            const result = session.getOutput(category, clear ?? false);
+            const result = session.getOutput(category, clear ?? false, since);
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
             };
@@ -715,6 +752,132 @@ export function createServer() {
         }
     });
     // ────────────────────────────────────────────────────────────────────────────
+    // 13. debug_inspect
+    // ────────────────────────────────────────────────────────────────────────────
+    server.tool("debug_inspect", "One-shot inspection: launch a program, run to a breakpoint, evaluate a list of expressions in that frame, then disconnect. Collapses launch + wait + evaluate + disconnect into a single call. Use for 'what is X at line N?' debugging.", {
+        adapter: z.string().describe("Adapter type to use (e.g. 'python', 'node')"),
+        program: z.string().describe("Path to the program to debug"),
+        args: z.array(z.string()).optional().describe("Program arguments"),
+        cwd: z.string().optional().describe("Working directory for the program"),
+        env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+        at: z
+            .object({
+            file: z.string().describe("Absolute path to the source file"),
+            line: z.number().describe("Line number (1-based)"),
+            condition: z.string().optional().describe("Conditional breakpoint expression"),
+            hitCondition: z.string().optional().describe("Hit-count condition (e.g. '5' for 5th hit)"),
+        })
+            .describe("Breakpoint location to stop at"),
+        expressions: z
+            .array(z.string())
+            .optional()
+            .describe("Expressions to evaluate when stopped at the breakpoint. Omit to just verify the line is reached."),
+        timeout: z
+            .number()
+            .optional()
+            .describe("Milliseconds to wait for the breakpoint to be hit (default: 30000)"),
+        adapterConfig: z
+            .object({
+            type: z.string(),
+            program: z.string(),
+            runtime: z.string().optional(),
+            args: z.array(z.string()).optional(),
+            launchDefaults: z.record(z.string(), z.unknown()).optional(),
+            installHint: z.string().optional(),
+        })
+            .optional()
+            .describe("Override adapter config inline"),
+    }, async (opts) => {
+        try {
+            const result = await runDebugInspect(registry, sessions, opts);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    // ────────────────────────────────────────────────────────────────────────────
+    // 14. list_breakpoints
+    // ────────────────────────────────────────────────────────────────────────────
+    server.tool("list_breakpoints", "List the breakpoints currently registered with a session, grouped by source file. Includes regular breakpoints, conditional breakpoints, and logpoints.", {
+        sessionId: z.string().optional().describe("Session ID (omit if only one session is active)"),
+    }, async ({ sessionId }) => {
+        try {
+            const session = sessions.resolve(sessionId);
+            const bps = session.getBreakpoints();
+            const files = Array.from(bps.entries()).map(([file, breakpoints]) => ({
+                file,
+                breakpoints,
+            }));
+            const totalCount = files.reduce((n, f) => n + f.breakpoints.length, 0);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ count: totalCount, files }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    // ────────────────────────────────────────────────────────────────────────────
+    // 15. debug_run
+    // ────────────────────────────────────────────────────────────────────────────
+    server.tool("debug_run", "Launch a program with no stops, let it run to completion, and return all stdout/stderr/console output. Optionally inject logpoints (breakpoints with logMessage) for printf-style debugging without modifying source. Use for 'what does this script actually do?' cases where you don't need to inspect intermediate state.", {
+        adapter: z.string().describe("Adapter type to use (e.g. 'python', 'node')"),
+        program: z.string().describe("Path to the program to debug"),
+        args: z.array(z.string()).optional().describe("Program arguments"),
+        cwd: z.string().optional().describe("Working directory for the program"),
+        env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+        logpoints: z
+            .array(z.object({
+            file: z.string().describe("Absolute path to the source file"),
+            line: z.number().describe("Line number (1-based)"),
+            logMessage: z.string().describe("Message template; expressions in {braces} are evaluated in scope"),
+        }))
+            .optional()
+            .describe("Logpoints to emit per-hit messages without pausing execution"),
+        timeout: z
+            .number()
+            .optional()
+            .describe("Total wall-clock timeout for the whole run in milliseconds (default: 60000)"),
+        adapterConfig: z
+            .object({
+            type: z.string(),
+            program: z.string(),
+            runtime: z.string().optional(),
+            args: z.array(z.string()).optional(),
+            launchDefaults: z.record(z.string(), z.unknown()).optional(),
+            installHint: z.string().optional(),
+        })
+            .optional()
+            .describe("Override adapter config inline"),
+    }, async (opts) => {
+        try {
+            const result = await runDebugRun(registry, sessions, opts);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    // ────────────────────────────────────────────────────────────────────────────
     // Resource: dap://sessions
     // ────────────────────────────────────────────────────────────────────────────
     // NOTE: This resource does not emit change notifications.