@vantageos/mcp-boilerplate 0.2.3 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.2.3",
+  "version": "0.3.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,167 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-28
+
+### Added
+
+- **Data-lake reader** (`src/lake/reader.ts`, exported from the package root): a derived server reads
+  its client's data lake through a READ-ONLY interface, `LakeReader` — `listPage({ after?, limit,
+  scope? })` -> `{ rows, exhausted }` in ascending key order, `get(key, scope?)`, `keyOf(row)`; no
+  write method. `list_items` reads through the reader injected as `AppDeps.lake` /
+  `McpServerDeps.lake`; the default is the in-memory seed (`EXAMPLE_ITEMS_READER`,
+  `createInMemoryLakeReader`), so the output is unchanged. The caller's tenant travels into the read
+  as `scope`, and a row of another tenant coming back fails the call closed. `readPage` (exported)
+  applies the tool's bounds and cursor to any reader and checks each page against the contract: an
+  unreadable page is a `LakeReadError` (`malformed_page`, `malformed_row`, `out_of_scope`,
+  `read_failed`), answered by `list_items` as a tool error with the stable code `lake_unreadable`
+  and a FR/EN message, never an empty page. The `list_items` widget resource no longer takes rows it
+  never rendered (`buildUiResource({ domain })`).
+- **Convex lake adapter** at its own subpath, `@vantageos/mcp-boilerplate/lake/convex`, with `convex`
+  as an OPTIONAL peer dependency (`^1.46.0`; dev dependency pinned `1.46.0`).
+  `createConvexLakeReader` takes the deployment URL (https, or http on loopback; no query, fragment
+  or credentials), an optional read token (sent through `setAuth`, or as the argument named by
+  `tokenArg`), the NAMES of the page and get query functions and the key field — all configuration
+  — and an optional `parseRow`. It only ever calls `ConvexHttpClient.query`, never a mutation, an
+  action or `function`. `convexLakeReaderFromEnv(env, names, options)` declares the connection
+  variables with `defineVariables` (url; token as a secret) and refuses at start, naming every
+  missing or invalid variable, never a value. A failing call is `read_failed` and the client's
+  message is not forwarded; no error carries the token, the URL or a row value.
+- **The verified person reaches tool handlers** (`src/verifiedPerson.ts`, exported from the package
+  root). With `AppDeps.identity` (`orgLookups`, `principalLookups`, and `adminRoles`, required and
+  non-empty, refused at build otherwise, no default role), each `/mcp` request resolves the
+  caller's person ONCE through `@vantageos/cloud-identity`'s `resolveCallerFromClaims`, from the
+  same verified claims as the tenant; nothing reads a claim locally. The person travels in the
+  per-request server deps beside the tenant (`McpServerDeps.caller`), frozen, exactly the package's
+  fields (`subject`, `actorName`, `org`, `principal`, `role`, `isOrgAdmin`), a copy that never
+  freezes the injected store's objects. A tool declares it needs the person with
+  `withVerifiedPerson(deps, handler)`; unless the person resolved, the handler does not run and the
+  call is an MCP tool error with the stable code `person_unresolved`, a FR/EN message, and a
+  `reason`: `identity_not_configured`, `no_verified_session` (public tier, and stdio, which never
+  has a person) or `refused` (the package's refusal `code` and `reason`, never a claim value).
+  Tools that do not wrap their handler are unchanged.
+- **Paginated upstream client** (`src/upstream/paginatedClient.ts`, exported from the package root)
+  for a derived server that reads a third-party endpoint paginated by offset and limit.
+  `createPaginatedUpstreamClient` takes the offset and limit parameter names, their placement
+  (`query` or `jsonBody`) and the method as configuration, a REQUIRED `allowedOrigins` list (every
+  request URL is checked before any network call, https or loopback http; redirects are refused,
+  never followed) and a REQUIRED finite `rowCeiling`. `readAll` walks the pages to the short page
+  (or the declared total) and refuses a set above the ceiling with an `UpstreamPageError`
+  (`row_ceiling_exceeded`) naming it, never a silently truncated set. `readPage` reads one page per
+  MCP call behind an opaque cursor bound to the path and params; a cursor replayed against another
+  query or altered without recomputing its unkeyed fingerprint is refused as `invalid_cursor`
+  (misuse detection, not forgery protection: a minted offset above the ceiling is refused before any
+  request). An empty page before a declared total is `inconsistent_page`, so a walk never
+  re-requests the same offset. 429 and 503 are retried with exponential backoff and jitter,
+  honouring `Retry-After` (capped); no other status is retried. An unreadable page fails closed.
+  Errors name the path and status, never a token, a parameter value or the body. Accepts the token
+  source's `fetchWithToken` as `fetchImpl`.
+- **Declared variables: a configuration extension point** (`src/declaredVariables.ts`, exported
+  from the package root) for a derived server's own environment variables. `defineVariables`
+  takes, per logical key, `{ env, type, required?, default?, secret?, description: { en, fr } }`
+  with `type` one of `string`, `integer` (`min`/`max`), `boolean` (`"0"`/`"1"`), `url` (https,
+  http on loopback only), `originList`, `enum` (`values`) and `json` (object or array); it reuses
+  the `src/envKnobs.ts` readers. `loadVariables` returns a frozen object whose type is inferred
+  from the declaration (an undeclared key does not compile, and reading one at runtime throws,
+  naming it), or throws ONE `ConfigurationError` whose `problems` list every missing or invalid
+  variable (`{ key, env, reason, expected }`) and whose FR+EN message names them, never a value.
+  A broken declaration (duplicate env name, unknown type or property, a default that does not
+  validate, a default on a required variable) is a `VariableDeclarationError` at definition.
+  `describeVariables` lists the contract without values, for `--help` or docs. Serialising the
+  result (`JSON.stringify`, `String()`, template literals, `util.inspect`) never throws and shows a
+  `secret: true` value as the fixed mask `[secret]`; a secret is non-enumerable, so spread,
+  `Object.entries` and `Object.keys` never copy it, and it is read by name only. The boilerplate's
+  own readers (`OAUTH_ENV`, the envKnobs knobs, `clientCredentialsFromEnv`) are left as they are:
+  candidates to migrate onto the registry, not migrated here.
+- **Outbound OAuth 2 `client_credentials` token source** (`src/upstream/clientCredentials.ts`,
+  exported from the package root) for a derived server that reads a third-party upstream API.
+  `createClientCredentialsTokenSource` caches the token until `expires_in` minus a skew (default
+  60 s; 300 s assumed when `expires_in` is absent), shares one in-flight token request between
+  concurrent callers, and `fetchWithToken` attaches the bearer token with one refetch and one
+  retry on a 401. `client_secret_basic` (default) or `client_secret_post`. A token endpoint
+  failure or an unreadable response is an `UpstreamTokenError` naming the status and the OAuth
+  `error` code, never a credential or a token. `clientCredentialsFromEnv` reads the variable
+  names the caller chooses and names any missing one, never its value. Create it once at module
+  scope (the server is rebuilt per request); both READMEs show the pattern.
+  The token request refuses redirects (`redirect: "error"`), so a 307/308 never re-sends the secret.
+- **`/register` budget per IPv6 /48** (`MCP_REGISTER_LIMIT_PER_48_PER_MINUTE`, default 100). Every
+  /64 inside one /48 shares it, beside the per-/64 budget, so one /48 cannot fill the client
+  registry to its 503. An invalid value stops the server at start.
+- A test pins that a denial with a forged `consentToken` is refused with no redirect; the deny
+  comment now states that the package verifies the token (cloud-identity >= 0.18).
+- **Server manifest** `mcp-server.json` (mcp-standard C-18): capabilities, transport, version and
+  feature switches in one file. `src/serverManifest.ts` loads it fail-closed, refusing an unreadable
+  field by name (FR+EN in one message). The factory serves its capabilities;
+  `scripts/sync-plugin-version.mjs` reads the version from it and refuses a `package.json` that
+  disagrees, naming both. Bump `package.json` and `mcp-server.json` together.
+- **Typed tool record** (`src/toolRecord.ts`, C-8, C-9, C-10, C-12, C-13): every tool declares in
+  its `annotations` the `authRead`/`authWrite` pair, the `verb`, the `table`, the `searchMechanism`
+  (`indexed-range`, never `unindexed-scan`) and `tokensEstimeContexte`, plus a `CONTEXT_CEILING`
+  (global and per tool). The sets are closed TypeScript unions. Served on the wire in both protocol
+  eras (the SDK `Client` drops unknown annotation keys; the tests read the raw result).
+- **Cursor pagination** on `list_items` (C-11, S-12): `limit` (default 20,
+  capped at 100) and an opaque `cursor` over the key-sorted collection; `nextCursor` and
+  `exhausted` tell a truncated page from the last one. An invalid or expired cursor is a TOOL INPUT
+  error, not a protocol error: a result with `isError: true` and the stable machine code
+  `invalid_cursor` in `structuredContent.error.code`, with an FR+EN message via `X-MCP-Locale`;
+  never a silent first page. **C-11 scope split:** the spec 2025-11-25 changelog (SEP-1303) says
+  input validation errors are returned as Tool Execution Errors, so JSON-RPC `-32602` stays only
+  with the cursor of the protocol list methods, which the SDK serves (S-12). The standard amendment
+  is tracked in task `k178z7mdt51jchj82e10jq1qp18g36s4`.
+- **Build identity** (C-25, S-7): `buildId`, a hash of the files the process runs from, beside
+  `version` on the unauthenticated `/health` and in the server identity of `server/discover` and
+  `initialize`. It changes when `dist/` changes.
+- **Release workflow** `.github/workflows/release.yml` (C-17): `npm publish --provenance`, then the
+  `dist-tag` re-read at the registry with the cache bypassed, then the GitHub release. GitHub
+  Actions is disabled across the fleet; the README documents the equivalent without CI (packed
+  tarball checksum against `dist.shasum`).
+- README (EN+FR): exact-version pin, rollback line and verification (C-7).
+- Evals: `list_items` has eight cases, covering the page limit, a truncated page, the
+  invalid-cursor failure path, the `ui://` link and the French fallback. The eval harness reads the
+  JSON body from the first text block that parses and gains a `resourceUri` assertion.
+
+### Removed (BREAKING for forks)
+
+- **The `render_items_ui` tool is removed; `list_items` carries the UI.** One operation on one
+  table is one tool (mcp-standard C-12): `render_items_ui` and `list_items` shared the triplet
+  (`list`, `items`, `indexed-range`). `list_items` now holds `_meta.ui.resourceUri` (plus the
+  additive `openai/outputTemplate` keys), takes an optional `locale`, and returns
+  `structuredContent` (`items`, `locale`, `exhausted`, `nextCursor`) with a markdown fallback first
+  (A-1) and the `ui://` resource. The `ui://` resource is kept and renders the `list_items` result.
+  A fork that calls or documents `render_items_ui` calls `list_items` instead. The seed is still 0.x.
+
+### Changed
+
+- **`@vantageos/cloud-identity` `^0.19.1` -> `^0.20.2`** for `resolveCallerFromClaims` (tagged
+  `@callerResolver`), the package entry from verified claims to the calling person. No breaking
+  change for this boilerplate: the runtime modules that changed between the two versions
+  (`org-by-id`, `person-principal`, `principal-by-id`, plus new exports on the index) export none of
+  `requireTenantId`, `isRowInTenant`, `unauthorizedChallenge`, `verifyMcpAccessToken`,
+  `buildProtectedResourceMetadata`, the authorize flow or the token exchange. The package's own
+  dependencies are unchanged, so only its lockfile entry moves.
+
+- `list_items` now returns one page (`exhausted`, optional `nextCursor`)
+  instead of every row, and its call result carries a markdown fallback, the JSON mirror and the
+  `ui://` resource; a call with no argument still returns the whole seed collection (three
+  rows, under the default page size).
+- `TOOL_ANNOTATIONS` (four booleans shared by all tools) is replaced by one record per tool in
+  `src/toolRecord.ts`.
+- `/health` answers `{ status, version, buildId }` instead of `{ status }`.
+
+## [0.2.4] - 2026-10-11
+
+### Changed
+
+- The consent / organisation picker page uses the VantagePeers dashboard design tokens: dark by
+  default, light under `prefers-color-scheme`, one option card per organisation with its role
+  (`admin`, not `(org:admin)`), a primary Approve button. It still loads no external asset; the
+  single inline style is hashed into the page CSP.
+
+### Added
+
+- `AUTHORIZE_BRAND_NAME` (optional): a display name shown above the consent page title. None by
+  default, so a fork carries no brand it did not set.
+
 ## [0.2.3] - 2026-10-11
 
 ### Added

