@vantageos/mcp-boilerplate 0.6.2 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.6.2",
+  "version": "0.7.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,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [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
+- The consent approval (and denial) no longer breaks for clients whose redirect target redirects again (VS Code: `vscode.dev/redirect`, then `vscode://` or a loopback). A browser applies the consent page's `form-action` to every redirect hop of the form submission, so the 302 to the client was blocked at the client's own next hop. The POST to `/authorize/org` now answers a same-origin hand-off page (200, meta refresh plus a visible link, CSP `default-src 'none'; form-action 'none'; frame-ancestors 'none'`), which ends the form submission here. The return from sign-in (a GET) still answers a plain redirect.
+
+### Added
+- `AUTHORIZE_ALLOWED_ORG_IDS` (comma-separated Clerk organisation ids): the consent offers only the person's organisations that this server authorises. Any other membership is not listed, an approval for one is refused with 403, and a person with none of them gets a 403 with a localized message instead of a picker. Unset, behaviour is unchanged.
+
 ## [0.6.2] - 2026-11-01
 
 ### Fixed
@@ -498,6 +532,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.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
 [0.6.0]: https://www.npmjs.com/package/@vantageos/mcp-boilerplate/v/0.6.0

package/README.fr.md

@@ -112,6 +112,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 +175,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.
@@ -259,7 +270,14 @@ fonctionne sur un serveur que vous hébergez, dans cet ordre :
    VantagePeers : sombre par défaut, clair quand le système de la personne le demande, une
    carte par organisation avec son rôle. Elle ne charge aucune ressource externe et porte donc
    ses propres tokens. Réglez `AUTHORIZE_BRAND_NAME` pour afficher le nom de votre produit
-   au-dessus du titre ; rien n'est affiché par défaut.
+   au-dessus du titre ; rien n'est affiché par défaut. Réglez `AUTHORIZE_ALLOWED_ORG_IDS`
+   (identifiants d'organisation Clerk séparés par des virgules) pour ne proposer que les
+   organisations que ce serveur autorise : les autres appartenances ne sont pas listées, une
+   validation pour l'une d'elles est refusée (403), et une personne qui n'en a aucune reçoit un
+   403 avec un message au lieu du choix. Non réglé, toutes les appartenances sont proposées.
+   Valider ou refuser répond une courte page de la même origine qui renvoie le navigateur vers
+   le client, pour que le `form-action` de la page ne bloque pas un client dont la cible de
+   redirection redirige à nouveau (le `vscode.dev/redirect` de VS Code).
 
 ### Multi-tenance
 
@@ -308,11 +326,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)
 
@@ -546,6 +592,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
@@ -555,6 +608,21 @@ 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.
+
 ## Packaging & distribution
 
 Quatre manifestes sont **générés** depuis `scripts/plugin-manifest.source.json` et
@@ -574,6 +642,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
@@ -651,7 +747,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

@@ -110,6 +110,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 +169,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.
@@ -245,7 +255,14 @@ server you host, in this order:
 6. **The consent page.** The organisation picker uses the VantagePeers dashboard design: dark
    by default, light when the person's system asks for it, one card per organisation with its
    role. It loads no external asset, so it carries its own tokens. Set `AUTHORIZE_BRAND_NAME`
-   to show your product's name above the title; nothing is shown by default.
+   to show your product's name above the title; nothing is shown by default. Set
+   `AUTHORIZE_ALLOWED_ORG_IDS` (comma-separated Clerk organisation ids) to offer only the
+   organisations this server authorises: other memberships are not listed, an approval for one
+   of them is refused (403), and a person with none of them gets a 403 with a message instead of
+   a picker. Unset, every membership is offered.
+   Approving or denying answers a short same-origin page that sends the browser on to the
+   client, so the page's `form-action` does not block a client whose redirect target redirects
+   again (VS Code's `vscode.dev/redirect`).
 
 ### Multi-tenancy
 
@@ -292,10 +309,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)
 
@@ -517,6 +561,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
@@ -525,6 +575,20 @@ 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.
+
 ## Packaging & distribution
 
 Four manifests are **generated** from `scripts/plugin-manifest.source.json` and
@@ -544,6 +608,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
@@ -617,8 +708,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/hostVerification.d.ts

@@ -0,0 +1,15 @@
+import type { Env, Hono } from "hono";
+/**
+ * The verification path each host reads to confirm we own the origin (mcp-server-standard S-45), served for every
+ * DECLARED target (`mcp-server.json` `distribution.targets`) from configuration — never a token written in source.
+ * A host with no verification path (claude, cursor, vscode, …) needs no route. One explicit route per host that has
+ * one, each reading `process.env` in its own handler, so a reader (and mcp-doctor) sees both the path and where its
+ * value comes from; a fork sets the value in its environment.
+ */
+export declare const HOST_VERIFICATION: ReadonlyArray<{
+    host: string;
+    path: string;
+    env: string;
+}>;
+/** Registers the verification route of every declared target that has one; returns the paths registered. */
+export declare function registerHostVerification<E extends Env>(app: Hono<E>, targets: readonly string[]): string[];

package/dist/hostVerification.js

