quickstart.md•4.86 kB
# Quickstart: Python Debugging MCP Tool
This guide shows how to use the tool locally via CLI or MCP protocol.
## Prerequisites
- Python 3.11+
- A Python project/script in the workspace
- For CLI usage: Install with `uv pip install -e ".[cli]"`
- For MCP usage: Install with `uv pip install -e .` (includes MCP SDK)
## CLI Usage (Recommended for Interactive Debugging)
### 1. Start a Session
```bash
# Basic usage
mcp-debug start-session src/main.py
# With arguments and environment variables
mcp-debug start-session tests/test.py --arg --verbose --arg --debug --env DEBUG=true --env LOG_LEVEL=info
# Get output in table format
mcp-debug start-session src/main.py --format table
```
### 2. Run to Breakpoint
```bash
# Set breakpoint and run (outputs JSON by default)
mcp-debug run-to-breakpoint session-abc123 src/main.py 15
# Table format shows locals clearly
mcp-debug run-to-breakpoint session-abc123 src/calculator.py 25 --format table
```
### 3. Continue to Next Breakpoint
```bash
# Continue execution to next breakpoint
mcp-debug continue session-abc123 src/main.py 42
# Table format
mcp-debug continue session-abc123 src/main.py 42 --format table
```
### 4. Check Session State
```bash
# Get current state
mcp-debug state session-abc123
# Table format
mcp-debug state session-abc123 --format table
```
### 5. End Session
```bash
mcp-debug end session-abc123
```
## MCP Protocol Usage (For AI Assistant Integration)
The tool uses the official MCP SDK with async support.
### MCP Server Configuration
Add to your MCP config file (e.g., `~/.config/mcp/settings.json`):
```json
{
"mcpServers": {
"python-debug": {
"command": "uv",
"args": ["run", "mcp-debug-server", "--workspace", "/path/to/your/project"],
"env": {"PYTHONUNBUFFERED": "1"}
}
}
}
```
### Available MCP Tools
The server exposes 5 tools via MCP protocol:
**1. sessions_create** - Start a new debug session
```json
{
"entry": "src/main.py",
"args": ["--flag"],
"env": {"FOO": "bar"},
"pythonPath": "/usr/bin/python3.11"
}
```
**2. sessions_breakpoint** - Run to breakpoint and capture locals
```json
{
"sessionId": "session-abc123",
"file": "src/main.py",
"line": 15
}
```
**3. sessions_continue** - Continue to next breakpoint
```json
{
"sessionId": "session-abc123",
"file": "src/main.py",
"line": 42
}
```
**4. sessions_state** - Get session state
```json
{
"sessionId": "session-abc123"
}
```
**5. sessions_end** - End a session
```json
{
"sessionId": "session-abc123"
}
```
### MCP Response Format
All tools return JSON via MCP `TextContent`:
```json
{
"type": "text",
"text": "{\"sessionId\": \"session-abc123\", ...}"
}
```
## API Usage (For LLM/MCP Integration)
### 1. Start a Session
```json
POST /sessions
{
"entry": "tests/integration/samples/buggy_script.py",
"args": ["--flag"],
"env": {"FOO": "bar"}
}
```
### 2. Run to a Breakpoint
```json
POST /sessions/{sessionId}/breakpoint
{
"file": "tests/integration/samples/buggy_script.py",
"line": 12
}
```
### 3. Inspect Local Variables
The response contains `locals` with type information:
```json
{
"hit": true,
"frameInfo": {"file": "buggy_script.py", "line": 12},
"locals": {
"x": {"type": "int", "repr": "10", "isTruncated": false},
"result": {"type": "float", "repr": "42.5", "isTruncated": false}
}
}
```
### 4. Continue to Next Breakpoint
```json
POST /sessions/{sessionId}/continue
{
"file": "tests/integration/samples/buggy_script.py",
"line": 25
}
```
### 5. End the Session
```json
DELETE /sessions/{sessionId}
```
## Common Workflows
### Debugging a Crash
```bash
# Start session
SESSION_ID=$(mcp-debug start-session src/app.py | jq -r .sessionId)
# Run to suspected crash location
mcp-debug run-to-breakpoint $SESSION_ID src/app.py 100 --format table
# Inspect locals, continue if needed
mcp-debug continue $SESSION_ID src/app.py 150 --format table
# End session
mcp-debug end $SESSION_ID
```
### Inspecting Function Behavior
```bash
# Start with arguments
SESSION_ID=$(mcp-debug start-session src/calculator.py --arg --verbose | jq -r .sessionId)
# Check input at function start
mcp-debug run-to-breakpoint $SESSION_ID src/calculator.py 10 --format table
# Check output before return
mcp-debug continue $SESSION_ID src/calculator.py 25 --format table
# Cleanup
mcp-debug end $SESSION_ID
```
## Notes
- **v1 Limitations**: Line breakpoints only; no conditional breakpoints or expression evaluation
- **Timeouts**: Default 20s per breakpoint; scripts exceeding this are terminated
- **Output Limits**: Max 10MB output capture per session
- **Interpreter**: Defaults to server's Python; override with `--python-path` (CLI) or `pythonPath` (API)
- **Format Options**:
- `json` (default): Machine-readable, best for scripting
- `table`: Human-readable, best for interactive debugging