@vantageos/mcp-boilerplate 0.1.2 → 0.2.0

package/.claude-plugin/plugin.json

@@ -1,16 +1,18 @@
 {
   "name": "vantage-mcp-boilerplate",
-  "version": "0.1.2",
-  "description": "Clonable dual-transport MCP server template (stdio + Streamable HTTP, stateless) on the official @modelcontextprotocol/sdk, with protocol-kit result types, OAuth 2.1 auth + public tier, multi-tenant JWT scoping, MCP Apps UI extension, server-side FR/EN i18n, and a declarative eval harness. Scaffold, extend, publish.",
-  "description_fr": "Template de serveur MCP clonable a double transport (stdio + Streamable HTTP, stateless) sur le @modelcontextprotocol/sdk officiel, avec types de resultats protocol-kit, auth OAuth 2.1 + tier public, scoping multi-tenant par JWT, extension UI MCP Apps, i18n FR/EN cote serveur, et un harnais d'evaluations declaratif. Scaffolder, etendre, publier.",
-  "author": "ElPi Corp / Laurent Perello",
+  "displayName": "VantageOS MCP Boilerplate",
+  "version": "0.2.0",
+  "description": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
+  "author": {
+    "name": "ElPi Corp / Laurent Perello"
+  },
+  "homepage": "https://github.com/elpiarthera/vantage-mcp-boilerplate#readme",
+  "repository": "https://github.com/elpiarthera/vantage-mcp-boilerplate",
   "license": "MIT",
-  "homepage": "https://github.com/elpiarthera/vantage-mcp-boilerplate",
-  "category": "mcp-server",
-  "bilingual": true,
   "keywords": [
     "mcp",
     "claude-code",
+    "chatgpt",
     "boilerplate",
     "starter",
     "template",
@@ -18,8 +20,14 @@
     "streamable-http",
     "oauth",
     "multi-tenant",
+    "mcp-apps",
     "i18n",
     "vantage",
     "elpi"
-  ]
+  ],
+  "metadata": {
+    "description_fr": "Template de serveur MCP clonable : SDK v2 sur le protocole 2026-07-28 (stdio + Streamable HTTP sans état), serveur d'autorisation OAuth 2.1 propre (personne + organisation Clerk), UI MCP Apps, i18n FR/EN et un harnais d'évaluations déclaratif. Scaffolder, étendre, publier.",
+    "category": "mcp-server",
+    "bilingual": true
+  }
 }

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "mcp-boilerplate": {
+      "type": "http",
+      "url": "${MCP_BOILERPLATE_URL:-https://your-server.example.com/mcp}"
+    }
+  }
+}

package/CHANGELOG.md

