dap-mcp-server 0.1.12 → 0.1.17

package/build/server.js

@@ -30,7 +30,10 @@ 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 { conciseDoctorResult, resolveProjectAdapter, runDebugDoctor, } from "./diagnostics/doctor.js";
+import { buildLaunchArgs, defaultCargoProgram } from "./adapters/recipes.js";
+import { COMPACT_STACK_DEPTH, renderState } from "./session/state-format.js";
 function readPackageVersion() {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -47,7 +50,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 +58,303 @@ 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.",
+            "step answers compactly (frame-local scopes, short stack) and states carry only output not reported before; use get_state for the full picture and get_output for the whole buffer.",
+            "To debug an already-running or suspended process, pass breakpoints to debug_attach so they bind before it resumes.",
+            "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"]),
+        })),
+        otherAdapters: z.array(z.string()).optional(),
+        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(),
+        hint: z.string().optional(),
+        exception: z
+            .object({
+            id: z.string().optional(),
+            description: z.string().optional(),
+            breakMode: z.string().optional(),
+        })
+            .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(),
+        exitCode: z.number().optional(),
+        timedOut: z.boolean().optional(),
+        breakpoint: breakpointResultSchema.optional(),
+    });
+    const breakpointInputSchema = z.object({
+        file: z.string().describe("Source file path"),
+        line: z.number().describe("Line number"),
+        condition: z.string().optional(),
+        hitCondition: z.string().optional(),
+        logMessage: z.string().optional(),
+    });
+    const detailSchema = z.enum(["compact", "full"]);
+    /** Set breakpoints grouped by file; must run between `initialized` and configurationDone. */
+    async function applyBreakpoints(session, breakpoints = []) {
+        const byFile = new Map();
+        for (const bp of breakpoints) {
+            const existing = byFile.get(bp.file) ?? [];
+            existing.push(bp);
+            byFile.set(bp.file, existing);
+        }
+        const results = [];
+        for (const [file, bps] of byFile) {
+            const fileResults = await session.setBreakpoints(file, bps.map(({ line, condition, hitCondition, logMessage }) => ({
+                line,
+                condition,
+                hitCondition,
+                logMessage,
+            })));
+            results.push({ file, breakpoints: fileResults });
+        }
+        return results;
+    }
+    /** What to report once the program is no longer running under our control. */
+    async function terminatedReport(session) {
+        return {
+            status: "terminated",
+            exitCode: await session.waitForExitCode(),
+            ...session.unreportedOutput(true),
+        };
+    }
+    /** Wait for the first stop after launch/attach/restart and describe the outcome. */
+    async function awaitFirstStop(session, timeout) {
+        const startedAt = Date.now();
+        const outcome = await session.waitForStopOrTermination(timeout);
+        if (outcome.status === "stopped") {
+            const state = await session.collectState(undefined, 10, 1, { consumeOutput: true });
+            return state;
+        }
+        if (outcome.status === "terminated")
+            return terminatedReport(session);
+        return { status: session.state, timedOut: true, elapsedMs: Date.now() - startedAt };
+    }
+    // ────────────────────────────────────────────────────────────────────────────
+    // 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"),
+            verbose: z
+                .boolean()
+                .optional()
+                .describe("Include full details for every known adapter, not just the selected 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) {
+                const { recommendedAdapter, detected, adapters, otherAdapters, nextSteps } = conciseDoctorResult(resolved.result);
+                const summary = {
+                    recommendedAdapter,
+                    languages: detected.languages,
+                    reason: adapters[0]?.reason,
+                    nextSteps,
+                    otherAdapters,
+                };
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Debugger is not ready: ${JSON.stringify(summary)}\nRun debug_doctor with verbose=true for full adapter details.`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const hasLaunchTarget = options.launchConfig !== undefined &&
+                ["program", "module", "code"].some((key) => options.launchConfig?.[key] !== undefined);
+            const compiledProgram = !options.program && !hasLaunchTarget && adapter === "cppdbg"
+                ? await defaultCargoProgram(cwd)
+                : undefined;
+            if (!options.program && !hasLaunchTarget && adapter === "cppdbg" && !compiledProgram) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Error: C/C++/Rust debugging requires the compiled executable in program or launchConfig.program. For a Cargo project, run `cargo build` first and program defaults to target/debug/<package name>.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const program = options.program ??
+                compiledProgram ??
+                (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 +384,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,30 +427,33 @@ 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()
             .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"),
-            line: z.number().describe("Line number"),
-            condition: z.string().optional(),
-            hitCondition: z.string().optional(),
-            logMessage: z.string().optional(),
-        }))
+            .array(breakpointInputSchema)
             .optional()
             .describe("Breakpoints to set before launching"),
         exceptionBreakpoints: z
             .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 +467,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) {
@@ -221,25 +493,15 @@ export function createServer() {
             sessions.add(session);
             // Initialize (waits for the initialized event internally)
             await session.initialize();
-            // Build launch request
-            const launchArgs = {
-                ...config.launchDefaults,
+            const launchArgs = await buildLaunchArgs(config, {
                 program,
+                args,
+                cwd,
+                env,
+                launchConfig,
                 stopOnEntry: shouldStop,
-            };
-            if (args !== undefined)
-                launchArgs.args = args;
-            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;
-            }
+                sourceFiles: breakpoints?.map((bp) => bp.file),
+            });
             // Send launch first (don't await — real adapters like debugpy block
             // the launch response until configurationDone arrives)
             const launchPromise = session.launch(launchArgs);
@@ -252,23 +514,7 @@ export function createServer() {
             // 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) {
-                const byFile = new Map();
-                for (const bp of breakpoints) {
-                    const existing = byFile.get(bp.file) ?? [];
-                    existing.push(bp);
-                    byFile.set(bp.file, existing);
-                }
-                for (const [file, bps] of byFile) {
-                    await session.setBreakpoints(file, bps.map((b) => ({
-                        line: b.line,
-                        condition: b.condition,
-                        hitCondition: b.hitCondition,
-                        logMessage: b.logMessage,
-                    })));
-                }
-            }
+            const breakpointResults = await applyBreakpoints(session, breakpoints);
             // Set exception breakpoints
             if (exceptionBreakpoints && exceptionBreakpoints.length > 0) {
                 await session.setExceptionBreakpoints(exceptionBreakpoints);
@@ -277,24 +523,15 @@ export function createServer() {
             await session.configurationDone();
             // Now await the launch response
             await launchPromise;
-            let stateData;
-            if (shouldStop) {
-                try {
-                    await session.waitForStopped(10000);
-                    stateData = (await session.collectState());
-                }
-                catch {
-                    stateData = { status: session.state };
-                }
-            }
-            else {
-                stateData = { status: session.state };
-            }
+            const shouldWait = waitForStop ?? (shouldStop || expectsConfiguredStop);
+            const stateData = shouldWait
+                ? await awaitFirstStop(session, timeout ?? 30000)
+                : { status: session.state };
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ sessionId: id, ...stateData }, null, 2),
+                        text: JSON.stringify({ sessionId: id, breakpoints: breakpointResults, ...stateData }, null, 2),
                     },
                 ],
             };
@@ -313,12 +550,25 @@ export function createServer() {
     // ────────────────────────────────────────────────────────────────────────────
     // 4. debug_attach
     // ────────────────────────────────────────────────────────────────────────────
-    server.tool("debug_attach", "Attach a debug adapter to an already-running process.", {
+    server.tool("debug_attach", "Attach a debug adapter to an already-running process. Pass breakpoints here rather than afterwards: they bind before the debuggee resumes, which is the only reliable way to stop a process started suspended (e.g. JDWP suspend=y). With breakpoints or exception breakpoints, waits and reports stopped, terminated, or timeout.", {
         adapter: z.string().describe("Adapter type to use"),
         port: z.number().optional().describe("Debug port to attach to"),
         host: z.string().optional().describe("Host to attach to (default: localhost)"),
         processId: z.number().optional().describe("PID of process to attach to"),
         attachConfig: z.record(z.string(), z.unknown()).optional().describe("Arbitrary attach configuration properties"),
+        breakpoints: z
+            .array(breakpointInputSchema)
+            .optional()
+            .describe("Breakpoints to bind before the debuggee resumes"),
+        exceptionBreakpoints: z
+            .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 breakpoints or exception breakpoints are given"),
+        timeout: z.number().positive().optional().describe("Wait timeout in milliseconds (default: 30000)"),
         adapterConfig: z
             .object({
             type: z.string(),
@@ -332,9 +582,12 @@ export function createServer() {
         })
             .optional()
             .describe("Override adapter config inline"),
-    }, async ({ adapter, port, host, processId, attachConfig, adapterConfig }) => {
+    }, async ({ adapter, port, host, processId, attachConfig, breakpoints, exceptionBreakpoints, waitForStop, timeout, adapterConfig, }) => {
+        const expectsConfiguredStop = (breakpoints !== undefined && breakpoints.length > 0) ||
+            (exceptionBreakpoints !== undefined && exceptionBreakpoints.length > 0);
         let session;
         try {
+            await registryReady;
             const config = adapterConfig ?? registry.get(adapter);
             if (!config) {
                 return {
@@ -368,13 +621,24 @@ export function createServer() {
             // will still throw if attach fails.
             attachPromise.catch(() => { });
             await session.waitForInitialized(10000);
+            const breakpointResults = await applyBreakpoints(session, breakpoints);
+            if (exceptionBreakpoints && exceptionBreakpoints.length > 0) {
+                await session.setExceptionBreakpoints(exceptionBreakpoints);
+            }
             await session.configurationDone();
             await attachPromise;
+            const stateData = waitForStop ?? expectsConfiguredStop
+                ? await awaitFirstStop(session, timeout ?? 30000)
+                : { status: session.state };
             return {
                 content: [
                     {
                         type: "text",
-                        text: JSON.stringify({ sessionId: id, status: session.state }, null, 2),
+                        text: JSON.stringify({
+                            sessionId: id,
+                            breakpoints: breakpointResults.length > 0 ? breakpointResults : undefined,
+                            ...stateData,
+                        }, null, 2),
                     },
                 ],
             };
@@ -455,32 +719,40 @@ export function createServer() {
         threadId: z.number().optional().describe("Thread ID (uses stopped thread if omitted)"),
         depth: z.number().optional().describe("Stack trace depth (default: 10)"),
         variableDepth: z.number().optional().describe("Variable expansion depth (default: 1)"),
+        scopes: z
+            .array(z.string())
+            .optional()
+            .describe("Scope names to fetch, e.g. ['Registers']. Default: every scope except CPU registers; skipped ones are listed in omittedScopes"),
+        detail: detailSchema
+            .optional()
+            .describe("'full' (default) or 'compact' (frame-local scopes only, slimmer JSON)"),
         timeout: z
             .number()
             .optional()
             .describe("If running, wait up to this many milliseconds for the program to stop (default: 0 = don't wait)"),
-    }, async ({ sessionId, threadId, depth, variableDepth, timeout }) => {
+    }, {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    }, async ({ sessionId, threadId, depth, variableDepth, scopes, detail, timeout }) => {
         try {
             const session = sessions.resolve(sessionId);
             const waitMs = timeout ?? 0;
+            const stateDetail = detail ?? "full";
+            if (waitMs > 0 && session.state === "running") {
+                await session.waitForStopOrTermination(waitMs);
+            }
             if (session.state === "stopped") {
-                const state = await session.collectState(threadId, depth ?? 10, variableDepth ?? 1);
+                // Read-only: output stays unreported so a later step still carries it.
+                const state = await session.collectState(threadId, depth ?? 10, variableDepth ?? 1, {
+                    scopes,
+                    localsOnly: stateDetail === "compact",
+                });
                 return {
-                    content: [{ type: "text", text: JSON.stringify(state, null, 2) }],
+                    content: [{ type: "text", text: renderState(state, stateDetail) }],
                 };
             }
-            if (waitMs > 0 && session.state === "running") {
-                try {
-                    await session.waitForStopped(waitMs);
-                    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 {
                 content: [
@@ -547,20 +819,29 @@ export function createServer() {
             .enum(["continue", "next", "stepIn", "stepOut", "pause"])
             .describe("Execution control action"),
         threadId: z.number().optional().describe("Thread ID (uses stopped thread if omitted)"),
+        detail: detailSchema
+            .optional()
+            .describe("'compact' (default: frame-local scopes, short stack, slimmer JSON) or 'full' (same shape as get_state)"),
         timeout: z
             .number()
             .optional()
             .describe("Milliseconds to wait for the program to stop after the action (default: 30000)"),
-    }, async ({ sessionId, action, threadId, timeout }) => {
+    }, async ({ sessionId, action, threadId, detail, timeout }) => {
         try {
             const session = sessions.resolve(sessionId);
             const waitMs = timeout ?? 30000;
             const startTime = Date.now();
+            const stateDetail = detail ?? "compact";
+            const collectSteppedState = () => session.collectState(threadId, stateDetail === "compact" ? COMPACT_STACK_DEPTH : 10, 1, {
+                localsOnly: stateDetail === "compact",
+                consumeOutput: true,
+            });
             // If already stopped and asking to pause, just return current state
             if (action === "pause" && session.state === "stopped") {
-                const state = await session.collectState(threadId);
                 return {
-                    content: [{ type: "text", text: JSON.stringify(state, null, 2) }],
+                    content: [
+                        { type: "text", text: renderState(await collectSteppedState(), stateDetail) },
+                    ],
                 };
             }
             switch (action) {
@@ -580,20 +861,13 @@ 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") {
-                    const { output } = session.getOutput();
+                if (outcome.status === "terminated") {
                     return {
                         content: [
-                            {
-                                type: "text",
-                                text: JSON.stringify({ status: "terminated", output: output.map((e) => e.text) }, null, 2),
-                            },
+                            { type: "text", text: JSON.stringify(await terminatedReport(session)) },
                         ],
                     };
                 }
@@ -606,20 +880,10 @@ 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) }],
+                content: [
+                    { type: "text", text: renderState(await collectSteppedState(), stateDetail) },
+                ],
             };
         }
         catch (err) {
@@ -643,6 +907,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,19 +1015,10 @@ export function createServer() {
             await newSession.configurationDone();
             await launchPromise;
             const stopOnEntry = launchConfig.stopOnEntry !== false;
-            let stateData;
-            if (stopOnEntry) {
-                try {
-                    await newSession.waitForStopped(10000);
-                    stateData = (await newSession.collectState());
-                }
-                catch {
-                    stateData = { status: newSession.state };
-                }
-            }
-            else {
-                stateData = { status: newSession.state };
-            }
+            const shouldWait = stopOnEntry || savedBreakpoints.size > 0;
+            const stateData = shouldWait
+                ? await awaitFirstStop(newSession, 30000)
+                : { status: newSession.state };
             return {
                 content: [
                     {
@@ -804,6 +1064,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 +1083,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 +1101,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 +1167,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) }],