USAGE.md•4.15 kB
# VSCode Debugger MCP Usage Guide
## Overview
This VSCode extension exposes debugging functionality through the Model Context Protocol (MCP), allowing AI agents to control VSCode's debugger programmatically.
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd vscode-debugger-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Compile the extension:
```bash
npm run compile
```
4. Install the extension in VSCode:
- Press `F5` to run in Extension Development Host, or
- Package as VSIX: `vsce package` and install manually
## Available MCP Tools
### 1. add_breakpoint
Adds a breakpoint to a specific file and line.
```json
{
"name": "add_breakpoint",
"arguments": {
"filePath": "/absolute/path/to/file.js",
"lineNumber": 10,
"condition": "x > 5" // optional
}
}
```
### 2. remove_breakpoint
Removes a breakpoint from a specific file and line.
```json
{
"name": "remove_breakpoint",
"arguments": {
"filePath": "/absolute/path/to/file.js",
"lineNumber": 10
}
}
```
### 3. start_debugging
Starts a debugging session with a specific configuration.
```json
{
"name": "start_debugging",
"arguments": {
"configurationName": "Launch Node.js Program", // optional
"workspaceFolderPath": "/path/to/workspace" // optional
}
}
```
### 4. stop_debugging
Stops the current or a specific debugging session.
```json
{
"name": "stop_debugging",
"arguments": {
"sessionId": "session-123" // optional
}
}
```
## AI Agent Usage Example
Here's how an AI agent might use these tools to debug an issue:
1. **Set breakpoints**: Add breakpoints at suspected problem areas
2. **Start debugging**: Launch the application in debug mode
3. **Analyze execution**: The debugger will pause at breakpoints
4. **Clean up**: Remove breakpoints and stop debugging when done
## Example Debugging Workflow
```javascript
// AI agent workflow for debugging a function
async function debugWorkflow() {
// 1. Add breakpoint at function entry
await mcpClient.callTool('add_breakpoint', {
filePath: '/project/src/calculator.js',
lineNumber: 15
});
// 2. Add conditional breakpoint for specific case
await mcpClient.callTool('add_breakpoint', {
filePath: '/project/src/calculator.js',
lineNumber: 25,
condition: 'result < 0'
});
// 3. Start debugging
await mcpClient.callTool('start_debugging', {
configurationName: 'Launch Calculator'
});
// 4. After analysis, clean up
await mcpClient.callTool('remove_breakpoint', {
filePath: '/project/src/calculator.js',
lineNumber: 15
});
await mcpClient.callTool('stop_debugging');
}
```
## 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"
}
]
}
```
## MCP Server Configuration
To connect AI agents to this extension, configure your MCP client:
```json
{
"mcpServers": {
"vscode-debugger": {
"command": "node",
"args": ["/path/to/extension/out/extension.js"]
}
}
}
```
## Troubleshooting
### Common Issues
1. **Breakpoints not working**: Ensure the file path is absolute and the file exists
2. **Debug configuration not found**: Check your `.vscode/launch.json` file
3. **MCP connection issues**: Verify the extension is running and MCP server is started
### Debug Logs
Enable debug logging by setting the environment variable:
```bash
export VSCODE_DEBUG_MODE=true
```
## Development
To contribute or modify the extension:
1. **Watch mode**: `npm run watch` for automatic compilation
2. **Testing**: Use the Extension Development Host (F5)
3. **Debugging**: Set breakpoints in the extension code itself
## Security Considerations
This extension provides powerful debugging capabilities. Ensure:
- Only trusted AI agents have access
- File paths are validated before use
- Debug sessions are properly cleaned up