Debugssy

AI-powered debugging for VS Code. Control your debugger with natural language through any AI coding assistant (Claude, Cursor, Copilot, etc.) using the Model Context Protocol (MCP).

🚀 For AI Assistants: Copy COMPACT_PROMPT.txt into your chat to understand Debugssy instantly!

What is Debugssy?

Debugssy is a VS Code extension that lets you debug with AI assistance. Instead of manually clicking through the debugger, you can ask your AI assistant to:

• Set breakpoints where bugs might be
• Inspect variables to understand what's wrong
• Step through code and explain what's happening
• Trace how values change during execution

Example conversation with AI:

You: "The calculation seems wrong in line 42"
AI: Let me set a breakpoint there and inspect the variables...
    [Sets breakpoint, asks you to run debugger]
AI: I can see x=10 and y=20, but result is undefined. 
    The issue is you're not returning the value!

Quick Start (3 Steps)

1. Install the Extension

Option A: From VS Code Marketplace (when published)

Search "Debugssy" in VS Code Extensions

Option B: Development Mode

git clone <repository>
cd debugssy
npm install
# Press F5 in VS Code

2. Configure Your AI Assistant

Add Debugssy's MCP server to your AI assistant settings:

For Cursor / Claude Desktop:

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

For other MCP-compatible assistants: Connect to http://localhost:3000/mcp

3. Start Debugging

1. Open your code in VS Code
2. Tell your AI assistant about the bug
3. The AI will guide you through debugging!

That's it! The AI can now help you debug by setting breakpoints, inspecting variables, and understanding your code's behavior.

Features at a Glance

• 🔴 Smart Breakpoints - AI sets breakpoints where bugs likely are
• 🔍 Variable Inspection - AI reads and explains variable values
• 📚 Call Stack Analysis - AI shows how you got to the current point
• 🎯 Conditional Breakpoints - Only stop when specific conditions are met
• 🚦 Two Automation Modes - Choose between assisted (you control) or full automation
• 🔒 Secure - Localhost-only, origin validation, follows MCP security best practices

Automation Modes

Debugssy offers two modes to balance AI power with your control:

🔵 Assisted Mode (Default, Recommended)

Best for: Learning, understanding code, maintaining control

The AI helps you debug, but you stay in control:

• ✅ AI sets breakpoints and inspects variables
• ✅ AI analyzes and explains what it finds
• 🔵 You start debugging (F5 in VS Code)
• 🔵 You control execution (Click Continue, Step Over, etc. in VS Code UI)

Why? You see every step, understand the process, and maintain full situational awareness.

🚀 Full Automation Mode

Best for: Rapid iteration, experienced users, "vibe coding"

The AI does everything automatically:

• ✅ Everything from assisted mode
• ✅ AI starts debugging sessions
• ✅ AI controls execution (continue, step, pause)
• ✅ AI waits for breakpoints automatically

Enable in VS Code settings:

{
  "debugssy.automationLevel": "full"
}

Configuration

VS Code Settings

Access via File → Preferences → Settings (search "debugssy"):

{
  "debugssy.mcp.enabled": true,                    // Enable the MCP server
  "debugssy.mcp.port": 3000,                       // Server port
  "debugssy.automationLevel": "assisted",          // or "full"
  "debugssy.waitForBreakpointTimeout": 10000       // Timeout in ms
}

MCP Client Configuration

Recommended Allowlist (for Claude Desktop, Cursor, etc.):

Add these safe, read-only tools that won't modify your code:

{
  "mcpServers": {
    "debugssy": {
      "url": "http://localhost:3000/mcp",
      "allowlist": [
        "debugssy:get_debug_state",
        "debugssy:get_variables",
        "debugssy:get_call_stack",
        "debugssy:get_threads",
        "debugssy:list_breakpoints"
      ]
    }
  }
}

📋 Need more details? See ALLOWLIST_GUIDE.md for complete configuration examples.

Example Workflow

Assisted Mode (Default)

1. You tell AI: "This function returns wrong values"

