# MCP Debugger Tools

VSCode extension that exposes debugging capabilities via Model Context Protocol (MCP), enabling AI agents to programmatically control VSCode's debugger.

## Features

The extension provides the following 4 MCP tools:

1. **add_breakpoint** - Add a breakpoint to a specific file and line number
2. **remove_breakpoint** - Remove a breakpoint from a specific file and line number  
3. **start_debugging** - Start debugging with a specific configuration
4. **stop_debugging** - Stop the current debugging session

## Installation & Setup

1. **Clone and build the extension:**
   ```bash
   git clone <repository-url>
   cd vscode-mcp-debugger
   npm install
   npm run compile
   ```

2. **Install the extension in VSCode:**
   - Press `F5` to run in Extension Development Host, or
   - Package as VSIX: `vsce package` and install manually

3. **Verify the MCP server is available:**
   - Open VSCode Command Palette (`Cmd+Shift+P`)
   - Run "MCP: List Servers"
   - You should see "MCP Debugger Tools" listed

4. **Enable in AI Chat:**
   - Open AI Chat in VSCode
   - Click the tools icon or type `/` to see available tools
   - You should see the 4 debugging tools available

## Usage with AI Agents

Once installed, AI agents can use these tools to:

- **Set breakpoints** in your code at specific lines
- **Start debugging sessions** using your launch configurations
- **Remove breakpoints** when no longer needed
- **Stop debugging** to clean up resources

### Communication Architecture

The extension uses a unique architecture to bridge the MCP protocol with VSCode's debugging APIs:

```
AI Agent → MCP Server → Temp File IPC → VSCode Extension → VSCode Debug API
             ↑                                    ↓
      JSON Response ← Response File ← Debug API Result
```

**How it works:**
1. **AI Agent** calls MCP tools (add_breakpoint, start_debugging, etc.)
2. **MCP Server** (standalone Node.js process) receives the tool calls
3. **File-based IPC** - Server writes command requests to temporary files
4. **VSCode Extension** monitors temp directory and processes commands
5. **VSCode Debug API** - Extension uses native VSCode debugging capabilities
6. **Response cycle** - Results flow back through the same IPC mechanism

This architecture ensures the MCP server runs independently while having full access to VSCode's debugging features.

### Example AI Agent Workflow

```
AI: I'll help you debug the issue in your calculator function.

1. First, let me add a breakpoint at the start of the function:
   [Uses add_breakpoint tool with filePath and lineNumber]

2. Now I'll start debugging with your launch configuration:
   [Uses start_debugging tool]

3. After analyzing the execution, I'll clean up:
   [Uses remove_breakpoint and stop_debugging tools]
```

## MCP Tools Reference

### add_breakpoint

**Description:** Add a breakpoint to a specific file and line number

**Parameters:**
- `filePath` (string, required): Absolute path to the file
- `lineNumber` (number, required): Line number (1-based)
- `condition` (string, optional): Conditional expression for the breakpoint

**Example:**
```json
{
  "filePath": "/path/to/your/file.js",
  "lineNumber": 25,
  "condition": "x > 10"
}
```

### remove_breakpoint

**Description:** Remove a breakpoint from a specific file and line number

**Parameters:**
- `filePath` (string, required): Absolute path to the file
- `lineNumber` (number, required): Line number (1-based)

**Example:**
```json
{
  "filePath": "/path/to/your/file.js",
  "lineNumber": 25
}
```

### start_debugging

**Description:** Start debugging with a specific configuration

**Parameters:**
- `configurationName` (string, optional): Name of the debug configuration to use
- `workspaceFolderPath` (string, optional): Path to the workspace folder

**Example:**
```json
{
  "configurationName": "Launch Node.js Program",
  "workspaceFolderPath": "/path/to/workspace"
}
```

### stop_debugging

**Description:** Stop the current debugging session

**Parameters:**
- `sessionId` (string, optional): Optional session ID to stop a specific session

**Example:**
```json
{
  "sessionId": "debug-session-123"
}
```

## Requirements

- **VSCode** with MCP support (latest version recommended)
- **Node.js** (v18+ for running the MCP server)
- **Project workspace** with debug configurations in `.vscode/launch.json`
- **Extension Development Host** (for development/testing)

## Supported Platforms

- ✅ **macOS** - Fully tested and supported
- ✅ **Linux** - Compatible with file-based IPC
- ✅ **Windows** - Should work with standard temp directory
- ⚠️ **WSL** - May require additional configuration for file permissions

## Debug Configuration Setup

Create a `.vscode/launch.json` file in your project:

```json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Launch Node.js Program",
      "type": "node",
      "request": "launch",
      "program": "${workspaceFolder}/src/index.js",
      "console": "integratedTerminal"
    }
  ]
}
```

## Development

### Building from Source

- **Install dependencies:** `npm install`
- **Compile TypeScript:** `npm run compile`
- **Watch for changes:** `npm run watch` for automatic compilation
- **Testing:** Use the Extension Development Host (F5)
- **Debugging:** Set breakpoints in the extension code itself

### Project Structure

```
src/
├── extension.ts          # Main extension entry point & MCP registration
├── debugBridge.ts        # VSCode Debug API wrapper
├── mcpServer.ts         # Standalone MCP server (stdio transport)
├── integratedMcpServer.ts # Alternative integrated server implementation
└── vscodeDebuggerMcp.ts  # Legacy server implementation
```

### Key Components

- **Extension.ts**: Registers MCP server definition, monitors IPC files
- **DebugBridge.ts**: Provides clean interface to VSCode debugging APIs
- **mcpServer.ts**: Standalone MCP server that communicates via file IPC
- **IPC System**: File-based communication between processes

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test with Extension Development Host
5. Submit a pull request

Please ensure all tools work correctly and add appropriate error handling.

## Troubleshooting

### Common Issues

1. **Tools not visible:** 
   - Check that MCP server is running via "MCP: List Servers"
   - Verify the extension is active in Extension Development Host
   - Look for "MCP Debugger Tools" in the MCP servers list

2. **Breakpoints not working:** 
   - Ensure file paths are absolute and files exist
   - Check that the file is currently open or can be opened in VSCode
   - Verify the line number is valid (1-based indexing)

3. **Debug config errors:** 
   - Verify `.vscode/launch.json` exists and is valid
   - Ensure the specified configuration name exists
   - Check that the workspace folder is correctly detected

4. **IPC communication issues:**
   - Check VSCode Developer Console for error messages
   - Verify temp directory permissions (the extension uses OS temp directory)
   - Look for MCP server stderr output in "MCP: List Servers" → Show Output

### Debug Mode

Enable detailed logging by checking the MCP server output:
1. Open Command Palette (`Cmd+Shift+P`)
2. Run "MCP: List Servers"
3. Select "MCP Debugger Tools"
4. Click "Show Output" to see server logs

### Technical Details

- **MCP Server Process**: Runs as standalone Node.js process via stdio transport
- **Extension Process**: Runs within VSCode extension host
- **IPC Mechanism**: Temporary JSON files in OS temp directory
- **Response Timeout**: 10 seconds (configurable in source code)
- **File Cleanup**: Automatic cleanup of temporary IPC files

## License

MIT