dap-mcp-server 0.1.12 → 0.1.16

package/integrations/claude/dap-debugging/skills/dap-debugging/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: dap-debugging
+description: Use a real debugger for opaque test failures, crashes, swallowed exceptions, incorrect runtime state, or a bug that remains unexplained after static inspection or a failed fix. Prefer this over adding multiple print statements when actual values, branches, or call stacks are needed.
+---
+
+# Debug Code with DAP
+
+Use the `dap` MCP server when static inspection cannot explain a runtime failure. Debugging executes local code and can trigger its normal side effects, so do not run untrusted targets.
+
+## Preferred Workflow
+
+1. Call `debug_doctor` with the project `cwd`. Follow its remediation when `ready` is false.
+2. Choose an executable line near the first observable bad state.
+3. Call `debug_at` with `file`, `line`, and a small set of hypothesis-driven `expressions`. It detects the adapter, launches, inspects, and cleans up in one call.
+
+```json
+{
+  "cwd": "/workspace/project",
+  "program": "/workspace/project/app.py",
+  "file": "/workspace/project/app.py",
+  "line": 42,
+  "expressions": ["request.user", "result"]
+}
+```
+
+Read the outcome precisely:
+
+- `hit: true`: use the location and values as evidence.
+- `status: terminated`: execution finished before the breakpoint; verify path, arguments, and branch.
+- `timedOut: true`: inspect captured output and narrow the target.
+- With `hit: false`, `breakpoint.verified: false` means the adapter could not bind the source location.
+
+Pass adapter-specific fields through `launchConfig`. Use absolute program and source paths.
+
+## Failing Tests
+
+Debug the smallest failing test. Supply its runner as `program` or through `launchConfig`, and its selector in `args`. Launch conventions differ across adapters; retain known-good fields from `.vscode/launch.json`. Put the breakpoint in application code before the assertion or exception boundary.
+
+## Interactive Exploration
+
+Use `debug_launch` only for multiple stops or stepping. A launch with breakpoints waits by default and reports stopped, terminated, or timeout.
+
+1. Inspect the state returned by `debug_launch`.
+2. Use `evaluate` for focused questions.
+3. Prefer `step` with `next`; use `stepIn` only when the callee is suspect.
+4. Move breakpoints with `set_breakpoints` as the hypothesis changes.
+5. Finish with `debug_disconnect`.
+
+Omit `sessionId` when one session is active. Use `debug_run` when output and termination are sufficient. For repeated observations, use logpoints (`logMessage`) and read them with `get_output` instead of editing source to add prints.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dap-mcp-server",
-  "version": "0.1.12",
+  "version": "0.1.16",
   "description": "MCP server wrapping the Debug Adapter Protocol for AI-driven debugging",
   "keywords": [
     "LLM",
@@ -19,6 +19,11 @@
   "bin": {
     "dap-mcp-server": "build/index.js"
   },
+  "files": [
+    "build",
+    "SKILL.md",
+    "integrations/claude/dap-debugging"
+  ],
   "directories": {
     "doc": "docs"
   },
@@ -31,7 +36,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "@vscode/debugprotocol": "^1.68.0"
   },
   "peerDependencies": {
@@ -40,6 +45,6 @@
   "devDependencies": {
     "@types/node": "^25.3.3",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.11"
   }
 }

package/.forgejo/workflows/publish.yml