2. AI: "Let me set a breakpoint and inspect..."
   → Sets breakpoint at function entry

3. You: Press F5 to start debugging in VS Code

4. You: Click "Continue" in VS Code debugger UI

5. AI: "Execution paused. I can see x=10, y=undefined"
   → Inspects variables and finds the issue

6. AI: "The problem is y is never assigned. You need to..."

7. You: Click "Stop" in VS Code when done

Full Automation Mode

1. You tell AI: "Debug this function automatically"

2. AI: "Starting automated debugging session..."
   → Automatically sets breakpoints
   → Starts debugging
   → Continues execution
   → Inspects variables at breakpoint
   → Steps through code
   → Analyzes and explains the issue
   → Stops debugging

3. AI: "Found it! The issue is on line 42 where..."

Security & Privacy

Debugssy is designed with security as a priority:

• 🔒 Localhost Only - Server binds exclusively to 127.0.0.1 (no network access)
• 🛡️ Origin Validation - Protects against DNS rebinding attacks
• 🔐 Secure Sessions - Cryptographically secure session IDs
• 🚫 No Remote Access - Cannot be accessed from other machines
• ✅ MCP Compliant - Follows MCP 2025-06-18 security best practices

📋 For security details: See MCP_COMPLIANCE.md

Available Tools

The AI assistant has access to these debugging tools:

🔍 Inspection Tools (Always Available)

• get_debug_state - Check if debugger is running/paused
• get_variables - Read variable values
• get_call_stack - See the call stack
• evaluate_expression - Evaluate expressions
• get_threads - List all threads

🔴 Breakpoint Tools (Always Available)

• set_breakpoint - Set breakpoints (with conditions, hit counts, log messages)
• remove_breakpoint - Remove specific breakpoint
• list_breakpoints - Show all breakpoints
• toggle_breakpoint - Enable/disable breakpoint
• remove_all_breakpoints - Clear all breakpoints

▶️ Execution Control

• stop_debugging - Stop session (always available)
• continue, step_over, step_into, step_out, pause, restart
  • Assisted mode: Not exposed (use VS Code UI)
  • Full mode: AI controls these automatically

🚀 Advanced (Full Mode Only)

• start_debugging - Start debug session programmatically
• wait_for_breakpoint - Wait for execution to pause

MCP Prompts (Debugging Workflows)

Debugssy provides structured debugging workflows that AI assistants can use:

• debug-crash - Debug crashes and exceptions
• trace-variable - Track where a variable becomes incorrect
• inspect-function - Examine function behavior
• debug-loop - Debug infinite loops or unexpected iterations
• auto-debug-session - Full automated debugging (full mode only)

💡 For AI Assistants: See DEBUGSSY_PROMPT.md for detailed guidance on using these workflows.

Requirements

• VS Code 1.85.0 or higher
• Node.js (for development/building)
• MCP-compatible AI assistant (Claude Desktop, Cursor, Copilot, or custom client)

Commands

Access these via Command Palette (Ctrl+Shift+P or Cmd+Shift+P):

• Debugssy: Start Server - Manually start the MCP server
• Debugssy: Stop Server - Stop the MCP server
• Debugssy: Restart Server - Restart the MCP server

Troubleshooting

"No active debug session" error

Solution: Start debugging in VS Code (press F5) before asking AI to inspect variables

Server won't start / Port in use

Solution: Change port in settings or stop process using port 3000

{ "debugssy.mcp.port": 3001 }

AI can't connect to server

Solution:

1. Check Output panel: View → Output → Debugssy
2. Verify server is running: curl http://localhost:3000/health
3. Check your AI assistant's MCP configuration

Variables not available

Solution:

1. Ensure execution is paused at a breakpoint
2. Try get_debug_state first to verify debugger state

Technical Details

