@vantageos/mcp-boilerplate 0.6.3 → 0.8.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.6.3",
+  "version": "0.8.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"

package/CHANGELOG.md

@@ -7,6 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-11-10
+
+### Added
+- `docs/manufact-gap.md`: the gap list of this boilerplate against every Manufact quality-score check (31 checks, server metadata, discoverability, policy review, domain), each with its verdict, the mcp-doctor rule, the evidence and the file that owns the fix.
+- Server metadata and discoverability (mcp-server-standard S-49, S-50; Manufact "Server Metadata" and "Discoverability"): `serverInfo` serves `title`, `description` (English, or French on `X-MCP-Locale: fr`), `websiteUrl` and a vector icon served at `/icon.svg`, all derived from `package.json` (`displayName`, `description`, `description_fr`, `homepage`) or the `MCP_SERVER_*` variables (`.env.example`); the instructions say how to use the tools instead of pointing to the README; the MCP Server Card is served without credential at `/mcp/server-card`, `/.well-known/mcp/server-card.json`, `/.well-known/mcp-server-card`, `/mcp.json` and `/.well-known/mcp.json`; a browser `GET /mcp` gets a bilingual setup page naming the MCP URL, ahead of the auth gate. Build identity (C-25): `/health` and `serverInfo` `buildId` is now the git commit the tree was built from (`dist/build-info.json`, written by `npm run build`), and the hash of the built files moves to `buildHash`.
+- **The view resource describes itself.** The `ui://` resource carries a bilingual `widgetDescription` (EN / FR) under `_meta.ui.widgetDescription` and `_meta["openai/widgetDescription"]`, the two keys Manufact's *tool-resource-metadata-complete* check reads (T2, docs/manufact-gap.md). The text lives in `src/locales/{en,fr}.json` (`widget.description`).
+
+### Fixed
+- **The package imports from a bundle: locales, version and identity fields are module values, never a file read at import.** `src/i18n.ts` read `locales/{en,fr}.json` and `src/version.ts` read `package.json` when imported, so a bundled consumer (a Convex action importing `@vantageos/lojii-client`, which depends on this package) failed with ENOENT before any code ran. `scripts/embed-static.mjs` now writes `src/embedded.generated.ts` from those files at build (`--check` refuses a stale copy); `getServerIdentity()` reads the embedded package fields too. Proven by importing the built `dist/` from a directory with no `locales/` and no `package.json` (tests/i18n-bundled.test.ts). Declared, unchanged: the server's runtime assets (mcp-server.json, the widget bundle, tool roles, the build-tree hash) are still read on demand when a server starts, not at import. (README: #server-side-i18n-fren)
+- `mcp-readme-fr` prints every line number 1-based: a region opened by `lang:fr` without its English part was reported as "opened at line 0", and an unclosed region at the end of a file ending with a newline named the empty line after it as the last line.
+
+## [0.7.0] - 2026-11-02
+
+### Added
+- Every tool record declares its `domain` and `mode` (`read` | `write`, agreeing with `readOnlyHint`), served in its annotations (mcp-server-standard "Agent tool roles", rule 2): `ping` is `system` / `read`, `list_items` is `items` / `read`. The start refuses a tool missing either, or with another mode, or whose mode disagrees with `readOnlyHint`, naming it.
+- **Agent tool roles enforced on the OAuth tier** (mcp-server-standard "Agent tool roles"): every tool is granted or refused by the caller's role through `@vantageos/cloud-identity` `decideToolRole`, at both points — `tools/list` holds only the granted tools, and a call to any other tool is `isError: true` with `TOOL_ROLE_DENIED` / `TOOL_ROLE_UNRESOLVED`, its handler never run. The OAuth start now requires both a role store (`MCP_ROLES_FILE`, format in `examples/roles.example.json`, or an injected `toolRoles`) and the identity stores, and is refused naming each missing piece. A caller the identity layer did not resolve is refused with its `person_unresolved` code before any tool runs, `ping` included. New identity tool `whoami` (outside the gate): who the caller is, the role, the granted tools, `rolesApplicable`. The declared global context ceiling rises 1200 -> 1400 for this third tool.
+- Tool invocation rate limiting (mcp-server-standard S-24): a token bucket per caller, `TOOL_RATE_LIMIT_BURST` (default 30) and `TOOL_RATE_LIMIT_PER_MINUTE` (default 60); a call past the limit is a tool error `rate_limited` with `retryAfterMs`; `withRateLimit(…)` wraps every tool handler.
+- The directory listing kit `listing/listing.json` (mcp-standard C-35): description, served tools with titles and hints, 5 positive and 3 negative test prompts by eval id, and how a reviewer obtains an account; written by `npm run listing:write` from `scripts/plugin-manifest.source.json` and the served `tools/list`; `npm run build` runs `scripts/listing-kit.mjs --check` and fails on a stale committed kit, as does `tests/listingKit.test.ts`.
+- `mcp-server.json` declares the target hosts (`distribution.targets`: claude, claude-code, vscode, cursor, chatgpt; mcp-server-standard S-45), and each declared host's verification path is served from configuration: `/.well-known/openai-apps-challenge` from `OPENAI_APPS_CHALLENGE`, `/.well-known/google-connected-apps` from `GOOGLE_CONNECTED_APPS_VERIFICATION`; unset, a 404 naming the variable.
+- An axe-core accessibility gate (mcp-app-standard A-4): `tests/widgetAxe.test.ts`, run by `npm run test:a11y` and by `npm test` (so by `prepublishOnly`), audits the shipped `dist/ui-bundle/widget.html` against WCAG 2.1 A/AA in both locales, empty and populated, and fails on any serious or critical violation; colour contrast is not proven (jsdom computes no layout). Dev dependencies: `axe-core`, `jsdom`, `@types/jsdom`.
+
+### Changed
+- The changelog is written as one fragment per pull request in `changelog.d/`, folded into `CHANGELOG.md` at release by `npm run changelog:release -- --version <x.y.z>`; `## [Unreleased]` stays empty and `npm run changelog:check` (part of `npm test`) refuses an entry written there. The entries accumulated under `## [Unreleased]` since 0.6.3 moved into fragments (one duplicated, stale entry dropped). `docs/releasing.md` describes the release.
+- The widget's `_meta.ui.domain` is derived from the served MCP URL (`PUBLIC_BASE_URL` + `/mcp`): the first 32 hex characters of its SHA-256 followed by `.claudemcpcontent.com` (mcp-app-standard A-11), in `src/ui/sandboxDomain.ts`. `MCP_UI_DOMAIN` is removed: a typed domain went stale the moment the URL changed. Without `PUBLIC_BASE_URL`, or on stdio, no domain is declared.
+- `@vantageos/cloud-identity` ^0.20.2 -> ^0.33.1. `/userinfo` verifies our own access token with cloud-identity's `verifyMcpAccessToken` (issuer = this server, audience = the protected resource, key set = the published JWKS) instead of a local `jwtVerify`; `TokenIssuer` only signs. The tenant is read by cloud-identity's `requireTenantFromIdentity` instead of a local `org_id` read. DLocalIdentity: 6 identity sites leave the boilerplate.
+- The `private_key_jwt` client-assertion verifier comes from `@vantageos/cloud-identity/client-assertion` (^0.34.1, which caps an assertion's lifetime at 300 s); the boilerplate's own copy, `src/oauth/clientAssertion.ts`, is removed. DLocalIdentity: 0 local identity primitives.
+
+### Fixed
+- A cursor sent to `tools/list`, `resources/list` or `resources/templates/list` is refused with JSON-RPC -32602 Invalid params (mcp-standard C-11 (a)); the SDK served those lists as one page and silently answered page 1. `list_items` now declares its default page size in its served `inputSchema`.
+- The C-11 (a) cursor guard also covers `prompts/list`: a fork that registers a prompt gets -32602 on a cursor its single-page list never issued, as for `tools/list`, `resources/list` and `resources/templates/list` (review correction on #52).
+- The served descriptions of `ping` and `list_items` carry both languages in their one field ("<en> / <fr>") and their trigger phrase (mcp-standard C-19); `ping` was English-only on the wire. Their declared context estimates rise to cover the longer text (`ping` 280, `list_items` 690 tokens), within the ceilings.
+- `scripts/readme-fr.mjs` reads a language marker only at 0 to 3 spaces of indent: a line indented 4 or more spaces, or with a tab, is an indented code block (CommonMark), so a marker there is text, copied with the part it sits in.
+- The tools' output schemas stay open to added fields (mcp-server-standard S-44): `ping`, `list_items` and its items are `z.looseObject`, so a field added in a later release no longer fails a client that validated against the schema it read at connect time.
+
+### Security
+- `/token` is rate limited per client address (`MCP_TOKEN_LIMIT_PER_MINUTE`, default 60; five times that per IPv6 /48; `429` with `Retry-After: 60`), so a caller cannot fill the single-use assertion slots and lock assertion-authenticated clients out.
+
 ## [0.6.3] - 2026-11-01
 
 ### Fixed
@@ -506,6 +543,8 @@ Initial published release.
 - MIT license, clonable as a starter template.
 
 [Unreleased]: https://github.com/elpiarthera/vantage-mcp-boilerplate/compare/v0.4.0...HEAD
+[0.8.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.8.0
+[0.7.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.7.0
 [0.6.3]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.3
 [0.6.2]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.2
 [0.6.1]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.1

package/README.fr.md

@@ -23,7 +23,10 @@ src/
   toolRecord.ts         # fiche d'outil typée : autorité, verbe, table, mécanisme, pagination, coût
   pagination.ts         # pagination par curseur appliquée par l'outil (défaut, max fini, invalid_cursor)
   signedCursor.ts       # primitive de curseur signé HMAC (createCursorSigner), utilisée par tout curseur
-  buildIdentity.ts      # identité de build dérivée de l'arbre servi
+  buildIdentity.ts      # identité de build : le commit git construit (buildId) + le hachage des fichiers construits (buildHash)
+  serverIdentity.ts     # titre, description, site, icône, instructions : package.json ou env
+  serverCard.ts         # la MCP Server Card publique
+  landingPage.ts        # la page d'installation servie à un navigateur sur /mcp
   stdio.ts              # serveStdio(factory) : les deux ères du protocole sur stdio
   http.ts               # adaptateur Node http.Server autour de l'app Hono
   httpApp.ts            # createMcpHandler(factory) sur /mcp + la barrière OAuth
@@ -112,6 +115,13 @@ de liste du protocole, servies par le SDK.
 échouent 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.
 
+Chaque appel d'outil est limité en débit (mcp-server-standard S-24) : un seau à jetons par appelant (l'organisation
+résolue, ou `public` sur le palier non cloisonné), partagé par le processus. `TOOL_RATE_LIMIT_BURST` appels peuvent
+partir en rafale (30 par défaut), puis le seau se remplit à `TOOL_RATE_LIMIT_PER_MINUTE` (60 par défaut). Un appel
+au-delà de la limite est une erreur d'outil portant `structuredContent.error.code` `rate_limited` et `retryAfterMs`
+(message FR/EN) ; une limite qui n'est pas un entier strictement positif arrête le serveur au démarrage. Un nouvel
+outil enveloppe son handler avec `withRateLimit(…)`.
+
 ## Paliers d'authentification
 
 | `AUTH_MODE` | Comportement |
@@ -168,7 +178,11 @@ Pour la mesurer, envoyez 21 enregistrements depuis un même client et attendez u
 21e. Un client IPv6 est compté sur son /64 ET sur son /48 : tous les /64 d'un même /48 se
 partagent `MCP_REGISTER_LIMIT_PER_48_PER_MINUTE` enregistrements par minute (défaut `100`),
 si bien qu'un /48, qui contient 65536 /64, ne peut pas remplir le registre de clients jusqu'à
-son `503`. Une valeur invalide arrête le serveur au démarrage.
+son `503`. Une valeur invalide arrête le serveur au démarrage. `/token` est limité de la même façon, sur la
+même adresse : `MCP_TOKEN_LIMIT_PER_MINUTE` requêtes par minute (défaut `60`), cinq fois plus par /48 IPv6,
+puis `429` avec `Retry-After: 60`. Chaque assertion client `private_key_jwt` qu'il vérifie occupe une place à
+usage unique jusqu'à son expiration (300 s au plus, plafond de la couche d'identité) : un appelant sans limite
+pourrait remplir ces places et bloquer tous les clients authentifiés par assertion ; la limite l'empêche.
 
 **Limites de requête et CORS** : Une variable d'exploitation définie mais invalide (par exemple `MCP_MAX_BODY_BYTES=abc`) arrête le serveur au démarrage avec le nom de la variable et la forme attendue, jamais un défaut silencieux ; non définie ou vide, le défaut s'applique. l'entrée Node lit au plus `MCP_MAX_BODY_BYTES`
 (défaut 1 Mio) du corps d'une requête et répond `413` avant tout handler.
@@ -315,11 +329,39 @@ server.registerTool("my_rows", config, withVerifiedPerson(deps, async (args, per
 
 Sauf si la personne est résolue, le handler ne s'exécute pas : l'appel reçoit une erreur d'outil
 MCP au code stable `person_unresolved` (`structuredContent.error.code`), un message FR/EN selon
-`X-MCP-Locale`, et une `reason` : `identity_not_configured` (aucune `identity` injectée),
+`X-MCP-Locale`, et une `reason` : `identity_not_configured` (aucune `identity` injectée — sur le
+palier public seulement, puisque le palier OAuth refuse de démarrer sans elle, voir plus bas),
 `no_verified_session` (palier public, et **stdio, qui n'a jamais de personne** : ce transport ne
 porte aucun bearer) ou `refused` (le paquet a refusé ; son `code` et sa `reason` sont transmis,
-jamais une valeur de claim). Un outil qui n'enveloppe pas son handler s'exécute exactement comme
-avant, sans personne.
+jamais une valeur de claim). Sur le palier public et en stdio, un outil qui n'enveloppe pas son
+handler s'exécute sans personne. Sur le palier OAuth, aucun outil ne s'exécute pour un appelant que
+la couche d'identité n'a pas résolu : le contrôle des rôles ci-dessous répond d'abord, avec ce même
+refus.
+
+### Rôles d'outils des agents
+
+Sur le palier OAuth, chaque outil est accordé ou refusé selon le RÔLE de l'appelant, par
+`decideToolRole` de `@vantageos/cloud-identity` (mcp-server-standard « Agent tool roles »). Chaque
+outil déclare son `domain` et son `mode` (voir « Ajouter un outil ») ; un rôle accorde la lecture
+et/ou l'écriture par domaine, plus `add` (outils accordés hors de ses domaines) et `remove` (outils
+retirés, qui l'emporte toujours). La même décision sert aux deux points : `tools/list` ne contient
+que les outils accordés, et l'appel de tout autre outil reçoit un résultat `isError: true` au
+`structuredContent.error.code` `TOOL_ROLE_DENIED` (`TOOL_ROLE_UNRESOLVED` quand le stockage des
+rôles n'a pas pu être lu), sans que son handler s'exécute.
+
+Le démarrage est refusé, en nommant chaque pièce manquante, sauf si les deux sont présents :
+
+- **les stores d'identité** (`identity`, plus haut) : un rôle est décidé pour l'organisation que la
+  couche d'identité résout, jamais pour un claim lu ici ;
+- **un stockage des rôles** : par défaut le fichier JSON nommé par `MCP_ROLES_FILE` (format dans
+  `examples/roles.example.json` : les rôles, et `agents` qui lie chaque sujet vérifié à un rôle).
+  Un fichier absent, illisible ou mal formé arrête le serveur ; aucun fichier ne veut jamais dire
+  « tous les outils ». Un déploiement avec un autre stockage injecte `toolRoles` (`src/toolRoles.ts`,
+  `RoleProvider`).
+
+L'outil d'identité `whoami` reste hors du contrôle : tout appelant peut lui demander qui il est,
+quel rôle décide de ses outils et quels outils ce rôle accorde (`rolesApplicable: false` sur le
+palier public et en stdio, où il n'y a pas d'appelant). Tests : `tests/toolRoles.test.ts`.
 
 ## Appeler une API amont (OAuth 2 client_credentials)
 
@@ -522,7 +564,10 @@ ligne.
 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é.
+parité. Ils sont intégrés au module au build (`scripts/embed-static.mjs` écrit
+`src/embedded.generated.ts`, avec la version et les champs d'identité du paquet) : rien n'est lu sur le disque
+à l'import, et un consommateur empaqueté (le bundler Convex, esbuild) exécute le paquet sans dossier `locales/`
+ni `package.json` à côté ; `--check` refuse une copie périmée.
 
 ## Un README français généré depuis un README bilingue
 
@@ -553,6 +598,13 @@ pilote l'app Hono en processus avec le `Client` du SDK v2 ; la suite stdio lance
 `dist/stdio.js` construit. `npm run evals` exécute le jeu de cas déclaratif contre
 stdio.
 
+**Accessibilité (mcp-app-standard A-4).** `npm run test:a11y` audite le widget livré, `dist/ui-bundle/widget.html`
+(construisez-le d'abord avec `npm run build:ui`), selon WCAG 2.1 A et AA avec `axe-core`, en anglais et en français,
+vide et rempli. Toute violation grave ou critique le fait échouer, et un contrôle positif prouve qu'une violation
+injectée est trouvée. Il fait partie de `npm test` : `prepublishOnly` l'exécute avant chaque publication. L'audit
+tourne dans jsdom, qui ne calcule aucune mise en page : le contraste des couleurs y est signalé comme incomplet et
+n'est pas prouvé par cette barrière.
+
 ## Ajouter un outil
 
 Déclarez sa fiche dans `src/toolRecord.ts` (couple d'autorité, verbe, table, et pour
@@ -562,6 +614,55 @@ une liste/recherche le mécanisme et la pagination), enregistrez-le une fois dan
 est alors servi sur les deux transports et les deux ères du protocole.
 `tests/toolRecordComplete.test.ts` le garde honnête.
 
+La fiche déclare aussi le `domain` de l'outil (le domaine métier qu'un rôle accorde, par exemple `items`) et son
+`mode`, exactement `read` ou `write`, en accord avec `readOnlyHint` (read <-> `true`). C'est sur eux que se décide le
+rôle d'un agent (mcp-server-standard « Agent tool roles », règle 2). Un outil auquel l'un manque, ou dont le mode
+vaut autre chose, n'est servi à personne : le serveur refuse de démarrer et le nomme
+(`tests/toolRoleDeclarations.test.ts`).
+
+## Changelog
+
+Une pull request ajoute UN fichier, `changelog.d/<branche>.md` (frontmatter `section:` et une entrée), et ne
+modifie jamais `CHANGELOG.md`, dont le bloc `## [Unreleased]` reste vide. `npm run changelog:check`, inclus dans
+`npm test`, refuse un fragment mal formé ou une entrée écrite sous `## [Unreleased]`. À la publication,
+`npm run changelog:release -- --version <x.y.z>` regroupe les fragments en `## [x.y.z] - <date>`
+(`changelog.d/README.md`, `docs/releasing.md`). Deux pull requests qui ajoutent deux fichiers n'entrent jamais
+en conflit, là où deux modifications du même bloc le faisaient.
+
+## Identité du serveur et découverte
+
+Ce qu'un hôte ou un annuaire lit du serveur avant et pendant la connexion est dérivé, jamais tapé dans le
+source (`src/serverIdentity.ts`, mcp-server-standard S-49 / S-50) :
+
+| Servi comme | Variable d'environnement | Sinon, `package.json` |
+|---|---|---|
+| `serverInfo.title` | `MCP_SERVER_TITLE` | `displayName` |
+| `serverInfo.description` (anglais) | `MCP_SERVER_DESCRIPTION` | `description` |
+| `serverInfo.description` (français, `X-MCP-Locale: fr`) | `MCP_SERVER_DESCRIPTION_FR` | `description_fr` |
+| `serverInfo.websiteUrl` | `MCP_SERVER_WEBSITE_URL` (https, ou http en bouclage) | `homepage` |
+
+Un fork modifie ces champs de `package.json`, ou définit les variables (`.env.example`). Une valeur qu'aucune
+des deux sources ne porte arrête le serveur au démarrage, en nommant la variable et le champ : le serveur ne
+sert jamais de valeur fictive.
+
+- **Instructions** (`initialize` / `server/discover`) : comment un agent utilise les outils, dans la langue de
+  l'appelant, depuis `Mcp.server.instructions` dans `src/locales/{en,fr}.json`. Réécrivez-les pour vos
+  outils : `tests/serverMetadata.test.ts` échoue quand un outil servi n'y est pas nommé ou que le texte dépasse
+  2048 octets (le budget de champ de Claude Code).
+- **Icône** : un vectoriel, `src/serverIcon.ts` (remplacez le SVG par votre logo), servi à `/icon.svg` et
+  nommé dans `serverInfo.icons` ; en stdio il voyage en URI `data:`.
+- **Carte serveur** : la MCP Server Card (forme SEP-2127, plus `capabilities` et un résumé `tools` lu sur les
+  outils enregistrés), servie sans identifiant à `/mcp/server-card`, `/.well-known/mcp/server-card.json`,
+  `/.well-known/mcp-server-card`, `/mcp.json` et `/.well-known/mcp.json`. Son `name` est en DNS inversé, dérivé
+  du site (`io.github.<propriétaire>/<nom>` pour une URL GitHub).
+- **Page d'installation** : un `GET /mcp` de navigateur (sans `Authorization`, avec un `Accept` sans
+  `text/event-stream`) reçoit une page bilingue qui nomme l'URL MCP et comment se connecter, sur les deux
+  paliers. Toute requête MCP est inchangée, y compris le 401 + `WWW-Authenticate` du palier OAuth.
+
+La carte, la page et l'URL de l'icône nomment `PUBLIC_BASE_URL` + `/mcp` quand il est défini. Non défini
+(développement), elles nomment l'origine à laquelle la requête était adressée et partent avec
+`Cache-Control: no-store`. Définissez `PUBLIC_BASE_URL` sur tout déploiement public.
+
 ## Packaging & distribution
 
 Quatre manifestes sont **générés** depuis `scripts/plugin-manifest.source.json` et
@@ -581,6 +682,34 @@ 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`.
 
+### Hôtes cibles et chemins de vérification
+
+`mcp-server.json` déclare où le serveur est distribué, sous `distribution.targets` (par défaut : `claude`,
+`claude-code`, `vscode`, `cursor`, `chatgpt`), comme le demande la règle S-45 du mcp-server-standard. Un hôte qui
+vérifie que vous possédez l'origine en lisant un chemin connu voit ce chemin servi pour chaque cible déclarée, la
+valeur étant lue dans l'environnement à chaque requête, jamais écrite dans le code :
+
+| Cible | Chemin | Variable |
+|---|---|---|
+| `chatgpt` | `/.well-known/openai-apps-challenge` | `OPENAI_APPS_CHALLENGE` |
+| `google-connected-apps` | `/.well-known/google-connected-apps` | `GOOGLE_CONNECTED_APPS_VERIFICATION` |
+
+Non définie, la variable fait répondre le chemin en 404 en la nommant : la vérification de l'hôte échoue de façon
+visible. Un fork retire les cibles qu'il ne vise pas, définit les variables de celles qu'il garde, et règle
+`PUBLIC_BASE_URL` sur son origine publique `https://` : la valeur du boilerplate est une valeur de développement, pas
+une origine que vous possédez.
+
+### Kit de référencement pour les annuaires
+
+`listing/listing.json` est ce que lit le relecteur d'un annuaire (mcp-standard C-35) : la description, chaque outil
+servi avec son titre et ses indications lecture seule / destructif, 5 invites de test positives et 3 négatives
+données par identifiant d'éval de `evals/evals.json`, et la façon d'obtenir un compte de relecture (jamais un compte).
+Chaque champ est dérivé : `scripts/listing-kit.mjs` lit la description et les identifiants d'éval choisis dans
+`scripts/plugin-manifest.source.json` (`listing`), et les outils dans le `tools/list` servi. Après avoir modifié une
+source ou un outil, lancez `npm run listing:write` et commitez le fichier. `npm run build` se contente de le
+vérifier : un kit commité qui s'écarte de ses sources, un identifiant d'éval inconnu ou un compte insuffisant fait
+échouer la construction, et `tests/listingKit.test.ts` échoue aussi. Modifiez la source, jamais le fichier.
+
 ### Scaffold → build → publish
 
 ```bash
@@ -640,9 +769,13 @@ curl -s -H 'Cache-Control: no-cache' https://registry.npmjs.org/@vantageos%2Fmcp
 
 Sommes égales : le registre sert ce que la source construit. Un serveur en marche
 prouve de la même façon ce qu'il sert : `GET /health` renvoie
-`{ status, version, buildId }` avant toute authentification. `buildId` est un hachage
-des fichiers dont le processus s'exécute ; il change quand ils changent, ce que
-`version` ne garantit pas.
+`{ status, version, buildId, buildHash }` avant toute authentification. `buildId` est le
+commit git à partir duquel l'arbre servi a été construit, dérivé par `npm run build`
+(`scripts/write-build-info.mjs` écrit `dist/build-info.json`) : `BUILD_COMMIT`, sinon le commit qu'un
+hébergeur injecte au build (`RAILWAY_GIT_COMMIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`,
+`GITHUB_SHA`, `SOURCE_VERSION`), sinon `git rev-parse HEAD` ; sans aucun, le build échoue en nommant
+`BUILD_COMMIT`. `buildHash` est un hachage des fichiers dont le processus s'exécute ; il change aussi
+quand un arbre modifié ou un `dist/` retouché est servi, ce que ni `version` ni le commit ne garantissent.
 
 ## Couche UI MCP Apps
 
@@ -658,7 +791,10 @@ n'y a pas d'outil de rendu séparé.
 - 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).
+  `domain` : l'origine de bac à sable de Claude, dérivée au démarrage de l'URL MCP servie
+  (`PUBLIC_BASE_URL` + `/mcp`) comme les 32 premiers caractères hexadécimaux de son SHA-256 suivis de
+  `.claudemcpcontent.com` (mcp-app-standard A-11), jamais tapée. Sans `PUBLIC_BASE_URL`, ou en stdio, il
+  n'y a pas d'URL servie et aucun domaine n'est déclaré.
   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

package/README.md

@@ -22,7 +22,10 @@ src/
   toolRecord.ts         # typed tool record: authority, verb, table, mechanism, pagination, cost
   pagination.ts         # cursor pagination applied by the tool (default, finite max, invalid_cursor)
   signedCursor.ts       # HMAC-signed cursor primitive (createCursorSigner), used by every cursor
-  buildIdentity.ts      # build identity derived from the served tree
+  buildIdentity.ts      # build identity: the git commit built (buildId) + the hash of the built files (buildHash)
+  serverIdentity.ts     # title, description, website, icon, instructions: package.json or env
+  serverCard.ts         # the public MCP Server Card
+  landingPage.ts        # the setup page a browser gets at /mcp
   stdio.ts              # serveStdio(factory): both protocol eras over stdio
   http.ts               # Node http.Server adapter around the Hono app
   httpApp.ts            # createMcpHandler(factory) on /mcp + the OAuth gate
@@ -110,6 +113,12 @@ stays with the protocol list methods' cursor, which the SDK serves.
 fail on any gap. Annotations are untrusted hints for the client (mcp-standard C-15);
 never gate an action on them alone.
 
+Every tool invocation is rate limited (mcp-server-standard S-24): a token bucket per caller (the resolved
+organisation, or `public` on the unscoped tier), shared by the process. `TOOL_RATE_LIMIT_BURST` calls may burst
+(default 30), then the bucket refills at `TOOL_RATE_LIMIT_PER_MINUTE` (default 60). A call past the limit is a tool
+error with `structuredContent.error.code` `rate_limited` and `retryAfterMs` (message FR/EN); a limit that is not a
+positive integer stops the server at start. A new tool wraps its handler with `withRateLimit(…)`.
+
 ## Authentication tiers
 
 | `AUTH_MODE` | Behavior |
@@ -163,7 +172,11 @@ many clients. To measure it, send 21 registrations from one client and expect a
 the 21st. An IPv6 client is keyed on its /64 and ALSO counted against its /48: every /64 inside one
 /48 shares `MCP_REGISTER_LIMIT_PER_48_PER_MINUTE` registrations per minute (default `100`), so
 one /48, which holds 65536 /64s, cannot fill the client registry to its `503`. An invalid value
-stops the server at start.
+stops the server at start. `/token` is limited the same way, keyed on the same address:
+`MCP_TOKEN_LIMIT_PER_MINUTE` requests per minute (default `60`), five times that per IPv6 /48, then `429` with
+`Retry-After: 60`. Each `private_key_jwt` client assertion it verifies holds a single-use slot until it expires
+(at most 300 s, the identity layer's cap), so an unlimited caller could fill those slots and lock every
+assertion-authenticated client out; the limit bounds that.
 
 **Request limits and CORS**: An operator variable that is set but invalid (for example `MCP_MAX_BODY_BYTES=abc`) stops the server at startup with the variable's name and the expected form, never a silent default; unset or empty keeps the default. the Node entry reads at most `MCP_MAX_BODY_BYTES`
 (default 1 MiB) of a request body and answers `413` before any handler runs.
@@ -299,10 +312,37 @@ server.registerTool("my_rows", config, withVerifiedPerson(deps, async (args, per
 
 Unless the person resolved, the handler does not run: the call gets an MCP tool error with the
 stable code `person_unresolved` (`structuredContent.error.code`), a FR/EN message per
-`X-MCP-Locale`, and a `reason`: `identity_not_configured` (no `identity` injected),
-`no_verified_session` (public tier, and **stdio, which never has a person**: there is no bearer
-on that transport) or `refused` (the package refused; its `code` and `reason` are carried, never
-a claim value). A tool that does not wrap its handler runs exactly as before, with no person.
+`X-MCP-Locale`, and a `reason`: `identity_not_configured` (no `identity` injected — on the public
+tier only, since the OAuth tier refuses to start without it, see below), `no_verified_session`
+(public tier, and **stdio, which never has a person**: there is no bearer on that transport) or
+`refused` (the package refused; its `code` and `reason` are carried, never a claim value). On the
+public tier and stdio, a tool that does not wrap its handler runs with no person. On the OAuth
+tier no tool runs for a caller the identity layer did not resolve: the role gate below answers
+first, with this same refusal.
+
+### Agent tool roles
+
+On the OAuth tier, every tool is granted or refused by the caller's ROLE, through
+`@vantageos/cloud-identity`'s `decideToolRole` (mcp-server-standard "Agent tool roles"). Each tool
+declares its `domain` and `mode` (see "Adding a tool"); a role grants read and/or write per domain,
+plus `add` (tools granted outside its domains) and `remove` (tools withheld, which always wins).
+The same decision drives both points: `tools/list` holds only the granted tools, and a call to any
+other tool is a tool result with `isError: true` and `structuredContent.error.code`
+`TOOL_ROLE_DENIED` (`TOOL_ROLE_UNRESOLVED` when the role store could not be read), its handler
+never run.
+
+The start is refused, naming each missing piece, unless both of these are present:
+
+- **the identity stores** (`identity`, above): a role is decided for the organisation the identity
+  layer resolves, never for a claim read here;
+- **a role store**: by default the JSON file named by `MCP_ROLES_FILE` (format in
+  `examples/roles.example.json`: the roles, and `agents` binding each verified subject to one role).
+  A missing, unreadable or malformed file stops the server; no file never means "every tool". A
+  deployment with another store injects `toolRoles` (`src/toolRoles.ts`, `RoleProvider`).
+
+The identity tool `whoami` stays outside the gate: every caller can ask it who they are, which role
+decides their tools, and which tools that role grants (`rolesApplicable: false` on the public tier
+and stdio, where there is no caller). Tests: `tests/toolRoles.test.ts`.
 
 ## Calling an upstream API (OAuth 2 client_credentials)
 
@@ -494,7 +534,10 @@ row value.
 client sends `X-MCP-Locale: fr|en` (default `en`); the browser picker follows
 `Accept-Language`. Resource files (`src/locales/{en,fr}.json`) keep the
 `<Namespace>.<category>.<key>` convention of `@vantageos/mosaic-i18n`, FR and EN
-in lockstep.
+in lockstep. They are embedded in the module at build (`scripts/embed-static.mjs` writes
+`src/embedded.generated.ts`, with the package version and identity fields), so nothing is read from disk at
+import and a bundled consumer (the Convex bundler, esbuild) runs the package with no `locales/` folder or
+`package.json` beside it; `--check` refuses a stale copy.
 
 ## A French README generated from a bilingual one
 
@@ -524,6 +567,12 @@ Runs both transports through the real SDK code paths: the HTTP suite drives the
 Hono app in-process with the SDK v2 `Client`; the stdio suite spawns the built
 `dist/stdio.js`. `npm run evals` runs the declarative case-set against stdio.
 
+**Accessibility (mcp-app-standard A-4).** `npm run test:a11y` audits the shipped widget, `dist/ui-bundle/widget.html`
+(build it first with `npm run build:ui`), against WCAG 2.1 A and AA with `axe-core`, in English and French, empty and
+populated. Any serious or critical violation fails it, and a positive control proves an injected violation is found.
+It is part of `npm test`, so `prepublishOnly` runs it before every publish. The audit runs in jsdom, which computes no
+layout, so colour contrast is reported as incomplete and is not proven by this gate.
+
 ## Adding a tool
 
 Declare its record in `src/toolRecord.ts` (authority pair, verb, table, and for a
@@ -532,6 +581,53 @@ list/search the mechanism and pagination), register it once in
 `inputSchema` and `outputSchema`, and return `structuredResult(...)`. It is then served on both transports and both
 protocol eras. `tests/toolRecordComplete.test.ts` keeps it honest.
 
+The record also declares the tool's `domain` (the business area a role grants, such as `items`) and its `mode`,
+exactly `read` or `write`, agreeing with `readOnlyHint` (read <-> `true`). This is what an agent's role is decided
+on (mcp-server-standard "Agent tool roles", rule 2). A tool missing either, or with any other mode, is served to no
+one: the server refuses to start and names it (`tests/toolRoleDeclarations.test.ts`).
+
+## Changelog
+
+A pull request adds ONE file, `changelog.d/<branch>.md` (frontmatter `section:` plus one entry), and never
+edits `CHANGELOG.md`, whose `## [Unreleased]` block stays empty. `npm run changelog:check`, part of `npm test`,
+refuses a malformed fragment or an entry written under `## [Unreleased]`. At release,
+`npm run changelog:release -- --version <x.y.z>` folds the fragments into `## [x.y.z] - <date>`
+(`changelog.d/README.md`, `docs/releasing.md`). Two pull requests adding two files never conflict, where two
+edits of the same block did.
+
+## Server identity and discovery
+
+What a host or a directory reads about the server before and at connection is derived, never typed in
+source (`src/serverIdentity.ts`, mcp-server-standard S-49 / S-50):
+
+| Served as | Environment override | Otherwise, `package.json` |
+|---|---|---|
+| `serverInfo.title` | `MCP_SERVER_TITLE` | `displayName` |
+| `serverInfo.description` (English) | `MCP_SERVER_DESCRIPTION` | `description` |
+| `serverInfo.description` (French, `X-MCP-Locale: fr`) | `MCP_SERVER_DESCRIPTION_FR` | `description_fr` |
+| `serverInfo.websiteUrl` | `MCP_SERVER_WEBSITE_URL` (https, or http on loopback) | `homepage` |
+
+A fork edits those `package.json` fields, or sets the variables (`.env.example`). A value neither source
+carries stops the server at start, naming the variable and the field: the server never serves a placeholder.
+
+- **Instructions** (`initialize` / `server/discover`): how an agent uses the tools, in the caller's locale, from
+  `Mcp.server.instructions` in `src/locales/{en,fr}.json`. Rewrite them for your tools:
+  `tests/serverMetadata.test.ts` fails when a served tool is not named or the text passes 2048 bytes (Claude
+  Code's field budget).
+- **Icon**: a vector, `src/serverIcon.ts` (replace the SVG with your mark), served at `/icon.svg` and named
+  in `serverInfo.icons`; on stdio it travels as a `data:` URI.
+- **Server card**: the MCP Server Card (SEP-2127 shape, plus `capabilities` and a `tools` summary read from
+  the registered tools), served without credential at `/mcp/server-card`, `/.well-known/mcp/server-card.json`,
+  `/.well-known/mcp-server-card`, `/mcp.json` and `/.well-known/mcp.json`. Its `name` is reverse-DNS, derived
+  from the website (`io.github.<owner>/<name>` for a GitHub URL).
+- **Setup page**: a browser `GET /mcp` (no `Authorization`, an `Accept` without `text/event-stream`) gets a
+  bilingual page naming the MCP URL and how to connect, on both tiers. Every MCP request is unchanged,
+  including the OAuth tier's 401 + `WWW-Authenticate`.
+
+The card, the page and the icon URL name `PUBLIC_BASE_URL` + `/mcp` when it is set. Unset (development),
+they name the origin the request was addressed to and are sent `Cache-Control: no-store`. Set
+`PUBLIC_BASE_URL` on every public deployment.
+
 ## Packaging & distribution
 
 Four manifests are **generated** from `scripts/plugin-manifest.source.json` and
@@ -551,6 +647,33 @@ to be overridden by the installer. The onboarding skill is
 `skills/connect-mcp-server/SKILL.md`, declared for OpenAI as
 `extensions["com.openai"].onboardingSkill`.
 
+### Target hosts and their verification paths
+
+`mcp-server.json` declares where the server is distributed, under `distribution.targets` (default: `claude`,
+`claude-code`, `vscode`, `cursor`, `chatgpt`), as mcp-server-standard S-45 asks. A host that confirms you own the
+origin by reading a well-known path gets that path served for each declared target, with the value read from the
+environment at request time, never written in source:
+
+| Target | Path | Variable |
+|---|---|---|
+| `chatgpt` | `/.well-known/openai-apps-challenge` | `OPENAI_APPS_CHALLENGE` |
+| `google-connected-apps` | `/.well-known/google-connected-apps` | `GOOGLE_CONNECTED_APPS_VERIFICATION` |
+
+Unset, the path answers 404 naming the variable, so the host's check fails visibly. A fork removes the targets it
+does not ship to, sets the variables of the ones it keeps, and sets `PUBLIC_BASE_URL` to its public `https://` origin:
+the boilerplate's own value is a development default, not an origin you own.
+
+### Directory listing kit
+
+`listing/listing.json` is what a directory reviewer reads (mcp-standard C-35): the description, every served tool
+with its title and its read-only / destructive hints, 5 positive and 3 negative test prompts given as eval ids of
+`evals/evals.json`, and where a reviewer obtains an account (never one). Every field is derived:
+`scripts/listing-kit.mjs` reads the description and the chosen eval ids from
+`scripts/plugin-manifest.source.json` (`listing`), and the tools from the served `tools/list`. After changing a
+source or a tool, run `npm run listing:write` and commit the file. `npm run build` only checks it: a committed kit
+that differs from its sources, an unknown eval id or a short count fails the build, and `tests/listingKit.test.ts`
+fails too. Edit the source, never the file.
+
 ### Scaffold → build → publish
 
 ```bash
@@ -606,9 +729,13 @@ curl -s -H 'Cache-Control: no-cache' https://registry.npmjs.org/@vantageos%2Fmcp
 ```
 
 Equal sums: the registry serves what the source builds. A running server proves what
-it serves the same way: `GET /health` returns `{ status, version, buildId }` before any
-authentication. `buildId` is a hash of the files the process runs from, so it changes
-when they change, which `version` does not guarantee.
+it serves the same way: `GET /health` returns `{ status, version, buildId, buildHash }` before any
+authentication. `buildId` is the git commit the served tree was built from, derived by `npm run build`
+(`scripts/write-build-info.mjs` writes `dist/build-info.json`): `BUILD_COMMIT`, else the commit a host
+injects at build time (`RAILWAY_GIT_COMMIT_SHA`, `VERCEL_GIT_COMMIT_SHA`, `RENDER_GIT_COMMIT`, `GITHUB_SHA`,
+`SOURCE_VERSION`), else `git rev-parse HEAD`; with none, the build fails, naming `BUILD_COMMIT`. `buildHash` is
+a hash of the files the process runs from, so it also changes when a dirty tree or a patched `dist/` is
+served, which neither `version` nor the commit guarantees.
 
 ## MCP Apps UI layer
 
@@ -624,8 +751,10 @@ separate render tool.
 - The resource declares `_meta.ui`: `csp` with `connectDomains`,
   `resourceDomains`, `frameDomains` and `baseUriDomains` (all empty — the widget
   makes no network request, loads no third-party asset and embeds no frame),
-  `prefersBorder`, and `domain` only when `MCP_UI_DOMAIN` is set (the format is
-  host-dependent). Its mime type is `text/html;profile=mcp-app`.
+  `prefersBorder`, and `domain`: Claude's sandbox origin, derived at start from the served MCP URL
+  (`PUBLIC_BASE_URL` + `/mcp`) as the first 32 hex characters of its SHA-256 followed by
+  `.claudemcpcontent.com` (mcp-app-standard A-11), never typed. Without `PUBLIC_BASE_URL`, or on stdio,
+  there is no served URL and no domain is declared. Its mime type is `text/html;profile=mcp-app`.
 - **ChatGPT keys are additive**: `openai/outputTemplate` (same URI) and the
   `openai/toolInvocation/invoking|invoked` strings. Nothing reads them; the
   server works with every `openai/*` key absent. `openai/ui` entrypoints are

package/dist/build-info.json

@@ -0,0 +1 @@
+{"commit":"4193f2a535d8229f071524265a7e6bb98e19d34e"}

package/dist/buildIdentity.d.ts

@@ -17,3 +17,19 @@
 export declare function computeBuildIdentity(dir: string): string;
 /** The identity of the tree THIS process runs from, computed once. */
 export declare function getBuildIdentity(): string;
+/**
+ * The git commit the served tree was built from: the `buildId` of /health and serverInfo (C-25,
+ * ruling: build identity = the commit). It is DERIVED at build time by
+ * scripts/write-build-info.mjs (`npm run build`), which writes `dist/build-info.json`, and read
+ * here — never typed. `src/` and `dist/` both sit one level under the package root, so the same
+ * relative URL resolves in source mode (vitest) and in the built output.
+ *
+ * The hash of the built files above stays served beside it as `buildHash`: the commit names the
+ * source, the hash proves the files a process runs from (a dirty tree or a patched dist changes
+ * the hash, not the commit).
+ */
+export declare const BUILD_INFO_URL: URL;
+/** The commit recorded in a build-info file. Throws, naming the file, if it is not readable. */
+export declare function readBuildCommit(path: string): string;
+/** The build commit of THIS process, read once. */
+export declare function getBuildCommit(): string;

package/dist/buildIdentity.js

@@ -60,3 +60,42 @@ export function getBuildIdentity() {
     processIdentity ??= computeBuildIdentity(dirname(fileURLToPath(import.meta.url)));
     return processIdentity;
 }
+/**
+ * The git commit the served tree was built from: the `buildId` of /health and serverInfo (C-25,
+ * ruling: build identity = the commit). It is DERIVED at build time by
+ * scripts/write-build-info.mjs (`npm run build`), which writes `dist/build-info.json`, and read
+ * here — never typed. `src/` and `dist/` both sit one level under the package root, so the same
+ * relative URL resolves in source mode (vitest) and in the built output.
+ *
+ * The hash of the built files above stays served beside it as `buildHash`: the commit names the
+ * source, the hash proves the files a process runs from (a dirty tree or a patched dist changes
+ * the hash, not the commit).
+ */
+export const BUILD_INFO_URL = new URL("../dist/build-info.json", import.meta.url);
+const FULL_COMMIT = /^[0-9a-f]{40}$/;
+/** The commit recorded in a build-info file. Throws, naming the file, if it is not readable. */
+export function readBuildCommit(path) {
+    let commit;
+    try {
+        commit = JSON.parse(readFileSync(path, "utf8")).commit;
+    }
+    catch (error) {
+        throw new Error(tBoth("buildIdentity.commitUnreadable", {
+            file: path,
+            reason: error instanceof Error ? error.message : String(error),
+        }));
+    }
+    if (typeof commit !== "string" || !FULL_COMMIT.test(commit)) {
+        throw new Error(tBoth("buildIdentity.commitUnreadable", {
+            file: path,
+            reason: "commit is not a 40-hex git commit id",
+        }));
+    }
+    return commit;
+}
+let processCommit;
+/** The build commit of THIS process, read once. */
+export function getBuildCommit() {
+    processCommit ??= readBuildCommit(fileURLToPath(BUILD_INFO_URL));
+    return processCommit;
+}