@@ -1,63 +0,0 @@
-name: Publish to npm
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  publish:
-    runs-on: docker
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-          token: ${{ secrets.REPO_TOKEN }}
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
-
-      - name: Install dependencies
-        run: npm ci
-
-      - name: Run tests
-        run: npm test
-
-      - name: Run typecheck
-        run: npm run typecheck
-
-      - name: Build
-        run: npm run build
-
-      - name: Configure git
-        run: |
-          git config user.name "Forgejo Actions"
-          git config user.email "actions@forgejo.local"
-
-      - name: Bump version and publish
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-        run: |
-          # Get current version
-          CURRENT_VERSION=$(node -p "require('./package.json').version")
-          echo "Current version: $CURRENT_VERSION"
-
-          # Bump patch version
-          npm version patch --no-git-tag-version
-          NEW_VERSION=$(node -p "require('./package.json').version")
-          echo "New version: $NEW_VERSION"
-
-          # Commit version bump
-          git add package.json package-lock.json
-          git commit -m "chore: bump version to $NEW_VERSION [skip ci]"
-          git tag "v$NEW_VERSION"
-
-          # Push changes back to repository
-          git push origin main --tags
-
-          # Publish to npm
-          npm publish --access public

package/CLAUDE.md

@@ -1,71 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-MCP server wrapping the Debug Adapter Protocol (DAP) for AI agent-driven debugging. TypeScript, Node.js, ESM modules. Published to npm as `dap-mcp-server`.
-
-## Commands
-
-```bash
-npm run build          # TypeScript compilation → build/
-npm run typecheck      # Type-check without emitting (tsc --noEmit)
-npm test               # vitest run (all tests)
-npm run test:watch     # vitest in watch mode
-npm run dev            # tsc --watch
-npm start              # Run the MCP server (stdio transport)
-npx vitest run src/path/to/file.test.ts   # Run a single test file
-```
-
-## Architecture
-
-Three layers, top to bottom:
-
-1. **MCP Layer** (`src/server.ts`, `src/index.ts`) — `McpServer` with 12 tools + 1 resource (`dap://sessions`). All tool handlers return `{ content: [{ type: "text", text: JSON.stringify(...) }] }` with `isError: true` on failure. Entry point connects via `StdioServerTransport`.
-
-2. **Session Layer** (`src/session/`) — `DebugSession` wraps a `DAPClient` with state machine (`idle → configuring → running ↔ stopped → terminated`), output buffering (`RingBuffer<OutputEntry>`), and composite state collection (`collectState()` fetches threads + stack + scopes + variables in one call). `SessionManager` handles multi-session tracking with auto-resolution (single active session doesn't need explicit ID).
-
-3. **DAP Layer** (`src/dap/`) — `DAPClient` spawns adapter as child process, communicates via stdin/stdout using DAP wire protocol (Content-Length headers + JSON bodies, same framing as LSP). `MessageParser` handles incremental parsing. `DAPClient` extends `EventEmitter`, emitting DAP events and tracking pending request/response correlation by sequence number.
-
-4. **Adapters** (`src/adapters/`) — `AdapterRegistry` with three tiers: builtins (`builtin.ts`) < global (`~/.dap-mcp/adapters.json`) < project (`./.dap-mcp/adapters.json`). Higher tiers override lower. `detect.ts` checks adapter binary availability via `which`/`where`.
-
-### Request Lifecycle
-
-`MCP tool call → server.ts handler → SessionManager.resolve(sessionId) → DebugSession method → DAPClient.sendRequest(command, args) → serialize to DAP wire format → adapter stdin → adapter stdout → MessageParser → response correlation by seq number → resolve Promise`
-
-Events flow the reverse direction: adapter emits events → `DAPClient` re-emits → `DebugSession.handleEvent()` updates state machine, resolves waiters, buffers output.
-
-## Code Conventions
-
-- ESM modules (`"type": "module"` in package.json)
-- Import paths use `.js` extension (e.g., `import { Foo } from "./foo.js"`)
-- Never `console.log()` in server code — stdout is MCP wire protocol; use `console.error()` for diagnostics
-- All tool execution errors use `isError: true` in MCP results, not JSON-RPC protocol errors
-- Types from `@vscode/debugprotocol` for DAP message types
-- Internal/MCP-facing types in `src/dap/types.ts`
-- All source files carry an MIT license header comment — preserve it when creating new files
-
-## Testing
-
-- Framework: vitest (no config file — uses defaults)
-- Unit tests: co-located with source (`*.test.ts`)
-- Integration tests: `src/integration/` — test full DAP lifecycle against mock adapters
-- Test fixtures: `src/test-fixtures/` — mock DAP adapters written in **plain JS** (not TypeScript), implementing enough of the DAP protocol to test against. `mock-adapter.js` is the full-featured one; `crash-adapter.js` and `silent-adapter.js` test error cases.
-
-## Key Design Decisions
-
-1. **Coarse-grained tools**: `get_state` returns threads+stack+scopes+variables in one call to minimize AI agent round-trips
-2. **Synchronous stepping**: `step` blocks until stopped, returns new state
-3. **Auto-session resolution**: `sessionId` optional when single session active
-4. **Output ring buffer**: 10K lines max, oldest dropped
-5. **Own DAP client**: Custom implementation (not `@vscode/debugadapter-testsupport`) for full control over event buffering and crash detection
-
-## CI/CD
-
-Forgejo Actions workflow (`.forgejo/workflows/publish.yml`) runs on push to `main`: tests → typecheck → build → bump patch version → publish to npm. Version bumps are auto-committed with `[skip ci]`.
-
-## Design Documents
-
-- Design: `docs/plans/2026-03-05-dap-wrapper-mcp-design.md`
-- Implementation plan: `docs/plans/2026-03-05-dap-wrapper-mcp-implementation.md`

package/TODO.md

@@ -1,32 +0,0 @@
-# DAP MCP Server — Improvement TODO
-
-Findings from a self-review of how usable this MCP is for an AI agent. Ordered by priority (descending). Check items off as completed.
-
-## Tier 1 — Documentation (SKILL.md). High leverage, low risk.
-
-- [x] **P1 — Logpoints section.** `breakpoints[].logMessage` is already wired through (session.ts:138) but is invisible in SKILL.md. It is the closest thing to a drop-in replacement for `print()` debugging: no code edits, captures every hit, no execution pause. Should have its own headline section with an example.
-- [x] **P2 — "Debug a failing test" section.** Most real bugs surface inside test runners (pytest, vitest, jest, go test, cargo test). Currently zero guidance. Add a per-framework template for launching a single test under the debugger.
-- [x] **P3 — "Switch from print() to debugger" triggers.** Concrete rules an AI agent will actually follow: "if first fix attempt was wrong, stop guessing"; "if about to add 3+ prints, use logpoints"; "if reasoning about iteration N, use `hitCondition`"; "if traceback is non-obvious, launch test under debugger".
-- [x] **P4 — Stepping strategy.** Default to `next`. Use `stepIn` only when you suspect the bug is *inside* the called function. Otherwise agents get lost in library internals.
-- [x] **P5 — Full worked example.** Real bug → real `debug_launch` call → real returned state → identified fix. Replaces all the abstract advice with one concrete walkthrough.
-- [x] **P5b — Node.js adapter recipe.** Builtin was removed; add a ready-to-paste `configure_adapter` snippet for `js-debug-dap`.
-
-## Tier 2 — Code changes that materially improve UX.
-
-- [x] **P6 — `debug_inspect` macro tool.** One call: launch, run to a breakpoint, evaluate a list of expressions, disconnect. Collapses a 5–7 round-trip workflow into 1. Most likely change to make me reach for the debugger reflexively.
-- [x] **P7 — Flip `stopOnEntry` default to `false` when breakpoints are provided.** Today defaults to `true` regardless (server.ts:206). Doing the right thing automatically is better than relying on the agent reading the SKILL.md.
-- [x] **P8 — Structured deep variables.** `getVariables` with `depth > 1` flattens children into the value string (session.ts:271–278). Hard for the AI to consume. Return nested `children: [...]` instead.
-- [x] **P9 — `list_adapters` summary line + surfaced install hints.** Add `summary: "2/4 installed"` and lift `installHint` for missing adapters to the top level so it's scannable.
-- [x] **P10 — `debug_run` macro tool.** Launch, run to completion, return all stdout/stderr. Zero breakpoints, zero round-trips. For "what does this script actually print/crash with?" cases.
-
-## Tier 3 — Polish.
-
-- [x] **P11 — Better "session is not stopped" error.** Currently says "use step with action: pause" (server.ts:549) — bad advice (Python `pause` lands in arbitrary library code). Suggest "set a breakpoint where you want to inspect, then continue to it".
-- [x] **P12 — Version drift.** `McpServer` registers as `0.1.0` (server.ts:48); package.json is `0.1.10`. Read from `package.json`.
-- [x] **P13 — `list_breakpoints` tool.** After several `set_breakpoints` calls, no way to introspect what's set. Minor.
-
-## Tier 4 — Speculative.
-
-- [x] **`get_output({ since })` for incremental polling.** Smaller substitute for streaming subscriptions. Caller passes the `nextSince` value from a prior call to receive only newly-emitted entries. Useful for watching logpoint output during `continue` against long-running programs.
-- [ ] ~~Streaming output via MCP resource subscriptions.~~ AI agents don't watch streams in real time; the request/response pattern doesn't benefit. `since`-based polling covers the practical case.
-- [ ] ~~Auto-detect test runner from program path.~~ Too magic; SKILL.md recipes (P2) make the right call explicit, and silent misfires would be worse than no detection at all.

package/docs/plans/2026-03-05-dap-wrapper-mcp-design.md

@@ -1,326 +0,0 @@
-# DAP Wrapper MCP Server — Design Document
-
-**Date**: 2026-03-05
-**Status**: Approved
-
-## Purpose
-
-An MCP server that wraps the Debug Adapter Protocol (DAP), enabling AI agents (Claude, etc.) to use real debuggers instead of relying on print statements and log analysis. The server spawns debug adapters as child processes and exposes a coarse-grained set of MCP tools optimized for agent-driven debugging workflows.
-
-## Decisions
-
-- **Language**: TypeScript (Node.js)
-- **Transport**: MCP over stdio; DAP over child process stdin/stdout
-- **Adapter management**: Config-based with a registration tool + built-in defaults for Python (debugpy), Node.js (js-debug), Go (delve), C/C++ (lldb-dap)
-- **Tool granularity**: Coarse-grained (~12 tools), composite responses
-- **Execution model**: Synchronous stepping with configurable timeout — `step` blocks until the debuggee stops and returns the new state
-
-## Architecture
-
-```
-┌──────────────────────────────────────────────────┐
-│                MCP Server (Node.js)               │
-│                                                   │
-│  ┌──────────┐  ┌─────────────────────────────┐   │
-│  │ Adapter   │  │ Session Manager              │   │
-│  │ Registry  │  │                              │   │
-│  │           │  │  Session ──► DAP Client ─────┼───┼──► adapter (child process)
-│  │ - python  │  │    • state (running/stopped) │   │      (stdin/stdout)
-│  │ - node    │  │    • breakpoints map         │   │
-│  │ - go      │  │    • output ring buffer      │   │
-│  │ - cppdbg  │  │    • event queue             │   │
-│  │ - custom  │  │    • focused thread          │   │
-│  └──────────┘  └─────────────────────────────┘   │
-│                                                   │
-│  ┌───────────────────────────────────────────┐   │
-│  │ MCP Layer (stdio transport)                │   │
-│  │  - 12 Tool handlers                        │   │
-│  │  - Resource: dap://sessions                │   │
-│  └───────────────────────────────────────────┘   │
-└──────────────────────────────────────────────────┘
-```
-
-### Components
-
-1. **Adapter Registry** — Stores adapter configurations. Each config: `type`, `runtime` (optional), `program` (path to adapter binary), `args`, `launchDefaults`. Built-in defaults for common adapters. Persisted to `~/.dap-mcp/adapters.json` (global) and `./.dap-mcp/adapters.json` (project-local).
-
-2. **Session Manager** — Manages active debug sessions. Each session owns a `DAPClient`, tracks state (`idle | configuring | running | stopped | terminated`), maintains breakpoints map, buffers output in a ring buffer (10,000 lines max), and handles adapter crash detection.
-
-3. **DAP Client** — Low-level protocol handler. Spawns adapter child process, sends/receives DAP messages with `Content-Length` framing, correlates request/response by `seq`, emits events to the session. Includes startup timeout (10s default).
-
-4. **MCP Layer** — Registers tools, handles tool calls, serves the `dap://sessions` resource.
-
-## Tools (12)
-
-### Session Lifecycle
-
-#### `debug_launch`
-Start a new debug session by launching a program.
-
-```typescript
-Input: {
-  adapter: string,                    // "python" | "node" | "go" | "cppdbg" | custom
-  program: string,
-  args?: string[],
-  cwd?: string,
-  env?: Record<string, string>,
-  stopOnEntry?: boolean,              // default: true
-  breakpoints?: Array<{
-    file: string,
-    lines: Array<{
-      line: number,
-      condition?: string,
-      hitCondition?: string,
-      logMessage?: string
-    }>
-  }>,
-  exceptionBreakpoints?: string[],    // e.g., ["uncaught"]
-  adapterConfig?: Record<string, any> // pass-through to adapter
-}
-Output: { sessionId: string, state: StoppedState | RunningState }
-```
-
-#### `debug_attach`
-Attach to a running process.
-
-```typescript
-Input: {
-  adapter: string,
-  processId?: number,
-  host?: string,
-  port?: number,
-  adapterConfig?: Record<string, any>
-}
-Output: { sessionId: string, state: StoppedState | RunningState }
-```
-
-#### `debug_restart`
-Restart the current debug session with the same configuration.
-
-```typescript
-Input: { sessionId?: string }
-Output: { sessionId: string, state: StoppedState | RunningState }
-```
-
-#### `debug_disconnect`
-End a debug session.
-
-```typescript
-Input: {
-  sessionId?: string,
-  terminateDebuggee?: boolean         // default: true for launch, false for attach
-}
-Output: { success: boolean }
-```
-
-### Breakpoints
-
-#### `set_breakpoints`
-Set or replace breakpoints in a source file. Replaces all breakpoints in the specified file (DAP semantics).
-
-```typescript
-Input: {
-  sessionId?: string,
-  file: string,
-  breakpoints: Array<{
-    line: number,
-    condition?: string,
-    hitCondition?: string,
-    logMessage?: string
-  }>
-}
-Output: {
-  breakpoints: Array<{
-    id: number,
-    verified: boolean,
-    line: number,
-    message?: string
-  }>
-}
-```
-
-#### `set_exception_breakpoints`
-Configure which exceptions cause the debugger to break.
-
-```typescript
-Input: {
-  sessionId?: string,
-  filters: string[]                   // adapter-specific, e.g., ["uncaught", "raised"]
-}
-Output: { filters: string[] }
-```
-
-### State Inspection
-
-#### `get_state`
-Get current debuggee state. When stopped: threads + stack trace + scopes + variables. When running: status + buffered output.
-
-```typescript
-Input: {
-  sessionId?: string,
-  threadId?: number,                  // default: thread that triggered stop
-  depth?: number,                     // stack frames to return, default 10
-  variableDepth?: number,             // nested expansion depth, default 1
-  timeout?: number                    // ms to wait if running, default 0
-}
-Output: StoppedState | RunningState
-```
-
-#### `evaluate`
-Evaluate an expression in the debuggee's context.
-
-```typescript
-Input: {
-  sessionId?: string,
-  expression: string,
-  frameId?: number,                   // default: top frame
-  context?: "repl" | "watch" | "hover"  // default: "repl"
-}
-Output: {
-  result: string,
-  type?: string,
-  hasChildren: boolean,
-  variablesReference: number
-}
-```
-
-#### `get_output`
-Get buffered program output.
-
-```typescript
-Input: {
-  sessionId?: string,
-  category?: "stdout" | "stderr" | "console",  // default: all
-  clear?: boolean                     // clear buffer after reading, default false
-}
-Output: {
-  output: Array<{ category: string, text: string, timestamp: string }>,
-  truncated: boolean
-}
-```
-
-### Execution Control
-
-#### `step`
-Control execution. Synchronous: blocks until debuggee stops or timeout.
-
-```typescript
-Input: {
-  sessionId?: string,
-  action: "continue" | "next" | "stepIn" | "stepOut" | "pause",
-  threadId?: number,
-  timeout?: number                    // ms, default 30000
-}
-Output: StoppedState | { status: "running", elapsedMs: number }
-```
-
-### Adapter Management
-
-#### `configure_adapter`
-Register or update a debug adapter configuration.
-
-```typescript
-Input: {
-  type: string,                       // adapter identifier
-  runtime?: string,                   // e.g., "node", "python3"
-  program: string,                    // path to adapter binary/script
-  args?: string[],
-  launchDefaults?: Record<string, any>,
-  scope?: "global" | "project"        // default: "project"
-}
-Output: { success: boolean }
-```
-
-#### `list_adapters`
-List available debug adapter configurations with availability status.
-
-```typescript
-Input: {}
-Output: {
-  adapters: Array<{
-    type: string,
-    source: "builtin" | "global" | "project",
-    available: boolean,               // binary exists on system
-    program: string,
-    installHint?: string              // e.g., "pip install debugpy"
-  }>
-}
-```
-
-## Common Response Types
-
-```typescript
-interface StoppedState {
-  status: "stopped";
-  reason: "breakpoint" | "step" | "exception" | "pause" | "entry";
-  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[];
-}
-
-interface RunningState {
-  status: "running";
-  output?: string[];
-}
-```
-
-## Built-in Adapter Defaults
-
-| Type | Adapter | Detection | Install Hint |
-|---|---|---|---|
-| `python` | debugpy | `python3 -c "import debugpy"` | `pip install debugpy` |
-| `node` | js-debug-dap | `which js-debug-dap` or bundled | Ships with MCP |
-| `go` | delve | `which dlv` | `go install github.com/go-delve/delve/cmd/dlv@latest` |
-| `cppdbg` | lldb-dap | `which lldb-dap` | `apt install lldb` / `brew install llvm` |
-
-## Error Handling
-
-All execution errors use MCP's `isError: true` in tool results (not JSON-RPC protocol errors), so the AI can read and self-correct.
-
-| Scenario | Behavior |
-|---|---|
-| Adapter binary not found | `isError: true` with install instructions |
-| Adapter crash (child exit) | Session marked `terminated`, stderr in error message |
-| DAP protocol error | Adapter's error message surfaced verbatim |
-| Timeout on step/continue | Return `{ status: "running", elapsedMs }` — not an error |
-| Invalid session ID | Error listing available sessions |
-| Expression eval failure | Adapter's error message (e.g., "NameError: ...") |
-
-## MCP Resource
-
-- `dap://sessions` — List of active sessions with status summary. Subscribable (emits `notifications/resources/updated` on session state changes).
-
-## Config Files
-
-- `~/.dap-mcp/adapters.json` — Global adapter configurations
-- `./.dap-mcp/adapters.json` — Project-local adapter overrides (takes precedence)
-
-## Key Design Principles
-
-1. **One call, maximum info**: Composite responses (stack + variables + threads) reduce round-trips
-2. **Smart defaults**: Auto-select single session, auto-select stopped thread, `stopOnEntry: true`
-3. **Errors are information**: Execution errors in results (not protocol errors) let the AI self-correct
-4. **Bounded resources**: Output ring buffer (10K lines), variable depth limits, stack frame limits
-5. **Crash resilience**: Adapter process monitoring with clear error reporting