debugger-mcp-server 0.1.0

package/src/bridge/connectionManager.ts

@@ -0,0 +1,82 @@
+import { readFileSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import type { BridgeHealthResponse } from "./bridgeTypes.js";
+
+const PORT_FILE_PATH = join(homedir(), ".agentic-debugger", "bridge-port");
+const HEALTH_TIMEOUT_MS = 5000;
+
+type CachedUrl = string | null;
+const cache: { bridgeUrl: CachedUrl } = { bridgeUrl: null };
+
+const readPortFile = (): number => {
+  try {
+    const content = readFileSync(PORT_FILE_PATH, "utf-8").trim();
+    const port = parseInt(content, 10);
+    if (isNaN(port) || port <= 0 || port > 65535) {
+      throw new Error("Invalid port number in bridge port file.");
+    }
+    return port;
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Invalid port")) {
+      throw error;
+    }
+    throw new Error(
+      "Bridge port file not found. Make sure VS Code is open with the Agentic Debugger extension installed."
+    );
+  }
+};
+
+const checkHealth = async (params: { url: string }): Promise<boolean> => {
+  const { url } = params;
+
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), HEALTH_TIMEOUT_MS);
+
+    try {
+      const response = await fetch(`${url}/api/health`, {
+        method: "GET",
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        return false;
+      }
+
+      const data = (await response.json()) as BridgeHealthResponse;
+      return data.status === "ok";
+    } finally {
+      clearTimeout(timeout);
+    }
+  } catch {
+    return false;
+  }
+};
+
+export const getBridgeUrl = async (): Promise<string> => {
+  if (cache.bridgeUrl !== null) {
+    const isHealthy = await checkHealth({ url: cache.bridgeUrl });
+    if (isHealthy) {
+      return cache.bridgeUrl;
+    }
+    cache.bridgeUrl = null;
+  }
+
+  const port = readPortFile();
+  const url = `http://127.0.0.1:${port}`;
+  const isHealthy = await checkHealth({ url });
+
+  if (!isHealthy) {
+    throw new Error(
+      "VS Code extension bridge is not responding. Make sure VS Code is open with the Agentic Debugger extension installed."
+    );
+  }
+
+  cache.bridgeUrl = url;
+  return url;
+};
+
+export const invalidateCache = (): void => {
+  cache.bridgeUrl = null;
+};

package/src/index.ts

@@ -0,0 +1,10 @@
+import { createApp } from "./server.js";
+
+const DEFAULT_PORT = 6090;
+const PORT = parseInt(process.env["PORT"] ?? String(DEFAULT_PORT), 10);
+
+const app = createApp();
+
+app.listen(PORT, () => {
+  console.log(`Debugger MCP server running on port ${PORT}.`);
+});

package/src/server.ts

@@ -0,0 +1,143 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { randomUUID } from "crypto";
+import express from "express";
+import { registerAllTools } from "./tools/toolRegistry.js";
+
+const createConnectedServer = (): McpServer => {
+  const server = new McpServer({
+    name: "debugger-mcp-server",
+    version: "0.1.0",
+  });
+  registerAllTools({ server });
+  return server;
+};
+
+export const createApp = (): express.Express => {
+  const app = express();
+  app.use(express.json());
+
+  const transports = new Map<string, StreamableHTTPServerTransport | SSEServerTransport>();
+
+  // ==========================================================================
+  // Streamable HTTP transport (protocol version 2025-11-25)
+  // ==========================================================================
+
+  app.post("/mcp", async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+
+    if (sessionId !== undefined && transports.has(sessionId)) {
+      const existingTransport = transports.get(sessionId) as NonNullable<ReturnType<typeof transports.get>>;
+      if (existingTransport instanceof SSEServerTransport) {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Session uses a different transport protocol." },
+          id: null,
+        });
+        return;
+      }
+      await existingTransport.handleRequest(req, res, req.body);
+      return;
+    }
+
+    if (isInitializeRequest(req.body)) {
+      const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: () => randomUUID(),
+        onsessioninitialized: (newSessionId) => {
+          transports.set(newSessionId, transport);
+        },
+      });
+
+      transport.onclose = () => {
+        const transportSessionId = transport.sessionId;
+        if (transportSessionId !== undefined) {
+          transports.delete(transportSessionId);
+        }
+      };
+
+      const server = createConnectedServer();
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      return;
+    }
+
+    res.status(400).json({ error: "Invalid request. Missing session ID or not an initialize request." });
+  });
+
+  app.get("/mcp", async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+    if (sessionId !== undefined && transports.has(sessionId)) {
+      const existingTransport = transports.get(sessionId) as NonNullable<ReturnType<typeof transports.get>>;
+      if (existingTransport instanceof SSEServerTransport) {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Session uses a different transport protocol." },
+          id: null,
+        });
+        return;
+      }
+      await existingTransport.handleRequest(req, res);
+      return;
+    }
+    res.status(400).json({ error: "Invalid session." });
+  });
+
+  app.delete("/mcp", async (req, res) => {
+    const sessionId = req.headers["mcp-session-id"] as string | undefined;
+    if (sessionId !== undefined && transports.has(sessionId)) {
+      const existingTransport = transports.get(sessionId) as NonNullable<ReturnType<typeof transports.get>>;
+      if (existingTransport instanceof SSEServerTransport) {
+        res.status(400).json({
+          jsonrpc: "2.0",
+          error: { code: -32000, message: "Session uses a different transport protocol." },
+          id: null,
+        });
+        return;
+      }
+      await existingTransport.handleRequest(req, res);
+      transports.delete(sessionId);
+      return;
+    }
+    res.status(400).json({ error: "Invalid session." });
+  });
+
+  // ==========================================================================
+  // Legacy SSE transport (protocol version 2024-11-05)
+  // ==========================================================================
+
+  app.get("/sse", async (_req, res) => {
+    const transport = new SSEServerTransport("/messages", res);
+    transports.set(transport.sessionId, transport);
+
+    res.on("close", () => {
+      transports.delete(transport.sessionId);
+    });
+
+    const server = createConnectedServer();
+    await server.connect(transport);
+  });
+
+  app.post("/messages", async (req, res) => {
+    const sessionId = req.query.sessionId as string | undefined;
+    if (sessionId === undefined) {
+      res.status(400).json({ error: "Missing sessionId query parameter." });
+      return;
+    }
+
+    const existingTransport = transports.get(sessionId);
+    if (!(existingTransport instanceof SSEServerTransport)) {
+      res.status(400).json({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "No SSE transport found for this session." },
+        id: null,
+      });
+      return;
+    }
+
+    await existingTransport.handlePostMessage(req, res, req.body);
+  });
+
+  return app;
+};

