@vantageos/backend-doctor 0.1.0

package/fixtures/mcp-app-standard-a74a042b.md

@@ -0,0 +1,279 @@
+# MCP App Standard — Complément App
+
+Version : v2.2 — 2026-08-16. Aligné standard GA MCP Apps `2026-07-28`. Table de détecteurs + table de source A-1..A-7.
+Owner : gamma
+Status : en vigueur — non déclaré fini tant que l'opérateur ne l'a pas dit.
+Références parent : `resources/references/mcp-standard.md` (le tronc), `resources/references/mcp-server-standard.md` (le complément serveur).
+Source benchmark : `analysis/mcp-apps-benchmark-2026-04-26.md`.
+
+Source canonique : `resources/references/mcp-app-standard.md`. **Ce document est un complément.** Il ne porte QUE ce qui est propre à une MCP App — repli markdown, bundle single-file, bac à sable, accessibilité, budgets de performance, clé UI GA. Tout le reste — bilinguisme (`C-1`), SemVer (`C-3`), suite d'évaluation dont le cas dégradé (`C-5`), obtention vérifiable de l'artefact (`C-7`) — vit dans le tronc et ne se réécrit jamais ici.
+
+**Ce que gouverne ce document** : une MCP App, c'est-à-dire un serveur MCP qui retourne, en plus du contenu texte, une UI interactive rendue dans le client. **Où passe la frontière** : une App EST un serveur — elle tient le tronc, le complément serveur ENTIER (règles `S-*` : transport, protocole, découverte, autorisation, sécurité), ET ce complément. Ce document ne porte que la couche visuelle qui s'ajoute au serveur.
+
+---
+
+## Règles propres à l'App (`A-1` à `A-6`)
+
+1. **`A-1` — Repli markdown obligatoire (dégradation gracieuse — graceful degradation)** dans `content[]` à côté de la ressource `ui://`. Un client sans couche UI reçoit une réponse texte équivalente et significative, sans erreur. Aucune exception. *(C'est aussi ce que doit un serveur pur qui retourne une App : la règle vit ici, le complément serveur y renvoie.)*
+2. **`A-2` — Bundle single-file** via `vite-plugin-singlefile` (ou équivalent) : HTML + JS + CSS dans un seul fichier servi via `ui://`. Aucun fetch externe au runtime UI — tout est passé en props ou demandé via le bridge.
+3. **`A-3` — Bac à sable respecté.** Pas de `window.parent.*`, pas de `localStorage` direct : tout passe par le bridge. Le modèle double-iframe sandbox-proxy (ci-dessous) applique une CSP dérivée par ressource — strictement plus strict, il s'ajoute à cette règle.
+4. **`A-4` — WCAG AA** validé en CI via `axe-core`, 0 violation bloquante avant release. Sémantique HTML native, ARIA sur tout interactif non-évident, contraste AA, navigation clavier, `prefers-reduced-motion`.
+5. **`A-5` — Budgets de performance respectés** : bundle < 250 KB gzipped, initial render < 1s LAN, roundtrip bridge < 500ms p95, mémoire steady-state < 50 MB. La moitié statique (taille du bundle) est mesurable sur l'artefact ; render/roundtrip demandent une sonde runtime.
+6. **`A-6` — Clé UI GA obligatoire (gate D6).** La ressource UI est liée par la clé imbriquée `_meta.ui.resourceUri` via `registerAppTool` (`@modelcontextprotocol/ext-apps`). Les formes dépréciées `_meta["ui/resourceUri"]` (plate) et l'id communautaire `io.modelcontextprotocol/ui` sont refusées en écriture. Le détecteur mcp-doctor D6 gate cette conformité en CI : 0 App publiée sans la clé GA.
+
+### Seconde source — pratique établie MCP
+
+7. **`A-7` — Consentement humain avant un outil destructif.** L'App/hôte est le point d'application du contrôle humain : elle gate tout appel d'outil dont les annotations indiquent un comportement destructif ou non idempotent — OU qui ne porte aucune annotation — derrière une confirmation utilisateur explicite, jamais une auto-exécution silencieuse. Les annotations d'une source non épinglée sont non fiables (`C-15`) : une App ne conditionne pas cette confirmation sur `destructiveHint=false` seul. *(Source : spec MCP 2025-06-18 `server/tools` §User Interaction Model — « there SHOULD always be a human in the loop with the ability to deny tool invocations » ; SHOULD.)*
+
+### Traçabilité — règles App → objectifs
+
+| Règle | production | entreprise | sécurité | jetons | cloisonnement |
+|---|:---:|:---:|:---:|:---:|:---:|
+| A-1 repli markdown obligatoire | ✓ | ✓ | | ✓ | |
+| A-2 bundle single-file, aucun fetch externe | ✓ | | ✓ | | |
+| A-3 bac à sable respecté | | | ✓ | | ✓ |
+| A-4 WCAG AA, 0 violation bloquante | ✓ | ✓ | | | |
+| A-5 budgets de performance | ✓ | | | ✓ | |
+| A-6 clé UI GA obligatoire | ✓ | ✓ | | | |
+| A-7 consentement avant outil destructif | | ✓ | ✓ | | |
+
+**Objectif faiblement servi côté App : multi-tenant.** Seul `A-3` y touche, par la bande (le bac à sable empêche une App de lire l'état d'une autre). Rien n'oblige une App à déclarer de quelle organisation proviennent les données qu'elle rend. Le cloisonnement est garanti en amont, par le serveur (`S-5`) et son backend (`R-11`), et l'App en hérite — c'est la frontière du tronc §7, pas une lacune de ce complément.
+
+### Spécifications de détecteur (règles App `A-1`..`A-7`)
+
+L'instrument reste gelé ; on spécifie ce qu'un détecteur lira. La colonne Genre porte le jeu fermé du tronc §5.2 — **`statique`** · **`dynamique`** · **`gate`**, seuls ou combinés par `+` — et rien d'autre (pour une App, `statique` lit le bundle/le code UI ; `dynamique` observe l'App servie/rendue ; `gate` = vérification au point de livraison, CI). La part non mécanique se lit dans les colonnes Rouge/Vert, jamais dans Genre.
+
+| Règle | Le check lit | Rouge | Vert | Genre |
+|---|---|---|---|---|
+| A-1 | le `content[]` servi à côté de la ressource `ui://` | une ressource `ui://` sans repli texte équivalent | `ui://` + repli markdown significatif présents | dynamique |
+| A-2 | le bundle servi | fetch externe au runtime UI, ou bundle multi-fichiers | HTML+JS+CSS en un seul fichier, aucun fetch externe | statique |
+| A-3 | le code UI | `window.parent.*` ou `localStorage` direct | tout passe par le bridge, CSP double-iframe respectée | statique |
+| A-4 | le résultat `axe-core` en CI | une violation WCAG AA bloquante | 0 violation bloquante | statique + gate |
+| A-5 | la taille du bundle (statique) + render/roundtrip (sonde) | bundle > 250 KB gz, render > 1s, roundtrip p95 > 500ms, mémoire > 50 MB | sous tous les budgets | statique + dynamique |
+| A-6 | la clé imbriquée `_meta.ui.resourceUri` | forme plate `_meta["ui/resourceUri"]` ou id communautaire `io.modelcontextprotocol/ui` en écriture | clé GA imbriquée via `registerAppTool` | statique + gate |
+| A-7 | la logique de gate de l'App/hôte | un outil destructif ou non annoté auto-exécuté sans confirmation | confirmation humaine explicite avant un tel appel, jamais conditionnée sur `destructiveHint=false` seul | statique |
+
+### Traçabilité — règles App → source
+
+Chaque règle nomme sa source, une cellule non vide par règle.
+
+| Règle | Source |
+|---|---|
+| A-1..A-6 | source une — nos produits + standard GA MCP Apps `2026-07-28` (clé `_meta.ui.resourceUri`, bundle single-file, bac à sable double-iframe) |
+| A-7 | pratique — spec MCP 2025-06-18 `server/tools` §User Interaction Model |
+
+---
+
+## Principe directeur
+
+Une MCP App retourne une UI interactive rendue dans le client (Claude web/desktop, ChatGPT, VS Code Insiders, Goose, Postman, MCPJam). Le standard GA (`2026-07-28`) lie la ressource UI à son tool via la clé imbriquée `_meta.ui.resourceUri`, écrite par `registerAppTool`. Les formes plates et l'ancien id communautaire sont DÉPRÉCIÉS : tolérés en lecture pour rétrocompat, refusés en écriture (`A-6`). C'est un produit visuel — la qualité d'exécution UI distingue un serveur moyen d'un serveur qui convertit.
+
+---
+
+## File structure
+
+```
+mcp-app-name/
+├── .claude-plugin/plugin.json
+├── src/
+│   ├── index.ts                 # MCP server entry — register tools + UI resources
+│   ├── server.ts
+│   ├── tools/                   # Tools qui retournent ui:// resources
+│   ├── ui/
+│   │   ├── components/          # React / Vue / Svelte
+│   │   ├── styles/
+│   │   ├── i18n/                # en.json + fr.json (tronc §5.1)
+│   │   └── entry.tsx
+│   ├── schemas/
+│   └── lib/
+├── tests/                       # unit / component / integration / a11y / visual
+├── evals/evals.json             # (tronc §5.5, cas "client sans support UI" — C-5)
+├── docs/                        # README.md, README.fr.md, ui-spec.md, architecture.md
+├── vite.config.ts               # Bundle single-file (A-2)
+├── package.json
+├── mcp.json
+└── CHANGELOG.md
+```
+
+Seuls `src/ui/`, `src/tools/*render*`, et `vite.config.ts` sont propres à l'App ; le socle serveur (`server.ts`, `mcp.json`, transport, protocole) obéit au complément serveur, et l'arborescence commune au tronc.
+
+---
+
+## UI components supported
+
+| Catégorie | Composants ElPi Corp standardisés |
+|---|---|
+| **Display** | Cards, KPI tiles, Tables interactives, Lists |
+| **Charts** | Mermaid, Recharts (line/bar/pie/scatter), Heatmaps |
+| **Visualisations 3D** | Three.js, CesiumJS (cas vantage-radar) |
+| **Forms** | Inputs, selects, multi-step wizards, file upload |
+| **Media** | PDF viewer, image viewer, audio player, video player |
+| **Layout** | Tabs, accordions, modals, drawers |
+| **Feedback** | Toast, progress bars, loading states |
+
+Frameworks autorisés : React (default), Vue, Svelte, Preact, Solid, vanilla. Pas d'Angular (lourdeur bundle). Stack default : **React 19 + Tailwind v4 + lit-ui**.
+
+---
+
+## Component definitions
+
+```ts
+// src/tools/render-dashboard.ts
+import { z } from "zod";
+import { renderUiResource } from "@modelcontextprotocol/ext-apps/server";
+
+export const inputSchema = z.object({
+  scoreRange: z.tuple([z.number(), z.number()]).default([0, 100]),
+  locale: z.enum(["en", "fr"]).default("en")
+});
+
+export const tool = {
+  name: "render_dashboard",
+  description: "Render the vantage-radar 9-angles dashboard. Use this whenever the user asks for a 'dashboard', 'visual report', or 'matrix view' — even if they don't say 'render' explicitly.",
+  inputSchema,
+  handler: async (input) => {
+    const data = await loadDashboardData(input);
+    const fallbackMarkdown = renderMarkdownFallback(data);   // A-1
+    const ui = await renderUiResource({ bundlePath: "dist/ui/dashboard.html", props: { data, locale: input.locale } });
+    return { content: [ { type: "text", text: fallbackMarkdown }, { type: "resource", resource: ui } ] };
+  }
+};
+```
+
+Le nommage, les schémas, l'écriture de la description bilingue obéissent au tronc (`C-2`, `C-4`, §5.7). Règles propres à l'App : bundle = single HTML file (`A-2`) ; props via `window.__MCP_PROPS__` ; aucun fetch externe au runtime.
+
+### Clé UI GA imbriquée (`A-6`)
+
+`renderUiResource()` attache la forme **nested** `_meta.ui` — jamais la clé plate `_meta["ui/resourceUri"]`, deprecated :
+
+> « **Deprecation notice:** The flat `_meta["ui/resourceUri"]` format is deprecated. Use `_meta.ui.resourceUri` instead. The deprecated format will be removed before GA. » (apps.mdx line 347)
+
+```ts
+// resources/list handler — forme nested obligatoire
+{
+  uri: `ui://vp/v1/${primitive}`,
+  name: primitive,
+  mimeType: "text/html;profile=mcp-app",
+  _meta: { ui: DEFAULT_UI_META }   // ← nested, jamais _meta["ui/resourceUri"]
+}
+```
+
+Toute App qui n'utilise pas `renderUiResource()` reproduit cette forme nested à l'identique — un server qui émet la clé plate est sur un chemin de suppression avant la GA.
+
+---
+
+## Render lifecycle
+
+1. **Déclaration** — le tool déclare une ressource `ui://` et la lie via `_meta.ui.resourceUri` (`A-6`).
+2. **Exécution** — le LLM appelle le tool.
+3. **Rendu** — le client récupère et affiche la ressource dans un iframe sandboxé ; communication bidirectionnelle via `postMessage` / JSON-RPC.
+
+Lors du handshake `initialize`, le serveur déclare `extensions: ["io.modelcontextprotocol/ui"]` (voir `mcp-server-standard.md`, `mcp.json`). Si le client ne supporte pas l'extension, le serveur retourne uniquement `content[type=text]` (repli markdown, `A-1`). Aucune erreur côté client.
+
+---
+
+## Double-iframe sandbox-proxy CSP model
+
+Spec source : `specification/2026-01-26/apps.mdx`, `modelcontextprotocol/ext-apps` (lines 109-163, 413-485, 1233-1325). Le rendu passe par **deux iframes imbriquées**.
+
+Une iframe **outer** (« sandbox-proxy ») négocie le handshake avec le host, puis charge une iframe **inner** sandboxée qui porte le contenu HTML du `ui://`. La CSP appliquée à l'inner est dérivée, par ressource, des métadonnées déclarées par le tool — elle n'est pas statique.
+
+| Métadonnée resource | Directive CSP inner iframe |
+|---|---|
+| `csp.connectDomains` | `connect-src` |
+| `csp.resourceDomains` | `img-src`, `script-src`, `style-src`, `font-src`, `media-src` |
+| (domaines autorisés à s'embarquer) | `frame-src` |
+| `csp.baseUri` | `base-uri` |
+
+### Règles
+
+- Le host MUST enforcer la CSP dérivée (apps.mdx line 274).
+- Le host SHOULD logger la config CSP appliquée pour audit (apps.mdx line 287).
+- Toute App déclarant des domaines externes (images, fonts, scripts tiers) les déclare explicitement dans `csp.connectDomains` / `csp.resourceDomains` — un domaine non déclaré est bloqué par construction.
+- Ce modèle est strictement plus strict que le bac à sable simple de `A-3` ; il s'y ajoute.
+
+---
+
+## Interaction model + state
+
+Le bridge `@modelcontextprotocol/ext-apps/app-bridge` expose une API JSON-RPC bidirectionnelle.
+
+```ts
+import { useBridge } from "@modelcontextprotocol/ext-apps/react";
+function ScoreSlider() {
+  const bridge = useBridge();
+  const onChange = (value: number) => bridge.callTool("update_threshold", { value });
+  return <input type="range" onChange={/* … */} />;
+}
+```
+
+- Toute interaction qui mute l'état serveur → `bridge.callTool`. Toute mutation locale (UI state, animations) → state local.
+- Pas de side-effect direct (fetch externe, localStorage) sans passer par le bridge (`A-3`).
+- Latence cible round-trip bridge : < 500ms p95 (`A-5`).
+
+| Niveau d'état | Lieu | Use case |
+|---|---|---|
+| **Server state** | MCP server | Source of truth métier |
+| **UI state** | React/Vue local | Animations, hover, focus, accordions |
+| **Bridge cache** | `@modelcontextprotocol/ext-apps` | Réponses tool récentes, dédoublonnage |
+
+Le serveur EST le store : pas de Redux/Zustand pour l'état métier, pas de duplication server↔UI. Optimistic UI autorisé pour les mutations à faible enjeu.
+
+---
+
+## Accessibility (WCAG AA — `A-4`)
+
+- Sémantique HTML native (button, nav, section, table) — pas de `<div onClick>`.
+- ARIA labels obligatoires sur tout interactif non-évident.
+- Contraste AA (4.5:1 texte normal, 3:1 texte large).
+- Navigation clavier complète, focus visible.
+- Screen reader : test minimum VoiceOver (macOS) ou NVDA (Windows) sur le flux principal.
+- `prefers-reduced-motion` respecté.
+- `axe-core` en CI, 0 violation bloquante.
+
+---
+
+## Performance constraints (`A-5`)
+
+| Métrique | Cible | Mesure |
+|---|---|---|
+| Bundle size (gzipped) | < 250 KB | `vite build` size-limit |
+| Initial render | < 1s LAN | Playwright trace |
+| Tool roundtrip via bridge | < 500ms p95 | Tracing custom |
+| Memory steady-state | < 50 MB | DevTools profiler |
+
+Code splitting par composant lourd, lazy load des charts/3D/éditeurs, target ES2022, images AVIF/WebP ou SVG inline.
+
+---
+
+## Testing (spécifique App)
+
+Au-delà des tests communs (tronc §5.2) :
+
+- **Component** : Vitest + Testing Library, ≥ 1 test par composant exposé, ≥ 1 test par locale.
+- **Integration (MCP roundtrip)** : spawn server stdio + client mock + render bundle dans Playwright headless. Assert : tool appelé → resource `ui://` retournée → composant rendu → interaction → callback tool reçu.
+- **Accessibility** : `axe-core` en CI, 0 violation bloquante (`A-4`) ; screen reader manuel par release majeure.
+- **Visual regression** : Playwright screenshot diffs, threshold 1 % pixel diff.
+- **Eval suite** (`C-5`, tronc) : les 3 cas incluent le cas dégradé « client sans support UI → fallback markdown » (`A-1`) et le cas erreur « data manquante → état d'erreur UI lisible ».
+
+---
+
+## Examples — Elastic case study (référence du benchmark)
+
+Elastic a publié 3 MCP Apps (Security, Observability, Search) — premier cas production-grade documenté.
+
+- **Security** : triage alertes SOC, dashboards inline avec entités cliquables, timelines. Node.js server, React UI, single-file bundle.
+- **Observability** : diagnostic SRE, graphes de topologie interactifs, drill-down par service. Reuse ElPi Corp : drill-down hiérarchique pour vantage-radar (9 angles → score → sources → preuves).
+- **Search** : création de dashboards en langage naturel, éditeur drag-and-drop. Reuse : pattern « natural language to UI ».
+
+**Patterns à répliquer** : bundle single-file, fallback markdown systématique, drill-down hiérarchique, entités cliquables qui re-trigger des tools. **Anti-patterns** : setup multi-étapes, mauvaise traduction auto FR, UI sans fallback texte, monétisation prématurée.
+
+---
+
+## ElPi Corp additions (au-delà de la spec MCP Apps)
+
+- **SELLABLE AS** dans le README — chaque App cible un nom de plugin marketplace.
+- **VantageRegistry registration** : `register_component` category `mcp-app` à chaque release (`C-14`, tronc §5.6).
+- **Stack canonique** : React 19 + Tailwind v4 + lit-ui + Recharts + axe-core. Tout fork justifie son écart.
+- **Bilingual i18n shared package** : `@elpi/mcp-app-i18n` pour partager les strings entre apps du même domaine.
+- **Premier candidat pilote** : vantage-radar Phase 2 (matrice 9 angles + scores en MCP App). Économie estimée vs web app séparée : 3-6 semaines de dev frontend.

package/fixtures/mcp-extension-standard-a74a042b.md

@@ -0,0 +1,259 @@
+# MCP Extension Standard — Complément extension
+
+Version : v2.1 — 2026-08-16. Protocole visé `2026-07-28`, plancher `2025-06-18`. Table de détecteurs + table de source E-1..E-6.
+Owner : gamma
+Status : en vigueur — non déclaré fini tant que l'opérateur ne l'a pas dit.
+Référence parent : `resources/references/mcp-standard.md` (le tronc).
+
+Source canonique : `resources/references/mcp-extension-standard.md`. **Ce document est un complément.** Il ne porte QUE ce qui est propre à une extension MCP — identifier, dégradation gracieuse, unicité de type, hooks de cycle de vie, absence d'effet global, timeouts. Tout le reste — bilinguisme (`C-1`), SemVer (`C-3`), suite d'évaluation dont le cas dégradé (`C-5`), et les déclarations de la surface servie (`C-8` à `C-11`) — vit dans le tronc et ne se réécrit jamais ici.
+
+**Ce que gouverne ce document** : une extension MCP, c'est-à-dire un composant additionnel qui étend un serveur existant sans en modifier le code source — middleware, tool extension, ou transport adapter. **Où passe la frontière** : le serveur hôte porte le protocole (`server/discover`, `resultType`, autorisation — voir `mcp-server-standard.md`) ; l'extension ne fait que respecter le contrat du résultat qu'elle intercepte et ne casse jamais le serveur qui l'embarque.
+
+---
+
+## Règles propres à l'extension (`E-1` à `E-6`)
+
+1. **`E-1` — Identifier reverse-DNS unique.** Préfixe `com.elpi/`, `com.<bu>/`, ou identifier officiel MCP (`io.modelcontextprotocol/*`). Collision = refus de publication.
+2. **`E-2` — Dégradation gracieuse toujours `true`.** Une extension ne casse JAMAIS le serveur hôte. Un client qui ne déclare pas l'extension voit le serveur fonctionner normalement. `graceful_degradation: true` dans `extension.json`, sans exception.
+3. **`E-3` — Une extension = un type** (middleware XOR tool-extension XOR transport). Pas de mix. `extension.json.type` a une cardinalité de 1.
+4. **`E-4` — Hooks déclarés = hooks implémentés.** Le champ `lifecycle` de `extension.json` correspond exactement aux fonctions de hook exportées. Pas de hook fantôme, pas de hook implémenté non déclaré.
+5. **`E-5` — Aucune mutation de l'identifier d'une autre extension, aucun effet global.** Sandboxé par contexte. Une extension ne modifie ni l'état ni l'identité d'une autre.
+6. **`E-6` — Timeouts respectés.** Un hook qui dépasse son timeout est skipped avec un warning log, jamais un blocker du serveur hôte. Défauts : `init` 5s, `beforeCall`/`afterCall` 1s, `onError` 500ms — surchargés via `extension.json.timeouts`.
+
+### Traçabilité — règles extension → objectifs
+
+| Règle | production | entreprise | sécurité | jetons | cloisonnement |
+|---|:---:|:---:|:---:|:---:|:---:|
+| E-1 identifier reverse-DNS unique | ✓ | ✓ | | | |
+| E-2 dégradation gracieuse toujours vraie | ✓ | | | | |
+| E-3 une extension = un type | | ✓ | | | |
+| E-4 hooks déclarés = hooks implémentés | ✓ | ✓ | | | |
+| E-5 aucune mutation d'identifier, aucun effet global | | | ✓ | | ✓ |
+| E-6 timeouts respectés | ✓ | | | | |
+
+**Objectif faiblement servi côté extension : token-efficient.** Aucune des six règles propres ne borne ce qu'une extension ajoute au contexte — la surface qu'un middleware injecte dans une réponse, le coût des tools qu'une tool-extension ajoute au catalogue du serveur hôte. Cette borne est portée par le tronc : une tool-extension qui ajoute des tools est soumise à `C-13` (plafond de contexte) au même titre que le serveur hôte, et son `tokens_estime_contexte` compte dans le plafond du catalogue composé.
+
+### Spécifications de détecteur (règles extension `E-1`..`E-6`)
+
+L'instrument reste gelé ; on spécifie ce qu'un détecteur lira. La colonne Genre porte le jeu fermé du tronc §5.2 — **`statique`** · **`dynamique`** · **`gate`**, seuls ou combinés par `+` — et rien d'autre (pour une extension, `statique` lit l'arbre + `extension.json` ; `dynamique` observe l'extension greffée sur un serveur hôte en marche). La part non mécanique se lit dans les colonnes Rouge/Vert, jamais dans Genre.
+
+| Règle | Le check lit | Rouge | Vert | Genre |
+|---|---|---|---|---|
+| E-1 | l'`identifier` de `extension.json` | id reverse-DNS absent, mal formé, ou en collision | id reverse-DNS unique et valide (`com.elpi/`, `com.<bu>/`, `io.modelcontextprotocol/*`) | statique |
+| E-2 | `extension.json.graceful_degradation` + le comportement du serveur hôte sans l'extension | `graceful_degradation ≠ true`, ou le serveur hôte casse quand le client ne déclare pas l'extension | `true` + serveur hôte fonctionnel sans l'extension | statique + dynamique |
+| E-3 | `extension.json.type` | `type` absent ou de cardinalité > 1 (mix middleware/tool/transport) | exactement un type | statique |
+| E-4 | le champ `lifecycle` vs les fonctions de hook exportées | un hook déclaré non exporté, ou un hook exporté non déclaré | correspondance exacte déclaré ↔ implémenté | statique |
+| E-5 | les écritures de l'extension vers l'identité/l'état d'une autre | mutation de l'identifier ou de l'état d'une autre extension ; effet global | sandboxé par contexte, aucun effet hors de soi | statique |
+| E-6 | la gestion des timeouts de hook | un hook dépassant son timeout bloque le serveur hôte au lieu d'être skippé + warn | skip + warning log, aux défauts déclarés (`init` 5s, etc.) ou surcharges `extension.json.timeouts` | dynamique |
+
+### Traçabilité — règles extension → source
+
+Chaque règle nomme sa source, une cellule non vide par règle.
+
+| Règle | Source |
+|---|---|
+| E-1..E-6 | source une — nos produits + délta de spec `2026-07-28` sur le contrat d'extension (`extension.json`, cycle de vie des hooks, négociation par capability `extensions`) |
+
+---
+
+## 2026-07-28 protocol delta — impact sur les extensions
+
+Changement par changement, ce qui touche réellement le contrat des extensions.
+
+### S'applique aux extensions
+
+- **`resultType` préservé** ([SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322)). Un middleware dont `afterCall` mute `ctx.output` DOIT préserver le champ `resultType` du résultat original — jamais le stripper ni le retyper. Casser `resultType` casse la négociation MRTR du serveur hôte.
+- **`CacheableResult` sur les listes** ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)). Une tool-extension qui ajoute des tools à `tools/list` fournit `ttlMs`/`cacheScope` cohérents avec la réponse composée. Un middleware de caching respecte `cacheScope: "private"` par défaut et ne promeut jamais un résultat `"private"` en `"public"`.
+- **Négociation par capability `extensions`** — confirmée stable dans `2026-07-28` (minor change #1). Le mécanisme d'identifier (`extensions: ["io.modelcontextprotocol/ui"]`) est inchangé.
+- **Streamable HTTP sans session** ([SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567), [SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)) — UNIQUEMENT la catégorie transport adapter. Ne plus s'appuyer sur `Mcp-Session-Id` ni un état par connexion ; tout état inter-appels transite par un handle serveur explicite. `minProtocolVersion` reste `2025-06-18`.
+- **Dépréciation HTTP+SSE** ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)) — tout transport adapter SSE migre vers Streamable HTTP avant la fin de la fenêtre (12 mois minimum).
+
+### Hors-scope pour les extensions (explicitement)
+
+- **`server/discover` RPC** ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)) — responsabilité du serveur HÔTE (`S-4`). L'extension expose son plancher via `extension.json.compatibility.minProtocolVersion`, mécanisme inchangé.
+- **Suppression handshake `initialize` / stateless par-requête** — concerne le protocole client↔serveur hôte. Les hooks `beforeCall`/`afterCall` opèrent sur le `ctx` déjà résolu, ne participent pas au handshake.
+- **Dépréciation Roots/Sampling/Logging** ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)) — feature de capability serveur, aucun hook de ce standard ne l'implémente.
+- **MRTR / `InputRequiredResult`** au-delà du champ `resultType` (ci-dessus) — orchestration portée par le serveur hôte et le client.
+
+---
+
+## File structure
+
+```
+mcp-extension-name/
+├── .claude-plugin/plugin.json
+├── src/
+│   ├── index.ts                 # Entry point — exporte la factory + identifier
+│   ├── extension.ts             # Implémentation principale
+│   ├── hooks/                   # before-call.ts, after-call.ts, on-error.ts
+│   ├── i18n/                    # Table de locales (tronc §5.1)
+│   └── lib/
+├── tests/                       # unit / integration (composition) / fixtures (tronc §5.2)
+├── evals/evals.json             # (tronc §5.5, cas dégradé "extension absente" — C-5)
+├── docs/                        # README.md, README.fr.md, compose.md
+├── examples/                    # basic.ts, stack.ts
+├── package.json
+├── extension.json               # Manifest extension (propre à l'extension)
+├── LICENSE
+└── CHANGELOG.md
+```
+
+Seuls `src/extension.ts`, `src/hooks/`, `examples/`, et `extension.json` sont propres à l'extension ; le reste obéit au tronc.
+
+---
+
+## Extension types (3 catégories)
+
+### 1. Middleware
+
+Intercepte requests / responses. Use cases : logging, rate limiting, caching, retries, redaction PII, traduction FR↔EN, audit trail.
+
+```ts
+import { defineMiddleware } from "@elpi/mcp-extension-sdk";
+
+export default defineMiddleware({
+  identifier: "com.elpi/middleware-redact-pii",
+  beforeCall: async (ctx) => { ctx.input = redactPII(ctx.input); return ctx; },
+  afterCall:  async (ctx) => { ctx.output = redactPII(ctx.output); return ctx; }
+});
+```
+
+### 2. Tool extension
+
+Ajoute des tools à un serveur existant sans modifier son code. Les tools ajoutés obéissent au tronc : nommage (`C-2`), schémas (`C-4`), description bilingue (`C-1`, §5.7), autorité/verbe/mécanisme/pagination déclarés (`C-8` à `C-11`).
+
+```ts
+import { defineToolExtension } from "@elpi/mcp-extension-sdk";
+
+export default defineToolExtension({
+  identifier: "com.elpi/github-mcp-fr-helpers",
+  baseServer: "github/github-mcp-server",
+  tools: [ { name: "summarize_pr_fr", description: "…", inputSchema, outputSchema, handler } ]
+});
+```
+
+### 3. Transport adapter
+
+Transport custom (SSE, WebSocket, ZeroMQ, named pipes). Use case : intégrations enterprise, air-gapped, bridges vers clients non-MCP. Un adapter Streamable HTTP suit le délta `2026-07-28` (sans session, ci-dessus).
+
+```ts
+import { defineTransport } from "@elpi/mcp-extension-sdk";
+
+export default defineTransport({
+  identifier: "com.elpi/transport-websocket",
+  open: async (config) => { /* … */ }, send: async (m) => { /* … */ },
+  receive: async () => { /* … */ }, close: async () => { /* … */ }
+});
+```
+
+---
+
+## Manifest — extension.json
+
+```json
+{
+  "identifier": "com.elpi/<reverse-dns-style>",
+  "name": "mcp-extension-name",
+  "version": "0.1.0",
+  "type": "middleware|tool-extension|transport",
+  "description": "EN description.",
+  "description_fr": "Description FR.",
+  "compatibility": {
+    "minProtocolVersion": "2025-06-18",
+    "compatibleServers": ["*"],
+    "incompatibleWith": []
+  },
+  "lifecycle": ["init", "before_call", "after_call", "on_error", "shutdown"],
+  "graceful_degradation": true,
+  "ui_extension_id": null
+}
+```
+
+### Validation rules (propres à l'extension)
+
+| Champ | Règle |
+|---|---|
+| `identifier` | Reverse-DNS unique (`E-1`). |
+| `type` | Une et une seule des 3 catégories (`E-3`). |
+| `compatibleServers` | Glob patterns (`["*"]` = universel). |
+| `graceful_degradation` | Toujours `true` (`E-2`). |
+| `lifecycle` | Correspond **exactement** aux hooks réellement implémentés — aucun hook déclaré non exporté, aucun hook exporté non déclaré (`E-4`). |
+
+*(le nommage du `name`, la description bilingue, la version obéissent au tronc — `C-2`, `C-1`, `C-3`.)*
+
+---
+
+## Lifecycle hooks
+
+```ts
+type Lifecycle = {
+  init?: (ctx: ServerContext) => Promise<void>;
+  beforeCall?: (ctx: CallContext) => Promise<CallContext>;
+  afterCall?: (ctx: CallContext) => Promise<CallContext>;
+  onError?: (ctx: ErrorContext) => Promise<ErrorContext | void>;
+  shutdown?: () => Promise<void>;
+};
+```
+
+- `init` : une fois au boot, idempotent. Échec = extension désactivée + warning + serveur continue (`E-2`).
+- `beforeCall` : peut muter `ctx.input`, doit retourner le contexte. Throw = abort de l'appel.
+- `afterCall` : peut muter `ctx.output`, doit retourner le contexte. Préserve `resultType` (délta ci-dessus).
+- `onError` : transforme ou avale une erreur ; `void` = erreur originale propagée.
+- `shutdown` : best-effort, pas garanti en kill -9.
+
+**Timeouts (`E-6`)** : `init` 5s, `beforeCall`/`afterCall` 1s, `onError` 500ms. Au-delà : warning, hook skip, exécution continue — jamais un blocker.
+
+---
+
+## Composition (plusieurs extensions sur un serveur)
+
+```
+Client request
+   ↓
+[ext1.beforeCall] → [ext2.beforeCall] → [ext3.beforeCall]
+   ↓  Tool handler  ↓
+[ext3.afterCall] → [ext2.afterCall] → [ext1.afterCall]
+   ↓
+Client response
+```
+
+LIFO sur `afterCall` : la première extension chargée est la dernière à transformer la sortie.
+
+### Règles de composition
+
+- Ordre déclaratif dans la config serveur (pas de magic).
+- Aucune dépendance implicite : si une extension dépend d'une autre, le déclarer dans `extension.json.requires`.
+- Conflit d'identifier : erreur fatale au boot.
+- Une extension ne mute JAMAIS l'identifier d'une autre — sandboxé par contexte (`E-5`).
+
+---
+
+## Examples — patterns clés
+
+### Middleware « redact-pii » (interne ElPi Corp)
+
+Hooks `beforeCall` (input scrubbing) + `afterCall` (output scrubbing). Compatible `["*"]`. Distribution npm `@elpi/mcp-ext-redact-pii`.
+
+### Tool extension « github-mcp-fr-helpers »
+
+Étend `github/github-mcp-server` avec `summarize_pr_fr`, `triage_issues_fr`, `weekly_digest_fr`. Compatible `["github/github-mcp-server@^1.0"]`. SELLABLE AS `perello-github-fr`.
+
+### Transport « websocket » (référence officielle)
+
+Identifier `io.modelcontextprotocol/transport-websocket` (officiel) ou `com.elpi/transport-websocket`. Use case : bridge MCP → frontend web. Hors scope Phase 1.
+
+### Composition ElPi Corp standard
+
+```
+[redact-pii] → [rate-limit-token-bucket] → [logger-structured]
+```
+
+Chaque extension est un repo séparé, distribuable séparément. L'orchestrateur compose dans la config serveur.
+
+---
+
+## ElPi Corp additions (au-delà de la spec MCP)
+
+- **SELLABLE AS** dans le README — chaque extension cible un nom de plugin marketplace.
+- **VantageRegistry registration** : `register_component` category `mcp-extension` à chaque release stable (`C-14`, tronc §5.6).
+- **Stack reference** : ElPi Corp publie une stack canonique (redact-pii + rate-limit + logger) que tout serveur commercial embarque par défaut.