Content
# 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](https://www.npmjs.com/package/opendebug) | [Repository](https://github.com/neriousy/opendebug) | [Skill](./skills/opendebug/SKILL.md)
## 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`:
```json
{
"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:
```bash
npm install -g opendebug
```
Then use:
```json
{
"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:
```bash
npx -y opendebug@latest
```
### Amp
Use the Amp MCP command:
```bash
amp mcp add opendebug -- npx -y opendebug@latest
```
### Antigravity
Add a custom MCP server using Antigravity's MCP settings:
```json
{
"mcpServers": {
"opendebug": {
"command": "npx",
"args": ["-y", "opendebug@latest"]
}
}
}
```
### Claude Code
Install via CLI (MCP only):
```bash
claude mcp add opendebug --scope user npx -y opendebug@latest
```
Install as a plugin (MCP + Skills):
```text
/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`:
```json
{
"mcpServers": {
"opendebug": {
"command": "npx",
"args": ["-y", "opendebug@latest"]
}
}
}
```
### Cline
Open Cline's MCP server settings and add:
```json
{
"mcpServers": {
"opendebug": {
"command": "npx",
"args": ["-y", "opendebug@latest"]
}
}
}
```
### Command Code
Use the Command Code CLI:
```bash
cmd mcp add opendebug --scope user npx -y opendebug@latest
```
### Codex
Add the MCP server to your Codex config:
```toml
[mcp_servers.opendebug]
command = "npx"
args = ["-y", "opendebug@latest"]
```
You can also add it with the Codex CLI:
```bash
codex mcp add opendebug -- npx -y opendebug@latest
```
To use the skill, install it with the skills CLI:
```bash
npx skills add neriousy/opendebug --skill opendebug
```
Restart Codex so the MCP server and skill are loaded.
### Copilot CLI
Start Copilot CLI:
```bash
copilot
```
Run:
```text
/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:
```bash
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:
```json
{
"mcpServers": {
"opendebug": {
"command": "npx",
"args": ["-y", "opendebug@latest"]
}
}
}
```
### Cursor
In Cursor settings, open MCP, add a new server named `opendebug`, and use:
```json
{
"mcpServers": {
"opendebug": {
"command": "npx",
"args": ["-y", "opendebug@latest"]
}
}
}
```
### Factory CLI
Use the Factory CLI:
```bash
droid mcp add opendebug "npx -y opendebug@latest"
```
### Gemini CLI
Install as a Gemini extension (MCP + Skills):
```bash
gemini extensions install --auto-update https://github.com/neriousy/opendebug
```
Install MCP only, project-wide:
```bash
gemini mcp add opendebug npx -y opendebug@latest
```
Install MCP only, globally:
```bash
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`.
```json
{
"mcpServers": {
"opendebug": {
"command": "npx",
"args": ["-y", "opendebug@latest"]
}
}
}
```
### Kiro
In Kiro settings, open the MCP configuration and add:
```json
{
"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:
```bash
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`.
```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:
```bash
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:
```json
{
"$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`:
```toml
[[mcp_servers]]
name = "opendebug"
transport = "stdio"
command = "npx"
args = ["-y", "opendebug@latest"]
```
### Qoder CLI
Install project-wide:
```bash
qodercli mcp add opendebug -- npx -y opendebug@latest
```
Install globally:
```bash
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:
```bash
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:
```json
{
"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:
```text
skills/opendebug/
```
Install it with the skills CLI:
```bash
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:
```text
Use $opendebug to debug this issue. Reproduce it from runtime evidence before changing code.
```
Without skill support, ask:
```text
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`:
```js
// #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:
```text
~/.local/share/opendebug/workspaces/<workspace-id>/
```
When `XDG_DATA_HOME` is set, it writes to:
```text
$XDG_DATA_HOME/opendebug/workspaces/<workspace-id>/
```
Reports written by `write_debug_report` and reproduction-step files live in that workspace state directory.
## Development
```bash
npm install
npm run typecheck
npm test
```
Before publishing:
```bash
npm pack --dry-run
npm publish --access public
```
