Runs pytest tests safely via subprocess, extracts failure locations from test output, and provides code context around failures to help debug Python projects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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
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.
Related MCP server: MCP Code Checker
Python 3.12+
uv
uv syncuv run python server.pyGitHub Actions runs server tests on each push/PR:
workflow: .github/workflows/tests.yml
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
pytest runs with a timeout + output cap, and file access is restricted to the server root unless explicitly allowlisted via MCP_ALLOWED_ROOTS.
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/ — minimal demo with an intentional failing test (fast to understand)
GEMINI_API_KEY — enable Gemini analysis (optional)
MCP_ALLOWED_ROOTS — allow access to absolute paths outside the server root (optional)
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.
Inputs: error_message (required), code_context. Returns: result
Inputs: target (required), max_output_lines, timeout_seconds, failure_limit, +1 more. Returns: result
Inputs: pytest_output (required), limit, base_dir. Returns: result
Inputs: path (required), line (required), radius, base_dir. Returns: result
Inputs: no named parameters. Returns: result
Inputs: target, max_output_lines, timeout_seconds. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Most tools have distinct purposes: analyze_error_with_gemini focuses on error analysis using Gemini, debug_project handles general debugging, extract_failures isolates test failures, open_context manages context, ping checks connectivity, and run_pytest runs tests. However, debug_project and analyze_error_with_gemini could overlap in error-related tasks, causing minor confusion.
The naming is mixed: analyze_error_with_gemini and open_context use snake_case with descriptive names, while ping and run_pytest are simpler verbs. There's no consistent verb_noun pattern, but the names are readable and mostly action-oriented, albeit with some variation in style.
With 6 tools, this server is well-scoped for debugging and testing support. Each tool appears to serve a specific function in the debugging workflow, and the count is neither too sparse nor bloated, fitting typical MCP server ranges.
For a debugging companion, the tools cover key areas like error analysis, test execution, and context management. However, there are notable gaps: no tools for logging, monitoring, or step-through debugging, which could limit agent effectiveness in complex debugging scenarios.
Diagnose why an AI agent failed and get the verified fix instantly. Free, no token.
The bug mediator for AI-built apps: plain-English diagnosis + a ready fix, in your editor.
Shared debugging memory for AI coding agents
Direct access to Cypress tests results and accessibility reports in your AI workflow.
