🐛 Super Debugger

Servidor MCP para depurar código Python con IA — breakpoints, inspección de variables y ejecución paso a paso en tiempo real.

🤔 ¿Qué es Super Debugger?

Super Debugger es un servidor MCP (Model Context Protocol) que expone herramientas de depuración de Python a cualquier agente de IA compatible (Claude Desktop, Cursor, Cline, Continue, etc.).

En vez de que un LLM adivine la causa de un bug, Super Debugger le permite:

• Ejecutar el script y ver el traceback real

• Detenerse en breakpoints específicos

• Inspeccionar el valor de cada variable en vivo

• Avanzar la ejecución paso a paso

• Modificar el código y verificar el fix

Todo sin dependencias pesadas: no usa debugpy, ni DAP, ni pdb, ni PTYs. Solo sys.settrace de Python estándar.

Related MCP server: agentic-debugger

✨ Características

Valor único: inspección de variables en vivo sin re-ejecutar ni adivinar.

📦 Instalación

Requisitos

• Python 3.12 o superior

• uv (recomendado) o pip

Pasos

# 1. Clonar el repositorio
git clone https://github.com/ahernandezvega907-crypto/super-debugger.git
cd super-debugger

# 2. Crear el entorno virtual
uv venv --python 3.12

# 3. Activar el entorno
# En Windows:
.venv\Scripts\activate
# En macOS/Linux:
source .venv/bin/activate

# 4. Instalar dependencias
uv add fastmcp

# 5. Verificar que el servidor carga
python -c "from server import mcp; print('OK')"

🚀 Uso

Opción 1: Claude Desktop

Edita claude_desktop_config.json (ubicación por sistema operativo):

Agrega este bloque:

{
  "mcpServers": {
    "super-debugger": {
      "command": "python",
      "args": ["/ruta/absoluta/a/super-debugger/server.py"]
    }
  }
}

⚠️ Reemplaza la ruta con la ubicación real donde clonaste el repo:

• Windows: C:\\Users\\TuUsuario\\super-debugger\\server.py

• macOS/Linux: /Users/TuUsuario/super-debugger/server.py

Reinicia Claude Desktop. Verás el ícono 🔌 en el chat.

Opción 2: Cursor

Edita ~/.cursor/mcp.json (o %USERPROFILE%\.cursor\mcp.json en Windows):

{
  "mcpServers": {
    "super-debugger": {
      "command": "python",
      "args": ["/ruta/absoluta/a/super-debugger/server.py"]
    }
  }
}

⚠️ Reemplaza la ruta con la ubicación real donde clonaste el repo:

• Windows: C:\\Users\\TuUsuario\\super-debugger\\server.py

• macOS/Linux: /Users/TuUsuario/super-debugger/server.py

Reinicia Cursor y verás el servidor disponible en el chat.

Opción 3: Cline (VS Code)

Instala la extensión Cline desde el Marketplace y agrega el servidor desde su panel de configuración MCP.

Opción 4: MCP Inspector (para probar sin IDE)

npx -y @modelcontextprotocol/inspector python server.py

Abre http://localhost:5173 en el navegador.

🎬 Ejemplo de uso

Código con bug (test_target.py):

def promedio_positivos(numeros):
    suma = 0
    cantidad = 0
    for i in range(len(numeros) + 1):  # ← bug: +1 de más
        if numeros[i] > 0:
            suma += numeros[i]
            cantidad += 1
    return suma / cantidad

Lo que hace el agente:

1. run_script → detecta IndexError: list index out of range

2. read_file → lee el código con números de línea

3. debug_run con breakpoint en línea 5 → se detiene y muestra numeros=[4,-2,7,0,9], i=0

4. debug_continue → avanza y ve cómo i llega hasta 5 (fuera de rango)

5. write_file → corrige: range(len(numeros)) sin el +1

6. run_script → verifica: OK (exit 0) con el resultado correcto

Sin adivinar. Sin re-ejecuciones infinitas. Solo inspección en vivo.

🏗️ Arquitectura

Cliente MCP (Claude/Cursor/Cline)
        │ stdio (JSON-RPC)
        ▼
┌─────────────────────────┐
│  server.py (FastMCP)    │
│  9 herramientas         │
└───────────┬─────────────┘
            │ subprocess.PIPE
            ▼
┌─────────────────────────┐
│  debug_wrapper.py       │
│  sys.settrace           │
│  JSON por stdout        │
└─────────────────────────┘

Decisiones de diseño:

• Sin debugpy: la API DAP requiere un handshake de autenticación complejo que hace frágil la integración.

• Sin pdb: requiere TTY real, falla en subprocess.

• Sin PTY: los bugs de compatibilidad en Windows lo hacen poco fiable.

• sys.settrace: es la API oficial de Python, funciona igual en todos los sistemas.

🧪 Tests

# Test del backend de debug (offline, sin MCP)
python test_tools_offline.py

# Test del cliente debug
python test_debug.py

🛠️ Desarrollo

Estructura del proyecto

super-debugger/
├── server.py              # Servidor MCP (herramientas expuestas)
├── debug_client.py        # Cliente del wrapper
├── debug_wrapper.py       # Motor de depuración (sys.settrace)
├── agent.py               # (opcional) Agente autónomo con LangGraph
│                          #   requiere ANTHROPIC_API_KEY (no incluido en el MVP)
├── test_*.py              # Tests
├── pyproject.toml         # Dependencias
└── README.md              # Este archivo

Agregar nuevas herramientas

1. Define la función en server.py con el decorador @mcp.tool().

2. Documenta el parámetro Args: en el docstring.

3. Reinicia el cliente MCP para recargar.

🗺️ Roadmap

• MVP: 9 herramientas core

• Compatibilidad con MCP Inspector

• Soporte para breakpoints condicionales

• Soporte para debugging multi-hilo

• Publicación en VS Code Marketplace

• Agente autónomo con modelo local (Ollama)

🤝 Contribuir

Pull requests son bienvenidas. Para cambios importantes, abrí un issue primero para discutir qué te gustaría cambiar.

📄 Licencia

MIT — usalo libremente en proyectos personales y comerciales.

🙏 Agradecimientos

• FastMCP por el framework del servidor

• Model Context Protocol por el estándar

• Comunidad de Python por sys.settrace

Hecho con 🐍 y ☕ por Armando Hernández