opendebug

MCP server for evidence-based debugging.

opendebug gives coding agents a local evidence loop for hard bugs. It starts debug runs, collects structured runtime logs, records reproduction steps, summarizes evidence, and writes debug reports. Optional skills and plugin metadata are included so capable clients can teach the agent how to use the MCP tools effectively, but the core product is the MCP server.

Links

npm package | Repository | Skill

Key Features

• Evidence-first debugging: start with testable hypotheses, collect runtime evidence, then fix.
• Local log ingest: starts a local HTTP endpoint that temporary instrumentation can post to.
• Workspace-scoped state: stores logs, reproduction steps, and reports outside the repo.
• Optional agent guidance: ships skills/opendebug and plugin metadata for clients that support skills or extensions.
• Effect-backed core: uses Effect for validation and IO flow in the server core.

Safety Notes

opendebug stores whatever your temporary instrumentation sends to it. Do not log secrets, tokens, passwords, API keys, cookies, auth headers, or personal data.

Runtime state is stored in XDG_DATA_HOME/opendebug when XDG_DATA_HOME is set. Otherwise it uses ~/.local/share/opendebug. Each workspace gets its own stable directory under workspaces/.

opendebug does not collect telemetry and does not run update checks.

Requirements

• Node.js 22 or newer
• npm
• An MCP client that can run local stdio servers
• Optional: an agent runtime that supports local skills

Getting Started

Add opendebug to your MCP client with npx:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Using opendebug@latest lets your MCP client pick up the newest published server without a global install.

You can also install the server globally:

npm install -g opendebug

Then use:

{
  "mcpServers": {
    "opendebug": {
      "command": "opendebug",
      "args": []
    }
  }
}

MCP Client Configuration

Most MCP clients can use the standard config from Getting Started. If a client expects one command string instead of JSON fields, use:

npx -y opendebug@latest

Amp

Use the Amp MCP command:

amp mcp add opendebug -- npx -y opendebug@latest

Antigravity

Add a custom MCP server using Antigravity's MCP settings:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Claude Code

Install via CLI (MCP only):

claude mcp add opendebug --scope user npx -y opendebug@latest

Install as a plugin (MCP + Skills):

/plugin marketplace add neriousy/opendebug
/plugin install opendebug@opendebug-plugins

Restart Claude Code so the MCP server and skill are loaded. Check with /mcp and /skills.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Cline

Open Cline's MCP server settings and add:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Command Code

Use the Command Code CLI:

cmd mcp add opendebug --scope user npx -y opendebug@latest

Codex

Add the MCP server to your Codex config:

[mcp_servers.opendebug]
command = "npx"
args = ["-y", "opendebug@latest"]

You can also add it with the Codex CLI:

codex mcp add opendebug -- npx -y opendebug@latest

To use the skill, install it with the skills CLI:

npx skills add neriousy/opendebug --skill opendebug

Restart Codex so the MCP server and skill are loaded.

Copilot CLI

Start Copilot CLI:

copilot

Run:

/mcp add

Use these fields:

• Server name: opendebug
• Server type: local
• Command: npx -y opendebug@latest

Copilot / VS Code

Install as an agent plugin from source (MCP + Skills):

1. Open the Command Palette.
2. Run Chat: Install Plugin From Source.
3. Paste https://github.com/neriousy/opendebug.

Install as an MCP server only with the VS Code CLI:

code --add-mcp '{"name":"opendebug","command":"npx","args":["-y","opendebug@latest"],"env":{}}'

Or add the MCP server manually in VS Code or Copilot settings using the standard config:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Cursor

In Cursor settings, open MCP, add a new server named opendebug, and use:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Factory CLI

Use the Factory CLI:

droid mcp add opendebug "npx -y opendebug@latest"

Gemini CLI

Install as a Gemini extension (MCP + Skills):

gemini extensions install --auto-update https://github.com/neriousy/opendebug

Install MCP only, project-wide:

gemini mcp add opendebug npx -y opendebug@latest

Install MCP only, globally:

gemini mcp add -s user opendebug npx -y opendebug@latest

Gemini Code Assist

Use the standard MCP config from Getting Started in Gemini Code Assist's MCP configuration.

JetBrains AI Assistant and Junie

Go to Settings | Tools | AI Assistant | Model Context Protocol (MCP) and add the standard config. Junie can use the same server under Settings | Tools | Junie | MCP Settings.

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Kiro

In Kiro settings, open the MCP configuration and add:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Katalon Studio

If your Katalon setup expects an HTTP MCP endpoint, run opendebug behind an MCP proxy:

mcp-proxy --transport streamablehttp --port 8080 -- npx -y opendebug@latest

Then add http://127.0.0.1:8080/mcp in StudioAssist with HTTP transport.

OpenCode

Add the following configuration to opencode.json. If you do not have one, create it at ~/.config/opencode/opencode.json.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opendebug": {
      "type": "local",
      "command": ["npx", "-y", "opendebug@latest"]
    }
  }
}

