dap-mcp-server 0.1.5

package/src/dap/protocol.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { describe, it, expect } from "vitest";
+import { encodeMessage, MessageParser } from "./protocol.js";
+import { DebugProtocol } from "@vscode/debugprotocol";
+
+describe("encodeMessage", () => {
+  it("encodes a DAP message with Content-Length header", () => {
+    const msg: DebugProtocol.Request = {
+      seq: 1,
+      type: "request",
+      command: "initialize",
+      arguments: { adapterID: "test" },
+    };
+    const encoded = encodeMessage(msg);
+    const str = encoded.toString("utf-8");
+    const json = JSON.stringify(msg);
+    expect(str).toBe(`Content-Length: ${Buffer.byteLength(json)}\r\n\r\n${json}`);
+  });
+});
+
+describe("MessageParser", () => {
+  it("parses a single complete message", () => {
+    const messages: DebugProtocol.ProtocolMessage[] = [];
+    const parser = new MessageParser((msg) => messages.push(msg));
+
+    const body = JSON.stringify({ seq: 1, type: "response", command: "initialize", success: true, request_seq: 1 });
+    const raw = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+    parser.feed(Buffer.from(raw));
+
+    expect(messages).toHaveLength(1);
+    expect(messages[0].seq).toBe(1);
+  });
+
+  it("handles messages split across multiple chunks", () => {
+    const messages: DebugProtocol.ProtocolMessage[] = [];
+    const parser = new MessageParser((msg) => messages.push(msg));
+
+    const body = JSON.stringify({ seq: 1, type: "event", event: "initialized" });
+    const raw = `Content-Length: ${Buffer.byteLength(body)}\r\n\r\n${body}`;
+    const mid = Math.floor(raw.length / 2);
+
+    parser.feed(Buffer.from(raw.slice(0, mid)));
+    expect(messages).toHaveLength(0);
+    parser.feed(Buffer.from(raw.slice(mid)));
+    expect(messages).toHaveLength(1);
+  });
+
+  it("handles multiple messages in one chunk", () => {
+    const messages: DebugProtocol.ProtocolMessage[] = [];
+    const parser = new MessageParser((msg) => messages.push(msg));
+
+    const body1 = JSON.stringify({ seq: 1, type: "event", event: "initialized" });
+    const body2 = JSON.stringify({ seq: 2, type: "event", event: "stopped" });
+    const raw = `Content-Length: ${Buffer.byteLength(body1)}\r\n\r\n${body1}Content-Length: ${Buffer.byteLength(body2)}\r\n\r\n${body2}`;
+    parser.feed(Buffer.from(raw));
+
+    expect(messages).toHaveLength(2);
+    expect(messages[0].seq).toBe(1);
+    expect(messages[1].seq).toBe(2);
+  });
+});

package/src/dap/protocol.ts

@@ -0,0 +1,78 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { DebugProtocol } from "@vscode/debugprotocol";
+
+const TWO_CRLF = "\r\n\r\n";
+const CONTENT_LENGTH = "Content-Length: ";
+
+export function encodeMessage(msg: DebugProtocol.ProtocolMessage): Buffer {
+  const json = JSON.stringify(msg);
+  const header = `${CONTENT_LENGTH}${Buffer.byteLength(json)}${TWO_CRLF}`;
+  return Buffer.from(header + json, "utf-8");
+}
+
+export class MessageParser {
+  private buffer = Buffer.alloc(0);
+  private contentLength = -1;
+  private onMessage: (msg: DebugProtocol.ProtocolMessage) => void;
+
+  constructor(onMessage: (msg: DebugProtocol.ProtocolMessage) => void) {
+    this.onMessage = onMessage;
+  }
+
+  feed(data: Buffer): void {
+    this.buffer = Buffer.concat([this.buffer, data]);
+    this.parse();
+  }
+
+  private parse(): void {
+    while (true) {
+      if (this.contentLength === -1) {
+        const headerEnd = this.buffer.indexOf(TWO_CRLF);
+        if (headerEnd === -1) return;
+
+        const header = this.buffer.subarray(0, headerEnd).toString("utf-8");
+        const match = header.match(/Content-Length:\s*(\d+)/i);
+        if (!match) {
+          this.buffer = this.buffer.subarray(headerEnd + TWO_CRLF.length);
+          continue;
+        }
+        this.contentLength = parseInt(match[1], 10);
+        this.buffer = this.buffer.subarray(headerEnd + TWO_CRLF.length);
+      }
+
+      if (this.buffer.length < this.contentLength) return;
+
+      const body = this.buffer.subarray(0, this.contentLength).toString("utf-8");
+      this.buffer = this.buffer.subarray(this.contentLength);
+      this.contentLength = -1;
+
+      try {
+        const msg = JSON.parse(body) as DebugProtocol.ProtocolMessage;
+        this.onMessage(msg);
+      } catch {
+        // Skip malformed JSON
+      }
+    }
+  }
+}

