dap-mcp-server 0.1.17 → 0.1.18

package/README.md

@@ -71,6 +71,57 @@ npm install
 npm run build
 ```
 
+## Usage with Codex
+
+Choose either direct MCP registration or the plugin; installing both exposes the same
+debugger twice. The plugin also supplies the activation skill.
+
+### Direct MCP registration
+
+Register the stdio server in Codex CLI (the CLI and IDE extension share this configuration):
+
+```bash
+codex mcp add dap -- npx -y dap-mcp-server
+codex mcp list
+```
+
+For a source checkout, build first and register the absolute entry-point path instead:
+
+```bash
+npm ci
+npm run build
+codex mcp add dap -- node "$(pwd)/build/index.js"
+```
+
+Direct registration exposes the tools but does not install the activation skill. To add
+the skill to a project after a global npm install:
+
+```bash
+mkdir -p .agents/skills/dap-debugging
+cp "$(npm root -g)/dap-mcp-server/SKILL.md" .agents/skills/dap-debugging/SKILL.md
+```
+
+### Plugin: MCP server and activation skill
+
+The npm package also ships a Codex plugin that bundles the MCP declaration with the
+`dap-debugging` activation skill. After a global install, register its marketplace and
+install the plugin:
+
+```bash
+npm install -g dap-mcp-server
+codex plugin marketplace add "$(npm root -g)/dap-mcp-server/integrations/codex"
+codex plugin add dap-debugging@dap-mcp-server
+```
+
+From a source checkout, the marketplace path is `"$(pwd)/integrations/codex"`. The
+plugin launches the published npm server via `npx`; use direct registration with
+`build/index.js` to test changes to the server itself.
+
+Start a new Codex session after installation. Ask Codex to run `debug_doctor` with the
+project's absolute `cwd`, then use `debug_at` for one-shot breakpoint inspection.
+The activation skill provides this workflow when installed. Debug adapters must still
+be installed separately (see the supported-adapters table above).
+
 ## Usage with Claude Code
 
 Register the server for the current user:

package/integrations/codex/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "dap-mcp-server",
+  "interface": {
+    "displayName": "DAP MCP Server"
+  },
+  "plugins": [
+    {
+      "name": "dap-debugging",
+      "source": {
+        "source": "local",
+        "path": "./dap-debugging"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/integrations/codex/dap-debugging/mcp.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
+  "mcpServers": {
+    "dap": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "-y",
+        "dap-mcp-server"
+      ]
+    }
+  }
+}

package/integrations/codex/dap-debugging/plugin.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "dap-debugging",
+  "version": "0.1.0",
+  "description": "Debug local programs with standard Debug Adapter Protocol adapters.",
+  "author": {
+    "name": "Ivan Iraci"
+  },
+  "license": "MIT",
+  "keywords": [
+    "debugging",
+    "dap",
+    "mcp",
+    "codex"
+  ]
+}

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

@@ -0,0 +1,51 @@
+---
+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`.
+
+`step` answers compactly (frame-local scopes, short stack, new output only); use `get_state` for globals, deeper stacks, or `scopes: ["Registers"]`. For a running or suspended process, call `debug_attach` with `breakpoints` so they bind before it resumes.
+
+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.17",
+  "version": "0.1.18",
   "description": "MCP server wrapping the Debug Adapter Protocol for AI-driven debugging",
   "keywords": [
     "LLM",
@@ -22,7 +22,8 @@
   "files": [
     "build",
     "SKILL.md",
-    "integrations/claude/dap-debugging"
+    "integrations/claude/dap-debugging",
+    "integrations/codex"
   ],
   "directories": {
     "doc": "docs"