To use the skill too, install it with the skills CLI:

npx skills add neriousy/opendebug --skill opendebug

If your OpenCode setup uses explicit skill paths instead, point it at the installed or checked-out skill directory:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "opendebug": {
      "type": "local",
      "command": ["npx", "-y", "opendebug@latest"]
    }
  },
  "skills": {
    "paths": ["/path/to/opendebug/skills/opendebug"]
  }
}

Mistral Vibe

Add this to ~/.vibe/config.toml:

[[mcp_servers]]
name = "opendebug"
transport = "stdio"
command = "npx"
args = ["-y", "opendebug@latest"]

Qoder CLI

Install project-wide:

qodercli mcp add opendebug -- npx -y opendebug@latest

Install globally:

qodercli mcp add -s user opendebug -- npx -y opendebug@latest

Warp

Go to Settings | AI | Manage MCP Servers, add a server named opendebug, and use:

npx -y opendebug@latest

Visual Studio

Use Visual Studio's MCP server settings and add the standard config from Getting Started.

Windsurf

Open Windsurf's MCP configuration and add:

{
  "mcpServers": {
    "opendebug": {
      "command": "npx",
      "args": ["-y", "opendebug@latest"]
    }
  }
}

Using The Skill

The MCP server works by itself in any MCP client. The skill is an optional workflow layer for clients that support local skills, extensions, or plugins.

This repo is laid out like a portable MCP+skills package:

• .mcp.json: standard MCP server configuration for clients that can read repo-provided MCP config.
• .claude-plugin/plugin.json: Claude Code plugin metadata with bundled MCP server config.
• .claude-plugin/marketplace.json: Claude Code marketplace entry so /plugin marketplace add neriousy/opendebug can discover the plugin.
• server.json: MCP Registry metadata. Its name matches mcpName in package.json.
• skills/opendebug/SKILL.md: the agent skill itself.
• skills/opendebug/agents/openai.yaml: OpenAI/Codex-style skill metadata and MCP dependency hints.

The core skill directory is:

skills/opendebug/

Install it with the skills CLI:

npx skills add neriousy/opendebug --skill opendebug

If your client does not support the skills CLI, use the client-specific plugin/extension path above, or clone the repo only as a fallback and point the client at skills/opendebug.

Clients that do not support skills at all can still use the MCP tools directly. Ask the agent to use the opendebug MCP tools and follow the debug-run lifecycle below.

Your First Prompt

With the skill available, ask your agent:

Use $opendebug to debug this issue. Reproduce it from runtime evidence before changing code.

Without skill support, ask:

Use the opendebug MCP tools to debug this issue. Start a debug run, gather runtime evidence, confirm a hypothesis, then change code.

The agent should start a debug run, add temporary opendebug instrumentation, ask you to reproduce the issue, read the logs, confirm or reject hypotheses, implement the fix, verify with a post-fix run, and remove temporary logs.

Tools

• start_debug_run: starts a local HTTP ingest endpoint and returns an <opendebug_config> block plus an instrumentation template.
• list_debug_runs: lists active ingest sessions in the current MCP server process.
• clear_debug_log: clears the workspace debug log before a reproduction.
• read_debug_log: parses recent NDJSON evidence.
• summarize_debug_log: groups logs by run, hypothesis, and location.
• record_reproduction_steps: records ordered reproduction steps and returns a user prompt.
• write_debug_report: writes a markdown report under the workspace state directory.
• stop_debug_run: stops an active ingest server.

Instrumentation Format

Temporary instrumentation should post one JSON object per observation to the ingestUrl returned by start_debug_run:

// #region opendebug log
fetch(ingestUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    sessionId,
    runId: "run-1",
    hypothesisId: "H1",
    location: "src/file.ts:123",
    message: "Observed state before failing branch",
    data: {},
    timestamp: Date.now()
  })
}).catch(() => {})
// #endregion

Wrap logs in opendebug log regions so cleanup is mechanical after verification.

Concepts

Debug Run Lifecycle

Most sessions use this flow:

1. Start a debug run with start_debug_run.
2. Write precise, testable hypotheses.
3. Add small instrumentation logs that test those hypotheses.
4. Clear the log.
5. Ask the user to reproduce the issue.
6. Read logs and classify each hypothesis as confirmed, rejected, or inconclusive.
7. Implement the fix only after evidence supports a hypothesis.
8. Verify with the same reproduction steps and a new runId, usually post-fix.
9. Remove temporary instrumentation.

State Directory

opendebug does not write logs into your repo by default. It writes workspace state to:

~/.local/share/opendebug/workspaces/<workspace-id>/

When XDG_DATA_HOME is set, it writes to:

$XDG_DATA_HOME/opendebug/workspaces/<workspace-id>/

Reports written by write_debug_report and reproduction-step files live in that workspace state directory.

Development

npm install
npm run typecheck
npm test

Before publishing:

npm pack --dry-run
npm publish --access public