# Debugssy

> AI debugger for VS Code, Cursor, Windsurf

- **Type:** MCP server
- **Install:** `agentstack add mcp-gmaynez-debugssy`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gmaynez](https://agentstack.voostack.com/s/gmaynez)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [gmaynez](https://github.com/gmaynez)
- **Source:** https://github.com/gmaynez/debugssy
- **Website:** https://marketplace.visualstudio.com/items?itemName=gamag.debugssy

## Install

```sh
agentstack add mcp-gmaynez-debugssy
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Debugssy

[](https://marketplace.visualstudio.com/items?itemName=gamag.debugssy)
[](https://open-vsx.org/extension/gamag/debugssy)
[](./LICENSE)

**Let your AI assistant drive the debugger.**

Debugssy connects AI assistants (Cursor, Copilot, Claude Desktop) to VS Code's
debugging engine via the
[Model Context Protocol](https://modelcontextprotocol.io). Instead of clicking
through the debugger UI, describe what you're hunting for.

[Install](https://marketplace.visualstudio.com/items?itemName=gamag.debugssy) ·
[Issues](https://github.com/gmaynez/debugssy/issues) · [Security](./SECURITY.md)

---

## What It Does

```
You: "Figure out why users get null when logging in"

AI: Sets breakpoint in auth handler → waits for hit → inspects `user` object →
    traces call stack → spots missing WHERE clause in the query. Done.
```

The AI gets tools to set breakpoints (with conditions, hit counts, logpoints),
read variables, walk the call stack, and evaluate expressions—all through MCP.
You stay in control of _when_ debugging runs, or hand over the reins entirely.

Works with any language that VS Code can debug: JavaScript, TypeScript, Python,
Go, Java, C++, Rust, you name it.

**Recommended models:** Claude 4.5 Haiku or Grok 4.1 Fast (speed + cost).

---

## Quick Start

### 1. Install the Extension

Search **"Debugssy"** in VS Code's extension panel (`Ctrl+Shift+X`), or grab it
from:

- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=gamag.debugssy)
- [Open VSX](https://open-vsx.org/extension/gamag/debugssy) (VSCodium, Gitpod,
  etc.)

### 2. Connect Your AI

**VS Code (Copilot) and Cursor — zero config.** The extension registers its MCP
server automatically. Just install Debugssy and start chatting. No JSON edits
needed.

> If you have an older manual `"debugssy"` entry in your settings, remove it to
> avoid duplicates.

**Other MCP clients** (Claude Desktop, Claude Code, OpenCode, etc.) — add this
to your client's config file:

```json
{
  "mcpServers": {
    "debugssy": { "url": "http://localhost:3000/mcp" }
  }
}
```

Config file locations:

- **Claude Desktop:**
  `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or
  `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
- **Claude Code / OpenCode / others:** see your client's docs — the URL is
  always `http://localhost:3000/mcp`

### 3. Debug Something

1. Start a debug session in VS Code (`F5`)
2. Ask your AI: _"Set a breakpoint where user authentication fails and show me
   what's in the request object"_
3. Watch it work

Type `/` in chat to see guided workflows like `/debug-crash` or
`/trace-variable`.

---

## Two Modes

**Assisted (default):** You control execution (F5, step, continue). The AI sets
breakpoints and inspects state. Good for learning and staying hands-on.

**Full automation:** The AI controls everything—starting sessions, continuing
past breakpoints, the works. Good for "just find the bug" scenarios.

```json
{ "debugssy.automationLevel": "full" }
```

Copilot users: restart VS Code after switching modes (it doesn't refresh tools
dynamically).

---

## Available Tools

Your AI sees these via MCP:

**Inspection** (always available): `get_debug_state`, `get_variables`,
`get_call_stack`, `evaluate_expression`, `get_console_output`, `get_threads`

**Breakpoints** (always available): `set_breakpoint`, `remove_breakpoint`,
`list_breakpoints`, `toggle_breakpoint`, `remove_all_breakpoints`

`set_breakpoint` supports conditions (`user.role === 'admin'`), hit counts
(`> 10`), and log messages (logpoints).

**Execution control** (full mode only): `start_debugging`, `stop_debugging`,
`continue`, `pause`, `restart`, `wait_for_breakpoint`

Step operations (`step_over`, `step_into`, `step_out`) are available in full
mode if you enable `debugssy.allowStepOperations`. Usually unnecessary—strategic
breakpoints + continue is faster for AI debugging.

---

## Settings

Open VS Code settings and search "debugssy":

| Setting                              | Default    | What it does                                                                                            |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------- |
| `debugssy.mcp.port`                  | `3000`     | Server port. Change if 3000 is taken.                                                                   |
| `debugssy.automationLevel`           | `assisted` | `assisted` or `full`                                                                                    |
| `debugssy.expressionValidationLevel` | `moderate` | How paranoid to be about `evaluate_expression`. Options: `strict`, `moderate`, `permissive`, `disabled` |
| `debugssy.maxExpressionLength`       | `100`      | Max chars for evaluated expressions                                                                     |
| `debugssy.waitForBreakpointTimeout`  | `5000`     | How long `wait_for_breakpoint` waits (ms)                                                               |
| `debugssy.allowStepOperations`       | `false`    | Enable step_over/into/out in full mode                                                                  |

For tighter security, configure an allowlist in your MCP client—see
[ALLOWLIST_GUIDE.md](./docs/ALLOWLIST_GUIDE.md).

---

## Security

Debugssy runs on localhost only. Your code never leaves your machine.

The expression validator blocks obvious injection attempts (`eval`,
`require('fs')`, `process.exit`, etc.) and asks for confirmation on anything
suspicious. Four levels of paranoia: `strict` (whitelist only), `moderate`
(default, blocks known dangerous patterns), `permissive` (blocks only the scary
stuff), `disabled` (you're on your own).

Best practices for AI-assisted debugging:

1. **Start fresh.** Use a new AI conversation for debug sessions to avoid prompt
   injection from earlier context.
2. **Skip web searches.** Don't search the web in the same conversation—external
   content is the main vector for prompt injection.
3. **Review elicitation prompts.** When the validator asks about an expression,
   actually read it before approving.

Full details: [SECURITY.md](./SECURITY.md),
[MCP_COMPLIANCE.md](./docs/MCP_COMPLIANCE.md)

---

## Troubleshooting

**"No active debug session"** — Start debugging (`F5`) before asking the AI to
inspect things. The debugger needs to be running.

**Port 3000 in use** — Change `debugssy.mcp.port` to something else (3001, 8080,
whatever). Or kill whatever's hogging 3000:

```bash
# Windows
netstat -ano | findstr :3000
taskkill /PID  /F

# Mac/Linux
lsof -ti:3000 | xargs kill -9
```

**AI can't connect** — Check the VS Code Output panel
(`View → Output → Debugssy`). Verify the server's up with
`curl http://localhost:3000/health`. Make sure your AI config points to
`http://localhost:3000/mcp`.

**Variables empty** — Execution must be paused at a breakpoint. If it's running,
there's nothing to inspect. Also try `scope: "Local"` to filter out noise.

**Copilot doesn't see new tools** — Restart VS Code. Copilot caches the tool
list.

---

## Architecture

```
┌─────────────────────────────────────────────────┐
│  VS Code Extension                              │
│                                                 │
│   MCP Server (localhost:3000)                   │
│        ↓                                        │
│   ToolRouter → Security Layer → Tool Registry   │
│        ↓                                        │
│   DAP Client ← → VS Code Debug API              │
└─────────────────────────────────────────────────┘
        ↑
        │ HTTP + MCP Protocol
        ↓
┌─────────────────────┐
│   AI Assistant      │
│ (Cursor/Copilot/    │
│  Claude Desktop)    │
└─────────────────────┘
```

The MCP server speaks Streamable HTTP (spec version 2025-06-18). Session IDs are
`crypto.randomUUID()`. All tool inputs go through Zod validation.

Key files if you're diving in:

- `src/MCPServer.ts` — Server setup and MCP protocol handling
- `src/routing/ToolRouter.ts` — Tool dispatch
- `src/security/ExpressionValidator.ts` — The paranoia engine
- `src/dap/Client.ts` — Debug Adapter Protocol integration

---

## Building from Source

```bash
git clone https://github.com/gmaynez/debugssy.git
cd debugssy
npm install
npm run compile    # Build
npm run package    # Creates .vsix
npm test           # Run tests
```

Press `F5` in VS Code to launch the Extension Development Host for live testing.

---

## Known Limitations

- **Single MCP client at a time.** If multiple AI assistants connect to the same
  Debugssy instance, the most recent connection takes over.
- **Copilot caches tools.** Restart VS Code after changing `automationLevel`.
- **No watch expressions.** Use `evaluate_expression` instead.
- **Single-threaded assumption.** Defaults to thread ID 1.
- **Assisted mode is blind to manual steps.** If you click Continue in the UI,
  the AI doesn't know.
- **Nested objects get truncated.** Blame the debugger, not us.

---

## Contributing

Found a bug? [Open an issue](https://github.com/gmaynez/debugssy/issues).

Want to contribute? Fork it, make a branch, open a PR. Follow the existing code
style (TypeScript, ESLint). Add tests for new features.

Check
[good first issues](https://github.com/gmaynez/debugssy/labels/good%20first%20issue)
for starter tasks.

---

## More Documentation

- [SECURITY.md](./SECURITY.md) — Threat model, security policy
- [ALLOWLIST_GUIDE.md](./docs/ALLOWLIST_GUIDE.md) — Lock down which tools your
  AI can use
- [DEBUGSSY_PROMPT.md](./DEBUGSSY_PROMPT.md) — Detailed guide for AI assistants
- [MCP Specification](https://modelcontextprotocol.io) — The protocol itself
- [Debug Adapter Protocol](https://microsoft.github.io/debug-adapter-protocol/)
  — What VS Code speaks under the hood

---

## License

Apache 2.0. See [LICENSE](./LICENSE).

Copyright © 2025-2026 Guillermo Garcia Maynez

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gmaynez](https://github.com/gmaynez)
- **Source:** [gmaynez/debugssy](https://github.com/gmaynez/debugssy)
- **License:** Apache-2.0
- **Homepage:** https://marketplace.visualstudio.com/items?itemName=gamag.debugssy

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gmaynez-debugssy
- Seller: https://agentstack.voostack.com/s/gmaynez
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.