package/src/tools/analysis/analyzeCode.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { AnalyzeCodeResponse } from "../../bridge/bridgeTypes.js";
+
+const ANALYZE_CODE_TIMEOUT_MS = 120000;
+
+export const registerAnalyzeCodeTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "analyze_code",
+    "Analyze codebase to find relevant code locations for debugging a feature. Uses AI to explore and identify entry points, core logic, and key functions.",
+    {
+      featureDescription: z.string().describe("Description of the feature or code area to analyze"),
+      workspacePath: z.string().describe("Absolute path to the workspace root"),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<AnalyzeCodeResponse>({
+          command: "analyzeCode",
+          args: {
+            featureDescription: args.featureDescription,
+            workspacePath: args.workspacePath,
+          },
+          timeoutMs: ANALYZE_CODE_TIMEOUT_MS,
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/breakpoints/listBreakpoints.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { ListBreakpointsResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerListBreakpointsTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "list_breakpoints",
+    "List all currently set breakpoints in VS Code with their locations and conditions.",
+    {},
+    async () => {
+      try {
+        const result = await sendBridgeCommand<ListBreakpointsResponse>({
+          command: "listBreakpoints",
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/breakpoints/removeBreakpoints.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { RemoveBreakpointsResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerRemoveBreakpointsTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "remove_breakpoints",
+    "Remove breakpoints by their IDs. If no IDs provided, removes all breakpoints.",
+    {
+      breakpointIds: z.array(z.string()).optional().describe("Specific breakpoint IDs to remove. Omit to remove all."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<RemoveBreakpointsResponse>({
+          command: "removeBreakpoints",
+          args: {
+            breakpointIds: args.breakpointIds,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/breakpoints/setBreakpoints.ts

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { SetBreakpointsResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerSetBreakpointsTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "set_breakpoints",
+    "Set breakpoints at specified file locations. Optionally clear existing breakpoints first.",
+    {
+      locations: z.array(
+        z.object({
+          filePath: z.string().describe("Absolute or workspace-relative file path"),
+          lineNumber: z.number().describe("Line number to set breakpoint on"),
+          condition: z.string().optional().describe("Conditional expression for the breakpoint"),
+          logMessage: z.string().optional().describe("Log message (logpoint) instead of breaking"),
+        })
+      ).describe("Array of breakpoint locations to set"),
+      shouldClearExisting: z.boolean().default(false).describe("Clear all existing breakpoints before setting new ones"),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<SetBreakpointsResponse>({
+          command: "setBreakpoints",
+          args: {
+            locations: args.locations,
+            shouldClearExisting: args.shouldClearExisting,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/continueExecution.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { StepResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerContinueExecutionTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "continue_execution",
+    "Continue execution until the next breakpoint or program termination.",
+    {
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      threadId: z.number().optional().describe("Thread ID to continue. Defaults to the first available thread."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<StepResponse>({
+          command: "continueExecution",
+          args: {
+            sessionId: args.sessionId,
+            threadId: args.threadId,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/evaluateExpression.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { EvaluateExpressionResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerEvaluateExpressionTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "evaluate_expression",
+    "Evaluate an expression in the context of the current debug session. Useful for inspecting values, calling functions, or testing conditions.",
+    {
+      expression: z.string().describe("The expression to evaluate"),
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      frameId: z.number().optional().describe("Stack frame ID for evaluation context. Defaults to the top frame."),
+      context: z.enum(["watch", "repl", "hover"]).optional().describe("Evaluation context type. Defaults to 'repl'."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<EvaluateExpressionResponse>({
+          command: "evaluateExpression",
+          args: {
+            expression: args.expression,
+            sessionId: args.sessionId,
+            frameId: args.frameId,
+            context: args.context,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/getCallStack.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { GetCallStackResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerGetCallStackTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "get_call_stack",
+    "Get the current call stack (stack trace) showing the chain of function calls.",
+    {
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      threadId: z.number().optional().describe("Thread ID to get call stack for. Defaults to the first available thread."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<GetCallStackResponse>({
+          command: "getCallStack",
+          args: {
+            sessionId: args.sessionId,
+            threadId: args.threadId,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/getVariables.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { GetVariablesResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerGetVariablesTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "get_variables",
+    "Get variables visible at the current debug position. Returns all scopes (local, closure, global) by default.",
+    {
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      frameId: z.number().optional().describe("Stack frame ID to get variables for. Defaults to the top frame."),
+      variablesReference: z.number().optional().describe("Specific variables reference to expand (for nested objects)."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<GetVariablesResponse>({
+          command: "getVariables",
+          args: {
+            sessionId: args.sessionId,
+            frameId: args.frameId,
+            variablesReference: args.variablesReference,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/startDebugSession.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { StartDebugSessionResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerStartDebugSessionTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "start_debug_session",
+    "Start a new debug session in VS Code. Supports launching programs or attaching to running processes.",
+    {
+      type: z.string().describe("Debug adapter type (e.g., 'node', 'python', 'cppdbg')"),
+      name: z.string().describe("Human-readable name for the debug session"),
+      request: z.enum(["launch", "attach"]).describe("Whether to launch a new process or attach to existing"),
+      program: z.string().optional().describe("Path to the program to debug"),
+      args: z.array(z.string()).optional().describe("Command line arguments for the program"),
+      cwd: z.string().optional().describe("Working directory for the program"),
+      additionalConfig: z.record(z.unknown()).optional().describe("Additional debug configuration properties passed to the debug adapter"),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<StartDebugSessionResponse>({
+          command: "startDebugSession",
+          args: {
+            type: args.type,
+            name: args.name,
+            request: args.request,
+            program: args.program,
+            args: args.args,
+            cwd: args.cwd,
+            additionalConfig: args.additionalConfig,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/stepInto.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { StepResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerStepIntoTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "step_into",
+    "Step into the function call at the current line in the debugger.",
+    {
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      threadId: z.number().optional().describe("Thread ID to step. Defaults to the first available thread."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<StepResponse>({
+          command: "stepInto",
+          args: {
+            sessionId: args.sessionId,
+            threadId: args.threadId,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/stepOut.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { StepResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerStepOutTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "step_out",
+    "Step out of the current function, returning to the caller.",
+    {
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      threadId: z.number().optional().describe("Thread ID to step. Defaults to the first available thread."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<StepResponse>({
+          command: "stepOut",
+          args: {
+            sessionId: args.sessionId,
+            threadId: args.threadId,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/stepOver.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { StepResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerStepOverTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "step_over",
+    "Step over the current line in the debugger, executing it without stepping into function calls.",
+    {
+      sessionId: z.string().optional().describe("Debug session ID. Defaults to the active session."),
+      threadId: z.number().optional().describe("Thread ID to step. Defaults to the first available thread."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<StepResponse>({
+          command: "stepOver",
+          args: {
+            sessionId: args.sessionId,
+            threadId: args.threadId,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};

package/src/tools/debugSession/stopDebugSession.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { sendBridgeCommand } from "../../bridge/bridgeClient.js";
+import { formatToolResult, formatErrorResult } from "../toolTypes.js";
+import type { StopDebugSessionResponse } from "../../bridge/bridgeTypes.js";
+
+export const registerStopDebugSessionTool = (params: { server: McpServer }): void => {
+  params.server.tool(
+    "stop_debug_session",
+    "Stop an active debug session. If no session ID is provided, stops the currently active session.",
+    {
+      sessionId: z.string().optional().describe("ID of the debug session to stop. Omit for the active session."),
+    },
+    async (args) => {
+      try {
+        const result = await sendBridgeCommand<StopDebugSessionResponse>({
+          command: "stopDebugSession",
+          args: {
+            sessionId: args.sessionId,
+          },
+        });
+        return { content: [{ type: "text" as const, text: formatToolResult({ data: result }) }] };
+      } catch (error) {
+        return { content: [{ type: "text" as const, text: formatErrorResult({ error }) }], isError: true };
+      }
+    }
+  );
+};