dap-mcp-server 0.1.12 → 0.1.16

package/build/server.js

@@ -30,7 +30,8 @@ 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";
+import { inspectAdapterAvailability } from "./adapters/detect.js";
+import { resolveProjectAdapter, runDebugDoctor } from "./diagnostics/doctor.js";
 function readPackageVersion() {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -47,7 +48,7 @@ export function createServer() {
     const registry = new AdapterRegistry(globalDir, projectDir);
     const sessions = new SessionManager();
     // Load persisted adapter configs (best-effort, don't block server start)
-    registry.load().catch((err) => {
+    const registryReady = registry.load().catch((err) => {
         console.error("Warning: failed to load adapter configs:", err);
     });
     const server = new McpServer({
@@ -55,57 +56,227 @@ export function createServer() {
         version: readPackageVersion(),
     }, {
         instructions: [
-            "This server provides AI-driven debugging via the Debug Adapter Protocol (DAP).",
-            "",
-            "## 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",
-            "",
-            "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**: 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.",
+            "Local source-code debugger using the Debug Adapter Protocol.",
+            "Use it when a test fails, a program crashes, runtime state is unclear, or code behavior cannot be explained statically.",
+            "Start with debug_doctor to detect the project and verify adapter readiness.",
+            "Prefer debug_at for a one-call breakpoint inspection: it selects the adapter, launches, waits, evaluates expressions, and cleans up.",
+            "Use debug_run when output or termination is enough. Use debug_launch only for interactive stepping or multiple inspection points.",
+            "For interactive sessions: debug_launch -> get_state/evaluate -> step -> debug_disconnect. A launch with breakpoints waits by default and reports stopped, terminated, or timeout explicitly.",
+            "Omit sessionId when exactly one session is active. Adapter-specific DAP fields belong in launchConfig. Tool errors use isError=true.",
         ].join("\n"),
     });
+    const doctorOutputSchema = z.object({
+        cwd: z.string(),
+        ready: z.boolean(),
+        recommendedAdapter: z.string().optional(),
+        detected: z.object({
+            languages: z.array(z.string()),
+            testFrameworks: z.array(z.string()),
+            packageManager: z.string().optional(),
+            pythonPath: z.string().optional(),
+            launchJson: z.string().optional(),
+        }),
+        adapters: z.array(z.object({
+            type: z.string(),
+            source: z.enum(["builtin", "global", "project"]),
+            selected: z.boolean(),
+            available: z.boolean(),
+            command: z.string(),
+            reason: z.string().optional(),
+            installHint: z.string().optional(),
+            runtime: z.string().optional(),
+            program: z.string(),
+            transport: z.enum(["stdio", "tcp"]),
+        })),
+        nextSteps: z.array(z.string()),
+    });
+    const breakpointResultSchema = z.object({
+        id: z.number().optional(),
+        verified: z.boolean(),
+        line: z.number(),
+        message: z.string().optional(),
+    });
+    const debugAtOutputSchema = z.object({
+        adapter: z.string(),
+        hit: z.boolean(),
+        reason: z.string().optional(),
+        location: z
+            .object({
+            file: z.string(),
+            line: z.number(),
+            functionName: z.string().optional(),
+            column: z.number().optional(),
+        })
+            .optional(),
+        values: z
+            .record(z.string(), z.object({
+            result: z.string().optional(),
+            type: z.string().optional(),
+            error: z.string().optional(),
+        }))
+            .optional(),
+        output: z.array(z.string()).optional(),
+        status: z.string().optional(),
+        timedOut: z.boolean().optional(),
+        breakpoint: breakpointResultSchema.optional(),
+    });
+    // ────────────────────────────────────────────────────────────────────────────
+    // High-level LLM entry points
+    // ────────────────────────────────────────────────────────────────────────────
+    server.registerTool("debug_doctor", {
+        title: "Check debugger readiness",
+        description: "Inspect a local project, detect its language/tooling, select the likely debug adapter, verify the complete adapter command, and return concrete remediation. Use this before debugging or when an adapter fails to start.",
+        inputSchema: z.object({
+            cwd: z.string().optional().describe("Project directory (default: server working directory)"),
+            adapter: z.string().optional().describe("Adapter to validate instead of auto-detecting one"),
+        }),
+        outputSchema: doctorOutputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async (options) => {
+        try {
+            await registryReady;
+            const result = await runDebugDoctor(registry, options);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                structuredContent: { ...result },
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool("debug_at", {
+        title: "Inspect runtime state at a line",
+        description: "Primary one-shot debugging tool for bugs and failing behavior. Auto-selects a ready adapter, launches the program, stops at file:line, evaluates expressions, reports breakpoint/termination/timeout details, and cleans up.",
+        inputSchema: z.object({
+            cwd: z.string().optional().describe("Project and debuggee working directory"),
+            adapter: z.string().optional().describe("Adapter type; auto-detected from file/project when omitted"),
+            program: z
+                .string()
+                .optional()
+                .describe("Launch target; defaults to file for Python/Node and cwd for Go"),
+            args: z.array(z.string()).optional().describe("Program arguments"),
+            env: z.record(z.string(), z.string()).optional().describe("Environment variables"),
+            file: z.string().describe("Source file containing the breakpoint"),
+            line: z.number().int().positive().describe("One-based breakpoint line"),
+            condition: z.string().optional().describe("Conditional breakpoint expression"),
+            hitCondition: z.string().optional().describe("Adapter-specific hit count condition"),
+            expressions: z.array(z.string()).optional().describe("Expressions to evaluate in the stopped frame"),
+            timeout: z.number().positive().optional().describe("Breakpoint wait timeout in milliseconds"),
+            launchConfig: z
+                .record(z.string(), z.unknown())
+                .optional()
+                .describe("Adapter-specific DAP launch fields"),
+        }),
+        outputSchema: debugAtOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+    }, async (options) => {
+        try {
+            await registryReady;
+            const cwd = path.resolve(options.cwd ?? process.cwd());
+            const sourceFile = path.resolve(cwd, options.file);
+            const resolved = await resolveProjectAdapter(registry, {
+                cwd,
+                adapter: options.adapter,
+                sourceFile,
+            });
+            const adapter = resolved.result.recommendedAdapter;
+            if (!adapter || !resolved.config || !resolved.result.ready) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Debugger is not ready:\n${JSON.stringify(resolved.result, null, 2)}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const hasLaunchTarget = options.launchConfig !== undefined &&
+                ["program", "module", "code"].some((key) => options.launchConfig?.[key] !== undefined);
+            if (!options.program && !hasLaunchTarget && adapter === "cppdbg") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: C/C++ debugging requires the compiled executable in program or launchConfig.program.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const program = options.program ??
+                (hasLaunchTarget ? undefined : adapter === "go" ? cwd : sourceFile);
+            const result = await runDebugInspect(registry, sessions, {
+                adapter,
+                adapterConfig: resolved.config,
+                program,
+                args: options.args,
+                cwd,
+                env: options.env,
+                at: {
+                    file: sourceFile,
+                    line: options.line,
+                    condition: options.condition,
+                    hitCondition: options.hitCondition,
+                },
+                expressions: options.expressions,
+                timeout: options.timeout,
+                launchConfig: options.launchConfig,
+            });
+            const structuredContent = { adapter, ...result };
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(structuredContent, null, 2) },
+                ],
+                structuredContent,
+            };
+        }
+        catch (err) {
+            return {
+                content: [{ type: "text", text: `Error: ${String(err)}` }],
+                isError: true,
+            };
+        }
+    });
     // ────────────────────────────────────────────────────────────────────────────
     // 1. list_adapters
     // ────────────────────────────────────────────────────────────────────────────
-    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 () => {
+    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.", {}, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async () => {
         try {
+            await registryReady;
             const adapters = registry.listAll();
             const results = await Promise.all(adapters.map(async (a) => {
-                const cmd = a.runtime || a.program;
-                const available = cmd ? await checkAdapterAvailable(cmd) : false;
-                return { ...a, available };
+                const availability = await inspectAdapterAvailability(a);
+                return { ...a, ...availability };
             }));
             const available = results.filter((r) => r.available);
             const missing = results
                 .filter((r) => !r.available)
-                .map((r) => ({ type: r.type, installHint: r.installHint }));
+                .map((r) => ({
+                type: r.type,
+                command: r.command,
+                reason: r.reason,
+                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(", ")}`;
@@ -135,10 +306,27 @@ export function createServer() {
         args: z.array(z.string()).optional().describe("Additional arguments to pass to the adapter"),
         launchDefaults: z.record(z.string(), z.unknown()).optional().describe("Default launch configuration properties"),
         installHint: z.string().optional().describe("Hint shown when adapter is not installed"),
+        transport: z.enum(["stdio", "tcp"]).optional().describe("DAP transport used by the adapter"),
+        portMatcher: z.string().optional().describe("Regex whose first capture group is the TCP port"),
         scope: z.enum(["global", "project"]).optional().describe("Where to persist the adapter config (default: project)"),
-    }, async ({ type, program, runtime, args, launchDefaults, installHint, scope }) => {
+    }, {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ type, program, runtime, args, launchDefaults, installHint, transport, portMatcher, scope }) => {
         try {
-            const config = { type, program, runtime, args, launchDefaults, installHint };
+            await registryReady;
+            const config = {
+                type,
+                program,
+                runtime,
+                args,
+                launchDefaults,
+                installHint,
+                transport,
+                portMatcher,
+            };
             const saveScope = scope ?? "project";
             registry.register(config, saveScope);
             await registry.save(saveScope);
@@ -161,12 +349,16 @@ export function createServer() {
     // ────────────────────────────────────────────────────────────────────────────
     // 3. debug_launch
     // ────────────────────────────────────────────────────────────────────────────
-    server.tool("debug_launch", "Launch a program under a debug adapter. Performs the full DAP initialization lifecycle and returns the session ID and initial stopped state.", {
+    server.tool("debug_launch", "Launch an interactive debug session. With a breakpoint or stopOnEntry, waits by default and reports whether execution stopped, terminated, or timed out.", {
         adapter: z.string().describe("Adapter type to use (e.g. 'python', 'node')"),
-        program: z.string().describe("Path to the program to debug"),
+        program: z.string().optional().describe("Path to the program to debug; may instead be supplied through launchConfig"),
         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"),
+        launchConfig: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Adapter-specific DAP launch properties; explicit common fields take precedence"),
         stopOnEntry: z
             .boolean()
             .optional()
@@ -185,6 +377,11 @@ export function createServer() {
             .array(z.string())
             .optional()
             .describe("Exception filter IDs (e.g. ['uncaughtExceptions'])"),
+        waitForStop: z
+            .boolean()
+            .optional()
+            .describe("Wait for stopped/terminated outcome; defaults to true when a stop is expected"),
+        timeout: z.number().positive().optional().describe("Wait timeout in milliseconds (default: 30000)"),
         adapterConfig: z
             .object({
             type: z.string(),
@@ -198,11 +395,14 @@ 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, }) => {
-        // Default: if breakpoints are provided, run to the first one; otherwise stop at entry.
-        const shouldStop = stopOnEntry ?? !(breakpoints !== undefined && breakpoints.length > 0);
+    }, async ({ adapter, program, args, cwd, env, launchConfig, stopOnEntry, breakpoints, exceptionBreakpoints, waitForStop, timeout, adapterConfig, }) => {
+        // Default: run to a configured breakpoint/exception; otherwise stop at entry.
+        const expectsConfiguredStop = (breakpoints !== undefined && breakpoints.length > 0) ||
+            (exceptionBreakpoints !== undefined && exceptionBreakpoints.length > 0);
+        const shouldStop = stopOnEntry ?? !expectsConfiguredStop;
         let session;
         try {
+            await registryReady;
             const config = adapterConfig ??
                 registry.get(adapter);
             if (!config) {
@@ -224,9 +424,11 @@ export function createServer() {
             // Build launch request
             const launchArgs = {
                 ...config.launchDefaults,
-                program,
+                ...launchConfig,
                 stopOnEntry: shouldStop,
             };
+            if (program !== undefined)
+                launchArgs.program = program;
             if (args !== undefined)
                 launchArgs.args = args;
             if (cwd !== undefined)
@@ -253,6 +455,7 @@ export function createServer() {
             // launch — that's why we fire launch first and wait for initialized here.
             await session.waitForInitialized(10000);
             // Set breakpoints grouped by file
+            const breakpointResults = [];
             if (breakpoints && breakpoints.length > 0) {
                 const byFile = new Map();
                 for (const bp of breakpoints) {
@@ -261,12 +464,13 @@ export function createServer() {
                     byFile.set(bp.file, existing);
                 }
                 for (const [file, bps] of byFile) {
-                    await session.setBreakpoints(file, bps.map((b) => ({
+                    const results = await session.setBreakpoints(file, bps.map((b) => ({
                         line: b.line,
                         condition: b.condition,
                         hitCondition: b.hitCondition,
                         logMessage: b.logMessage,
                     })));
+                    breakpointResults.push({ file, breakpoints: results });
                 }
             }
             // Set exception breakpoints
@@ -277,14 +481,23 @@ export function createServer() {
             await session.configurationDone();
             // Now await the launch response
             await launchPromise;
+            const shouldWait = waitForStop ?? (shouldStop || expectsConfiguredStop);
             let stateData;
-            if (shouldStop) {
-                try {
-                    await session.waitForStopped(10000);
+            if (shouldWait) {
+                const startedAt = Date.now();
+                const outcome = await session.waitForStopOrTermination(timeout ?? 30000);
+                if (outcome.status === "stopped") {
                     stateData = (await session.collectState());
                 }
-                catch {
-                    stateData = { status: session.state };
+                else if (outcome.status === "terminated") {
+                    const { output } = session.getOutput();
+                    stateData = {
+                        status: "terminated",
+                        output: output.map((entry) => entry.text),
+                    };
+                }
+                else {
+                    stateData = { status: session.state, timedOut: true, elapsedMs: Date.now() - startedAt };
                 }
             }
             else {
@@ -294,7 +507,7 @@ export function createServer() {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ sessionId: id, ...stateData }, null, 2),
+                        text: JSON.stringify({ sessionId: id, breakpoints: breakpointResults, ...stateData }, null, 2),
                     },
                 ],
             };
@@ -335,6 +548,7 @@ export function createServer() {
     }, async ({ adapter, port, host, processId, attachConfig, adapterConfig }) => {
         let session;
         try {
+            await registryReady;
             const config = adapterConfig ?? registry.get(adapter);
             if (!config) {
                 return {
@@ -459,6 +673,11 @@ export function createServer() {
             .number()
             .optional()
             .describe("If running, wait up to this many milliseconds for the program to stop (default: 0 = don't wait)"),
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ sessionId, threadId, depth, variableDepth, timeout }) => {
         try {
             const session = sessions.resolve(sessionId);
@@ -470,16 +689,13 @@ export function createServer() {
                 };
             }
             if (waitMs > 0 && session.state === "running") {
-                try {
-                    await session.waitForStopped(waitMs);
+                const outcome = await session.waitForStopOrTermination(waitMs);
+                if (outcome.status === "stopped") {
                     const state = await session.collectState(threadId, depth ?? 10, variableDepth ?? 1);
                     return {
                         content: [{ type: "text", text: JSON.stringify(state, null, 2) }],
                     };
                 }
-                catch {
-                    // Timed out — fall through to return running status
-                }
             }
             const { output } = session.getOutput();
             return {
@@ -580,13 +796,10 @@ export function createServer() {
                     await session.pause(threadId);
                     break;
             }
-            try {
-                await session.waitForStopped(waitMs);
-            }
-            catch (err) {
-                // Timeout or terminated
+            const outcome = await session.waitForStopOrTermination(waitMs);
+            if (outcome.status !== "stopped") {
                 const elapsed = Date.now() - startTime;
-                if (session.state === "terminated") {
+                if (outcome.status === "terminated") {
                     const { output } = session.getOutput();
                     return {
                         content: [
@@ -606,17 +819,6 @@ export function createServer() {
                     ],
                 };
             }
-            if (session.state === "terminated") {
-                const { output } = session.getOutput();
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({ status: "terminated", output: output.map((e) => e.text) }, null, 2),
-                        },
-                    ],
-                };
-            }
             const state = await session.collectState(threadId);
             return {
                 content: [{ type: "text", text: JSON.stringify(state, null, 2) }],
@@ -643,6 +845,11 @@ export function createServer() {
             .number()
             .optional()
             .describe("Return only entries with seq > since. Pass the `nextSince` value from a prior call to fetch incremental output."),
+    }, {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: false,
+        openWorldHint: false,
     }, async ({ sessionId, category, clear, since }) => {
         try {
             const session = sessions.resolve(sessionId);
@@ -746,14 +953,18 @@ export function createServer() {
             await newSession.configurationDone();
             await launchPromise;
             const stopOnEntry = launchConfig.stopOnEntry !== false;
+            const shouldWait = stopOnEntry || savedBreakpoints.size > 0;
             let stateData;
-            if (stopOnEntry) {
-                try {
-                    await newSession.waitForStopped(10000);
+            if (shouldWait) {
+                const outcome = await newSession.waitForStopOrTermination(30000);
+                if (outcome.status === "stopped") {
                     stateData = (await newSession.collectState());
                 }
-                catch {
-                    stateData = { status: newSession.state };
+                else {
+                    stateData = {
+                        status: outcome.status === "timeout" ? newSession.state : "terminated",
+                        timedOut: outcome.status === "timeout",
+                    };
                 }
             }
             else {
@@ -804,6 +1015,10 @@ export function createServer() {
             .number()
             .optional()
             .describe("Milliseconds to wait for the breakpoint to be hit (default: 30000)"),
+        launchConfig: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Adapter-specific DAP launch fields"),
         adapterConfig: z
             .object({
             type: z.string(),
@@ -819,6 +1034,7 @@ export function createServer() {
             .describe("Override adapter config inline"),
     }, async (opts) => {
         try {
+            await registryReady;
             const result = await runDebugInspect(registry, sessions, opts);
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -836,6 +1052,11 @@ export function createServer() {
     // ────────────────────────────────────────────────────────────────────────────
     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)"),
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
     }, async ({ sessionId }) => {
         try {
             const session = sessions.resolve(sessionId);
@@ -897,6 +1118,7 @@ export function createServer() {
             .describe("Override adapter config inline"),
     }, async (opts) => {
         try {
+            await registryReady;
             const result = await runDebugRun(registry, sessions, opts);
             return {
                 content: [{ type: "text", text: JSON.stringify(result, null, 2) }],