Debugssy

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. Instead of clicking
through the debugger UI, describe what you're hunting for.

Install ·
Issues · Security

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
• Open VSX (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:

{
  "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.

{ "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":

For tighter security, configure an allowlist in your MCP client—see
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,
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:

# Windows
netstat -ano | findstr :3000
taskkill /PID <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

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.

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
for starter tasks.

More Documentation

• SECURITY.md — Threat model, security policy
• ALLOWLIST_GUIDE.md — Lock down which tools your
  AI can use
• DEBUGSSY_PROMPT.md — Detailed guide for AI assistants
• MCP Specification — The protocol itself
• Debug Adapter Protocol
  — What VS Code speaks under the hood

License

Apache 2.0. See LICENSE.

Copyright © 2025-2026 Guillermo Garcia Maynez