package/src/dap/ring-buffer.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { describe, it, expect } from "vitest";
+import { RingBuffer } from "./ring-buffer.js";
+
+describe("RingBuffer", () => {
+  it("stores and retrieves entries", () => {
+    const buf = new RingBuffer<string>(100);
+    buf.push("a");
+    buf.push("b");
+    expect(buf.getAll()).toEqual(["a", "b"]);
+    expect(buf.truncated).toBe(false);
+  });
+
+  it("drops oldest entries when full", () => {
+    const buf = new RingBuffer<string>(3);
+    buf.push("a");
+    buf.push("b");
+    buf.push("c");
+    buf.push("d");
+    expect(buf.getAll()).toEqual(["b", "c", "d"]);
+    expect(buf.truncated).toBe(true);
+  });
+
+  it("clears entries", () => {
+    const buf = new RingBuffer<string>(10);
+    buf.push("a");
+    buf.push("b");
+    buf.clear();
+    expect(buf.getAll()).toEqual([]);
+    expect(buf.truncated).toBe(false);
+  });
+
+  it("filters entries", () => {
+    const buf = new RingBuffer<{ cat: string; text: string }>(10);
+    buf.push({ cat: "stdout", text: "hello" });
+    buf.push({ cat: "stderr", text: "error" });
+    buf.push({ cat: "stdout", text: "world" });
+    const filtered = buf.getFiltered((e) => e.cat === "stdout");
+    expect(filtered).toEqual([
+      { cat: "stdout", text: "hello" },
+      { cat: "stdout", text: "world" },
+    ]);
+  });
+
+  it("reports size correctly", () => {
+    const buf = new RingBuffer<string>(5);
+    expect(buf.size).toBe(0);
+    buf.push("a");
+    buf.push("b");
+    expect(buf.size).toBe(2);
+  });
+
+  it("removes only matching entries", () => {
+    const buf = new RingBuffer<{ cat: string; text: string }>(10);
+    buf.push({ cat: "stdout", text: "hello" });
+    buf.push({ cat: "stderr", text: "error" });
+    buf.push({ cat: "stdout", text: "world" });
+    buf.removeMatching((e) => e.cat === "stdout");
+    expect(buf.getAll()).toEqual([{ cat: "stderr", text: "error" }]);
+  });
+});

package/src/dap/ring-buffer.ts

@@ -0,0 +1,64 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+export class RingBuffer<T> {
+  private buffer: T[] = [];
+  private maxSize: number;
+  private _truncated = false;
+
+  constructor(maxSize: number) {
+    this.maxSize = maxSize;
+  }
+
+  push(item: T): void {
+    if (this.buffer.length >= this.maxSize) {
+      this.buffer.shift();
+      this._truncated = true;
+    }
+    this.buffer.push(item);
+  }
+
+  getAll(): T[] {
+    return [...this.buffer];
+  }
+
+  getFiltered(predicate: (item: T) => boolean): T[] {
+    return this.buffer.filter(predicate);
+  }
+
+  clear(): void {
+    this.buffer = [];
+    this._truncated = false;
+  }
+
+  removeMatching(predicate: (item: T) => boolean): void {
+    this.buffer = this.buffer.filter((item) => !predicate(item));
+  }
+
+  get size(): number {
+    return this.buffer.length;
+  }
+
+  get truncated(): boolean {
+    return this._truncated;
+  }
+}

