DevGuard MCP

Serveur MCP (Model Context Protocol) qui booste le débogage backend FastAPI/Python et la qualité de code, pour n'importe quel agent : Cline, Claude Code, Cursor…

L'idée : au lieu de laisser l'agent deviner, on lui donne des outils déterministes qui rapportent des faits structurés (assertions échouées, traceback localisé, etc.).

Les 7 outils (v1 complète)

Outil	Pilier	Ce qu'il fait
run_pytest	Runtime	Lance pytest, renvoie échecs structurés (assertion + traceback localisé user vs lib).
call_endpoint	Runtime	Frappe un endpoint HTTP ; sur 422, erreurs de validation Pydantic champ par champ.
get_openapi_schema	Doc vérifiée	Synthétise /openapi.json : routes, params, modèle de corps (champs + requis), codes réponse.
parse_traceback	Runtime	Traceback brut → type, message, frames, cause probable (code utilisateur).
pack_debug_context	Contexte	Condense les fichiers d'un bug en un seul document (repomix, multi-langages) : vision holistique instantanée au lieu de longues navigations.
lint	Qualité	ruff en JSON : chaque violation avec code de règle + lien doc officielle + auto-fixable.
log_debug_note	Mémoire	Note une découverte de debug (anti-boucle) dans .devguard/journal.jsonl.
get_debug_notes	Mémoire	Relit les notes du projet (récentes d'abord, filtre par tag).

Boucle de débogage type

1. get_debug_notes — repartir de ce qui est déjà connu.
2. run_pytest / call_endpoint — voir l'échec réel (assertion, champ 422).
3. pack_debug_context(error_text=<le traceback>) — condenser les fichiers du bug en un seul document, pour saisir d'un coup comment ils s'articulent.
4. get_openapi_schema — connaître le contrat exact de l'endpoint (si API).
5. corriger, lint pour la qualité, re-run_pytest pour valider.
6. log_debug_note — consigner la cause pour la prochaine fois.

pack_debug_context est agnostique du langage (repomix + tree-sitter) : il marche sur du Python, JS/TS, Go, Java… même si les autres outils ciblent Python.

Forcer le "pack avant debug" (règle harness, pas MCP)

Un MCP ne peut pas forcer l'agent. Pour que le pack soit systématique, ajoute une règle côté client, ex. dans les règles Cline / CLAUDE.md :

« Avant de déboguer un problème touchant plusieurs fichiers, appelle d'abord pack_debug_context avec le traceback pour obtenir une vue consolidée. »

Installation (dev)

cd devguard-mcp
uv sync
uv run pytest          # tests du MCP lui-même

Brancher dans Cline

Dans les réglages MCP de Cline (cline_mcp_settings.json) :

{
  "mcpServers": {
    "devguard": {
      "command": "uv",
      "args": ["--directory", "D:/mcp/devguard-mcp", "run", "devguard-mcp"]
    }
  }
}

Puis l'agent peut appeler run_pytest(project_dir="D:/mon-projet-fastapi").

Brancher dans Claude Code

claude mcp add devguard -- uv --directory D:/mcp/devguard-mcp run devguard-mcp

Architecture

src/devguard/
  server.py        entrypoint MCP (enregistre les 7 outils)
  models.py        contrats Pydantic (retours structurés stricts)
  core/
    process.py     exécution sous-process robuste (timeout, utf-8)
    parsing.py     parsers traceback + JUnit XML pytest
  tools/
    debug.py       run_pytest
    api.py         call_endpoint + get_openapi_schema
    quality.py     lint (ruff)
    context.py     pack_debug_context (repomix)
    memory.py      journal de débogage

Prérequis

• Python ≥ 3.11, uv.
• Node + repomix (npm i -g repomix) pour pack_debug_context.

Développement

uv sync --extra dev
uv run pytest          # 25 tests
uv run python -m ruff check src/