dap-mcp-server 0.1.10 → 0.1.12

package/src/server.ts

@@ -24,12 +24,28 @@ 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(): string {
+  try {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const pkg = JSON.parse(
+      readFileSync(path.join(here, "..", "package.json"), "utf-8")
+    ) as { version?: string };
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
 export function createServer(): McpServer {
   const globalDir = path.join(os.homedir(), ".dap-mcp");
   const projectDir = path.join(process.cwd(), ".dap-mcp");
@@ -45,41 +61,44 @@ export function createServer(): McpServer {
   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.",
+        "",
+        "## Interactive Debugging Workflow",
         "",
-        "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.",
+        "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"),
     }
   );
@@ -89,7 +108,7 @@ export function createServer(): McpServer {
   // ────────────────────────────────────────────────────────────────────────────
   server.tool(
     "list_adapters",
-    "List all known debug adapters with their availability status on this machine.",
+    "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 {
@@ -101,8 +120,21 @@ export function createServer(): McpServer {
             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" as const, text: JSON.stringify(results, null, 2) }],
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({ summary, adapters: results, missing }, null, 2),
+            },
+          ],
         };
       } catch (err) {
         return {
@@ -163,7 +195,10 @@ export function createServer(): McpServer {
       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({
@@ -188,6 +223,8 @@ export function createServer(): McpServer {
           args: z.array(z.string()).optional(),
           launchDefaults: z.record(z.string(), z.unknown()).optional(),
           installHint: z.string().optional(),
+          transport: z.enum(["stdio", "tcp"]).optional(),
+          portMatcher: z.string().optional(),
         })
         .optional()
         .describe("Override adapter config inline instead of looking up from registry"),
@@ -203,7 +240,9 @@ export function createServer(): McpServer {
       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: DebugSession | undefined;
       try {
         const config =
@@ -239,9 +278,27 @@ export function createServer(): McpServer {
         if (cwd !== undefined) launchArgs.cwd = cwd;
         if (env !== undefined) launchArgs.env = env;
 
+        // Adapter-specific arg normalization. delve's `cwd` is the debuggee's
+        // working directory; the *build* (go build) runs from delve's own
+        // process cwd, controlled by `dlvCwd`. Mirror cwd → dlvCwd so a
+        // user-supplied cwd is found by `go build` looking for go.mod.
+        if (config.type === "go" && cwd !== undefined && launchArgs.dlvCwd === undefined) {
+          launchArgs.dlvCwd = cwd;
+        }
+
         // Send launch first (don't await — real adapters like debugpy block
         // the launch response until configurationDone arrives)
         const launchPromise = session.launch(launchArgs);
+        // Suppress unhandled rejection: the real `await launchPromise` below
+        // will still throw if launch fails. Without this, an early launch
+        // rejection (e.g. adapter rejects the request) crashes the MCP server.
+        launchPromise.catch(() => { /* handled at await */ });
+
+        // Wait for the adapter to emit the "initialized" event before sending
+        // configuration requests. Some adapters (delve) emit it right after the
+        // initialize response; others (debugpy) only emit it after receiving
+        // launch — that's why we fire launch first and wait for initialized here.
+        await session.waitForInitialized(10000);
 
         // Set breakpoints grouped by file
         if (breakpoints && breakpoints.length > 0) {
@@ -328,6 +385,8 @@ export function createServer(): McpServer {
           args: z.array(z.string()).optional(),
           launchDefaults: z.record(z.string(), z.unknown()).optional(),
           installHint: z.string().optional(),
+          transport: z.enum(["stdio", "tcp"]).optional(),
+          portMatcher: z.string().optional(),
         })
         .optional()
         .describe("Override adapter config inline"),
@@ -365,6 +424,10 @@ export function createServer(): McpServer {
 
         // Send attach first (don't await — real adapters block until configurationDone)
         const attachPromise = session.attach(attachArgs);
+        // Suppress unhandled rejection: the real `await attachPromise` below
+        // will still throw if attach fails.
+        attachPromise.catch(() => { /* handled at await */ });
+        await session.waitForInitialized(10000);
         await session.configurationDone();
         await attachPromise;
 
@@ -546,7 +609,7 @@ export function createServer(): McpServer {
             content: [
               {
                 type: "text" as const,
-                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,
@@ -678,7 +741,7 @@ export function createServer(): McpServer {
   // ────────────────────────────────────────────────────────────────────────────
   server.tool(
     "get_output",
-    "Get buffered stdout/stderr and debug adapter output for a session.",
+    "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
@@ -686,11 +749,17 @@ export function createServer(): McpServer {
         .optional()
         .describe("Filter by output category: 'stdout', 'stderr', 'console', etc."),
       clear: z.boolean().optional().describe("Clear the output buffer after reading (default: false)"),
+      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 }) => {
+    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" as const, text: JSON.stringify(result, null, 2) }],
         };
@@ -796,6 +865,10 @@ export function createServer(): McpServer {
 
         // Send launch first (don't await — real adapters block until configurationDone)
         const launchPromise = newSession.launch(launchConfig);
+        // Suppress unhandled rejection: the real `await launchPromise` below
+        // will still throw if launch fails.
+        launchPromise.catch(() => { /* handled at await */ });
+        await newSession.waitForInitialized(10000);
 
         // Re-apply saved breakpoints
         for (const [file, bps] of savedBreakpoints) {
@@ -843,6 +916,153 @@ export function createServer(): McpServer {
     }
   );
 
+  // ────────────────────────────────────────────────────────────────────────────
+  // 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(),
+          transport: z.enum(["stdio", "tcp"]).optional(),
+          portMatcher: z.string().optional(),
+        })
+        .optional()
+        .describe("Override adapter config inline"),
+    },
+    async (opts) => {
+      try {
+        const result = await runDebugInspect(registry, sessions, opts);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, 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" as const,
+              text: JSON.stringify({ count: totalCount, files }, null, 2),
+            },
+          ],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, 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(),
+          transport: z.enum(["stdio", "tcp"]).optional(),
+          portMatcher: z.string().optional(),
+        })
+        .optional()
+        .describe("Override adapter config inline"),
+    },
+    async (opts) => {
+      try {
+        const result = await runDebugRun(registry, sessions, opts);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Error: ${String(err)}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   // ────────────────────────────────────────────────────────────────────────────
   // Resource: dap://sessions
   // ────────────────────────────────────────────────────────────────────────────

package/src/session/inspect.test.ts

@@ -0,0 +1,126 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { describe, it, expect } from "vitest";
+import { runDebugInspect } from "./inspect.js";
+import { AdapterRegistry } from "../adapters/registry.js";
+import { SessionManager } from "./session-manager.js";
+import path from "node:path";
+import os from "node:os";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MOCK_ADAPTER = path.join(__dirname, "../test-fixtures/mock-adapter.js");
+
+describe("runDebugInspect", () => {
+  it("launches, hits a breakpoint, evaluates expressions, and disconnects", async () => {
+    const registry = new AdapterRegistry(
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-global`),
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-project`)
+    );
+    const sessions = new SessionManager();
+
+    const result = await runDebugInspect(registry, sessions, {
+      adapter: "mock",
+      program: "/test/app.py",
+      at: { file: "/test/app.py", line: 5 },
+      expressions: ["x", "name"],
+      timeout: 5000,
+      adapterConfig: {
+        type: "mock",
+        runtime: "node",
+        program: MOCK_ADAPTER,
+      },
+    });
+
+    expect(result.hit).toBe(true);
+    expect(result.reason).toBe("breakpoint");
+    expect(result.location?.file).toBe("/test/app.py");
+    expect(result.values).toBeDefined();
+    expect(result.values!["x"].result).toBe("42");
+    expect(result.values!["name"].result).toBe("42");
+    expect(sessions.listAll()).toHaveLength(0);
+  });
+
+  it("returns hit=true with no values when expressions omitted", async () => {
+    const registry = new AdapterRegistry(
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-global`),
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-project`)
+    );
+    const sessions = new SessionManager();
+
+    const result = await runDebugInspect(registry, sessions, {
+      adapter: "mock",
+      program: "/test/app.py",
+      at: { file: "/test/app.py", line: 5 },
+      timeout: 5000,
+      adapterConfig: {
+        type: "mock",
+        runtime: "node",
+        program: MOCK_ADAPTER,
+      },
+    });
+
+    expect(result.hit).toBe(true);
+    expect(result.values).toBeUndefined();
+  });
+
+  it("rejects when adapter is unknown and no inline config provided", async () => {
+    const registry = new AdapterRegistry(
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-global`),
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-project`)
+    );
+    const sessions = new SessionManager();
+
+    await expect(
+      runDebugInspect(registry, sessions, {
+        adapter: "nonexistent",
+        program: "/test/app.py",
+        at: { file: "/test/app.py", line: 5 },
+      })
+    ).rejects.toThrow(/not found/);
+  });
+
+  it("cleans up the session even when the breakpoint never hits", async () => {
+    const registry = new AdapterRegistry(
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-global`),
+      path.join(os.tmpdir(), `dap-test-${Date.now()}-project`)
+    );
+    const sessions = new SessionManager();
+
+    const noStopAdapter = path.join(__dirname, "../test-fixtures/no-stop-adapter.js");
+    const result = await runDebugInspect(registry, sessions, {
+      adapter: "mock",
+      program: "/test/app.py",
+      at: { file: "/test/app.py", line: 5 },
+      timeout: 200,
+      adapterConfig: {
+        type: "mock",
+        runtime: "node",
+        program: noStopAdapter,
+      },
+    });
+
+    expect(result.hit).toBe(false);
+    expect(sessions.listAll()).toHaveLength(0);
+  });
+});