Which integrations are available for this server?

Runs pytest tests safely via subprocess, extracts failure locations from test output, and provides code context around failures to help debug Python projects.

How do I use Debug Companion MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Debug Companion MCP debug the demo_project and show me the failing test" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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

uv sync

Run the MCP server

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:

debug_project(target="demo_project")

Expected output (example):

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.