@@ -0,0 +1,32 @@
+/**
+ * The verification path each host reads to confirm we own the origin (mcp-server-standard S-45), served for every
+ * DECLARED target (`mcp-server.json` `distribution.targets`) from configuration — never a token written in source.
+ * A host with no verification path (claude, cursor, vscode, …) needs no route. One explicit route per host that has
+ * one, each reading `process.env` in its own handler, so a reader (and mcp-doctor) sees both the path and where its
+ * value comes from; a fork sets the value in its environment.
+ */
+export const HOST_VERIFICATION = [
+    { host: "chatgpt", path: "/.well-known/openai-apps-challenge", env: "OPENAI_APPS_CHALLENGE" },
+    {
+        host: "google-connected-apps",
+        path: "/.well-known/google-connected-apps",
+        env: "GOOGLE_CONNECTED_APPS_VERIFICATION",
+    },
+];
+/** The configured value, read at request time; unset, 404 naming the variable (the host's check fails visibly). */
+function answer(c, value, variable) {
+    return value ? c.text(value) : c.text(`${variable} is not configured`, 404);
+}
+/** Registers the verification route of every declared target that has one; returns the paths registered. */
+export function registerHostVerification(app, targets) {
+    const registered = [];
+    if (targets.includes("chatgpt")) {
+        app.get("/.well-known/openai-apps-challenge", (c) => answer(c, process.env.OPENAI_APPS_CHALLENGE, "OPENAI_APPS_CHALLENGE"));
+        registered.push("/.well-known/openai-apps-challenge");
+    }
+    if (targets.includes("google-connected-apps")) {
+        app.get("/.well-known/google-connected-apps", (c) => answer(c, process.env.GOOGLE_CONNECTED_APPS_VERIFICATION, "GOOGLE_CONNECTED_APPS_VERIFICATION"));
+        registered.push("/.well-known/google-connected-apps");
+    }
+    return registered;
+}

package/dist/http.js

@@ -2,8 +2,11 @@ import { loadAuthConfig, loadAuthMode } from "./config.js";
 import { buildHttpApp } from "./httpApp.js";
 import { createNodeListener, maxBodyBytesFrom } from "./nodeAdapter.js";
 import { loadHttpSettings } from "./settings.js";
+import { claudeSandboxDomain, servedMcpUrl } from "./ui/sandboxDomain.js";
 const authMode = loadAuthMode();
-const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
+// A-11: the widget's Claude sandbox domain is derived from the served MCP URL, never configured as a literal.
+const mcpUrl = servedMcpUrl(process.env);
+const uiDomain = mcpUrl ? claudeSandboxDomain(mcpUrl) : undefined;
 // S-22: MCP_ALLOWED_ORIGINS, declared in src/settings.ts. A wildcard or a path stops the server
 // here with a ConfigurationError naming the variable.
 const { allowedOrigins } = loadHttpSettings();

package/dist/httpApp.d.ts

@@ -28,11 +28,15 @@ import type { AuthMode } from "./config.js";
 import type { ExampleItem } from "./exampleItems.js";
 import type { LakeReader } from "./lake/reader.js";
 import { type AuthorizationServerDeps } from "./oauth/authorizationServer.js";
+import type { RateLimiter } from "./rateLimit.js";
 import type { CursorSigner } from "./signedCursor.js";
 import { type ResolvedTenant } from "./tenancy.js";
