# leadtech-bmad-mcp

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

Etat actuel : **prototype exploitable** pour un rollout advisory.

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

```bash
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 :

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

Quickstart complet :

- `docs/quickstart_dev_local.md`
- `docs/rollout_bmad_advisory.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 :

```bash
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)

```bash
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