@@ -7,6 +7,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-10
+
+SDK v2 / protocol 2026-07-28 migration, own authorization server, MCP Apps + ChatGPT
+metadata, generated packaging manifests. Breaking for forks that import the removed SDK.
+
+### Changed
+
+- **BREAKING**: `@modelcontextprotocol/sdk` replaced by `@modelcontextprotocol/server`
+  ^2.3.1 (`@modelcontextprotocol/client` ^2.3.1 as a devDependency); Zod ^4.4.3 everywhere
+  (the `zod` / `zod/v4` mix is gone); `@modelcontextprotocol/ext-apps` ^2.0.3;
+  `@vantageos/cloud-identity` ^0.15.0, now the ONLY identity layer: its resource-server
+  entry point (`verifyMcpAccessToken`, `buildProtectedResourceMetadata`) replaces
+  `@vantageos/mcp-auth-kit`. `AuthConfig.jwks` is a `{ keys }` JWK set or a function returning
+  one (the external-issuer tier fetches and caches it); an unreachable key set answers 503,
+  never 401. `jose` remains for minting only.
+- HTTP is `createMcpHandler(factory)` and stdio is `serveStdio(factory)`: one factory serves
+  the 2026-07-28 era (`server/discover`) and the 2025 era (`initialize`). The 2025 floor is
+  2025-06-18 (`supportedProtocolVersions`). `ttlMs` / `cacheScope` come from the SDK's
+  `cacheHints`. Legacy HTTP responses are now server-sent-event framed.
+- The advertised server version is derived from `package.json` (was the literal `0.1.0`).
+- `tenancy.ts` leaves the deprecated `scopeFilterList` for cloud-identity's `isRowInTenant`:
+  rows are selected by their stored `orgId` (added to `ExampleItem`), never by a creator name.
+- `render_items_ui` now refuses an organisation-less caller on the OAuth tier, like
+  `list_items` (it used to fall through to the unscoped items).
+- `.claude-plugin/plugin.json`: `description_fr`, `category`, `bilingual` moved under `metadata`.
+- `docs/architecture.md`: wire posture rewritten; the false "no auth here" section removed.
+
+### Added
+
+- Own OAuth 2.1 authorization server (`src/oauth/`): `/authorize`, `/authorize/callback`,
+  `/authorize/org` (person + organisation picker, FR/EN), `/token` (PKCE S256), `/register`
+  (DCR fallback), CIMD client ids (SSRF-guarded), RFC 8414 metadata, `/.well-known/jwks.json`,
+  `/userinfo`, RFC 9207 `iss`, PRM at `/.well-known/oauth-protected-resource/mcp`. Decisions
+  delegated to cloud-identity; missing configuration answers 503. Code store and client registry
+  are interfaces with in-memory adapters (`docs/oauth-stores.md`).
+- Tool records: `title`, the four annotations as explicit booleans, input AND output schemas,
+  `structuredContent` plus a same-JSON text block on all three tools.
+  `tests/toolRecordComplete.test.ts` fails on any gap.
+- MCP Apps: resource `_meta.ui` (`csp` four domain arrays, `prefersBorder`, `domain` from
+  `MCP_UI_DOMAIN`), explicit tool `visibility`, additive `openai/outputTemplate` and
+  `openai/toolInvocation/*` keys, the resource-read locale taken from the caller.
+- Packaging generated from one source (`scripts/plugin-manifest.source.json`): `.mcp.json`,
+  OpenAI `plugin.json` + `mcp.json`, onboarding skill `skills/connect-mcp-server/SKILL.md`,
+  `scripts/generate-signing-key.mjs`, `examples/oauth.env.example`.
+
+### Removed
+
+- `@vantageos/mcp-protocol-kit` dependency: the SDK emits `resultType` / cache fields itself.
+- The private `_requestHandlers` access and the hand-rolled `server/discover` request schema.
+
+### Known
+
+- Per-organisation API keys for non-ChatGPT clients were never part of this code; not added.
+
 ## [0.1.2] - 2026-08-07
 
 Two derive-never-type fixes, released together.
@@ -50,7 +104,7 @@ Initial published release.
   `@modelcontextprotocol/sdk` transports: stdio (`StdioServerTransport`) and
   stateless Streamable HTTP (`WebStandardStreamableHTTPServerTransport`).
 - `@vantageos/mcp-protocol-kit` wiring for shared result types.
-- OAuth 2.1 resource-server auth layer (`@vantageos/mcp-auth-kit`), with a
+- OAuth 2.1 resource-server auth layer (since replaced, see 0.2.0), with a
   public no-auth tier alongside the authenticated tier.
 - Multi-tenant scoping layer with proven tenant isolation.
 - MCP Apps UI extension: `ui://` resource serving a bundled widget

package/README.fr.md

@@ -1,95 +1,146 @@
 # @vantageos/mcp-boilerplate
 
-Un squelette de serveur MCP clonable : bootstrap double-transport (stdio +
-Streamable HTTP, sans état) construit exclusivement sur les transports
-officiels du [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk).
-Aucune route REST personnalisée ne se place jamais devant un appel d'outil.
+VENDABLE SOUS : `mcp-boilerplate` — un starter de serveur MCP clonable pour la marketplace Claude Code / le catalogue VantageRegistry et pour ChatGPT, publié sous `@vantageos/mcp-boilerplate` sur npm.
 