+import { type ToolRolesConfig } from "./toolRoles.js";
 import { type CallerResolution, type IdentityDeps } from "./verifiedPerson.js";
 export interface AppDeps {
     authMode?: AuthMode;
+    /** The tool invocation limiter (S-24); default the process-wide one. A test injects its own. */
+    rateLimiter?: RateLimiter;
     /** External-issuer resource-server configuration (no authorization server mounted). */
     auth?: AuthConfig;
     /** Own authorization server (R1). Takes precedence over `auth`. */
@@ -47,6 +51,11 @@ export interface AppDeps {
      * (`identity_not_configured`).
      */
     identity?: IdentityDeps;
+    /**
+     * Agent tool roles (src/toolRoles.ts). Default: read at start by `loadToolRoles` — on the OAuth tier `MCP_ROLES_FILE`
+     * is required; elsewhere roles are not applicable. A test or a deployment with another store injects its own.
+     */
+    toolRoles?: ToolRolesConfig;
     /**
      * The data-lake reader `list_items` reads through (src/lake/reader.ts), read-only by design.
      * Injected by the deployment like `identity`; absent, the in-memory seed is read.

package/dist/httpApp.js

@@ -27,28 +27,78 @@ import { unauthorizedChallenge } from "@vantageos/cloud-identity";
 import { Hono } from "hono";
 import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
 import { getBuildIdentity } from "./buildIdentity.js";
-import { detectLocale, t } from "./i18n.js";
+import { registerHostVerification } from "./hostVerification.js";
+import { detectLocale, t, tBoth } from "./i18n.js";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
 import { createAuthorizationServer, } from "./oauth/authorizationServer.js";
 import { MCP_SCOPE } from "./oauth/settings.js";
 import { loadServerManifest } from "./serverManifest.js";
 import { resolveTenantFromJwtPayload } from "./tenancy.js";
+import { callerScopeOf } from "./toolRoleGate.js";
+import { ToolRolesConfigError, loadToolRoles } from "./toolRoles.js";
 import { assertIdentityDeps, resolveVerifiedPerson, } from "./verifiedPerson.js";
 import { SERVER_VERSION } from "./version.js";
 const PRM_PATHS = [
     "/.well-known/oauth-protected-resource",
     "/.well-known/oauth-protected-resource/mcp",
 ];
+/**
+ * The per-request role context: the caller's member scope (from the person the identity layer resolved) and the role
+ * the provider returns for it. No resolved person -> no lookup and a null scope, so every gated tool is denied
+ * (caller-not-resolved). A provider that throws is a failed read -> TOOL_ROLE_UNRESOLVED, never "all tools".
+ */
+async function toolRolesFor(config, caller) {
+    if (!config.applicable)
+        return { applicable: false };
+    const person = caller?.ok ? caller.person : undefined;
+    const scope = callerScopeOf(person);
+    let lookup = { status: "absent", cause: "unassigned" };
+    if (person && scope?.orgClerkId) {
+        try {
+            lookup = await config.provider({ subject: person.subject, orgClerkId: scope.orgClerkId });
+        }
+        catch {
+            lookup = { status: "unresolved" };
+        }
+    }
+    return { applicable: true, lookup, caller: scope, resolution: caller, roleName: config.roleName };
+}
 export function buildHttpApp(deps = {}) {
     const app = new Hono();
     const authMode = deps.authMode ?? "public";
     // Refuses at start, naming the field, a manifest without a readable context ceiling (G6).
-    loadServerManifest();
+    const manifest = loadServerManifest();
     if (deps.identity)
         assertIdentityDeps(deps.identity);
+    // Agent tool roles (Pi's rulings on task k17103j933e6en0aqyws2v1twx8hc0s3): on the OAuth tier every tool is decided
+    // by the caller's role, which needs BOTH a role store and the identity stores that resolve the caller to an
+    // organisation. The start refuses, naming each piece that is missing; an absent store never widens access.
+    const toolRoles = authMode === "oauth"
+        ? (() => {
+            const missing = [];
+            let config = deps.toolRoles;
+            if (!config) {
+                try {
+                    config = loadToolRoles("oauth");
+                }
+                catch (e) {
+                    if (!(e instanceof ToolRolesConfigError))
+                        throw e;
+                    missing.push(e.message);
+                }
+            }
+            if (!deps.identity)
+                missing.push(tBoth("toolRoles.identityMissing"));
+            if (missing.length > 0)
+                throw new ToolRolesConfigError(missing.join("; "));
+            return config;
+        })()
+        : { applicable: false };
     // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25), so a
     // deployment is proven from what the server returns, not from what the deploy printed.
     app.get("/health", (c) => c.json({ status: "ok", version: SERVER_VERSION, buildId: getBuildIdentity() }));
+    // S-45: the verification path of every declared target host, served from configuration.
+    registerHostVerification(app, manifest.distribution.targets);
     // S-22 Origin validation, on /mcp ONLY and registered BEFORE the auth gate: a request that carries
     // an Origin header (a browser) must name an allowed origin (exact full-origin match, case-
     // insensitive), else 403 before any token is looked at. No Origin header (server-to-server, Claude
@@ -154,6 +204,7 @@ export function buildHttpApp(deps = {}) {
             ? c.get("caller")
             : await resolveVerifiedPerson(undefined, deps.identity);
         const locale = detectLocale(c.req.header("X-MCP-Locale"));
+        const roles = await toolRolesFor(toolRoles, caller);
         const handler = createMcpHandler(() => createBoilerplateMcpServer({
             tenant,
             requireTenant: authMode === "oauth",
@@ -162,6 +213,8 @@ export function buildHttpApp(deps = {}) {
             uiDomain: deps.uiDomain,
             lake: deps.lake,
             cursorSigner: deps.cursorSigner,
+            rateLimiter: deps.rateLimiter,
+            toolRoles: roles,
         }));
         return handler.fetch(c.req.raw);
     });

package/dist/listCursor.d.ts

@@ -0,0 +1,10 @@
+import { type McpServer } from "@modelcontextprotocol/server";
+/**
+ * C-11 (a) (mcp-standard): an invalid cursor sent to a protocol list method is JSON-RPC -32602 Invalid params, never a
+ * silent first page. The SDK serves `tools/list`, `resources/list`, `resources/templates/list` and `prompts/list` as
+ * ONE page and issues no `nextCursor`, so every cursor such a request carries is one this server never issued: invalid.
+ * The SDK itself ignores the cursor and answers page 1, so each of these handlers is wrapped in place (the SDK keeps them
+ * in a map) to refuse first. A list that cannot be wrapped refuses the start: it must not answer a cursor silently.
+ */
+export declare const SINGLE_PAGE_LISTS: readonly ["tools/list", "resources/list", "resources/templates/list", "prompts/list"];
+export declare function rejectCursorOnSinglePageLists(server: McpServer): void;