package/README.fr.md

@@ -10,8 +10,8 @@ serveur d'autorisation OAuth 2.1** (une personne Clerk choisit une organisation)
 une UI MCP Apps et des messages FR/EN. Aucune route REST personnalisée ne se place
 jamais devant un appel d'outil.
 
-Il embarque trois petits outils d'exemple (`ping`, `list_items`, `render_items_ui`)
-qui exercent chaque couche. Remplacez-les par les vôtres ; le câblage reste.
+Il embarque deux petits outils d'exemple (`ping`, `list_items`) qui exercent
+chaque couche ; `list_items` porte aussi le widget MCP Apps. Remplacez-les par les vôtres ; le câblage reste.
 
 ## Structure
 
@@ -19,16 +19,24 @@ qui exercent chaque couche. Remplacez-les par les vôtres ; le câblage reste.
 src/
   mcpServerFactory.ts   # définition unique du serveur MCP, partagée par les deux transports
   version.ts            # nom + version du serveur, dérivés de package.json
+  serverManifest.ts     # chargeur fail-closed de mcp-server.json (le manifeste serveur)
+  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)
+  buildIdentity.ts      # identité de build dérivée de l'arbre servi
   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
   auth.ts               # câblage resource-server (@vantageos/cloud-identity)
   config.ts             # AuthMode + AuthConfig d'émetteur externe, dérivés de l'environnement
   tenancy.ts            # JWT vérifié -> tenant ; lignes filtrées par orgId stocké