┌─────────────────────────────────────┐
│   VS Code Extension (Debugssy)       │
│                                     │
│  ┌──────────────────────────────┐  │
│  │   MCP Server                 │  │
│  │   (Streamable HTTP)          │  │
│  │   Port: 3000                 │  │
│  └──────────────┬───────────────┘  │
│                 │                   │
│  ┌──────────────┴───────────────┐  │
│  │   Tool Registry              │  │
│  │   - Debug Control Tools      │  │
│  │   - Breakpoint Tools         │  │
│  │   - Inspection Tools         │  │
│  └──────────────┬───────────────┘  │
│                 │                   │
│  ┌──────────────┴───────────────┐  │
│  │   VS Code Debug API          │  │
│  │   + DAP Client               │  │
│  └──────────────────────────────┘  │
└─────────────────────────────────────┘
                 │
                 │ HTTP/MCP Protocol
                 │
        ┌────────▼────────┐
        │   MCP Client    │
        │ (AI Assistant)  │
        └─────────────────┘

# Health check
curl http://localhost:3000/health

# List tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';

const transport = new StreamableHTTPClientTransport(
  new URL('http://localhost:3000/mcp')
);

const client = new Client({
  name: 'my-client',
  version: '1.0.0'
});

await client.connect(transport);

// List available tools
const tools = await client.listTools();

// Call a tool
const result = await client.callTool({
  name: 'get_call_stack'
});

{
  "filePath": "/absolute/path/to/file.js",
  "line": 42,
  "condition": "x > 10",              // Optional
  "hitCondition": "> 5",              // Optional
  "logMessage": "Value: {x}"          // Optional (creates logpoint)
}

{
  "scope": "Local",                    // Optional: "Local", "Global", etc.
  "frameId": 0                         // Optional: defaults to current frame
}

{
  "expression": "x + y",
  "frameId": 0                         // Optional: defaults to current frame
}

{
  "name": "Launch Program",            // Name from launch.json
  "workspaceFolder": "myproject",      // Optional
  "configuration": { /* custom */ }    // Optional: full config object
}

{
  "timeout": 5000                      // Optional: ms (default: 10000)
}

1. Change debugssy.automationLevel in VS Code settings
2. Server detects change and restarts
3. New tool set becomes available
4. MCP clients reconnect automatically

Known Limitations

• Watch expressions not directly accessible (use evaluate_expression instead)
• Assumes thread ID 1 for some operations (simplified for single-threaded debugging)
• In assisted mode, AI cannot detect when you manually click continue/step (use get_debug_state to check)
• wait_for_breakpoint requires debug session to be running (call after continue in full mode)

Development

Building from Source

# Clone and install
git clone <repository>
cd debugssy
npm install

# Compile
npm run compile

# Run in development mode
# Press F5 in VS Code to open Extension Development Host

Project Structure

debugssy/
├── src/
│   ├── extension.ts              # Extension entry point
│   ├── mcpServer.ts              # MCP server with HTTP transport
│   ├── config.ts                 # Configuration management
│   ├── dap/
│   │   └── client.ts             # Debug Adapter Protocol client
│   └── tools/
│       ├── debugControl.ts       # Debug control tools
│       ├── breakpoints.ts        # Breakpoint management
│       ├── inspection.ts         # Variable inspection
│       └── index.ts              # Tool registry
├── example/
│   └── test.js                   # Example for testing
└── README.md                     # This file

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support This Project

If you find Debugssy helpful, consider supporting its development! Your contributions help maintain and improve the extension.

💝 Donate via PayPal

Every contribution, no matter how small, is greatly appreciated! 🙏

License

Copyright © 2025 Guillermo Garcia Maynez

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

Additional Resources

• 📋 ALLOWLIST_GUIDE.md - MCP client allowlist configuration examples
• 🔒 MCP_COMPLIANCE.md - Security implementation and MCP spec compliance
• 🤖 DEBUGSSY_PROMPT.md - Comprehensive guide for AI assistants
• 📝 COMPACT_PROMPT.txt - Quick AI assistant reference

External Links

• Model Context Protocol Specification
• VS Code Debug API
• Debug Adapter Protocol
• MCP TypeScript SDK