package/src/dap/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+// src/dap/types.ts
+
+export type SessionState = "idle" | "configuring" | "running" | "stopped" | "terminated";
+
+export interface StoppedState {
+  status: "stopped";
+  reason: string;
+  location: {
+    file: string;
+    line: number;
+    column?: number;
+    functionName?: string;
+  };
+  threads: Array<{ id: number; name: string; stopped: boolean }>;
+  stackTrace: Array<{
+    id: number;
+    name: string;
+    file: string;
+    line: number;
+    column?: number;
+  }>;
+  scopes: Array<{
+    name: string;
+    variables: Array<{
+      name: string;
+      value: string;
+      type?: string;
+      hasChildren: boolean;
+      variablesReference: number;
+    }>;
+  }>;
+  output?: string[];
+}
+
+export interface RunningState {
+  status: "running";
+  output?: string[];
+  elapsedMs?: number;
+}
+
+export type DebugState = StoppedState | RunningState;
+
+export interface AdapterConfig {
+  type: string;
+  runtime?: string;
+  program: string;
+  args?: string[];
+  launchDefaults?: Record<string, unknown>;
+  installHint?: string;
+}
+
+export interface OutputEntry {
+  category: string;
+  text: string;
+  timestamp: string;
+}
+
+export interface BreakpointConfig {
+  line: number;
+  condition?: string;
+  hitCondition?: string;
+  logMessage?: string;
+}
+
+export interface BreakpointResult {
+  id?: number;
+  verified: boolean;
+  line: number;
+  message?: string;
+}

package/src/index.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error("dap-mcp-server running on stdio");

package/src/integration/debug-lifecycle.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Copyright (c) 2026 Ivan Iraci <ivan.iraci@professioneit.com>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { DebugSession } from "../session/session.js";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MOCK_ADAPTER = path.join(__dirname, "../test-fixtures/mock-adapter.js");
+
+describe("Debug Lifecycle Integration", () => {
+  let session: DebugSession | undefined;
+
+  afterEach(async () => {
+    if (session && session.state !== "terminated") {
+      try { await session.disconnect(); } catch { /* ignore */ }
+    }
+    session = undefined;
+  });
+
+  it("full debug lifecycle: launch, stop, inspect, step, evaluate, disconnect", async () => {
+    session = new DebugSession("integ-1", { type: "mock", runtime: "node", program: MOCK_ADAPTER });
+
+    // Initialize
+    const caps = await session.initialize();
+    expect(caps.supportsConfigurationDoneRequest).toBe(true);
+    expect(session.state).toBe("configuring");
+
+    // Set breakpoints
+    const bps = await session.setBreakpoints("/test/app.py", [{ line: 5 }, { line: 10 }]);
+    expect(bps).toHaveLength(2);
+    expect(bps[0].verified).toBe(true);
+
+    // Configuration done + launch
+    await session.configurationDone();
+    await session.launch({ program: "/test/app.py", stopOnEntry: true });
+
+    // Wait for stopped on entry
+    const stoppedEvent = await session.waitForStopped(5000);
+    expect(stoppedEvent.body.reason).toBe("entry");
+    expect(session.state).toBe("stopped");
+
+    // Collect composite state
+    const state = await session.collectState(1, 10, 1);
+    expect(state.status).toBe("stopped");
+    expect(state.reason).toBe("entry");
+    expect(state.threads).toHaveLength(1);
+    expect(state.threads[0].name).toBe("MainThread");
+    expect(state.stackTrace.length).toBeGreaterThan(0);
+    expect(state.scopes.length).toBeGreaterThan(0);
+
+    // Check variables
+    const locals = state.scopes.find(s => s.name === "Locals");
+    expect(locals).toBeDefined();
+    expect(locals!.variables.some(v => v.name === "x" && v.value === "42")).toBe(true);
+    expect(locals!.variables.some(v => v.name === "name")).toBe(true);
+
+    // Step next
+    await session.next(1);
+    const stoppedAfterStep = await session.waitForStopped(5000);
+    expect(stoppedAfterStep.body.reason).toBe("step");
+
+    // Evaluate expression
+    const evalResult = await session.evaluate("x + 1", 1);
+    expect(evalResult.result).toBe("42");
+
+    // Continue
+    await session.continueExecution(1);
+    const stoppedAtBp = await session.waitForStopped(5000);
+    expect(stoppedAtBp.body.reason).toBe("breakpoint");
+
+    // Check output
+    const output = session.getOutput();
+    expect(output.output.some(o => o.text.includes("Program started"))).toBe(true);
+
+    // Disconnect
+    await session.disconnect();
+    expect(session.state).toBe("terminated");
+  });
+
+  it("handles adapter crash gracefully", async () => {
+    const crashAdapter = path.join(__dirname, "../test-fixtures/crash-adapter.js");
+    session = new DebugSession("integ-crash", { type: "mock", runtime: "node", program: crashAdapter });
+    await expect(session.initialize()).rejects.toThrow();
+    expect(session.state).toBe("terminated");
+  });
+});