polybugger-mcp: Instructions file for Codex

Python Debugger MCP

Project Overview

This is a Python MCP (Model Context Protocol) server that enables AI agents to debug Python code interactively. It translates MCP tool calls to DAP (Debug Adapter Protocol) messages for debugpy.

Tech Stack

• Language: Python 3.10+
• Framework: FastAPI with uvicorn, MCP SDK
• Debugger: debugpy (Python debugger)
• Testing: pytest with pytest-asyncio
• Package Manager: pip with pyproject.toml

Project Structure

src/polybugger_mcp/
  api/           # FastAPI routers (sessions, breakpoints, execution, inspection, output)
  adapters/      # DAP client and debugpy adapter
  core/          # Session management, events, exceptions
  models/        # Pydantic models (DAP, requests, responses)
  persistence/   # Breakpoint storage
  utils/         # Output buffer
  config.py      # Pydantic Settings configuration
  main.py        # FastAPI app entry point
  mcp_server.py  # MCP server with debug_* tools

tests/
  unit/          # Unit tests for buffer and persistence
  integration/   # API integration tests
  e2e/           # End-to-end debug session tests

Running the Project

# Activate virtual environment
source .venv/bin/activate

# Start the HTTP server
python -m polybugger_mcp.main

# Start the MCP server (stdio)
python -m polybugger_mcp.mcp_server

# Run tests
pytest tests/ -v

Debugging This Project

This project includes its own debugging tools as MCP tools.

Using the Debug Tools

1. Start the MCP server - Configure your MCP client to use:

   {
     "mcpServers": {
       "python-debugger": {
         "command": "uvx",
         "args": ["polybugger-mcp"]
       }
     }
   }
   

2. Use the debug_ tools* to debug Python code in this project:

   • debug_create_session - Create a session with project_root
   • debug_set_breakpoints - Set breakpoints in source files
   • debug_launch - Launch test scripts or the server itself
   • debug_get_stacktrace, debug_get_variables, debug_evaluate - Inspect state