# Debug Companion MCP (Pytest Debugging Agent)
Local MCP server that helps an AI coding agent debug Python projects by turning `pytest` failures into:
- Exact failure locations (`file:line`)
- A focused code context window around the failure
- Optional LLM suggestion (Gemini) for a fix
## Why this exists
When an agent gets a long pytest output, it often wastes time hunting for the real failure spot.
This server extracts the actionable bits and returns them in a structured, tool-friendly way.
## Requirements
- Python 3.12+
- uv
## Install
```bash
uv sync
```
## Run the MCP server
```bash
uv run python server.py
```
## CI
GitHub Actions runs server tests on each push/PR:
- workflow: `.github/workflows/tests.yml`
## Tools
- `ping` — health check
- `run_pytest(target, max_output_lines=200, timeout_seconds=30)` — run pytest safely (bounded output + timeout)
- `extract_failures(pytest_output, limit=5, base_dir=".")` — parse `file.py:line` locations from pytest output
- `open_context(path, line, radius=12, base_dir=".")` — return a code window around a line
- `debug_project(target, ...)` — orchestrates:
`run_pytest → extract_failures → open_context → (optional) Gemini analysis`
### Safety
pytest runs with a timeout + output cap, and file access is restricted to the server root unless explicitly allowlisted via `MCP_ALLOWED_ROOTS`.
## Quick demo
Run on the intentionally failing demo project:
```text
debug_project(target="demo_project")
```
Expected output (example):
```text
Failures:
- demo_project/test_calc.py:11 (test_divide_by_zero) — Failed: DID NOT RAISE ZeroDivisionError
Context (±12):
10 def test_divide_by_zero():
11 with pytest.raises(ZeroDivisionError):
12 _ = divide(10, 0)
```
## Demo project
- `demo_project/` — minimal demo with an intentional failing test (fast to understand)
## Environment variables
- `GEMINI_API_KEY` — enable Gemini analysis (optional)
- `MCP_ALLOWED_ROOTS` — allow access to absolute paths outside the server root (optional)
## Future work (ideas)
- **Test scaffolding (opt-in):** detect projects with no tests and optionally generate a minimal smoke test skeleton (e.g., `tests/test_smoke.py`) to validate imports / basic execution before running deeper debugging flows.
- **Richer failure parsing:** better extraction for parameterized tests and multi-traceback outputs.
- **Autofix loop:** apply a patch (manual approval) → re-run pytest → summarize diff + results.
> Note: Automatically generating meaningful tests is highly project-specific. The goal would be lightweight scaffolding (opt-in), not replacing real, requirement-driven tests.
