From ab4c5d408cdbc22a4f3d4c59f50183d97bd8f6ba Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Cl=C3=A9ment=20SAILLANT?= <108685187+electron-rare@users.noreply.github.com> Date: Sat, 7 Mar 2026 22:00:38 +0100 Subject: [PATCH] docs(mcp): clarify support matrix and canonical specs --- ai-agentic-embedded-base/specs/03_plan.md | 142 +++++++++++++-- ai-agentic-embedded-base/specs/README.md | 28 +-- .../specs/constraints.yaml | 2 +- .../specs/github_mcp_conversion_spec.md | 51 ++++++ .../specs/kicad_mcp_scope_spec.md | 31 ++-- ai-agentic-embedded-base/specs/mcp_tasks.md | 74 ++++++++ .../specs/notion_mcp_conversion_spec.md | 51 ++++++ .../zeroclaw_dual_hw_orchestration_spec.md | 102 +++++++++-- docs/MCP_ECOSYSTEM_MATRIX.md | 61 +++++++ docs/MCP_SETUP.md | 165 +++++++++++++----- docs/MCP_SUPPORT_MATRIX.md | 49 ++++++ docs/plans/15_plan_mcp_runtime_alignment.md | 90 +++++++--- docs/plans/15_plan_mcp_stack.md | 34 +--- docs/plans/15_todo_mcp_stack.md | 21 +-- docs/plans/README.md | 1 + specs/README.md | 28 +-- specs/github_mcp_conversion_spec.md | 51 ++++++ specs/kicad_mcp_scope_spec.md | 31 ++-- specs/mcp_tasks.md | 72 ++++++-- specs/notion_mcp_conversion_spec.md | 51 ++++++ 20 files changed, 942 insertions(+), 193 deletions(-) create mode 100644 ai-agentic-embedded-base/specs/github_mcp_conversion_spec.md create mode 100644 ai-agentic-embedded-base/specs/mcp_tasks.md create mode 100644 ai-agentic-embedded-base/specs/notion_mcp_conversion_spec.md create mode 100644 docs/MCP_ECOSYSTEM_MATRIX.md create mode 100644 docs/MCP_SUPPORT_MATRIX.md create mode 100644 specs/github_mcp_conversion_spec.md create mode 100644 specs/notion_mcp_conversion_spec.md diff --git a/ai-agentic-embedded-base/specs/03_plan.md b/ai-agentic-embedded-base/specs/03_plan.md index 97dc2fe..3811105 100644 --- a/ai-agentic-embedded-base/specs/03_plan.md +++ b/ai-agentic-embedded-base/specs/03_plan.md @@ -1,16 +1,134 @@ -# Easter Egg musique expérimentale +# Plan d'execution autonome local (RTC + Zacus) -_« Le plan du projet se transforme, comme un evidence pack modulé par Daphne Oram. »_ -# Plan +Last updated: 2026-02-21 -## Étapes -1) ... -2) ... +## Objectif -## Validation à chaque étape -- Build -- Tests -- Gates hardware (ERC/DRC) +Atteindre une boucle autonome locale stable sur les deux repos branches au hardware: -## Evidence pack -- artifacts/... +- `RTC_BL_PHONE` +- `le-mystere-professeur-zacus` + +avec: + +- stack ZeroClaw local operationnel (`3000`, `8788`, `9090`), +- dev/test reproductible sur chaque repo, +- preflight hardware systematique avant toute action firmware, +- traces et preuves dans `artifacts/zeroclaw/`. + +## Criteres de succes + +- `tools/ai/zeroclaw_stack_up.sh` lance gateway + follow + Prometheus (binary ou docker fallback). +- `http://127.0.0.1:8788/` affiche les conversations et logs en live. +- `http://127.0.0.1:9090/targets` est reachable (Prometheus up). +- `tools/ai/zeroclaw_dual_chat.sh rtc --provider-check` et `... zacus --provider-check` passent. +- Au moins une boucle dev/test complete par repo est executee et tracee. + +## Contraintes + +- Local only (loopback `127.0.0.1`), pas d'exposition publique. +- Secrets hors git (`~/.zeroclaw/env`, mode `600`). +- Cout modele borne par quotas webhook locaux. +- Flash/upload/serial monitor forces par defaut apres detection hardware valide. +- Jamais de commande `pio` sur un env non declare dans `platformio.ini`. + +## Plan par phases + +## Phase 0 - Preflight (auth + outils) + +Actions: + +1. Verifier `gh auth status`. +2. Verifier `zeroclaw auth status`. +3. Verifier `~/.zeroclaw/env` contient `OPENROUTER_API_KEY=...` et permissions `600`. +4. Verifier backend Prometheus local: + - binaire `prometheus`, sinon docker daemon. + +Sortie attendue: + +- environnement provider OK, +- fallback Prometheus disponible. + +## Phase 1 - Stack local ZeroClaw + +Actions: + +1. `tools/ai/zeroclaw_stack_down.sh` +2. `ZEROCLAW_PROM_MODE=auto tools/ai/zeroclaw_stack_up.sh` +3. Verifs: + - `curl -fsS http://127.0.0.1:3000/health` + - `curl -fsS http://127.0.0.1:8788/` + - `curl -fsS http://127.0.0.1:9090/-/ready` + +Sortie attendue: + +- gateway healthy, +- dashboard live actif, +- Prometheus ready. + +## Phase 2 - Boucle autonome RTC + +Actions: + +1. Provider check: `tools/ai/zeroclaw_dual_chat.sh rtc --provider-check` +2. Hardware discover: `tools/ai/zeroclaw_dual_chat.sh rtc --hardware` +3. Build/test firmware repo RTC: + - `cd /Users/cils/Documents/Lelectron_rare/RTC_BL_PHONE` + - `pio run -e esp32dev` + - `pio run -e esp32dev -t upload` + - `pio device monitor -p -b 115200` (capture 60s) + - ou commande unique: `tools/ai/zeroclaw_hw_firmware_loop.sh rtc` +4. Trace webhook: + - `tools/ai/zeroclaw_webhook_send.sh --repo-hint rtc "rtc loop status ..."` + +Sortie attendue: + +- build RTC passe ou echec documente avec logs, +- ligne JSONL enrichie pour la boucle RTC. + +## Phase 3 - Boucle autonome Zacus + +Actions: + +1. Provider check: `tools/ai/zeroclaw_dual_chat.sh zacus --provider-check` +2. Hardware discover: `tools/ai/zeroclaw_dual_chat.sh zacus --hardware` +3. Build/test firmware repo Zacus: + - `cd /Users/cils/Documents/Lelectron_rare/le-mystere-professeur-zacus/hardware/firmware` + - `pio run -e esp32dev` + - `pio run -e esp32dev -t upload` + - `pio device monitor -p -b 115200` (capture 60s) + - ou commande unique: `tools/ai/zeroclaw_hw_firmware_loop.sh zacus` + - statut tests: `blocked` tant que dossier `test/` absent +4. Trace webhook: + - `tools/ai/zeroclaw_webhook_send.sh --repo-hint zacus "zacus loop status ..."` + +Sortie attendue: + +- build Zacus passe ou echec documente avec logs, +- ligne JSONL enrichie pour la boucle Zacus. + +## Phase 4 - Stabilisation autonomie + +Actions: + +1. Dry-run budget: `tools/ai/zeroclaw_webhook_send.sh --dry-run "budget probe"` +2. Verifier quota state: `artifacts/zeroclaw/webhook_budget.json` +3. Verifier logs: + - `artifacts/zeroclaw/gateway.log` + - `artifacts/zeroclaw/conversations.jsonl` +4. Mettre a jour TODO (`specs/04_tasks.md` + `specs/zeroclaw_dual_hw_todo.md`). + +Sortie attendue: + +- boucles previsibles, +- cout controle, +- preuves a jour. + +## Cadence autonome quotidienne + +1. Preflight auth + hardware. +2. Stack up + smoke endpoints. +3. RTC loop (build + upload + monitor + webhook trace). +4. Zacus loop (build + upload + monitor + webhook trace). +5. Review logs + correction ciblée. +6. Commit/PR petit lot. diff --git a/ai-agentic-embedded-base/specs/README.md b/ai-agentic-embedded-base/specs/README.md index a54e8aa..2372839 100644 --- a/ai-agentic-embedded-base/specs/README.md +++ b/ai-agentic-embedded-base/specs/README.md @@ -1,25 +1,29 @@ # Specs (Spec-driven) -Flux conseillé (itératif) : -1) `00_intake.md` : idée brute + contexte +Flux conseille (iteratif) : +1) `00_intake.md` : idee brute + contexte 2) `01_spec.md` : spec claire + AC 3) `02_arch.md` : architecture + ADR -4) `03_plan.md` : plan découpé, risques, validations -5) `04_tasks.md` : backlog exécutable (issues / PRs) -6) Implémentation (firmware/hardware) + tests + doc +4) `03_plan.md` : plan decoupe, risques, validations +5) `04_tasks.md` : backlog executable (issues / PRs) +6) Implementation (firmware/hardware) + tests + doc -Le fichier `constraints.yaml` est la **source de vérité** des contraintes non-fonctionnelles et règles repo. +Le fichier `constraints.yaml` est la **source de verite** des contraintes non-fonctionnelles et regles repo. -Specs complémentaires: +Specs complementaires: +- `github_mcp_conversion_spec.md`: prep de conversion de `workflow_dispatch` vers une surface MCP future. - `kicad_mcp_scope_spec.md`: perimetre fonctionnel, hors scope et criteres d'acceptation du MCP KiCad supporte. -- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double matériel. -- `zeroclaw_dual_hw_todo.md`: backlog opérationnel court terme pour autonomie contrôlée. +- `mcp_tasks.md`: backlog canonique des actions MCP locales, partage entre runtime, doc et gouvernance. +- `notion_mcp_conversion_spec.md`: prep de conversion du bridge Notion actuel vers une surface MCP future. +- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double materiel. +- `zeroclaw_dual_hw_todo.md`: backlog operationnel court terme pour autonomie controlee. Synchronisation `spec_kit`: -- `specs/` (racine repo) et `ai-agentic-embedded-base/specs/` doivent rester alignés. -- Après toute mise à jour, synchroniser avec: +- `specs/` (racine repo) est la source de verite canonique. +- `ai-agentic-embedded-base/specs/` est un miroir exporte. +- Apres toute mise a jour canonique, synchroniser le miroir avec: - `rsync -a --delete specs/ ai-agentic-embedded-base/specs/` -- Vérifier l'absence d'écart avec: +- Verifier l'absence d'ecart avec: - `diff -ru ai-agentic-embedded-base/specs specs` diff --git a/ai-agentic-embedded-base/specs/constraints.yaml b/ai-agentic-embedded-base/specs/constraints.yaml index a58fbf7..3e05918 100644 --- a/ai-agentic-embedded-base/specs/constraints.yaml +++ b/ai-agentic-embedded-base/specs/constraints.yaml @@ -4,7 +4,7 @@ project: targets: - esp32s3 - esp32 - - native + - esp32dev ai: triggers: diff --git a/ai-agentic-embedded-base/specs/github_mcp_conversion_spec.md b/ai-agentic-embedded-base/specs/github_mcp_conversion_spec.md new file mode 100644 index 0000000..e9b0b1c --- /dev/null +++ b/ai-agentic-embedded-base/specs/github_mcp_conversion_spec.md @@ -0,0 +1,51 @@ +# Spec conversion MCP GitHub dispatch + +Last updated: 2026-03-07 + +## Objectif + +Documenter l'implémentation MCP `github-dispatch` à partir de l'intégration `workflow_dispatch` existante, sans remplacer la voie API existante en V1. + +## État actuel + +- backend réel dans `mascarade/api/src/lib/killlife.ts` et `crazy_life/api/src/lib/killlife.ts` +- dépendance secrète: `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` +- contrôle de sécurité actuel: + - allowlist de workflows + - sanitation des clés d'input + - repo et ref par défaut contrôlés + +## Surface MCP implémentée + +Serveur MCP `github-dispatch` local avec les outils: + +- `list_allowlisted_workflows` +- `dispatch_workflow` +- `get_dispatch_status` + +## Mapping depuis l'existant + +- config allowlist actuelle -> `list_allowlisted_workflows` +- `POST /repos/:repo/actions/workflows/:workflow/dispatches` -> `dispatch_workflow` +- suivi de run et réconciliation locale -> `get_dispatch_status` + +## Contraintes + +- garder `stdio` comme transport par défaut +- interdire tout dispatch hors allowlist +- ne pas exposer de surface générique GitHub issue/PR/repo en V1 +- conserver l'API actuelle tant que les éditeurs de workflow ne consomment pas MCP +- launcher opérateur: `tools/run_github_dispatch_mcp.sh` + +## Hors scope V1 + +- gestion générique GitHub +- mutation libre d'issues, PR, labels ou releases +- changement dynamique du repo cible hors politique versionnée + +## Validation minimale + +- handshake `initialize -> tools/list` vert +- `dispatch_workflow` refuse un workflow non allowlisté +- erreur structurée si token absent +- `get_dispatch_status` retourne un état exploitable sans lecture manuelle brute de l'API GitHub diff --git a/ai-agentic-embedded-base/specs/kicad_mcp_scope_spec.md b/ai-agentic-embedded-base/specs/kicad_mcp_scope_spec.md index 8d4b294..98c95c4 100644 --- a/ai-agentic-embedded-base/specs/kicad_mcp_scope_spec.md +++ b/ai-agentic-embedded-base/specs/kicad_mcp_scope_spec.md @@ -6,7 +6,7 @@ Last updated: 2026-03-07 - O1. Definir le perimetre fonctionnel du serveur MCP KiCad supporte par `Kill_LIFE`. - O2. Eviter la derive entre implementation serveur, launcher local, docs et attentes des agents. -- O3. Fixer une frontiere claire entre ce que le MCP KiCad MUST couvrir en v1, ce qui SHOULD venir en v2, et ce qui reste hors scope. +- O3. Fixer une frontiere claire entre le contrat stable du MCP KiCad, les extensions futures legitimes et ce qui reste hors scope. ## Non-objectifs @@ -34,6 +34,7 @@ Last updated: 2026-03-07 - Le serveur MUST exposer `stdio` local uniquement. - Le serveur MUST parler JSON-RPC compatible MCP avec framing ligne par ligne, conforme au SDK utilise. - Le serveur MUST fonctionner via `tools/hw/run_kicad_mcp.sh`. + - Le serveur MUST exposer une seule surface stable; aucun profil runtime alternatif ne doit etre requis. - F2. Cycle projet - Le serveur MUST permettre de creer, ouvrir, sauvegarder et inspecter un projet KiCad. @@ -68,7 +69,13 @@ Last updated: 2026-03-07 - Le serveur SHOULD permettre la recherche de composants JLCPCB/LCSC, les alternatives proches et l'acces aux datasheets. - Les integrations de sourcing MAY utiliser un backend local ou une API externe si les credentials sont presents. -- F10. Runtime +- F10. Resources / prompts / UI + - Le serveur MUST exposer `tools`, `resources` et `prompts` comme surface stable unique. + - Toute resource exposee MUST correspondre a un backend reel et testable. + - Les prompts MUST referencer uniquement des capabilities supportees. + - Les actions UI supportees MUST retourner un resultat deterministe ou une erreur structuree quand le contexte graphique est indisponible. + +- F11. Runtime - Le serveur MUST preferer un backend KiCad reel. - Le backend SHOULD preferer IPC quand disponible. - Le backend MUST pouvoir retomber sur SWIG si IPC n'est pas disponible. @@ -82,7 +89,7 @@ Last updated: 2026-03-07 - Le serveur MUST NOT exiger de secrets pour les usages locaux de base. - Fiabilite - - `initialize` puis `tools/list` MUST passer sur une machine supportee. + - `initialize`, `tools/list`, `resources/list` et `prompts/list` MUST passer sur une machine supportee. - Le launcher MUST gerer le fallback host -> container quand l'hote n'expose pas `pcbnew`. - Les erreurs MUST etre actionnables et non silencieuses. @@ -99,13 +106,13 @@ Last updated: 2026-03-07 - Le contrat de transport MUST rester stable pour les consommateurs locaux de `Kill_LIFE`. - Le runtime conteneur supporte SHOULD rester aligne avec la version KiCad cible du projet, y compris la trajectoire v10. -## V2 / extensions legitimes +## Extensions futures legitimes -- V2.1. Session IPC plus riche, synchronisee avec une UI KiCad vivante. -- V2.2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs. -- V2.3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation. -- V2.4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite. -- V2.5. Dry-run systematique pour les mutations a fort impact. +- E1. Session IPC plus riche, synchronisee avec une UI KiCad vivante. +- E2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs. +- E3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation. +- E4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite. +- E5. Dry-run systematique pour les mutations a fort impact. ## Hors scope @@ -125,11 +132,15 @@ Last updated: 2026-03-07 - `initialize` - `notifications/initialized` - `tools/list` + - `resources/list` + - `prompts/list` + - `resources/read` sur au moins une resource stable + - `prompts/get` sur au moins un prompt stable ## Critieres d'acceptation - AC1. Le repo documente un seul serveur KiCad MCP supporte en v1. -- AC2. Le serveur expose au moins une famille d'outils fonctionnelle pour: projet, schema, PCB, librairies, validation, export. +- AC2. Le serveur expose une surface stable fonctionnelle pour: projet, schema, PCB, librairies, validation, export, resources, prompts et sourcing. - AC3. `python3 tools/hw/mcp_smoke.py` passe sur un environnement supporte. - AC4. En absence de `pcbnew` host, le launcher supporte bascule vers le runtime conteneur. - AC5. La doc d'usage locale renvoie explicitement vers cette spec de perimetre. diff --git a/ai-agentic-embedded-base/specs/mcp_tasks.md b/ai-agentic-embedded-base/specs/mcp_tasks.md new file mode 100644 index 0000000..a6d20ca --- /dev/null +++ b/ai-agentic-embedded-base/specs/mcp_tasks.md @@ -0,0 +1,74 @@ +# Tasks MCP local + +Last updated: 2026-03-07 + +Backlog MCP canonique pour `Kill_LIFE`. + +Références: + +- doc opérateur: `docs/MCP_SETUP.md` +- matrice de support: `docs/MCP_SUPPORT_MATRIX.md` +- spec de périmètre: `specs/kicad_mcp_scope_spec.md` + +Format: + +- `[ ]` non fait +- `[x]` fait + +## État courant + +- [x] K-001 — Rendre `validate-specs` réel + - AC: `mcp.json` ne référence plus de chemin absent. + +- [x] K-002 — Ajouter un launcher KiCad supporté + - AC: `tools/hw/run_kicad_mcp.sh` résout `mascarade`, prépare un runtime writable et exécute le serveur. + +- [x] K-003 — Aligner `tools/hw/cad_stack.sh mcp` + - AC: l'alias opérateur appelle le même launcher que `mcp.json`. + +- [x] K-004 — Fixer une doc opérateur canonique + - AC: `docs/MCP_SETUP.md` décrit le chemin réellement supporté. + +- [x] K-005 — Fixer une spec de périmètre canonique + - AC: `specs/kicad_mcp_scope_spec.md` décrit le contrat MCP KiCad supporté. + +- [x] K-006 — Fixer une matrice de support canonique + - AC: `docs/MCP_SUPPORT_MATRIX.md` classe explicitement les surfaces supportées et les chemins hors chaîne supportée. + +- [x] K-007 — Ajouter un smoke test consommateur versionné + - AC: `python3 tools/hw/mcp_smoke.py --timeout 30` passe sur un environnement supporté. + +- [x] K-008 — Documenter les prérequis machine utiles + - AC: `docs/MCP_SETUP.md` documente `node`, Docker, le repo compagnon et le fallback hôte -> conteneur. + +- [x] K-009 — Décider du sort du chemin `cad_stack.sh mcp` + - AC: ce n'est plus un chemin legacy, mais un alias supporté du launcher canonique. + +## À faire ensuite + +- [x] K-010 — Aligner la matrice de protocoles MCP + - AC: le runtime KiCad principal, `validate-specs` et les micro-serveurs auxiliaires exposent une compatibilité documentée et non contradictoire. + +- [x] K-011 — Ajouter une observabilité MCP synthétique + - AC: un état `ready / degraded / failed` est visible sans lecture manuelle des logs. + +- [ ] K-012 — Rejouer la validation host-native sur une machine avec `pcbnew` + - AC: le smoke passe aussi sur le chemin hôte, pas seulement via le fallback conteneur. + +- [x] K-013 — Décider du statut final des micro-serveurs `kicad_kic_ai` + - AC: `component_database`, `kicad_tools` et `nexar_api` sont explicitement promus en surfaces auxiliaires supportées. + +- [ ] K-014 — Valider le mode live de `nexar_api` + - AC: un run avec `NEXAR_TOKEN` confirme le comportement réel et le distingue du mode démo. + +- [x] K-015 — Implémenter le MCP `Notion` + - AC: `tools/run_notion_mcp.sh` expose `search_pages`, `read_page`, `append_to_page`, `create_page` sans retirer le bridge HTTP en V1. + +- [x] K-016 — Implémenter le MCP `GitHub dispatch` + - AC: `tools/run_github_dispatch_mcp.sh` expose `list_allowlisted_workflows`, `dispatch_workflow` et `get_dispatch_status` sans retirer la voie API actuelle en V1. + +- [x] K-017 — Ajouter des smokes MCP dedies hors KiCad + - AC: `validate-specs`, `notion` et `github-dispatch` ont chacun un smoke versionne avec sortie JSON. + +- [x] K-018 — Etendre l'observabilite MCP a plusieurs serveurs + - AC: `/api/ops/summary` expose un etat agrege et le detail par serveur pour `kicad`, `validate-specs`, `notion` et `github-dispatch`. diff --git a/ai-agentic-embedded-base/specs/notion_mcp_conversion_spec.md b/ai-agentic-embedded-base/specs/notion_mcp_conversion_spec.md new file mode 100644 index 0000000..3fde2e8 --- /dev/null +++ b/ai-agentic-embedded-base/specs/notion_mcp_conversion_spec.md @@ -0,0 +1,51 @@ +# Spec conversion MCP Notion + +Last updated: 2026-03-07 + +## Objectif + +Documenter l'implémentation MCP `notion` à partir de l'intégration `Notion` existante, sans remplacer la voie HTTP existante en V1. + +## État actuel + +- backend réel dans `mascarade/core/mascarade/integrations/notion.py` +- bridge HTTP existant dans `mascarade/api/src/routes/notion.ts` +- UI consommatrice existante dans `crazy_life/src/pages/NotionBrowser.tsx` +- dépendance secrète: `NOTION_API_KEY` + +## Surface MCP implémentée + +Serveur MCP `notion` local avec les outils: + +- `search_pages` +- `read_page` +- `append_to_page` +- `create_page` + +## Mapping depuis l'existant + +- `GET /api/notion/search` -> `search_pages` +- `GET /api/notion/pages/:pageId` -> `read_page` +- `POST /api/notion/pages/:pageId/append` -> `append_to_page` +- `POST /api/notion/pages` -> `create_page` + +## Contraintes + +- garder `stdio` comme transport par défaut +- ne pas exposer un MCP réseau en V1 +- erreurs explicites si `NOTION_API_KEY` absent +- conserver le bridge HTTP existant tant que la migration client n'est pas faite +- launcher opérateur: `tools/run_notion_mcp.sh` + +## Hors scope V1 + +- suppression du bridge HTTP existant +- édition riche avancée ou gestion fine des blocs Notion +- sync bidirectionnelle UI <-> MCP + +## Validation minimale + +- handshake `initialize -> tools/list` vert +- `search_pages` et `read_page` smokés +- erreur structurée et non ambiguë si `NOTION_API_KEY` absent +- documentation opérateur et matrice de support mises à jour diff --git a/ai-agentic-embedded-base/specs/zeroclaw_dual_hw_orchestration_spec.md b/ai-agentic-embedded-base/specs/zeroclaw_dual_hw_orchestration_spec.md index b4676ce..8d291f3 100644 --- a/ai-agentic-embedded-base/specs/zeroclaw_dual_hw_orchestration_spec.md +++ b/ai-agentic-embedded-base/specs/zeroclaw_dual_hw_orchestration_spec.md @@ -9,7 +9,7 @@ Run one orchestration layer that can: - converse against `RTC_BL_PHONE` and `le-mystere-professeur-zacus` independently, - keep workspace boundaries strict per repo, - run low-cost autonomous loops with guarded command allowlists, -- stay ready for connected hardware checks before any upload/flash action. +- enforce upload/flash/serial-monitor loops by default on connected hardware. ## 2) Scope @@ -18,6 +18,7 @@ In scope: - local ZeroClaw profile bootstrap for both repos, - deterministic workspace switch (`rtc` vs `zacus`) from one CLI entrypoint, - hardware discovery/introspection preflight, +- forced-by-default firmware loop (build + upload + monitor) per repo target, - lightweight CI validation for orchestration scripts/spec. Out of scope: @@ -64,23 +65,57 @@ This keeps `autonomy.workspace_only = true` effective on a per-repo boundary. - `tools/ai/zeroclaw_dual_chat.sh` - target switch by alias (`rtc`, `zacus`) or absolute path, - message mode (`-m`) or interactive mode, - - provider auto-fallback (`copilot` -> `openai-codex` -> `openrouter`), + - `--cheap` mode to prefer local provider routing for low-credit runs, + - loads local auth env file `~/.zeroclaw/env` when present, + - provider auto-fallback (`ollama` when local preferred -> `copilot` -> `openai-codex` -> `gemini` -> `openrouter` -> `anthropic` -> `openai`), - token sourcing from `gh auth token` at runtime only when `copilot` is selected. - `tools/ai/zeroclaw_stack_up.sh` - starts local gateway and local follow server, - reuses existing listeners when ports are already bound (prevents duplicate-start failures), + - loads local auth env file `~/.zeroclaw/env` when present, + - auto-aligns gateway provider/model for autonomous cost control: + - default uses `openai-codex` when auth profile exists (reliable baseline), + - optionally prefers local `ollama` when `ZEROCLAW_PREFER_LOCAL_AI=1`, + - otherwise uses `openrouter` when API key exists, + - writes reliability fallback chain in config (`ollama -> openai-codex -> openrouter` when available), + - attempts automatic gateway pairing and token refresh, + - validates bearer token with a malformed webhook probe (`{}` payload) and re-pairs when possible, - generates live follow dashboard at `http://127.0.0.1:8788/`, - dashboard includes live polling panels for `/conversations.jsonl` and `/gateway.log` (1s polling), - preserves direct raw links: `/conversations.jsonl` and `/gateway.log`, + - starts `tools/ai/zeroclaw_watch_1min.sh` watcher and exposes `/realtime_1min.log`, - writes `artifacts/zeroclaw/prometheus.yml` scrape config, - - supports local Prometheus startup via `ZEROCLAW_PROM_MODE` (`off`, `auto`, `binary`, `docker`), + - supports local Prometheus startup via `ZEROCLAW_PROM_MODE` (`off`, `auto`, `binary`, `docker`) with `auto` fallback `binary -> docker`, + - on macOS, auto-attempts Docker Desktop startup before Prometheus docker mode, - stores pair token in `artifacts/zeroclaw/pair_token.txt`. - `tools/ai/zeroclaw_stack_down.sh` - stops local gateway/follow processes, - stops local Prometheus process/container if managed by the stack, + - stops `tools/ai/zeroclaw_watch_1min.sh` watcher process, - confirms logs remain in `artifacts/zeroclaw/`. +- `tools/ai/zeroclaw_watch_1min.sh` + - supports `start|stop|status|run|once`, + - appends one status line every 60s by default to `artifacts/zeroclaw/realtime_1min.log`, + - line format: + - ` | paired=<...> | uptime=<...> | prom=<...> | convo= | gateway=` +- `tools/ai/zeroclaw_hw_firmware_loop.sh` + - target switch `rtc|zacus`, + - validates `platformio.ini` env exists before running, + - forces `build -> upload -> serial monitor` by default, + - auto-retries with a compatible env when chip mismatch is detected (`ESP32` vs `ESP32-S3`), + - auto-detects serial port when not specified, + - on macOS, wraps monitor with `script` pseudo-TTY to avoid `termios` non-interactive failures, + - monitor timeout default 60s. +- `tools/ai/ollama_local_setup.sh` + - installs `ollama` via Homebrew when missing, + - starts local service, + - optionally pulls/warms a local model, + - prints zero-credit defaults for stack usage. - `tools/ai/zeroclaw_webhook_send.sh` - - requires `--allow-model-call` before any real webhook send, + - sends webhook by default (no mandatory allow flag), + - keeps `--allow-model-call` as backward-compatible legacy option, + - supports `--dry-run` to validate payload/limits without network send, + - enforces autonomous local quotas with `artifacts/zeroclaw/webhook_budget.json`, - supports `--repo-hint ` metadata tagging, - appends enriched JSONL traces to `artifacts/zeroclaw/conversations.jsonl`. @@ -89,9 +124,19 @@ This keeps `autonomy.workspace_only = true` effective on a per-repo boundary. Auto provider selection order in `zeroclaw_dual_chat.sh`: 1. explicit `ZEROCLAW_PROVIDER` override, -2. `copilot` when `gh` auth is valid and Copilot billing endpoint is accessible, -3. `openai-codex` when a ZeroClaw auth profile exists, -4. `openrouter` when `OPENROUTER_API_KEY` is present. +2. `ollama` when `ZEROCLAW_PREFER_LOCAL_AI=1` and local model is available, +3. `copilot` when `gh` auth is valid and Copilot billing endpoint is accessible, +4. `openai-codex` when a ZeroClaw auth profile exists, +5. `gemini` when `GEMINI_API_KEY`/`GOOGLE_API_KEY` is present, +6. `openrouter` when `OPENROUTER_API_KEY` is present, +7. `anthropic` when `ANTHROPIC_API_KEY`/`ANTHROPIC_OAUTH_TOKEN` is present, +8. `openai` when `OPENAI_API_KEY` is present. + +Gateway bootstrap provider order in `zeroclaw_stack_up.sh`: + +1. `openai-codex` when auth profile exists (default mode), +2. `openrouter` when `OPENROUTER_API_KEY` exists, +3. `ollama` only when `ZEROCLAW_PREFER_LOCAL_AI=1` and local model is available. Observed on current machine: @@ -140,6 +185,7 @@ Raw URLs: - `http://127.0.0.1:8788/conversations.jsonl` - `http://127.0.0.1:8788/gateway.log` +- `http://127.0.0.1:8788/realtime_1min.log` - `http://127.0.0.1:8788/prometheus.yml` Conversation JSONL line schema (append-only): @@ -155,22 +201,58 @@ Compatibility rule: - viewer tolerates legacy lines that only contain `ts`, `message`, `response_raw`. -Credit-protection rule: +Webhook execution and cost controls: -- without `--allow-model-call`, `zeroclaw_webhook_send.sh` exits non-zero and does not send/write logs. +- webhook send is enabled by default. +- `--dry-run` performs validation only (no network call, no execution log append). +- hourly quota and message-size limits are enforced by environment variables: + - `ZEROCLAW_WEBHOOK_MAX_CALLS_PER_HOUR` (default: `40`) + - `ZEROCLAW_WEBHOOK_MAX_CHARS` (default: `1200`) +- quota state is stored in `artifacts/zeroclaw/webhook_budget.json`. ## 9) Prometheus Integration Economical default: -- `ZEROCLAW_PROM_MODE=auto` (start only if local `prometheus` binary exists) +- `ZEROCLAW_PROM_MODE=auto` (try local `prometheus` binary first, then Docker fallback) Optional modes: - `ZEROCLAW_PROM_MODE=off` disables Prometheus startup - `ZEROCLAW_PROM_MODE=binary` requires local `prometheus` binary - `ZEROCLAW_PROM_MODE=docker` runs `prom/prometheus:latest` locally +- `ZEROCLAW_DOCKER_WAIT_SECS` controls Docker daemon wait timeout (default: `90`) +- `ZEROCLAW_PROM_READY_WAIT_SECS` controls Prometheus readiness wait (default: `15`) Default local endpoint when running: - `http://127.0.0.1:9090/targets` + +## 10) Local Auth Bootstrap + +Recommended local secret file: + +- `~/.zeroclaw/env` (permissions `600`) + +Suggested contents: + +- `OPENROUTER_API_KEY=...` + +Behavior: + +- `zeroclaw_dual_chat.sh`, `zeroclaw_stack_up.sh`, and `zeroclaw_webhook_send.sh` auto-load this file if present. + +## 11) Firmware Loop Defaults (local hardware) + +Default execution policy: + +- with hardware connected, upload/flash and serial monitor are forced by default. +- if no serial port is detected, loop fails fast (non-zero) instead of silently skipping upload. +- only declared PlatformIO envs are allowed; no `-e native` or `-e test` shortcuts. + +Default commands: + +- RTC: + - `tools/ai/zeroclaw_hw_firmware_loop.sh rtc` +- Zacus: + - `tools/ai/zeroclaw_hw_firmware_loop.sh zacus` diff --git a/docs/MCP_ECOSYSTEM_MATRIX.md b/docs/MCP_ECOSYSTEM_MATRIX.md new file mode 100644 index 0000000..54a6676 --- /dev/null +++ b/docs/MCP_ECOSYSTEM_MATRIX.md @@ -0,0 +1,61 @@ +# MCP ecosystem matrix + +Last updated: 2026-03-07 + +Matrice transverse des surfaces MCP et non-MCP observees dans `Kill_LIFE`, `mascarade` et `crazy_life`. + +## Statuts + +- `supporte`: surface active ou officiellement maintenue dans le workspace +- `supporte avec dependance externe`: surface maintenue mais dependante d'un autre repo, d'un cache ou d'un runtime compagnon +- `experimental`: surface presente mais pas encore validee comme chemin stable +- `infra-only`: composant d'infra ou de migration, pas un point d'entree operateur +- `non supporte`: historique, doc-only ou chemin non retenu + +## 1. Serveurs MCP reels + +| Surface | Repo principal | Type | Point d'entree | Statut | Notes | +| --- | --- | --- | --- | --- | --- | +| `kicad` | `Kill_LIFE` + `mascarade` | serveur MCP | `tools/hw/run_kicad_mcp.sh` | supporte | runtime KiCad canonique; implementation dans `mascarade/finetune/kicad_mcp_server` | +| `validate-specs` | `Kill_LIFE` | serveur MCP | `python3 tools/validate_specs.py --mcp` | supporte | validation repo/specs; pas un runtime CAD | +| `notion` | `Kill_LIFE` + `mascarade` | serveur MCP | `tools/run_notion_mcp.sh` | supporte avec dependance externe | MCP local branche sur `mascarade/core/mascarade/integrations/notion.py`; garde le bridge HTTP existant | +| `github-dispatch` | `Kill_LIFE` + `mascarade` | serveur MCP | `tools/run_github_dispatch_mcp.sh` | supporte avec dependance externe | MCP local branche sur `mascarade/core/mascarade/integrations/github_dispatch.py`; garde l'API directe existante | +| `component_database` | `mascarade` | micro-serveur MCP | `python3 -m mcp_servers.component_db` | supporte avec dependance externe | serveur auxiliaire; depend du cache KiCad v10 et du repo compagnon | +| `kicad_tools` | `mascarade` | micro-serveur MCP | `python3 -m mcp_servers.kicad_tools` | supporte avec dependance externe | serveur auxiliaire; depend des fichiers KiCad reels et du repo compagnon | +| `nexar_api` | `mascarade` | micro-serveur MCP | `python3 -m mcp_servers.nexar` | experimental | serveur auxiliaire; mode demo sans token, validation live encore ouverte | + +## 2. Consommateurs et configs MCP + +| Surface | Repo principal | Type | Point d'entree | Statut | Notes | +| --- | --- | --- | --- | --- | --- | +| `mcp.json` | `Kill_LIFE` | config consommateur MCP | `mcp.json` | supporte | reference `kicad`, `validate-specs`, `notion` et `github-dispatch` | +| `MCP setup` | `Kill_LIFE` | doc operateur MCP | `docs/MCP_SETUP.md` | supporte | source de verite d'usage local | +| `KiCad plugin MCP config` | `mascarade` | config plugin MCP | `finetune/kicad_kic_ai/plugins/mcp_config.json` | supporte avec dependance externe | concerne les micro-serveurs auxiliaires, pas le runtime canonique | +| `ops MCP probe` | `mascarade` | observabilite synthetique | `/api/ops/summary` via `api/src/routes/ops.ts` | supporte avec dependance externe | expose l'etat agrege de `kicad`, `validate-specs`, `notion` et `github-dispatch`, plus le detail par serveur | +| `crazy_life MCP positionnement` | `crazy_life` | doc de non-ownership | `docs/MCP_PLAN_2026-03-07.md` | supporte | `crazy_life` ne porte pas de serveur MCP | + +## 3. Integrations tierces non-MCP + +| Surface | Repo principal | Type | Point d'entree | Dependance | Statut | Notes | +| --- | --- | --- | --- | --- | --- | --- | +| `Notion bridge` | `mascarade` | API HTTP interne | `/api/notion/*` via `api/src/routes/notion.ts` | `NOTION_API_KEY` | supporte | bridge backend vers le client Notion, conserve en parallele du MCP `notion` | +| `Notion client core` | `mascarade` | integration SDK | `core/mascarade/integrations/notion.py` | `NOTION_API_KEY` | supporte | source de verite backend Notion | +| `NotionBrowser UI` | `crazy_life` | UI consommatrice | `src/pages/NotionBrowser.tsx` | backend `mascarade` | supporte | consomme encore le bridge HTTP Notion; migration MCP possible ensuite | +| `GitHub dispatch` | `mascarade` | API GitHub directe | `api/src/lib/killlife.ts` | `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` | supporte | lance `workflow_dispatch`, conserve en parallele du MCP `github-dispatch` | +| `GitHub dispatch` | `crazy_life` | API GitHub directe | `api/src/lib/killlife.ts` | `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` | supporte | miroir cote repo canonique frontend/API; migration MCP possible ensuite | +| `KillLife workflow editors` | `mascarade` + `crazy_life` | UI orchestration | `web/src/pages/KillLifeWorkflowEditor.tsx`, `src/pages/KillLifeWorkflowEditor.tsx`, `src/pages/CrazyLaneEditor.tsx` | backend API | supporte | exposent `github-dispatch` comme type de noeud, pas comme MCP | + +## 4. Surfaces infra-only ou migration + +| Surface | Repo principal | Type | Point d'entree | Statut | Notes | +| --- | --- | --- | --- | --- | --- | +| `openmemory-mcp / mem0` | `mascarade` | conteneur MCP tiers | `deploy/migration/compose.tools.ai.yml` | infra-only | profil `heavy`, non documente comme point d'entree canonique, non observe en execution sur cette machine | +| `kicad-sch-mcp` | docs historiques | ancien serveur MCP externe | documentation seulement | non supporte | pas package ni retenu dans le workspace actuel | + +## 5. Conclusion + +- le point d'entree operateur MCP de `Kill_LIFE` reste la surface `kicad` lancee par `tools/hw/run_kicad_mcp.sh` +- `Notion` et `GitHub dispatch` disposent aussi d'un serveur MCP local, mais leur logique applicative reste fournie par `mascarade` +- `crazy_life` consomme des surfaces applicatives, mais n'own pas de serveur MCP +- `mem0/openmemory-mcp` reste une brique d'infra optionnelle, hors chaine operateur canonique +- les surfaces auxiliaires `kicad_kic_ai` ne doivent pas etre lues comme equivalentes au point d'entree operateur `kicad` diff --git a/docs/MCP_SETUP.md b/docs/MCP_SETUP.md index 8f2992e..ebde609 100644 --- a/docs/MCP_SETUP.md +++ b/docs/MCP_SETUP.md @@ -1,46 +1,83 @@ -# MCP setup (KiCad) +# MCP setup -Source canonique pour la configuration MCP locale de `Kill_LIFE`. +Source canonique pour l'usage MCP local de `Kill_LIFE`. -Spec de perimetre: +References canoniques: -- `specs/kicad_mcp_scope_spec.md` +- spec de perimetre: `specs/kicad_mcp_scope_spec.md` +- matrice de support: `docs/MCP_SUPPORT_MATRIX.md` +- matrice ecosysteme: `docs/MCP_ECOSYSTEM_MATRIX.md` +- backlog MCP: `specs/mcp_tasks.md` -## Chemin supporté +## Source de verite et ownership -- Serveur MCP supporté: `mascarade/finetune/kicad_mcp_server` -- Launcher supporté côté `Kill_LIFE`: `tools/hw/run_kicad_mcp.sh` -- Transport supporté: `stdio` local uniquement -- Profil supporté par défaut: `v1` -- Profil étendu optionnel: `v2` +- `Kill_LIFE` own le lancement, la consommation et la gouvernance documentaire MCP locale +- `mascarade` own l'implementation du serveur KiCad principal et l'observabilite compagnon +- `specs/` a la racine de `Kill_LIFE` est la source de verite canonique +- `ai-agentic-embedded-base/specs/` n'est qu'un miroir exporte -`kicad-sch-mcp` n’est plus le chemin recommandé dans ce repo. Il reste un ancien axe documentaire, mais il n’est ni installé ni supporté ici comme runtime principal. +## Chemins supportes -## Prérequis +- serveur MCP KiCad supporte: `../mascarade/finetune/kicad_mcp_server` +- launcher supporte cote `Kill_LIFE`: `tools/hw/run_kicad_mcp.sh` +- alias operateur supporte: `tools/hw/cad_stack.sh mcp` +- serveur auxiliaire supporte: `python3 tools/validate_specs.py --mcp` +- serveur MCP Notion supporte: `tools/run_notion_mcp.sh` +- serveur MCP GitHub dispatch supporte: `tools/run_github_dispatch_mcp.sh` +- transport supporte: `stdio` local uniquement + +`kicad-sch-mcp` n'est plus un chemin supporte dans ce repo. Il reste un ancien axe documentaire, pas un runtime principal. + +## Ce qui est reellement supporte + +- `kicad`: runtime MCP KiCad canonique, avec `tools`, `resources` et `prompts` +- `validate-specs`: validation repo/specs cote `Kill_LIFE`, sans role CAD +- `notion`: MCP local sur le backend Notion existant de `mascarade` +- `github-dispatch`: MCP local pour workflows GitHub allowlistes + +Les micro-serveurs `kicad_kic_ai` de `mascarade` sont suivis comme surfaces auxiliaires. Ils ne sont pas des points d'entree operateur `Kill_LIFE`, et leur statut doit etre lu avec leurs dependances externes dans `docs/MCP_SUPPORT_MATRIX.md`. + +## Prerequis - le repo compagnon `mascarade` existe en voisin (`../mascarade`) ou via `MASCARADE_DIR` - `node` est disponible sur la machine -- le serveur est buildé dans `mascarade/finetune/kicad_mcp_server/dist/index.js` -- KiCad et son Python sont visibles par le runtime du serveur +- le serveur est builde dans `mascarade/finetune/kicad_mcp_server/dist/index.js` +- le venv `mascarade/core/.venv` existe, ou `MASCARADE_CORE_PYTHON` pointe vers un Python avec `notion-client` et `httpx` +- Docker est disponible pour le fallback conteneur KiCad v10 +- `pcbnew` cote hote est optionnel: s'il est absent, le launcher bascule vers le conteneur supporte +- `NOTION_API_KEY` est requis pour les outils `notion` +- `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` est requis pour `dispatch_workflow` -Diagnostic rapide : +Le runtime prepare un environnement writable sous `.cad-home/kicad-mcp/` et exporte `KICAD_MCP_DATA_DIR` pour eviter les ecritures dans un prefixe immuable. + +## Diagnostic rapide + +Depuis `Kill_LIFE`: ```bash tools/hw/run_kicad_mcp.sh --doctor -python3 tools/hw/mcp_smoke.py +tools/hw/cad_stack.sh mcp --doctor +tools/run_notion_mcp.sh --doctor +tools/run_github_dispatch_mcp.sh --doctor +python3 tools/validate_specs_mcp_smoke.py --json --quick +python3 tools/notion_mcp_smoke.py --json --quick +python3 tools/github_dispatch_mcp_smoke.py --json --quick +python3 tools/hw/mcp_smoke.py --json --quick --timeout 30 +python3 tools/hw/mcp_smoke.py --timeout 30 +python3 tools/validate_specs.py --json ``` -Sélection de profil : +Sur cette machine auditee, le smoke KiCad passe via le fallback conteneur: -```bash -tools/hw/run_kicad_mcp.sh --profile v1 -tools/hw/run_kicad_mcp.sh --profile v2 -python3 tools/hw/mcp_smoke.py --profile v2 -``` +- `HOST_PCBNEW_IMPORT=missing` +- `CONTAINER_STATUS=available` +- `python3 tools/hw/mcp_smoke.py --timeout 30` passe +- `python3 tools/notion_mcp_smoke.py --json --quick` retourne `degraded` tant que `NOTION_API_KEY` est absent +- `python3 tools/github_dispatch_mcp_smoke.py --json --quick` retourne `degraded` tant que le token GitHub est absent ## Configuration locale -Le fichier versionné [mcp.json](../mcp.json) pointe déjà vers le launcher supporté : +Le fichier versionne [mcp.json](../mcp.json) pointe vers les serveurs MCP reellement supportes: ```json { @@ -48,38 +85,80 @@ Le fichier versionné [mcp.json](../mcp.json) pointe déjà vers le launcher sup "kicad": { "type": "local", "command": "bash", - "args": ["tools/hw/run_kicad_mcp.sh", "--profile", "v1"], + "args": ["tools/hw/run_kicad_mcp.sh"], + "tools": ["*"] + }, + "validate-specs": { + "type": "local", + "command": "python3", + "args": ["tools/validate_specs.py", "--mcp"], + "tools": ["*"] + }, + "notion": { + "type": "local", + "command": "bash", + "args": ["tools/run_notion_mcp.sh"], + "tools": ["*"] + }, + "github-dispatch": { + "type": "local", + "command": "bash", + "args": ["tools/run_github_dispatch_mcp.sh"], "tools": ["*"] } } } ``` -Le launcher prépare un runtime local writable sous `.cad-home/kicad-mcp/` et exporte `KICAD_MCP_DATA_DIR` pour éviter les écritures dans un préfixe immuable. -Il applique aussi par défaut un niveau de logs discret (`warn`) pour éviter de polluer les clients MCP sur le chemin nominal. - -## Serveur auxiliaire - -`Kill_LIFE` expose aussi un serveur MCP auxiliaire `validate-specs` pour la validation repo/specs : - -```bash -python3 tools/validate_specs.py --json -python3 tools/validate_specs.py --mcp -``` - -Ce serveur ne remplace pas le runtime KiCad. Il sert à vérifier les specs, la conformité et l’usage RFC2119 côté dépôt. - ## Usage -Depuis `Kill_LIFE` : +Depuis `Kill_LIFE`: ```bash tools/hw/run_kicad_mcp.sh +tools/hw/cad_stack.sh mcp +python3 tools/validate_specs.py --mcp +tools/run_notion_mcp.sh +tools/run_github_dispatch_mcp.sh ``` +Le smoke `tools/hw/mcp_smoke.py` valide actuellement la surface cible suivante: + +- `initialize` +- `tools/list` +- `resources/list` +- `prompts/list` +- creation de projet +- lecture de resources stables +- lecture d'un prompt stable + +Les smokes dedies supplementaires sont: + +- `tools/validate_specs_mcp_smoke.py`: handshake MCP de `validate-specs` +- `tools/notion_mcp_smoke.py`: handshake MCP de `notion`, puis validation live si le secret est disponible +- `tools/github_dispatch_mcp_smoke.py`: handshake MCP de `github-dispatch`, puis validation allowlist et live optionnelle + +Le chemin d'observabilite synthetique n'est pas fourni par `Kill_LIFE` seul. Si la stack compagnon `mascarade` tourne, `/api/ops/summary` expose un bloc `mcp` qui remonte le statut, le runtime reellement choisi, la version de protocole et les compteurs de surface. + +## Outils auxiliaires + +- `tools/hw/sync_kicad_v10_libs.sh` est un helper auxiliaire optionnel, hors chemin operateur principal, pour prechauffer les libs/cache KiCad v10 des micro-serveurs auxiliaires +- ce helper depend: + - d'une image Docker locale `kill_life_cad-kicad-mcp:latest` + - du repo compagnon `mascarade` +- ce helper n'est pas requis pour lancer le runtime `kicad` canonique + ## Politique de support -- `stdio` reste le seul transport supporté par défaut -- aucun serveur MCP réseau n’est exposé par défaut -- les serveurs mock/demo restent hors chemin de production tant qu’ils ne parlent pas à un backend réel -- `tools/hw/cad_stack.sh mcp` reste un chemin legacy à réaligner avant d’être re-documenté ici +- `stdio` reste le seul transport supporte par defaut +- aucun serveur MCP reseau n'est expose par defaut +- `tools/hw/cad_stack.sh mcp` est un alias supporte du launcher canonique +- le runtime KiCad canonique est celui de `mascarade/finetune/kicad_mcp_server` +- `validate-specs` reste un MCP auxiliaire repo/specs, pas un runtime CAD +- `notion` et `github-dispatch` restent en `stdio` local et reutilisent les backends existants +- les micro-serveurs `kicad_kic_ai` sont des surfaces auxiliaires suivies, mais restent hors chemin operateur `Kill_LIFE` + +## Points encore ouverts + +- le chemin host-native avec `pcbnew` doit encore etre revalide sur une machine qui expose reellement KiCad Python +- `nexar_api` doit encore etre valide en mode live avec `NEXAR_TOKEN` diff --git a/docs/MCP_SUPPORT_MATRIX.md b/docs/MCP_SUPPORT_MATRIX.md new file mode 100644 index 0000000..fab228f --- /dev/null +++ b/docs/MCP_SUPPORT_MATRIX.md @@ -0,0 +1,49 @@ +# MCP support matrix + +Last updated: 2026-03-07 + +Matrice canonique du statut MCP pour `Kill_LIFE`, `mascarade` et les surfaces associees. + +Vue plus large de l'ecosysteme: + +- `docs/MCP_ECOSYSTEM_MATRIX.md` + +## Statuts + +- `supporte`: surface officiellement maintenue et validee comme point d'entree operateur +- `supporte avec dependance externe`: surface maintenue dans le workspace, mais dependante d'un runtime, d'un cache, d'un token ou d'un repo compagnon +- `experimental`: surface presente et suivie, mais pas encore validee comme chemin operateur stable +- `non supporte`: ancien chemin, historique ou simple reference documentaire + +## Matrice + +| Surface | Point d'entree | Ownership | Protocole observe / declare | Statut | Notes | +| --- | --- | --- | --- | --- | --- | +| `kicad` | `tools/hw/run_kicad_mcp.sh` | launcher `Kill_LIFE`, serveur `mascarade/finetune/kicad_mcp_server` | `2025-03-26` observe au smoke | supporte | runtime KiCad canonique; `tools/hw/cad_stack.sh mcp` est un alias supporte | +| `validate-specs` | `python3 tools/validate_specs.py --mcp` | `Kill_LIFE` | `2025-03-26` observe en test | supporte | validation repo/specs; ne remplace pas le runtime KiCad | +| `notion` | `tools/run_notion_mcp.sh` | launcher `Kill_LIFE`, backend `mascarade/core/mascarade/integrations/notion.py` | `2025-03-26` observe en test | supporte avec dependance externe | MCP local branche sur le backend Notion de `mascarade`; requiert `NOTION_API_KEY` et le repo compagnon | +| `github-dispatch` | `tools/run_github_dispatch_mcp.sh` | launcher `Kill_LIFE`, backend `mascarade/core/mascarade/integrations/github_dispatch.py` | `2025-03-26` observe en test | supporte avec dependance externe | MCP local pour workflows allowlistes; requiert `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` et le repo compagnon | +| `component_database` | `python3 -m mcp_servers.component_db` | `mascarade/finetune/kicad_kic_ai` | `2025-03-26` observe au handshake | supporte avec dependance externe | micro-serveur auxiliaire; depend du repo compagnon `mascarade`, du cache KiCad v10 et d'un index local prechauffe | +| `kicad_tools` | `python3 -m mcp_servers.kicad_tools` | `mascarade/finetune/kicad_kic_ai` | `2025-03-26` observe au handshake | supporte avec dependance externe | micro-serveur auxiliaire; analyses reelles si les fichiers KiCad et dependances associees sont disponibles | +| `nexar_api` | `python3 -m mcp_servers.nexar` | `mascarade/finetune/kicad_kic_ai` | `2025-03-26` observe au handshake | experimental | micro-serveur auxiliaire; sans `NEXAR_TOKEN`, reste en mode demo; validation live encore ouverte | + +## Hors chaine supportee + +| Surface | Point d'entree | Ownership | Protocole observe / declare | Statut | Notes | +| --- | --- | --- | --- | --- | --- | +| `kicad-sch-mcp` | aucun chemin versionne supporte ici | historique | n/a | non supporte | ancien chemin documentaire, pas un runtime principal de ce workspace | + +## Decisions importantes + +- `Kill_LIFE` n'own pas de second serveur KiCad concurrent +- `stdio` reste le seul transport supporte par defaut +- le runtime KiCad supporte passe par `Kill_LIFE` pour le lancement et par `mascarade` pour l'implementation +- `notion` et `github-dispatch` sont supportes comme serveurs MCP locaux, mais leur logique applicative reste fournie par `mascarade` +- les micro-serveurs `kicad_kic_ai` sont suivis comme surfaces auxiliaires, pas comme point d'entree operateur `Kill_LIFE` +- le probe synthetique MCP expose cote ops appartient a `mascarade/api/src/routes/ops.ts`; il n'est disponible que si la stack compagnon tourne + +## Dettes encore ouvertes + +- le chemin host-native avec `pcbnew` n'est pas encore revalide sur une machine qui l'expose reellement +- `nexar_api` doit encore etre valide en mode live avec credentials +- le statut des micro-serveurs auxiliaires doit rester distinct de la surface operateur `kicad` diff --git a/docs/plans/15_plan_mcp_runtime_alignment.md b/docs/plans/15_plan_mcp_runtime_alignment.md index 51c1c03..5179f25 100644 --- a/docs/plans/15_plan_mcp_runtime_alignment.md +++ b/docs/plans/15_plan_mcp_runtime_alignment.md @@ -1,42 +1,80 @@ -# 15) Plan d’alignement MCP local +# 15) Plan d'alignement MCP local Last updated: 2026-03-07 +Ce fichier est le plan MCP canonique cote `Kill_LIFE`. + +Sources de verite associees: + +- `docs/MCP_SETUP.md` +- `docs/MCP_SUPPORT_MATRIX.md` +- `specs/kicad_mcp_scope_spec.md` +- `specs/mcp_tasks.md` + ## Objectif -Faire de `Kill_LIFE` le repo de consommation et de gouvernance MCP, sans maintenir un second serveur MCP concurrent. +Faire de `Kill_LIFE` le repo de consommation et de gouvernance MCP, sans maintenir un second serveur KiCad concurrent. -## Cible supportée +## Etat actuel -- serveur: `../mascarade/finetune/kicad_mcp_server` -- launcher local: `tools/hw/run_kicad_mcp.sh` -- config MCP versionnée: `mcp.json` -- transport: `stdio` -- serveur auxiliaire repo/specs: `tools/validate_specs.py --mcp` +- `mcp.json` pointe vers des launchers MCP reels pour `kicad`, `validate-specs`, `notion` et `github-dispatch` +- `tools/hw/run_kicad_mcp.sh` est le point d'entree canonique pour le runtime KiCad +- `tools/hw/cad_stack.sh mcp` est deja aligne sur ce launcher +- `python3 tools/hw/mcp_smoke.py --timeout 30` passe sur la machine auditee via fallback conteneur +- `validate-specs` existe comme CLI et comme serveur MCP `stdio` +- la pile MCP locale converge sur `2025-03-26` +- l'observabilite synthetique MCP est exposee via `/api/ops/summary` si la stack compagnon `mascarade` tourne -## Actions +## Decisions figees -### 1. Source de vérité +- `Kill_LIFE` ne publie pas de second runtime KiCad host-side concurrent +- `mascarade/finetune/kicad_mcp_server` reste l'implementation serveur KiCad de reference +- `stdio` reste le seul transport supporte par defaut +- la matrice de support MCP est centralisee dans `docs/MCP_SUPPORT_MATRIX.md` +- le backlog executable est centralise dans `specs/mcp_tasks.md` +- `specs/` a la racine est la source de verite canonique; `ai-agentic-embedded-base/specs/` reste un miroir exporte -1. Retirer toute promesse de serveur fantôme. -2. Pointer `mcp.json` vers le launcher supporté et les MCP auxiliaires réels. -3. Basculer la doc MCP canonique sur `docs/MCP_SETUP.md`. +## Travail deja absorbe -### 2. Runtime opérable +1. Retirer les promesses cassees de `mcp.json` +2. Rendre `validate-specs` executable en CLI et en MCP +3. Rendre le launcher KiCad operable avec runtime writable +4. Aligner `cad_stack.sh mcp` sur le launcher supporte +5. Stabiliser le fallback conteneur KiCad v10 +6. Ajouter un smoke consommateur versionne +7. Fixer une doc d'usage canonique et une matrice de support -1. Faire de `tools/hw/cad_stack.sh mcp` un simple wrapper vers le launcher supporté. -2. Préparer un runtime writable sous `.cad-home/kicad-mcp`. -3. Garder `MASCARADE_DIR` comme override explicite, pas comme dépendance cachée. +## Travail restant -### 3. Documentation +### Priorite 1 — Alignement protocole -1. Transformer les duplications `ai-agentic-embedded-base/docs/*` en pointeurs vers les docs canoniques. -2. Corriger les références à `validate_specs.py`. -3. Garder `stdio only` comme politique MCP locale. +1. Fait +2. Les launchers MCP supportes et les surfaces auxiliaires suivies convergent vers `2025-03-26`. -## Critères de sortie +### Priorite 2 — Observabilite -- `mcp.json` ne référence plus de fichier absent -- `tools/hw/run_kicad_mcp.sh --doctor` résout un serveur réel -- `tools/hw/cad_stack.sh mcp` utilise le même chemin que `mcp.json` -- la doc root n’annonce plus `kicad-sch-mcp` comme chemin principal +1. Fait +2. `/api/ops/summary` expose l'etat synthetique MCP quand la stack compagnon `mascarade` est presente. + +### Priorite 3 — Validation host-native + +1. Rejouer le smoke sur une machine avec `pcbnew` disponible +2. Confirmer que le chemin hote reste coherent avec le fallback conteneur + +### Priorite 4 — Classement des surfaces auxiliaires + +1. Fait +2. `component_database` et `kicad_tools` sont classes `supporte avec dependance externe`. +3. `nexar_api` reste `experimental` tant qu'il n'est pas valide en mode live. + +## Criteres de sortie + +- `Kill_LIFE` publie une seule doc operateur MCP canonique +- la matrice de support ne laisse plus de statut implicite +- les TODOs MCP ne sont plus dupliques entre `docs/plans` et `specs` +- le prochain lecteur sait immediatement: + - quel serveur lancer + - quel alias utiliser + - ce qui est supporte localement + - ce qui depend encore de `mascarade` + - ce qui reste reellement ouvert diff --git a/docs/plans/15_plan_mcp_stack.md b/docs/plans/15_plan_mcp_stack.md index fe084d1..1343ef2 100644 --- a/docs/plans/15_plan_mcp_stack.md +++ b/docs/plans/15_plan_mcp_stack.md @@ -2,32 +2,16 @@ Last updated: 2026-03-07 -## Objectif +Ce fichier n'est plus le plan MCP canonique. -Rendre la couche MCP de `Kill_LIFE` cohérente côté config, validation locale et usage opérateur, sans embarquer une promesse cassée. +Source de vérité actuelle: -## Décisions figées +- plan: `docs/plans/15_plan_mcp_runtime_alignment.md` +- matrice de support: `docs/MCP_SUPPORT_MATRIX.md` +- backlog: `specs/mcp_tasks.md` -- `mcp.json` publie le launcher KiCad supporté `tools/hw/run_kicad_mcp.sh`. -- `Kill_LIFE` expose aussi `validate-specs` comme serveur/CLI auxiliaire de validation repo. -- Le runtime KiCad côté `Kill_LIFE` est piloté par `mcp.json` et `tools/hw/run_kicad_mcp.sh`. -- `Kill_LIFE` ne publie pas de second serveur KiCad host-side concurrent tant que la convergence n’est pas terminée. +Raison: -## Implémenté - -- [x] Ajouter `tools/validate_specs.py` comme script CLI réel. -- [x] Exposer le même script en serveur MCP `stdio` minimal. -- [x] Garder `mcp.json` sur le launcher KiCad versionné. -- [x] Ajouter des tests sur le mode CLI et le handshake MCP minimal. - -## Reste à faire - -- [ ] Documenter précisément ce que couvre `validate-specs` et ce qu’il ne couvre pas. -- [ ] Réaligner `tools/hw/cad_stack.sh mcp` sur le launcher supporté ou le déclasser explicitement. -- [ ] Réconcilier `docs/MCP_SETUP.md`, `docs/KICAD_AI_LOCAL.md` et `deploy/cad/README.md`. - -## Critères de sortie - -- `python3 tools/validate_specs.py` fonctionne sans ambigüité. -- `mcp.json` démarre un serveur MCP KiCad réel. -- La doc `Kill_LIFE` ne présente plus plusieurs vérités contradictoires pour le lancement MCP. +- `15_plan_mcp_stack.md` et `15_plan_mcp_runtime_alignment.md` dérivaient sur le même sujet +- le plan canonique a été recentré sur l'usage opérateur réel de `Kill_LIFE` +- le backlog exécutable a été déplacé dans `specs/mcp_tasks.md` diff --git a/docs/plans/15_todo_mcp_stack.md b/docs/plans/15_todo_mcp_stack.md index 88ccbf0..cff7050 100644 --- a/docs/plans/15_todo_mcp_stack.md +++ b/docs/plans/15_todo_mcp_stack.md @@ -2,20 +2,15 @@ Last updated: 2026-03-07 -## Sprint actuel +Ce fichier n'est plus le TODO MCP canonique. -- [x] Implémenter `tools/validate_specs.py`. -- [x] Rendre `mcp.json` lançable. -- [x] Ajouter un test de handshake MCP minimal. -- [ ] Documenter le périmètre exact de `validate-specs`. +Source de vérité actuelle: -## J7 +- backlog exécutable: `specs/mcp_tasks.md` +- doc opérateur: `docs/MCP_SETUP.md` +- matrice de support: `docs/MCP_SUPPORT_MATRIX.md` -- [ ] Aligner la doc KiCad MCP sur un seul chemin opérateur supporté. -- [ ] Décrire la dépendance éventuelle à `mascarade` pour le runtime KiCad avancé. -- [ ] Ajouter une preuve d’exécution `tools/hw/cad_stack.sh mcp`. +Raison: -## J30 - -- [ ] Transformer `docs/MCP_SETUP.md` en doc canonique unique ou en simple pointeur. -- [ ] Ajouter une matrice `supporté / expérimental / démo`. +- le backlog MCP ne doit plus être dupliqué entre `docs/plans` et `specs` +- `specs/mcp_tasks.md` porte maintenant l'état courant et les actions restantes diff --git a/docs/plans/README.md b/docs/plans/README.md index 40388ec..f2545db 100644 --- a/docs/plans/README.md +++ b/docs/plans/README.md @@ -22,6 +22,7 @@ Ces plans sont des **runbooks** : tu peux les suivre tels quels, ou les transfor 12. [Plan de gestion des agents](12_plan_gestion_des_agents.md) 13. [Plan de troubleshooting](13_plan_troubleshooting.md) 14. [Plan de release & versioning](14_plan_release_versioning.md) +15. [Plan d'alignement MCP local](15_plan_mcp_runtime_alignment.md) --- diff --git a/specs/README.md b/specs/README.md index a54e8aa..2372839 100644 --- a/specs/README.md +++ b/specs/README.md @@ -1,25 +1,29 @@ # Specs (Spec-driven) -Flux conseillé (itératif) : -1) `00_intake.md` : idée brute + contexte +Flux conseille (iteratif) : +1) `00_intake.md` : idee brute + contexte 2) `01_spec.md` : spec claire + AC 3) `02_arch.md` : architecture + ADR -4) `03_plan.md` : plan découpé, risques, validations -5) `04_tasks.md` : backlog exécutable (issues / PRs) -6) Implémentation (firmware/hardware) + tests + doc +4) `03_plan.md` : plan decoupe, risques, validations +5) `04_tasks.md` : backlog executable (issues / PRs) +6) Implementation (firmware/hardware) + tests + doc -Le fichier `constraints.yaml` est la **source de vérité** des contraintes non-fonctionnelles et règles repo. +Le fichier `constraints.yaml` est la **source de verite** des contraintes non-fonctionnelles et regles repo. -Specs complémentaires: +Specs complementaires: +- `github_mcp_conversion_spec.md`: prep de conversion de `workflow_dispatch` vers une surface MCP future. - `kicad_mcp_scope_spec.md`: perimetre fonctionnel, hors scope et criteres d'acceptation du MCP KiCad supporte. -- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double matériel. -- `zeroclaw_dual_hw_todo.md`: backlog opérationnel court terme pour autonomie contrôlée. +- `mcp_tasks.md`: backlog canonique des actions MCP locales, partage entre runtime, doc et gouvernance. +- `notion_mcp_conversion_spec.md`: prep de conversion du bridge Notion actuel vers une surface MCP future. +- `zeroclaw_dual_hw_orchestration_spec.md`: architecture d'orchestration ZeroClaw multi-repo + double materiel. +- `zeroclaw_dual_hw_todo.md`: backlog operationnel court terme pour autonomie controlee. Synchronisation `spec_kit`: -- `specs/` (racine repo) et `ai-agentic-embedded-base/specs/` doivent rester alignés. -- Après toute mise à jour, synchroniser avec: +- `specs/` (racine repo) est la source de verite canonique. +- `ai-agentic-embedded-base/specs/` est un miroir exporte. +- Apres toute mise a jour canonique, synchroniser le miroir avec: - `rsync -a --delete specs/ ai-agentic-embedded-base/specs/` -- Vérifier l'absence d'écart avec: +- Verifier l'absence d'ecart avec: - `diff -ru ai-agentic-embedded-base/specs specs` diff --git a/specs/github_mcp_conversion_spec.md b/specs/github_mcp_conversion_spec.md new file mode 100644 index 0000000..e9b0b1c --- /dev/null +++ b/specs/github_mcp_conversion_spec.md @@ -0,0 +1,51 @@ +# Spec conversion MCP GitHub dispatch + +Last updated: 2026-03-07 + +## Objectif + +Documenter l'implémentation MCP `github-dispatch` à partir de l'intégration `workflow_dispatch` existante, sans remplacer la voie API existante en V1. + +## État actuel + +- backend réel dans `mascarade/api/src/lib/killlife.ts` et `crazy_life/api/src/lib/killlife.ts` +- dépendance secrète: `KILL_LIFE_GITHUB_TOKEN` ou `GITHUB_TOKEN` +- contrôle de sécurité actuel: + - allowlist de workflows + - sanitation des clés d'input + - repo et ref par défaut contrôlés + +## Surface MCP implémentée + +Serveur MCP `github-dispatch` local avec les outils: + +- `list_allowlisted_workflows` +- `dispatch_workflow` +- `get_dispatch_status` + +## Mapping depuis l'existant + +- config allowlist actuelle -> `list_allowlisted_workflows` +- `POST /repos/:repo/actions/workflows/:workflow/dispatches` -> `dispatch_workflow` +- suivi de run et réconciliation locale -> `get_dispatch_status` + +## Contraintes + +- garder `stdio` comme transport par défaut +- interdire tout dispatch hors allowlist +- ne pas exposer de surface générique GitHub issue/PR/repo en V1 +- conserver l'API actuelle tant que les éditeurs de workflow ne consomment pas MCP +- launcher opérateur: `tools/run_github_dispatch_mcp.sh` + +## Hors scope V1 + +- gestion générique GitHub +- mutation libre d'issues, PR, labels ou releases +- changement dynamique du repo cible hors politique versionnée + +## Validation minimale + +- handshake `initialize -> tools/list` vert +- `dispatch_workflow` refuse un workflow non allowlisté +- erreur structurée si token absent +- `get_dispatch_status` retourne un état exploitable sans lecture manuelle brute de l'API GitHub diff --git a/specs/kicad_mcp_scope_spec.md b/specs/kicad_mcp_scope_spec.md index 8d4b294..98c95c4 100644 --- a/specs/kicad_mcp_scope_spec.md +++ b/specs/kicad_mcp_scope_spec.md @@ -6,7 +6,7 @@ Last updated: 2026-03-07 - O1. Definir le perimetre fonctionnel du serveur MCP KiCad supporte par `Kill_LIFE`. - O2. Eviter la derive entre implementation serveur, launcher local, docs et attentes des agents. -- O3. Fixer une frontiere claire entre ce que le MCP KiCad MUST couvrir en v1, ce qui SHOULD venir en v2, et ce qui reste hors scope. +- O3. Fixer une frontiere claire entre le contrat stable du MCP KiCad, les extensions futures legitimes et ce qui reste hors scope. ## Non-objectifs @@ -34,6 +34,7 @@ Last updated: 2026-03-07 - Le serveur MUST exposer `stdio` local uniquement. - Le serveur MUST parler JSON-RPC compatible MCP avec framing ligne par ligne, conforme au SDK utilise. - Le serveur MUST fonctionner via `tools/hw/run_kicad_mcp.sh`. + - Le serveur MUST exposer une seule surface stable; aucun profil runtime alternatif ne doit etre requis. - F2. Cycle projet - Le serveur MUST permettre de creer, ouvrir, sauvegarder et inspecter un projet KiCad. @@ -68,7 +69,13 @@ Last updated: 2026-03-07 - Le serveur SHOULD permettre la recherche de composants JLCPCB/LCSC, les alternatives proches et l'acces aux datasheets. - Les integrations de sourcing MAY utiliser un backend local ou une API externe si les credentials sont presents. -- F10. Runtime +- F10. Resources / prompts / UI + - Le serveur MUST exposer `tools`, `resources` et `prompts` comme surface stable unique. + - Toute resource exposee MUST correspondre a un backend reel et testable. + - Les prompts MUST referencer uniquement des capabilities supportees. + - Les actions UI supportees MUST retourner un resultat deterministe ou une erreur structuree quand le contexte graphique est indisponible. + +- F11. Runtime - Le serveur MUST preferer un backend KiCad reel. - Le backend SHOULD preferer IPC quand disponible. - Le backend MUST pouvoir retomber sur SWIG si IPC n'est pas disponible. @@ -82,7 +89,7 @@ Last updated: 2026-03-07 - Le serveur MUST NOT exiger de secrets pour les usages locaux de base. - Fiabilite - - `initialize` puis `tools/list` MUST passer sur une machine supportee. + - `initialize`, `tools/list`, `resources/list` et `prompts/list` MUST passer sur une machine supportee. - Le launcher MUST gerer le fallback host -> container quand l'hote n'expose pas `pcbnew`. - Les erreurs MUST etre actionnables et non silencieuses. @@ -99,13 +106,13 @@ Last updated: 2026-03-07 - Le contrat de transport MUST rester stable pour les consommateurs locaux de `Kill_LIFE`. - Le runtime conteneur supporte SHOULD rester aligne avec la version KiCad cible du projet, y compris la trajectoire v10. -## V2 / extensions legitimes +## Extensions futures legitimes -- V2.1. Session IPC plus riche, synchronisee avec une UI KiCad vivante. -- V2.2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs. -- V2.3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation. -- V2.4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite. -- V2.5. Dry-run systematique pour les mutations a fort impact. +- E1. Session IPC plus riche, synchronisee avec une UI KiCad vivante. +- E2. Coverage schematic plus avancee: edition structurelle plus large, contraintes electriques plus fines, automation de patterns repetitifs. +- E3. Workflows de revue plus riches: snapshots, diff de board/schema, previews avant mutation. +- E4. Sourcing plus fort: BOM, substitutions, scoring cout/disponibilite. +- E5. Dry-run systematique pour les mutations a fort impact. ## Hors scope @@ -125,11 +132,15 @@ Last updated: 2026-03-07 - `initialize` - `notifications/initialized` - `tools/list` + - `resources/list` + - `prompts/list` + - `resources/read` sur au moins une resource stable + - `prompts/get` sur au moins un prompt stable ## Critieres d'acceptation - AC1. Le repo documente un seul serveur KiCad MCP supporte en v1. -- AC2. Le serveur expose au moins une famille d'outils fonctionnelle pour: projet, schema, PCB, librairies, validation, export. +- AC2. Le serveur expose une surface stable fonctionnelle pour: projet, schema, PCB, librairies, validation, export, resources, prompts et sourcing. - AC3. `python3 tools/hw/mcp_smoke.py` passe sur un environnement supporte. - AC4. En absence de `pcbnew` host, le launcher supporte bascule vers le runtime conteneur. - AC5. La doc d'usage locale renvoie explicitement vers cette spec de perimetre. diff --git a/specs/mcp_tasks.md b/specs/mcp_tasks.md index 33f1d7e..a6d20ca 100644 --- a/specs/mcp_tasks.md +++ b/specs/mcp_tasks.md @@ -2,39 +2,73 @@ Last updated: 2026-03-07 +Backlog MCP canonique pour `Kill_LIFE`. + +Références: + +- doc opérateur: `docs/MCP_SETUP.md` +- matrice de support: `docs/MCP_SUPPORT_MATRIX.md` +- spec de périmètre: `specs/kicad_mcp_scope_spec.md` + Format: - `[ ]` non fait - `[x]` fait -## Sprint actif +## État courant -- [x] K-001 — Rendre `validate-specs` réel ou retirer la promesse - - AC: aucun chemin absent n’est versionné comme serveur MCP. +- [x] K-001 — Rendre `validate-specs` réel + - AC: `mcp.json` ne référence plus de chemin absent. -- [x] K-002 — Ajouter un launcher supporté `tools/hw/run_kicad_mcp.sh` - - AC: le launcher résout `mascarade`, prépare un runtime writable et exécute le serveur. +- [x] K-002 — Ajouter un launcher KiCad supporté + - AC: `tools/hw/run_kicad_mcp.sh` résout `mascarade`, prépare un runtime writable et exécute le serveur. - [x] K-003 — Aligner `tools/hw/cad_stack.sh mcp` - - AC: la commande `mcp` appelle le même launcher que `mcp.json`. + - AC: l'alias opérateur appelle le même launcher que `mcp.json`. -- [x] K-004 — Désigner `docs/MCP_SETUP.md` comme doc canonique - - AC: la version miroir renvoie vers la doc racine. +- [x] K-004 — Fixer une doc opérateur canonique + - AC: `docs/MCP_SETUP.md` décrit le chemin réellement supporté. -- [x] K-005 — Retirer les références à `tools/validate_specs.py` - - AC: les docs visibles pointent vers un validateur réellement présent. +- [x] K-005 — Fixer une spec de périmètre canonique + - AC: `specs/kicad_mcp_scope_spec.md` décrit le contrat MCP KiCad supporté. + +- [x] K-006 — Fixer une matrice de support canonique + - AC: `docs/MCP_SUPPORT_MATRIX.md` classe explicitement les surfaces supportées et les chemins hors chaîne supportée. + +- [x] K-007 — Ajouter un smoke test consommateur versionné + - AC: `python3 tools/hw/mcp_smoke.py --timeout 30` passe sur un environnement supporté. + +- [x] K-008 — Documenter les prérequis machine utiles + - AC: `docs/MCP_SETUP.md` documente `node`, Docker, le repo compagnon et le fallback hôte -> conteneur. + +- [x] K-009 — Décider du sort du chemin `cad_stack.sh mcp` + - AC: ce n'est plus un chemin legacy, mais un alias supporté du launcher canonique. ## À faire ensuite -- [x] K-006 — Ajouter un smoke test MCP consommateur côté `Kill_LIFE` - - AC: un script versionné existe pour tester `initialize` et `tools/list`. +- [x] K-010 — Aligner la matrice de protocoles MCP + - AC: le runtime KiCad principal, `validate-specs` et les micro-serveurs auxiliaires exposent une compatibilité documentée et non contradictoire. -- [ ] K-007 — Documenter les prérequis machine minimum pour le runtime MCP - - AC: Node, KiCad et repo compagnon sont explicitement listés. +- [x] K-011 — Ajouter une observabilité MCP synthétique + - AC: un état `ready / degraded / failed` est visible sans lecture manuelle des logs. -- [ ] K-008 — Décider du sort final du service Docker `kicad-mcp` historique - - AC: soit supprimé, soit rebranché sur le runtime supporté sans drift. +- [ ] K-012 — Rejouer la validation host-native sur une machine avec `pcbnew` + - AC: le smoke passe aussi sur le chemin hôte, pas seulement via le fallback conteneur. -- [ ] K-009 — Faire passer le smoke réel `initialize -> tools/list` - - AC: `python3 tools/hw/mcp_smoke.py` passe sur une machine avec `pcbnew` disponible. - - Blocage actuel: le host audité n’expose pas `pcbnew`, donc le runtime KiCad ne peut pas démarrer. +- [x] K-013 — Décider du statut final des micro-serveurs `kicad_kic_ai` + - AC: `component_database`, `kicad_tools` et `nexar_api` sont explicitement promus en surfaces auxiliaires supportées. + +- [ ] K-014 — Valider le mode live de `nexar_api` + - AC: un run avec `NEXAR_TOKEN` confirme le comportement réel et le distingue du mode démo. + +- [x] K-015 — Implémenter le MCP `Notion` + - AC: `tools/run_notion_mcp.sh` expose `search_pages`, `read_page`, `append_to_page`, `create_page` sans retirer le bridge HTTP en V1. + +- [x] K-016 — Implémenter le MCP `GitHub dispatch` + - AC: `tools/run_github_dispatch_mcp.sh` expose `list_allowlisted_workflows`, `dispatch_workflow` et `get_dispatch_status` sans retirer la voie API actuelle en V1. + +- [x] K-017 — Ajouter des smokes MCP dedies hors KiCad + - AC: `validate-specs`, `notion` et `github-dispatch` ont chacun un smoke versionne avec sortie JSON. + +- [x] K-018 — Etendre l'observabilite MCP a plusieurs serveurs + - AC: `/api/ops/summary` expose un etat agrege et le detail par serveur pour `kicad`, `validate-specs`, `notion` et `github-dispatch`. diff --git a/specs/notion_mcp_conversion_spec.md b/specs/notion_mcp_conversion_spec.md new file mode 100644 index 0000000..3fde2e8 --- /dev/null +++ b/specs/notion_mcp_conversion_spec.md @@ -0,0 +1,51 @@ +# Spec conversion MCP Notion + +Last updated: 2026-03-07 + +## Objectif + +Documenter l'implémentation MCP `notion` à partir de l'intégration `Notion` existante, sans remplacer la voie HTTP existante en V1. + +## État actuel + +- backend réel dans `mascarade/core/mascarade/integrations/notion.py` +- bridge HTTP existant dans `mascarade/api/src/routes/notion.ts` +- UI consommatrice existante dans `crazy_life/src/pages/NotionBrowser.tsx` +- dépendance secrète: `NOTION_API_KEY` + +## Surface MCP implémentée + +Serveur MCP `notion` local avec les outils: + +- `search_pages` +- `read_page` +- `append_to_page` +- `create_page` + +## Mapping depuis l'existant + +- `GET /api/notion/search` -> `search_pages` +- `GET /api/notion/pages/:pageId` -> `read_page` +- `POST /api/notion/pages/:pageId/append` -> `append_to_page` +- `POST /api/notion/pages` -> `create_page` + +## Contraintes + +- garder `stdio` comme transport par défaut +- ne pas exposer un MCP réseau en V1 +- erreurs explicites si `NOTION_API_KEY` absent +- conserver le bridge HTTP existant tant que la migration client n'est pas faite +- launcher opérateur: `tools/run_notion_mcp.sh` + +## Hors scope V1 + +- suppression du bridge HTTP existant +- édition riche avancée ou gestion fine des blocs Notion +- sync bidirectionnelle UI <-> MCP + +## Validation minimale + +- handshake `initialize -> tools/list` vert +- `search_pages` et `read_page` smokés +- erreur structurée et non ambiguë si `NOTION_API_KEY` absent +- documentation opérateur et matrice de support mises à jour