_Assistant_Lead_Tech/mcp/leadtech_bmad_mcp/README.md

leadtech-bmad-mcp

Serveur MCP sidecar pour brancher la base Lead_tech dans un workflow BMAD sans remplacer BMAD.

Etat actuel : Phase 2 partielle — 3 blocages stricts cibles actifs sur les workflows dev-story et create-story, advisory sur le reste. Voir docs/rollout_bmad_advisory.md.

Documents de référence phase 1 :

• docs/mcp_v1.md — contrat fonctionnel stable pour les tools/resources
• docs/knowledge_metadata.md — format de front matter pour knowledge/
• docs/implementation_plan.md — plan de chantier et checklist inter-sessions

Objectif

• BMAD garde l'orchestration (story, roles, statut, handoff).
• Ce serveur apporte des outils de guidance et de gate qualite.
• Ecriture controlee: uniquement 95_a_capitaliser.md et memoire projet (optionnel, avec flag).

Ce que le serveur fait bien aujourd'hui

• exposer la base Lead_tech en resources MCP lisibles par un agent
• retrouver les patterns/risques les plus probables pour une story
• utiliser un index local compile si disponible, avec fallback automatique sur le scan Markdown
• appliquer quelques gates transverses deja stabilises dans Lead_tech
• encapsuler la capitalisation dans un flux plus propre que l'edition manuelle

Ce qu'il ne faut pas lui demander pour l'instant

• remplacer la lecture humaine complete des docs prioritaires
• faire du ranking semantique avance
• ecrire directement dans knowledge/
• prendre la decision finale de merge, de done, ou de capitalisation

Tools exposes

• get_guidance(domain, task_type, story_text?, keywords?, max_items?)
• validate_plan(domain, plan_text, agent_role?, strict?)
• validate_patch(domain, diff_text, changed_files?, strict?)
• emit_checklist(agent_role, domain, story_text?)
• propose_capitalization(project_name, target_file, why, proposal, dry_run?)
• triage_capitalization(project_filter?, max_entries?)
• route_to_project_memory(project_name, section, content, dry_run?)

Resources exposees

• leadtech://index
• leadtech://capitalisation/pending
• leadtech://projects/conf
• leadtech://knowledge/{domain}/{bucket}/{slug}
• leadtech://global/architecture
• leadtech://global/debug
• leadtech://global/conventions

Design de securite

• lecture libre sur les fichiers Lead_tech exposes
• ecriture desactivee par defaut
• aucune ecriture autorisee dans knowledge/*
• ecriture conditionnelle uniquement sur :
  • 95_a_capitaliser.md
  • CLAUDE.md projet

Gates configurables

Les gates textuelles de validate_plan() et validate_patch() sont maintenant configurees dans :

• config/gates.yaml

Le serveur charge ce fichier au demarrage logique et peut etre pointe vers un autre chemin via :

• LEADTECH_GATES_CONFIG

Les regles purement structurelles qui ne sont pas basees sur du texte libre, comme changed_files avec uniquement _bmad-output/, restent codees a part.

Integration recommandee dans BMAD

1. Analyst Appeler get_guidance(...) a l'entree de story pour injecter patterns, risques et docs a lire.
2. Builder Appeler validate_plan(...) avant implementation puis validate_patch(...) apres generation du diff.
3. Reviewer Appeler emit_checklist(...) et, si besoin, relancer validate_patch(...) sur le diff final.
4. Curator Utiliser propose_capitalization(..., dry_run=true) puis triage_capitalization().

Installation locale

cd /srv/helpers/_Assistant_Lead_Tech/mcp/leadtech_bmad_mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

Pour le dev local avec tests :

pip install -e ".[dev]"
pytest tests -q

Quickstart complet :

• docs/quickstart_dev_local.md
• docs/rollout_bmad_advisory.md
• docs/pilot_bmad_10_stories.md

Rebuild de l'index local

Le MCP cherche d'abord un index JSON local a la racine de LEADTECH_ROOT :

• LEADTECH_ROOT/.leadtech_mcp_index.json

Pour le regenerer :

cd /srv/helpers/_Assistant_Lead_Tech/mcp/leadtech_bmad_mcp
source .venv/bin/activate
leadtech-bmad-build-index

Si le fichier est absent, invalide ou d'une autre version, le serveur retombe automatiquement sur le scan Markdown direct.

Lancement (stdio)

source .venv/bin/activate
export LEADTECH_ROOT=/srv/helpers/_Assistant_Lead_Tech
leadtech-bmad-mcp

Variables d'environnement

• LEADTECH_ROOT (defaut: /srv/helpers/_Assistant_Lead_Tech)
• LEADTECH_MCP_ALLOW_WRITE (defaut: 0)
  • mettre 1 pour autoriser l'ecriture dans 95_a_capitaliser.md et CLAUDE.md projet

Mode de branchement BMAD

Voir 80_bmad/integration_mcp_sidecar.md pour les points d'injection exacts dans le workflow.

Merge checklist recommandee

Avant de merger cette brique dans main :

• supprimer du repo les artefacts locaux (.venv, __pycache__, *.pyc)
• verifier l'installation sur une machine vierge avec pip install -e ".[dev]"
• lancer pytest tests -q
• confirmer que les tools/resources exposes sont bien ceux attendus par les prompts BMAD
• documenter la phase de rollout retenue : advisory only ou blocage sur blocking_issues

Upgrades conseilles

• metadonnees YAML/front matter dans knowledge/ pour fiabiliser le ranking
• schémas MCP formalises et versionnes pour chaque tool
• logs d'execution par story pour auditer les gates et la decision humaine
• suites de tests complementaires sur les faux positifs/faux negatifs des regex