+  lake/                 # lecteur de data-lake en lecture seule : interface + défaut en mémoire, adaptateur Convex
+    reader.ts  convex.ts
   oauth/                # serveur d'autorisation propre (cloud-identity décide)
     authorizationServer.ts  settings.ts  clerk.ts  tokenIssuer.ts
     clientRegistry.ts       codeStore.ts picker.ts
   ui/                   # widget MCP Apps + ressource ui://
+mcp-server.json         # le manifeste serveur : capabilities, transport, version, interrupteurs de fonctionnalités
+.github/workflows/release.yml   # npm publish --provenance + preuve au registre (Actions est désactivé dans la flotte)
 skills/connect-mcp-server/SKILL.md   # skill d'onboarding (anglais)
 scripts/
   plugin-manifest.source.json  # l'UNIQUE source de tous les manifestes de packaging
@@ -74,13 +82,34 @@ lue dans `package.json`.
 
 ## Fiches d'outils
 
-Chaque outil déclare `title`, les quatre annotations en booléens explicites
-(`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), un schéma
-d'entrée et un schéma de sortie typés (Zod 4), et renvoie `structuredContent` plus
-un bloc texte portant le même JSON. `tests/toolRecordComplete.test.ts` parcourt
-`tools/list` et échoue au moindre manque. Les annotations sont des indications non
-fiables pour le client (mcp-standard C-15) : ne conditionnez jamais une action sur
-elles seules.
+Chaque outil déclare `title`, un schéma d'entrée et un schéma de sortie typés
+(Zod 4), et renvoie `structuredContent` plus un bloc texte portant le même JSON. Ses
+`annotations` portent la fiche typée de `src/toolRecord.ts`, lisible depuis
+`tools/list` sans lire la source :
+
+| Clé | Règle | Sens |
+|---|---|---|
+| `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` | C-15 | les quatre booléens de comportement |
+| `authRead`, `authWrite` | C-8 | couple d'autorité parmi `public` / `org-member` / `org-admin` / `fleet-internal` / `master`, distincts ; résolu depuis l'identité vérifiée, jamais depuis un argument |
+| `verb`, `table` | C-9, C-12 | l'opération (`list`, `get`, `create`, `pure`...) et la donnée touchée |
+| `searchMechanism` | C-10 | comment une liste/recherche est servie (`indexed-range` ici) ; `unindexed-scan` ne se publie pas |
+| `paginationCursor`, `paginationDefault`, `paginationMax` | C-11 | curseur, taille de page par défaut et maximum fini, appliqués par `src/pagination.ts` |
+| `tokensEstimeContexte` | C-13 | coût de contexte estimé ; `CONTEXT_CEILING` borne chaque outil et la somme |
+
+Les ensembles sont des unions TypeScript fermées : une valeur hors ensemble ne
+compile pas, et un outil de liste ne peut omettre ni son mécanisme ni sa pagination.
+La fiche de chaque outil est un objet de littéraux, lisible par un contrôleur
+statique. `list_items` pagine ses lignes : `limit` (20 par
+défaut, plafonné à 100) et un `cursor` opaque ; une page tronquée porte `nextCursor`
+et `exhausted: false`, la dernière page `exhausted: true` ; un curseur invalide ou expiré est
+une erreur d'entrée de l'outil : un résultat `isError: true` avec
+`structuredContent.error.code` valant `invalid_cursor` (message FR/EN), jamais une
+première page silencieuse. Le `-32602` JSON-RPC reste réservé au curseur des méthodes
+de liste du protocole, servies par le SDK.
+
+`tests/toolRecordComplete.test.ts` et les suites C-8..C-13 parcourent `tools/list` et
+é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.
 
 ## Paliers d'authentification
 
@@ -130,7 +159,15 @@ déploiement mono-instance. Derrière un reverse proxy, réglez `MCP_TRUSTED_PRO
 sur le nombre de proxys de confiance (défaut `0`) : la limite de débit de `/register`
 se fonde alors sur l'entrée `X-Forwarded-For` ajoutée par le proxy, jamais sur la
 première, fournie par le client ; avec `0`, elle se fonde sur l'adresse du socket et
-ignore l'en-tête.
+ignore l'en-tête. La valeur est le nombre de SAUTS de proxy qui ajoutent une entrée à
+`X-Forwarded-For`, pas le nombre de produits déployés : Railway demande `2` (mesuré : son
+en-tête porte le client, puis le proxy d'entrée). Une valeur trop BASSE échoue en silence,
+car le limiteur se fonde alors sur l'adresse d'un proxy partagée par de nombreux clients.
+Pour la mesurer, envoyez 21 enregistrements depuis un même client et attendez un `429` au
+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.
 
 **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.
@@ -194,6 +231,11 @@ fonctionne sur un serveur que vous hébergez, dans cet ordre :
    nomme l'exigence de Home URL. C'est un avertissement, jamais un refus : il signifie « une
    connexion distante ne marchera que si la Home URL pointe sur ce serveur, ou si vous passez à
    une instance de production ». Il ne contient ni clé ni secret.
+6. **La page de consentement.** Le choix d'organisation reprend le design du tableau de bord
+   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.
 
 ### Multi-tenance
 
@@ -202,6 +244,220 @@ vérifiée de l'appelant (`isRowInTenant`) ; un jeton sans organisation reçoit
 refus d'outil explicite, jamais une vue non filtrée. Ne résolvez le tenant de
 l'appelant qu'à partir du jeton vérifié, jamais d'un argument d'outil.
 
+### La personne vérifiée dans un outil
+
+Un outil peut aussi avoir besoin de la PERSONNE derrière l'appel (sujet, rôle, statut
+d'administrateur), par exemple pour filtrer des lignes par personne. La personne est résolue une
+fois par requête `/mcp` par `resolveCallerFromClaims` de `@vantageos/cloud-identity`, à partir des
+mêmes claims vérifiés que le tenant ; le serveur ne lit jamais un claim lui-même. Le paquet lit
+deux magasins que vous injectez, et les rôles d'administrateur sont à vous de les nommer
+(obligatoires, non vides, aucun défaut) :
+
+```ts
+import { buildHttpApp } from "@vantageos/mcp-boilerplate";
+
+const app = buildHttpApp({
+  authMode: "oauth",
+  authorizationServer,
+  identity: {
+    orgLookups: { orgById: (orgId) => orgStore.get(orgId) },
+    principalLookups: {
+      personById: (personId, orgId) => people.get(orgId, personId),
+      organisationById: (orgId) => orgStore.row(orgId),
+      orgKindOf: (orgId) => orgStore.kind(orgId),
+    },
+    adminRoles: ["org:admin"],
+  },
+});
+```
+
+Un outil déclare qu'il exige la personne en enveloppant son handler avec `withVerifiedPerson`
+(dans `src/mcpServerFactory.ts`, où `deps` est le contexte par requête dans lequel voyage le
+tenant) :
+
+```ts
+server.registerTool("my_rows", config, withVerifiedPerson(deps, async (args, person) => {
+  // person : { subject, actorName, org, principal, role, isOrgAdmin }, gelée, telle que le paquet l'a rendue
+  return structuredResult({ rows: rowsVisibleTo(person.subject) });
+}));
+```
+
+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),
+`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.
+
+## Appeler une API amont (OAuth 2 client_credentials)
+
+Un serveur dérivé de ce boilerplate qui lit une API tierce avec ses propres identifiants utilise
+`createClientCredentialsTokenSource` (`src/upstream/clientCredentials.ts`). Créez-le UNE fois,
+au niveau du module : le serveur MCP est reconstruit à chaque requête, et le cache du jeton vit
+dans la source.
+
+```ts
+const upstream = createClientCredentialsTokenSource(
+  clientCredentialsFromEnv({
+    clientIdVar: "UPSTREAM_CLIENT_ID",
+    clientSecretVar: "UPSTREAM_CLIENT_SECRET",
+    tokenUrlVar: "UPSTREAM_TOKEN_URL",
+  })
+);
+// dans un handler d'outil :
+const res = await upstream.fetchWithToken("https://api.upstream.example/v1/things");
+```
+
+Les noms de variables sont à votre choix. Le jeton est mis en cache jusqu'à `expires_in` moins
+une marge de 60 s, les appels simultanés partagent une seule requête de jeton, et un 401
+déclenche un seul nouveau jeton et une seule nouvelle tentative, jamais plus. L'authentification
+du client est `client_secret_basic` par défaut, ou `client_secret_post`. Une variable manquante
+est nommée au démarrage, sans jamais afficher sa valeur ; un échec du point de jeton est une
+`UpstreamTokenError` portant le statut et le code OAuth `error`, jamais un identifiant ni un
+jeton.
+
+### Lire toutes les pages d'un endpoint paginé par décalage
+
+`createPaginatedUpstreamClient` (`src/upstream/paginatedClient.ts`) lit un endpoint amont paginé
+par décalage (offset) et taille (limit). Les noms des paramètres, leur emplacement (`query` ou
+`jsonBody`) et la méthode sont de la configuration. Créez-le une fois au niveau du module, à côté
+de la source de jeton :
+
+```ts
+const things = createPaginatedUpstreamClient({
+  fetchImpl: upstream.fetchWithToken,
+  baseUrl: "https://api.upstream.example/v1/",
+  allowedOrigins: ["https://api.upstream.example"],
+  offsetParam: "offset",
+  limitParam: "limit",
+  placement: "jsonBody", // POST avec offset et limit dans le corps JSON ; "query" envoie un GET
+  rowCeiling: 5000,
+  extractRows: (body) => (body as { data: unknown[] }).data,
+});
+const all = await things.readAll("things", { status: "active" }); // toutes les pages, ou un refus
+const page = await things.readPage("things", { status: "active" }, cursor); // une page par appel
+```
+
+`allowedOrigins` et `rowCeiling` sont obligatoires. Un chemin qui se résout vers une autre origine
+est refusé avant tout appel réseau : le jeton ne part jamais vers un hôte nommé par un argument
+d'outil, et les redirections sont refusées, jamais suivies (`redirect: "error"`). `readAll` s'arrête
+sur la page incomplète (ou au total, avec `extractTotal`) et refuse un ensemble au-delà du plafond
+avec `row_ceiling_exceeded`, jamais un ensemble tronqué en silence. `readPage` renvoie
+`{ rows, nextCursor?, exhausted }` ; son curseur est lié au chemin et aux paramètres, et un curseur rejoué
+sur une autre requête ou altéré sans recalcul de son empreinte est refusé en `invalid_cursor`.
+L'empreinte n'est pas signée : elle détecte un mauvais usage, pas une falsification ; l'offset ne
+confère aucun droit et un offset forgé au-delà du plafond est refusé avant toute requête. Une page
+vide avant le total déclaré est refusée en `inconsistent_page`, jamais redemandée. Les 429 et 503
+sont rejoués avec un délai exponentiel (5 tentatives par défaut, base 500 ms, plafond 30 s) et
+respectent `Retry-After` ; aucun autre statut n'est rejoué. Les erreurs (`UpstreamPageError`)
+nomment le chemin et le statut, jamais un jeton, une valeur de paramètre ni le corps. Gardez
+`pageSize` (défaut 100) dans le maximum réel de l'amont : une page plafonnée en silence en dessous
+se lit comme la dernière, sauf si la réponse déclare un total.
+
+## Déclarer sa propre configuration
+
+Un serveur dérivé déclare une fois les variables d'environnement qu'il lit, et reçoit au
+démarrage un objet typé, validé et gelé (`src/declaredVariables.ts`) :
+
+```ts
+import { defineVariables, describeVariables, loadVariables } from "@vantageos/mcp-boilerplate";
+
+export const declared = defineVariables({
+  apiBaseUrl: {
+    env: "UPSTREAM_API_BASE_URL",
+    type: "url",
+    description: { en: "Upstream API base URL", fr: "URL de base de l'API amont" },
+  },
+  readKey: {
+    env: "LAKE_READ_KEY",
+    type: "string",
+    secret: true,
+    description: { en: "Data lake read key", fr: "Clé de lecture du lac de données" },
+  },
+  pageSize: {
+    env: "UPSTREAM_PAGE_SIZE",
+    type: "integer",
+    min: 1,
+    max: 500,
+    required: false,
+    default: 100,
+    description: { en: "Rows per upstream page", fr: "Lignes par page amont" },
+  },
+  fieldMap: {
+    env: "FIELD_MAPPINGS",
+    type: "json",
+    description: { en: "Code-to-label mappings", fr: "Correspondances code-libellé" },
+  },
+});
+
+export const settings = loadVariables(declared); // settings.pageSize : number
+console.log(describeVariables(declared)); // le contrat, pour --help : aucune valeur, aucun défaut
+```
+
+Les noms de variables sont à votre choix. Types : `string`, `integer` (`min`/`max`), `boolean`
+(`"0"` ou `"1"`), `url` (https, http seulement sur la boucle locale), `originList`, `enum`
+(`values`) et `json` (un objet ou un tableau). Une variable est requise sauf si elle indique
+`required: false` ; un `default` exige `required: false`. Absente ou vide, elle est manquante ;
+une valeur définie mais invalide est refusée, jamais remplacée par le défaut. Toutes les variables
+manquantes ou invalides sont signalées ensemble dans UNE `ConfigurationError`
+(`problems: { key, env, reason, expected }[]`, message en anglais et en français) qui les nomme
+sans jamais afficher de valeur. Le résultat est gelé et typé d'après la déclaration : une clé non
+déclarée ne compile pas, et sa lecture à l'exécution lève une erreur. `JSON.stringify`, `String()`
+et `console.log` du résultat ne lèvent jamais d'erreur et affichent une valeur `secret: true`
+sous la forme `[secret]` ; un secret est ignoré par la décomposition (`...`) et `Object.entries`,
+et se lit uniquement par son nom. Une déclaration cassée (nom de variable en double, type ou
+propriété inconnus, défaut qui ne se valide pas) est refusée dès l'appel à `defineVariables`. Les
+variables propres au boilerplate (`OAUTH_ENV`, les réglages du serveur, `clientCredentialsFromEnv`)
+n'utilisent pas encore ce registre.
+
+## Lire le data-lake du client
+
+Un serveur dérivé lit le data-lake de son client (l'unique source persistée) à travers une
+interface en LECTURE SEULE, `LakeReader` (`src/lake/reader.ts`) : `listPage({ after?, limit, scope? })`
+renvoie `{ rows, exhausted }` dans l'ordre croissant des clés, `get(key, scope?)` renvoie une ligne
+ou `undefined`, et `keyOf(row)` désigne la clé stable que porte le curseur. Il n'existe aucune
+méthode d'écriture. `list_items` lit à travers le lecteur injecté par `buildHttpApp({ lake })` (ou
+`McpServerDeps.lake`) ; sans injection, il lit les données d'exemple en mémoire
+(`EXAMPLE_ITEMS_READER`), exactement comme avant. Le tenant de l'appelant voyage DANS la lecture
+sous la forme de `scope`, et chaque ligne renvoyée est revérifiée : une ligne d'un autre tenant fait
+échouer l'appel, fermé. `readPage` applique les bornes et le curseur de l'outil à n'importe quel
+lecteur et contrôle chaque page contre le contrat ; une page illisible (pas une liste, plus de
+lignes que demandé, clés désordonnées ou non postérieures au curseur, page tronquée sans ligne,
+ligne sans clé) est une `LakeReadError`, à laquelle `list_items` répond par une erreur d'outil au
+code stable `lake_unreadable` avec la raison, jamais par une page vide ou partielle.
+
+L'adaptateur Convex est livré sous son propre sous-chemin ; `convex` est une dépendance pair
+optionnelle, installée seulement par un serveur qui l'importe :
+
+```ts
+import { convexLakeReaderFromEnv } from "@vantageos/mcp-boilerplate/lake/convex";
+
+const lake = convexLakeReaderFromEnv(
+  process.env,
+  { urlVar: "LAKE_URL", tokenVar: "LAKE_READ_KEY" },
+  {
+    functions: { page: "lakeRead:listRows", get: "lakeRead:getRow" },
+    keyField: "rowKey",
+    tokenArg: "readKey", // à omettre pour envoyer le jeton par setAuth (Authorization: Bearer)
+  }
+);
+const app = buildHttpApp({ authMode: "oauth", authorizationServer, lake });
+```
+
+Les noms de variables, les noms des fonctions de requête et le champ clé sont de la configuration :
+rien dans le paquet ne nomme une table ou une fonction. Les variables de connexion sont déclarées
+avec `defineVariables` (l'URL en `url` : https, http seulement sur la boucle locale ; le jeton en
+`secret`), si bien qu'une variable manquante ou invalide est refusée au démarrage, par son nom,
+jamais par sa valeur. L'adaptateur n'appelle que `ConvexHttpClient.query`, jamais une mutation ni
+une action. La fonction de page reçoit `{ after?, limit, tenantId? }` et renvoie les lignes dont la
+clé suit `after`, par ordre croissant, au plus `limit` (l'adaptateur demande une ligne de plus que
+la page pour distinguer une page tronquée de la dernière) ; la fonction de lecture unitaire reçoit
+`{ key, tenantId? }` et renvoie la ligne ou `null`. Un `parseRow` optionnel (par exemple un `parse`
+Zod) type chaque ligne et refuse celle qu'il ne sait pas lire. Un appel en échec est `read_failed`,
+et le message du client n'est pas relayé : aucune erreur ne porte le jeton, l'URL ni une valeur de
+ligne.
+
 ## i18n côté serveur (FR/EN)
 
 `src/i18n.ts` localise les messages d'erreur/validation MCP et la page de sélection :
@@ -223,8 +479,10 @@ stdio.
 
 ## Ajouter un outil
 
-Enregistrez-le une fois dans `src/mcpServerFactory.ts` avec `title`, les quatre
-annotations, `inputSchema` et `outputSchema`, et renvoyez `structuredResult(...)`. Il
+Déclarez sa fiche dans `src/toolRecord.ts` (couple d'autorité, verbe, table, et pour
+une liste/recherche le mécanisme et la pagination), enregistrez-le une fois dans
+`src/mcpServerFactory.ts` avec `title`, `annotations: VOS_ANNOTATIONS`,
+`inputSchema` et `outputSchema`, et renvoyez `structuredResult(...)`. Il
 est alors servi sur les deux transports et les deux ères du protocole.
 `tests/toolRecordComplete.test.ts` le garde honnête.
 
@@ -262,10 +520,60 @@ npm publish                 # prepublishOnly relance build + test + evals
 La publication se prouve par le `dist-tag` du registre, jamais par le code de sortie
 de `npm publish`.
 
+La version vit dans `package.json` ET dans `mcp-server.json` (le manifeste serveur,
+mcp-standard C-18). Montez les deux à la même valeur : `scripts/sync-plugin-version.mjs`
+lit la version dans le manifeste et refuse un `package.json` qui diffère, en nommant
+les deux. Le manifeste déclare aussi les capabilities du serveur, que la fabrique
+sert, et les interrupteurs de fonctionnalités que les versions suivantes liront.
+
+## Épingler et vérifier le paquet publié
+
+Installez depuis npm, le registre de référence, et épinglez une version EXACTE pour
+qu'une mise à jour n'arrive jamais sans l'avoir demandée. `1.2.3` ci-dessous est un
+exemple, pas une version publiée : listez les vraies et remplacez-la par la version
+que vous avez auditée.
+
+```bash
+npm view @vantageos/mcp-boilerplate versions --json     # les versions publiées
+npm install @vantageos/mcp-boilerplate@1.2.3             # épingler une version exacte
+```
+
+Le retour arrière consiste à épingler la version précédente ; aucune version publiée
+n'est jamais retirée.
+
+```bash
+npm install @vantageos/mcp-boilerplate@1.2.2             # retour arrière : la version précédente
+```
+
+Un second canal indépendant porte le même tag : la GitHub release de
+`elpiarthera/vantage-mcp-boilerplate`. Le paquet est publié avec
+`npm publish --provenance` par `.github/workflows/release.yml` ; vérifiez
+l'attestation avec `npm audit signatures`.
+
+GitHub Actions est désactivé dans toute la flotte ElPi Corp : une publication faite
+sans CI n'a pas d'attestation de provenance. La vérification équivalente est la somme
+de contrôle du tarball empaqueté, reproduite depuis un checkout propre du tag puis
+relue au registre :
+
+```bash
+npm pack                                # affiche le nom du tarball
+shasum mcp-boilerplate-1.2.3.tgz        # la somme que vous reproduisez (nom réel)
+curl -s -H 'Cache-Control: no-cache' https://registry.npmjs.org/@vantageos%2Fmcp-boilerplate/1.2.3 \
+  | node -p "JSON.parse(require('fs').readFileSync(0,'utf8')).dist.shasum"
+```
+
+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.
+
 ## Couche UI MCP Apps
 
-`render_items_ui` rend `EXAMPLE_ITEMS` sous forme de widget interactif
-(`io.modelcontextprotocol/ui`, spec 2026-01-26).
+`list_items` rend sa page de `EXAMPLE_ITEMS` sous forme de widget interactif
+(`io.modelcontextprotocol/ui`, spec 2026-01-26). Une opération sur une table est un
+seul outil (mcp-standard C-12) : l'outil de données porte lui-même le lien UI, il
+n'y a pas d'outil de rendu séparé.
 
 - L'outil relie sa ressource `ui://` par la clé imbriquée `_meta.ui.resourceUri`
   avec `visibility: ["model", "app"]` explicite. L'outil est enregistré avec
@@ -289,7 +597,7 @@ en un seul fichier HTML autonome (un plugin d'inlining local dans `vite.config.t
 `dist/ui-bundle/widget.html`) par `npm run build:ui`, sur un chemin qui n'entre
 jamais en collision avec `dist/ui/` de tsc.
 
-**Couche d'identité** : `@vantageos/cloud-identity` (^0.19.0) est le seul paquet
+**Couche d'identité** : `@vantageos/cloud-identity` (^0.20.2) est le seul paquet
 d'identité. Son point d'entrée resource-server (`verifyMcpAccessToken`,
 `buildProtectedResourceMetadata`) vérifie le jeton Bearer sur `/mcp` ; `jose` ne sert
 plus qu'à signer les jetons d'accès du serveur d'autorisation. Un jeu de clés