-Ceci est une fondation, pas un produit fini : il embarque un outil d'exemple
-trivial (`ping`) dont le seul but est de prouver que la poignée de main MCP
-fonctionne sur les deux transports. Les couches ultérieures (types de résultat
-protocol-kit, authentification, scoping multi-tenant, extensions UI, i18n) se
-construisent au-dessus de ce bootstrap sans modifier le câblage du transport.
+Un squelette de serveur MCP clonable sur le SDK officiel
+[`@modelcontextprotocol/server`](https://www.npmjs.com/package/@modelcontextprotocol/server)
+v2 : protocole **2026-07-28** avec la poignée de main 2025 toujours servie, stdio
+et Streamable HTTP sans état depuis une seule définition de serveur, son **propre
+serveur d'autorisation OAuth 2.1** (une personne Clerk choisit une organisation),
+une UI MCP Apps et des messages FR/EN. Aucune route REST personnalisée ne se place
+jamais devant un appel d'outil.
+
+Il embarque trois petits outils d'exemple (`ping`, `list_items`, `render_items_ui`)
+qui exercent chaque couche. Remplacez-les par les vôtres ; le câblage reste.
 
 ## Structure
 
 ```
 src/
   mcpServerFactory.ts   # définition unique du serveur MCP, partagée par les deux transports
-  stdio.ts              # point d'entrée StdioServerTransport du SDK officiel
+  version.ts            # nom + version du serveur, dérivés de package.json
+  stdio.ts              # serveStdio(factory) : les deux ères du protocole sur stdio
   http.ts               # adaptateur Node http.Server autour de l'app Hono
-  httpApp.ts            # WebStandardStreamableHTTPServerTransport du SDK officiel (sans état)
-  auth.ts               # câblage OAuth 2.1 resource-server (@vantageos/mcp-auth-kit)
-  config.ts             # chargeurs AuthMode + AuthConfig dérivés de l'environnement
-  index.ts              # exports du package
-tests/
-  helpers/mcpRpc.ts      # helpers de requête JSON-RPC pour le transport HTTP
-  helpers/authFixtures.ts # fixtures de signature JWT RS256 réservées aux tests
-  httpHandshake.test.ts  # initialize -> tools/list -> tools/call sur Streamable HTTP
-  stdioHandshake.test.ts # même poignée de main sur un vrai process enfant stdio
-  oauth.test.ts          # les deux paliers d'authentification : gate oauth + palier public sans auth
-docs/
-  architecture.md        # posture du protocole : version au niveau outil vs au niveau transport
+  httpApp.ts            # createMcpHandler(factory) sur /mcp + la barrière OAuth
+  auth.ts               # câblage resource-server (@vantageos/cloud-identity)
+  config.ts             # AuthMode + AuthConfig d'émetteur externe, dérivés de l'environnement
+  tenancy.ts            # JWT vérifié -> tenant ; lignes filtrées par orgId stocké
+  oauth/                # serveur d'autorisation propre (cloud-identity décide)
+    authorizationServer.ts  settings.ts  clerk.ts  tokenIssuer.ts
+    clientRegistry.ts       codeStore.ts picker.ts
+  ui/                   # widget MCP Apps + ressource ui://
+skills/connect-mcp-server/SKILL.md   # skill d'onboarding (anglais)
+scripts/
+  plugin-manifest.source.json  # l'UNIQUE source de tous les manifestes de packaging
+  sync-plugin-version.mjs      # génère les quatre manifestes (dans `npm run build`)
+  generate-signing-key.mjs     # affiche une JWK privée RS256 pour MCP_OAUTH_SIGNING_JWK
+tests/  evals/  docs/
 ```
 
 ## Démarrage rapide
 
 ```bash
 npm install
-npm run build
+npm run build && npm run build:ui
 
 # stdio (config client local, ex. Claude Code / Cursor) — jamais gardé,
 # le process local qui invoque stdio EST l'appelant.
 npm run start:stdio
 
-# Streamable HTTP (distant, sans état) — gate OAuth 2.1 par défaut :
-MCP_OAUTH_ISSUER=https://your-tenant.example.com \
-MCP_OAUTH_AUDIENCE=https://your-mcp-server.example.com \
-PORT=8787 npm run start:http
-
-# Streamable HTTP, palier "Public MCP" sans authentification (local/self-host, appelant de confiance) :
+# Streamable HTTP, palier public (local/self-host, appelant de confiance) :
 AUTH_MODE=public PORT=8787 npm run start:http
+
+# Streamable HTTP, palier OAuth (défaut) : ce serveur est son propre serveur
+# d'autorisation. Voir examples/oauth.env.example pour chaque variable requise.
+node scripts/generate-signing-key.mjs   # -> MCP_OAUTH_SIGNING_JWK
+PORT=8787 npm run start:http
 ```
 
-## Paliers d'authentification
+## Protocole et transports
 
-Deux paliers, selon `mcp-standard.md` "Authentication & Authorization" :
+Une seule fabrique (`createBoilerplateMcpServer`) construit un `McpServer` neuf par
+requête (HTTP) ou par connexion (stdio). Le SDK tranche l'ère du protocole :
+
+- un client **2026-07-28** ouvre par `server/discover` ; les résultats de
+  `tools/list`, `server/discover` et `resources/*` portent `resultType`, `ttlMs` et
+  `cacheScope` issus des `cacheHints` du SDK (définis une fois dans la fabrique) ;
+- un client **ère 2025** ouvre par `initialize` et est servi par la branche legacy
+  sans état du SDK en HTTP, ou par une connexion épinglée en stdio.
+
+Le plancher 2025 est **2025-06-18** : l'option `supportedProtocolVersions` du SDK ne
+liste que `2025-11-25` et `2025-06-18` ; un `initialize` plus ancien se voit
+proposer `2025-11-25`, jamais sa propre version. La version annoncée du serveur est
+lue dans `package.json`.
+
+## Fiches d'outils
+
+Chaque outil déclare `title`, les quatre annotations en booléens explicites
+(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), un schéma
+d'entrée et un schéma de sortie typés (Zod 4), et renvoie `structuredContent` plus
+un bloc texte portant le même JSON. `tests/toolRecordComplete.test.ts` parcourt
+`tools/list` et échoue au moindre manque. Les annotations sont des indications non
+fiables pour le client (mcp-standard C-15) : ne conditionnez jamais une action sur
+elles seules.
+
+## Paliers d'authentification
 
 | `AUTH_MODE` | Comportement |
 |---|---|
-| `oauth` (par défaut) | Resource server OAuth 2.1 (`@vantageos/mcp-auth-kit`) : chaque appel HTTP `/mcp` exige un Bearer JWT RS256 valide, lié à l'audience/l'émetteur. Token manquant/invalide -> `401` + `WWW-Authenticate`. Les métadonnées RFC 9728 Protected Resource sont servies sur `/.well-known/oauth-protected-resource`. `/health` reste sans token. Nécessite `MCP_OAUTH_ISSUER` + `MCP_OAUTH_AUDIENCE`. |
-| `public` | Aucun gate sur le transport HTTP — pour un usage local/self-host où l'appelant est déjà de confiance. Reprend le modèle de confiance du transport stdio (stdio n'a jamais eu de gate). Aucun document `.well-known/oauth-protected-resource` n'est servi dans ce mode (il n'y a pas de serveur d'autorisation à décrire). |
-
-Le transport stdio (`stdio.ts`) n'est jamais gardé, dans aucun des deux modes
-— le process local qui l'invoque EST l'appelant, selon le modèle de confiance
-de `mcp-standard.md` pour les outils locaux/self-host.
-
-`buildHttpApp()` appelé sans argument revient par défaut au palier `public` —
-c'est ce que les tests du squelette de transport (`httpHandshake.test.ts`,
-`protocolKitWiring.test.ts`) exercent, donc ils n'ont besoin d'aucune
-configuration OAuth. Le point d'entrée de production (`http.ts`) résout
-toujours `AUTH_MODE` depuis l'environnement via `config.ts`, avec `oauth`
-comme valeur par défaut si non défini.
-
-## i18n côté serveur (messages d'erreur FR/EN)
-
-`src/i18n.ts` localise les messages d'erreur/validation MCP (rejet
-d'authentification, refus de tenant, validation d'entrée d'outil) selon le
-mandat bilingue de `mcp-standard.md` (§Bilingual) : le client envoie
-`X-MCP-Locale: fr` ou `X-MCP-Locale: en` (par défaut `en` si absent), et
-`src/httpApp.ts` + `src/mcpServerFactory.ts` acheminent le message
-correspondant via `t(locale, key)`.
-
-Les deux fichiers de ressources (`src/locales/{en,fr}.json`) suivent
-exactement la convention de ressource à espace de noms livrée par
-`@vantageos/mosaic-i18n@0.1.1`
-(`node_modules/@vantageos/mosaic-i18n/src/locales/{en,fr}.json`) : un objet
-plat `<Namespace>.<catégorie>.<clé>` -> chaîne, FR et EN maintenus clé pour
-clé en parfait alignement. `mosaic-i18n` lui-même est un package
-React/`react-i18next` et ne peut pas être appelé directement depuis un
-serveur JSON-RPC, donc son API d'exécution n'est pas importée ici — la forme
-de son fichier de ressources est réutilisée à la place, sous le namespace
-`Mcp` propre à ce boilerplate.
+| `oauth` (défaut) | OAuth 2.1. Sans `MCP_OAUTH_ISSUER`, ce serveur est à la fois serveur d'autorisation et serveur de ressources (ci-dessous). Avec `MCP_OAUTH_ISSUER` + `MCP_OAUTH_AUDIENCE`, il est serveur de ressources seul, pour un émetteur externe. Jeton absent ou invalide -> `401` + `WWW-Authenticate` pointant vers la PRM. |
+| `public` | Aucune barrière en HTTP — local/self-host, appelant de confiance. Aucun document de serveur d'autorisation n'est servi. |
+
+stdio n'est jamais gardé, dans aucun des deux modes.
+
+### Serveur d'autorisation propre (arbitrage R1)
+
+| Route | Rôle |
+|---|---|
+| `GET /.well-known/oauth-authorization-server` (+ `openid-configuration`) | métadonnées RFC 8414 : S256 seul, `iss` RFC 9207, CIMD et DCR annoncés |
+| `GET /.well-known/oauth-protected-resource/mcp` | PRM RFC 9728 (`resource` = `<base>/mcp`) via cloud-identity |
+| `GET /.well-known/jwks.json` | clés de signature publiques uniquement |
+| `POST /register` | repli Dynamic Client Registration (clients publics, PKCE) |
+| `GET /authorize`, `GET /authorize/callback`, `POST /authorize/org` | connexion Clerk, puis sélecteur personne + organisation avec consentement |
+| `POST /token` | `authorization_code` + PKCE S256 -> JWT RS256 lié à la ressource, à l'émetteur et à l'organisation choisie |
+| `GET /userinfo` | sujet OIDC (et e-mail quand le scope le permet) |
+
+Toute décision — contrôles redirect/PKCE/ressource/scope, jeton de consentement,
+liaison et échange du code, formes de la découverte et de userinfo — est prise par
+`@vantageos/cloud-identity` (`startAuthorize`, `resumeAuthorize`,
+`exchangeAuthorizationCode`, `buildDiscoveryDocument`, `buildUserInfo`). Cette app
+fournit l'environnement, les stores, les appels Clerk, la page de sélection et la
+signature. Un client peut s'identifier par l'URL d'un Client ID Metadata Document
+(récupéré avec garde SSRF) ou s'enregistrer via `/register`.
+
+**Fail-closed** : une variable manquante (`PUBLIC_BASE_URL`, `CLERK_DOMAIN`,
+`AUTHORIZE_SIGN_IN_URL`, `AUTHORIZE_CALLBACK_URL`, `AUTHORIZE_STATE_SECRET`,
+`CLERK_SECRET_KEY`, `MCP_OAUTH_SIGNING_JWK`) répond `503` et est nommée dans le
+journal (les noms, jamais les valeurs). Il n'existe aucun chemin d'approbation
+automatique.
+
+**Stores** : le store des codes d'autorisation et le registre des clients sont des
+interfaces avec adaptateurs en mémoire pour les tests et le développement
+mono-processus. Utilisez des adaptateurs durables en production — contrat dans
+[`docs/oauth-stores.md`](docs/oauth-stores.md).
+
+**Non inclus** : jetons de rafraîchissement (les jetons d'accès durent une heure),
+clés d'API par organisation pour les clients hors ChatGPT (ce code n'a jamais eu ce
+chemin ; c'est un manque, pas une régression), URI de redirection à joker, et liste
+de révocation des jetons.
+
+### Multi-tenance
+
+`list_items` filtre les lignes par leur `orgId` stocké face à l'organisation
+vérifiée de l'appelant (`isRowInTenant`) ; un jeton sans organisation reçoit un
+refus d'outil explicite, jamais une vue non filtrée. Ne résolvez le tenant de
+l'appelant qu'à partir du jeton vérifié, jamais d'un argument d'outil.
+
+## i18n côté serveur (FR/EN)
+
+`src/i18n.ts` localise les messages d'erreur/validation MCP et la page de sélection :
+le client envoie `X-MCP-Locale: fr|en` (défaut `en`) ; le sélecteur navigateur suit
+`Accept-Language`. Les fichiers de ressources (`src/locales/{en,fr}.json`) gardent la
+convention `<Namespace>.<category>.<key>` de `@vantageos/mosaic-i18n`, FR et EN en
+parité.
 
 ## Tests
 
@@ -97,97 +148,81 @@ de son fichier de ressources est réutilisée à la place, sous le namespace
 npm test
 ```
 
-Exécute les deux transports contre les vrais chemins de code du SDK officiel :
-la suite HTTP pilote l'app Hono en mémoire ; la suite stdio lance le binaire
-`dist/stdio.js` compilé comme un vrai process enfant via `StdioClientTransport`.
+Exécute les deux transports via les vrais chemins de code du SDK : la suite HTTP
+pilote l'app Hono en processus avec le `Client` du SDK v2 ; la suite stdio lance le
+`dist/stdio.js` construit. `npm run evals` exécute le jeu de cas déclaratif contre
+stdio.
 
 ## Ajouter un outil
 
-Enregistrez-le une seule fois dans `src/mcpServerFactory.ts` — il devient
-alors disponible automatiquement sur les deux transports. Il n'y a aucune
-route REST séparée à ajouter.
+Enregistrez-le une fois dans `src/mcpServerFactory.ts` avec `title`, les quatre
+annotations, `inputSchema` et `outputSchema`, et renvoyez `structuredResult(...)`. Il
+est alors servi sur les deux transports et les deux ères du protocole.
+`tests/toolRecordComplete.test.ts` le garde honnête.
 
 ## Packaging & distribution
 
-Ce boilerplate est lui-même un package npm publiable/clonable. Deux
-artefacts portent son identité de distribution :
-
-- `package.json` — le package npm. `files` ne livre que l'arbre `dist/`
-  compilé (serveur compilé + `dist/locales/` + `dist/ui-bundle/widget.html`),
-  le `README.md`, la `LICENSE`, le manifeste de plugin, et la config client
-  d'exemple — jamais `src/`, les tests, ou l'outillage. `main`/`types`/`exports`
-  pointent vers `dist/index.js` ; le bin `mcp-boilerplate` pointe vers
-  `dist/stdio.js`. `publishConfig.access = public` est requis pour le scope
-  `@vantageos`.
-- `.claude-plugin/plugin.json` — le manifeste de catalogue Claude Code
-  marketplace / VantageRegistry, suivant la convention fleet des serveurs MCP
-  (miroir de `vantage-frameworks-mcp` / `vantage-agent-composer-mcp`) :
-  `name`, `version`, `description` bilingue + `description_fr`, `author`,
-  `license`, `homepage`, `category: "mcp-server"`, `bilingual: true`,
-  `keywords`.
+Quatre manifestes sont **générés** depuis `scripts/plugin-manifest.source.json` et
+`package.json` par `scripts/sync-plugin-version.mjs` (dans `npm run build`). Ne les
+éditez jamais à la main ; `tests/pluginManifests.test.ts` échoue sur toute dérive.
+
+| Fichier | Pour |
+|---|---|
+| `.claude-plugin/plugin.json` | marketplace Claude Code ; les champs non standard (`description_fr`, `category`, `bilingual`) sont sous `metadata` |
+| `.mcp.json` | Claude Code : `type: http`, URL seule, aucun secret |
+| `plugin.json` + `mcp.json` | OpenAI Agent Plugins ; `streamable-http`, auth sous `extensions["com.openai"].auth` (OAuth, CIMD préféré, repli DCR) |
+
+L'URL du serveur est un placeholder unique dans le fichier source. Fixez-la pour un
+vrai déploiement avec `MCP_SERVER_URL=https://votre-hote/mcp node scripts/sync-plugin-version.mjs`
+(les deux entrées changent), ou laissez `${MCP_BOILERPLATE_URL:-<placeholder>}` de
+Claude être surchargé par l'installateur. Le skill d'onboarding est
+`skills/connect-mcp-server/SKILL.md`, déclaré pour OpenAI en
+`extensions["com.openai"].onboardingSkill`.
 
 ### Scaffold → build → publish
 
 ```bash
-# 1. Scaffold : clonez ce repo (ou le tarball npm) comme squelette de votre serveur.
 git clone https://github.com/elpiarthera/vantage-mcp-boilerplate.git my-mcp
-cd my-mcp && npm install --legacy-peer-deps   # voir la note de skew peer-range dev ci-dessous
-
-# 2. Renommer : définissez "name"/"bin" dans package.json et "name" dans
-#    .claude-plugin/plugin.json pour votre serveur, puis ajoutez des outils dans src/mcpServerFactory.ts.
-
-# 3. Build + vérification depuis un arbre propre (ce que CI et prepublishOnly imposent) :
-rm -rf dist node_modules/.vite && npm run build && npm test && npm run evals
-
-# 4. Inspectez le tarball avant publication — confirmez que dist/ est bien livré et que rien ne fuit :
-npm pack --dry-run
-
-# 5. Publiez sur les deux canaux :
-npm publish                 # registre npm (prepublishOnly relance build+test+evals)
-#   Catalogue VantageRegistry : enregistrez .claude-plugin/plugin.json via
-#   le skill fleet create-plugin / generate-marketplace (upsert VR).
+cd my-mcp && npm install
+# Renommez "name"/"bin" dans package.json et les noms dans scripts/plugin-manifest.source.json,
+# puis ajoutez vos outils dans src/mcpServerFactory.ts.
+rm -rf dist && npm run build && npm run build:ui && npm test && npm run evals
+npm pack --dry-run          # vérifiez que dist/, les manifestes et skills/ sont livrés
+npm publish                 # prepublishOnly relance build + test + evals
 ```
 
-`prepublishOnly` relance `build → build:ui → test → evals` pour qu'un
-tarball cassé ou contenant uniquement `src` ne puisse jamais atteindre npm.
-Les canaux de distribution sont **npm** (le package exécutable) et le
-**catalogue VantageRegistry / Claude Code marketplace** (découverte, via
-`plugin.json`).
+La publication se prouve par le `dist-tag` du registre, jamais par le code de sortie
+de `npm publish`.
 
 ## Couche UI MCP Apps
 
-`render_items_ui` affiche `EXAMPLE_ITEMS` comme un widget interactif via
-l'officiel `@modelcontextprotocol/ext-apps/server` (`registerAppTool` +
-`registerAppResource`), forme imbriquée GA `_meta.ui.resourceUri` (stable
-depuis le 2026-01-26) — jamais la clé plate dépréciée `_meta["ui/resourceUri"]`.
-Un repli markdown est toujours présent dans `content[0]`, même pour les
-clients qui ne négocient jamais l'extension `io.modelcontextprotocol/ui`.
-
-Le widget (`src/ui/`) réutilise une famille `MosaicCard` vendorisée
-(`src/ui/mosaic-card.tsx` — atomes présentationnels, aucune dépendance
-d'exécution) et est empaqueté en un seul fichier HTML autonome
-(`vite-plugin-singlefile`, `dist/ui-bundle/widget.html`, ~70 Ko gzippé,
-aucun fetch d'exécution externe). `npm run build:ui` produit ce bundle
-indépendamment de `npm run build` (tsc), sur un chemin de sortie sans
-collision (`dist/ui-bundle/` vs `dist/ui/` de tsc) — les deux étapes de
-build écrivent sur des arbres `dist/ui*` d'apparence similaire mais jamais
-sur le même répertoire, si bien que `emptyOutDir` côté vite ne peut jamais
-supprimer un module serveur compilé par tsc.
-
-**Hygiène du template** : les atomes `MosaicCard` sont vendorisés
-localement plutôt qu'importés depuis `@vantageos/mosaic-blocks`, un paquet
-interne sans version stable (non-alpha) publiée sur npm. Une
-devDependency de template épinglée sur un tag alpha mouvant casse au
-prochain bump alpha ; vendoriser les quatre primitives présentationnelles
-réellement utilisées par le widget élimine ce mode de défaillance.
-
-**Ordre de publication (exigence stricte)** : ce boilerplate dépend de
-`@vantageos/mcp-protocol-kit@^0.2.0`. Le câblage de `tools/list` utilise
-`buildToolsListResult` du kit, qui existe UNIQUEMENT à partir du kit 0.2.0+.
-En semver 0.x, `^0.2.0` n'accepte PAS le 0.1.x, donc un `npm install` frais
-depuis le registre résout la version du kit dont le code a réellement
-besoin. Par conséquent, **le kit `@vantageos/mcp-protocol-kit` 0.2.0 DOIT
-être publié sur npm AVANT que ce boilerplate puisse être installé ou publié
-depuis le registre.** C'est un ordre strict, non optionnel : publiez d'abord
-le kit, confirmez que 0.2.0 est en ligne sur le registre, puis publiez le
-boilerplate.
+`render_items_ui` rend `EXAMPLE_ITEMS` sous forme de widget interactif
+(`io.modelcontextprotocol/ui`, spec 2026-01-26).
+
+- L'outil relie sa ressource `ui://` par la clé imbriquée `_meta.ui.resourceUri`
+  avec `visibility: ["model", "app"]` explicite. L'outil est enregistré avec
+  `server.registerTool`, et non `registerAppTool` d'ext-apps, car ce helper écrit
+  aussi la clé plate dépréciée `_meta["ui/resourceUri"]` (mcp-app-standard A-6).
+- La ressource déclare `_meta.ui` : `csp` avec `connectDomains`, `resourceDomains`,
+  `frameDomains` et `baseUriDomains` (tous vides — le widget ne fait aucune requête
+  réseau, ne charge aucun actif tiers et n'intègre aucune frame), `prefersBorder`, et
+  `domain` seulement quand `MCP_UI_DOMAIN` est défini (le format dépend de l'hôte).
+  Son type MIME est `text/html;profile=mcp-app`.
+- **Les clés ChatGPT sont additives** : `openai/outputTemplate` (même URI) et les
+  chaînes `openai/toolInvocation/invoking|invoked`. Rien ne les lit ; le serveur
+  fonctionne sans aucune clé `openai/*`. Les entrées `openai/ui` ne sont pas
+  émises — elles sont optionnelles ; ajoutez-les au `_meta` de l'outil dans
+  `src/ui/uiResource.ts` si votre app ChatGPT en a besoin.
+- Un repli markdown est toujours présent dans le résultat d'appel, pour les clients
+  qui ne négocient jamais l'extension.
+
+Le widget (`src/ui/`) réutilise une famille `MosaicCard` vendorisée et est empaqueté
+en un seul fichier HTML autonome (`vite-plugin-singlefile`,
+`dist/ui-bundle/widget.html`) par `npm run build:ui`, sur un chemin qui n'entre
+jamais en collision avec `dist/ui/` de tsc.
+
+**Couche d'identité** : `@vantageos/cloud-identity` (^0.15.0) est le seul paquet
+d'identité. Son point d'entrée resource-server (`verifyMcpAccessToken`,
+`buildProtectedResourceMetadata`) vérifie le jeton Bearer sur `/mcp` ; `jose` ne sert
+plus qu'à signer les jetons d'accès du serveur d'autorisation. Un jeu de clés
+injoignable répond 503, jamais 401.