@vantageos/mcp-boilerplate 0.6.3 → 0.7.0

package/.claude-plugin/plugin.json

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

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.
@@ -315,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)
 
@@ -553,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
@@ -562,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
@@ -581,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
@@ -658,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.
@@ -299,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)
 
@@ -524,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
@@ -532,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
@@ -551,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
@@ -624,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;

package/dist/listCursor.js

@@ -0,0 +1,37 @@
+import { ProtocolError, ProtocolErrorCode } 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 const SINGLE_PAGE_LISTS = [
+    "tools/list",
+    "resources/list",
+    "resources/templates/list",
+    // The seed registers no prompt, so it serves no prompts/list; a fork that registers one gets it guarded.
+    "prompts/list",
+];
+export function rejectCursorOnSinglePageLists(server) {
+    const handlers = server.server
+        ._requestHandlers;
+    if (!handlers)
+        throw new Error("C-11 (a): the SDK's request handlers were not found; list cursors cannot be checked");
+    for (const method of SINGLE_PAGE_LISTS) {
+        const inner = handlers.get(method);
+        if (typeof inner !== "function")
+            continue; // a list this server does not serve (no resources) has no handler
+        handlers.set(method, async (req, ctx) => {
+            const cursor = req?.params?.cursor;
+            if (cursor !== undefined)
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `invalid cursor: ${method} is served as one page and issues no cursor`);
+            const result = (await inner(req, ctx));
+            // The refusal above rests on the SDK serving one page. If it ever returns a nextCursor, cursors become valid
+            // and refusing them all would be wrong: fail loud instead of answering a page with a cursor we would refuse.
+            if (result?.nextCursor !== undefined)
+                throw new Error(`C-11 (a): ${method} now returns a nextCursor; src/listCursor.ts must accept its cursors`);
+            return result;
+        });
+    }
+}

package/dist/locales/en.json

@@ -12,6 +12,9 @@
       "noVerifiedSession": "permission denied: this tool needs the verified person, and this call carries no verified session",
       "refused": "permission denied: the verified person behind this call could not be resolved"
     },
+    "rateLimit": {
+      "exceeded": "too many tool calls: retry in {seconds} s"
+    },
     "validation": {
       "messageTooLong": "message exceeds the maximum length of 200 characters"
     },
@@ -42,9 +45,17 @@
         "object": "an object",
         "boolean": "true or false",
         "positiveInteger": "a positive whole number",
-        "atLeastPerTool": "at least the perTool ceiling"
+        "atLeastPerTool": "at least the perTool ceiling",
+        "stringArray": "an array of non-empty strings"
       }
     },
+    "toolRoles": {
+      "identityMissing": "the identity stores are not injected (AppDeps.identity): on the OAuth tier a caller's role is decided for the organisation the identity layer resolves, so both are required",
+      "denied": "permission denied: your role does not grant the tool {tool} ({reason})",
+      "unresolved": "permission denied: your role could not be read, so no tool is granted",
+      "configMissing": "{variable} is not set: on the OAuth tier every tool is decided by the caller's role, read from that roles file",
+      "configInvalid": "{variable} ({path}) is not a valid roles file: {problem}"
+    },
     "toolRecord": {
       "unsound": "tool records or the context ceiling are unsound: {problems}"
     },