@vantageos/mcp-boilerplate 0.3.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "vantage-mcp-boilerplate",
   "displayName": "VantageOS MCP Boilerplate",
-  "version": "0.3.0",
+  "version": "0.4.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,41 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-28
+
+> **BREAKING for forks.** `CONTEXT_CEILING` is no longer exported and `mcp-server.json` must declare
+> `contextCeiling`. Migration: add `contextCeiling: { global, perTool }` to your `mcp-server.json`
+> (the seed uses `{ "global": 1200, "perTool": 700 }`) and replace every `CONTEXT_CEILING` import
+> with `loadServerManifest().contextCeiling`.
+
+### Added
+
+- **Per-server context ceiling** (G6): `mcp-server.json` carries `contextCeiling: { global, perTool }`
+  (positive integers, `global >= perTool`), read by `loadServerManifest`. A missing or non-numeric
+  value refuses at start, naming the field (FR+EN); `features` stays booleans only.
+  `checkContextCeiling` and `assertToolRecords` (exported) enforce the standard's rule against the
+  server's own ceiling: no tool above `perTool`, the sum not above `global`.
+- **`upstream-delegated(<upstream>)` search mechanism** for a tool answered by a live upstream call.
+  `checkToolRecord` / `assertToolRecords` refuse an undeclared live call (a list/search tool with
+  `openWorldHint: true` and an indexed mechanism or none), the declaration without
+  `openWorldHint: true`, an empty upstream name, `unindexed-scan` and any value outside the set.
+
+### Changed
+
+- **BREAKING for forks** (0.x): the start refusal for tool records now runs on the tools AS
+  REGISTERED. The factory no longer holds a hand-typed `{ ping, list_items }` map: it wraps
+  `server.registerTool` (`trackToolRecords`, exported) and asserts the collected annotations once
+  every tool is registered. A tool registered with an unsound record, or with none, refuses the
+  start by name (FR+EN); a fork adds nothing to a list.
+- `upstream-delegated(<upstream>)` refuses `upstream-delegated())`; the indexed mechanism set is
+  matched whole, so `indexed-range(anything` is refused.
+
+### Removed (BREAKING for forks)
+
+- **`CONTEXT_CEILING`** is no longer exported by `src/toolRecord.ts`: read
+  `loadServerManifest().contextCeiling`. A fork's `mcp-server.json` must add `contextCeiling`
+  (the seed declares `{ "global": 1200, "perTool": 700 }`, the former constant).
+
 ## [0.3.0] - 2026-10-28
 
 ### Added

package/README.fr.md

@@ -92,9 +92,9 @@ Chaque outil déclare `title`, un schéma d'entrée et un schéma de sortie typ
 | `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 |
+| `searchMechanism` | C-10 | comment une liste/recherche est servie (`indexed-range` ici) ; `unindexed-scan` ne se publie pas. Un outil servi par un appel tiers en direct déclare `upstream-delegated(<amont>)` avec `openWorldHint: true` ; `assertToolRecords` refuse un appel en direct non déclaré, ou la déclaration sans le hint |
 | `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 |
+| `tokensEstimeContexte` | C-13 | coût de contexte estimé ; le `contextCeiling` propre au serveur (`global`, `perTool`, dans `mcp-server.json`) borne chaque outil et la somme, appliqué par `assertToolRecords` au démarrage ; un plafond absent ou non numérique arrête le serveur |
 
 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.

package/README.md

@@ -91,9 +91,9 @@ and returns `structuredContent` plus a text block with the same JSON. Its
 | `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` | C-15 | the four behavioural booleans |
 | `authRead`, `authWrite` | C-8 | authority pair from `public` / `org-member` / `org-admin` / `fleet-internal` / `master`, distinct; resolved from the verified identity, never from an argument |
 | `verb`, `table` | C-9, C-12 | the operation (`list`, `get`, `create`, `pure`...) and the data it touches |
-| `searchMechanism` | C-10 | how a list/search is served (`indexed-range` here); `unindexed-scan` does not publish |
+| `searchMechanism` | C-10 | how a list/search is served (`indexed-range` here); `unindexed-scan` does not publish. A tool answered by a live third-party call declares `upstream-delegated(<upstream>)` with `openWorldHint: true`; `assertToolRecords` refuses an undeclared live call, or the declaration without the hint |
 | `paginationCursor`, `paginationDefault`, `paginationMax` | C-11 | cursor, default page size and a finite maximum, applied by `src/pagination.ts` |
-| `tokensEstimeContexte` | C-13 | estimated context cost; `CONTEXT_CEILING` bounds each tool and the sum |
+| `tokensEstimeContexte` | C-13 | estimated context cost; the server's own `contextCeiling` (`global`, `perTool`, in `mcp-server.json`) bounds each tool and the sum, enforced by `assertToolRecords` at start; a missing or non-numeric ceiling stops the server |
 
 The sets are closed TypeScript unions: a value outside them does not compile, and a
 list tool cannot omit its mechanism or its pagination. Each tool's record is a plain

package/dist/httpApp.js

@@ -31,6 +31,7 @@ import { detectLocale, t } 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 { assertIdentityDeps, resolveVerifiedPerson, } from "./verifiedPerson.js";
 import { SERVER_VERSION } from "./version.js";
@@ -41,6 +42,8 @@ const PRM_PATHS = [
 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();
     if (deps.identity)
         assertIdentityDeps(deps.identity);
     // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25), so a

package/dist/index.d.ts

@@ -12,3 +12,9 @@ export { UpstreamTokenError, clientCredentialsFromEnv, createClientCredentialsTo
 export type { ClientAuthMethod, ClientCredentialsEnvOptions, ClientCredentialsEnvVars, ClientCredentialsOptions, ClientCredentialsTokenSource, } from "./upstream/clientCredentials.js";
 export { UpstreamPageError, createPaginatedUpstreamClient } from "./upstream/paginatedClient.js";
 export type { FetchLike, PaginatedUpstreamClient, PaginatedUpstreamOptions, PaginationPlacement, ParamObject, ParamValue, UpstreamPage, UpstreamPageErrorCode, UpstreamParams, } from "./upstream/paginatedClient.js";
+export { ServerManifestError, loadServerManifest, parseServerManifest, } from "./serverManifest.js";
+export type { ContextCeiling, ServerManifest } from "./serverManifest.js";
+export { trackToolRecords } from "./servedToolRecords.js";
+export type { ServedToolRecords } from "./servedToolRecords.js";
+export { ToolRecordError, assertToolRecords, checkContextCeiling, checkToolRecord, } from "./toolRecord.js";
+export type { ContextEstimate, SearchMechanism, ToolSlots } from "./toolRecord.js";

package/dist/index.js

@@ -6,3 +6,6 @@ export { buildHttpApp } from "./httpApp.js";
 export { PERSON_UNRESOLVED_CODE, resolveVerifiedPerson, withVerifiedPerson, } from "./verifiedPerson.js";
 export { UpstreamTokenError, clientCredentialsFromEnv, createClientCredentialsTokenSource, } from "./upstream/clientCredentials.js";
 export { UpstreamPageError, createPaginatedUpstreamClient } from "./upstream/paginatedClient.js";
+export { ServerManifestError, loadServerManifest, parseServerManifest, } from "./serverManifest.js";
+export { trackToolRecords } from "./servedToolRecords.js";
+export { ToolRecordError, assertToolRecords, checkContextCeiling, checkToolRecord, } from "./toolRecord.js";

package/dist/locales/en.json

@@ -36,9 +36,14 @@
         "string": "a non-empty string",
         "semver": "a semantic version (x.y.z)",
         "object": "an object",
-        "boolean": "true or false"
+        "boolean": "true or false",
+        "positiveInteger": "a positive whole number",
+        "atLeastPerTool": "at least the perTool ceiling"
       }
     },
+    "toolRecord": {
+      "unsound": "tool records or the context ceiling are unsound: {problems}"
+    },
     "pagination": {
       "invalidCursor": "invalid cursor: it was not issued by this tool or is no longer valid; start again without a cursor"
     },

package/dist/locales/fr.json

@@ -36,9 +36,14 @@
         "string": "une chaîne non vide",
         "semver": "une version sémantique (x.y.z)",
         "object": "un objet",
-        "boolean": "true ou false"
+        "boolean": "true ou false",
+        "positiveInteger": "un entier strictement positif",
+        "atLeastPerTool": "au moins le plafond perTool"
       }
     },
+    "toolRecord": {
+      "unsound": "fiches d'outils ou plafond de contexte invalides : {problems}"
+    },
     "pagination": {
       "invalidCursor": "curseur invalide : il n'a pas été émis par cet outil ou n'est plus valide ; recommencez sans curseur"
     },

package/dist/mcpServerFactory.js

@@ -35,6 +35,7 @@ import { getBuildIdentity } from "./buildIdentity.js";
 import { t } from "./i18n.js";
 import { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, } from "./lake/reader.js";
 import { INVALID_CURSOR_CODE, InvalidCursorError, PAGINATION, readPage } from "./pagination.js";
+import { trackToolRecords } from "./servedToolRecords.js";
 import { loadServerManifest } from "./serverManifest.js";
 import { scopeRowsForTenant } from "./tenancy.js";
 import { LIST_ITEMS_ANNOTATIONS, PING_ANNOTATIONS } from "./toolRecord.js";
@@ -95,6 +96,10 @@ function refusal(text) {
 }
 export function createBoilerplateMcpServer(deps = {}) {
     const locale = deps.locale ?? "en";
+    // The manifest carries the server's context ceiling. Every tool registered below is recorded
+    // at registration and checked against it (and the closed mechanism set) before the server is
+    // returned: the check covers what is served, there is no list to keep in step.
+    const manifest = loadServerManifest();
     // The identity the server announces: version (declared) AND buildId (derived from the served
     // tree, src/buildIdentity.ts). The SDK sends `serverInfo` as given, on `server/discover`
     // (2026-07-28, `_meta["io.modelcontextprotocol/serverInfo"]`) and on `initialize` (2025-era).
@@ -105,7 +110,7 @@ export function createBoilerplateMcpServer(deps = {}) {
         ...{ buildId: getBuildIdentity() },
     }, {
         // The capabilities come from the server manifest (mcp-server.json, C-18): one source.
-        capabilities: loadServerManifest().capabilities,
+        capabilities: manifest.capabilities,
         instructions: "Clonable MCP server boilerplate — see README.md",
         supportedProtocolVersions: SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
         cacheHints: {
@@ -115,6 +120,7 @@ export function createBoilerplateMcpServer(deps = {}) {
             "server/discover": { ttlMs: 300_000, cacheScope: "public" },
         },
     });
+    const served = trackToolRecords(server);
     server.registerTool("ping", {
         title: "Ping",
         description: "Echoes the given message (or 'pong' if none given). Proves the MCP handshake end to end.",
@@ -212,5 +218,7 @@ export function createBoilerplateMcpServer(deps = {}) {
     }, async () => ({
         contents: [buildUiResource({ domain: deps.uiDomain })],
     }));
+    // Start refusal: every registered tool's record, as registered, must be sound.
+    served.assertServed(manifest.contextCeiling);
     return server;
 }

package/dist/servedToolRecords.d.ts

@@ -0,0 +1,18 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { ContextCeiling } from "./serverManifest.js";
+/**
+ * The tool records AS REGISTERED. The start refusal (`assertToolRecords`) must run on the tools
+ * the server actually serves, not on a second list a fork has to keep in step with its
+ * `registerTool` calls: a tool missing from such a list would ship unchecked.
+ *
+ * `trackToolRecords` wraps `server.registerTool` on that instance and keeps each tool's
+ * `annotations` as given. A tool registered with none is kept as `{}`, so it fails the check
+ * by name instead of being skipped. Call `assertServed` once every tool is registered.
+ */
+export interface ServedToolRecords {
+    /** The annotations of every tool registered so far, by tool name. */
+    readonly records: Readonly<Record<string, Record<string, unknown>>>;
+    /** Throws `ToolRecordError` naming every unsound tool; same check as the wire test. */
+    assertServed(ceiling: ContextCeiling): void;
+}
+export declare function trackToolRecords(server: McpServer): ServedToolRecords;

package/dist/servedToolRecords.js

@@ -0,0 +1,10 @@
+import { assertToolRecords } from "./toolRecord.js";
+export function trackToolRecords(server) {
+    const records = {};
+    const register = server.registerTool.bind(server);
+    server.registerTool = ((name, config, callback) => {
+        records[name] = { ...(config.annotations ?? {}) };
+        return register(name, config, callback);
+    });
+    return { records, assertServed: (ceiling) => assertToolRecords(records, ceiling) };
+}

package/dist/serverManifest.d.ts

@@ -8,6 +8,15 @@
  * message. Nothing is defaulted — a manifest that silently falls back hides the very drift
  * C-18 exists to catch.
  */
+/**
+ * The context ceiling (mcp-standard C-13), in estimated tokens, declared by THIS server: no tool
+ * may pass `perTool`, and the tools together may not pass `global`. A server with more tools
+ * declares a larger ceiling here; `checkContextCeiling` (src/toolRecord.ts) enforces it.
+ */
+export interface ContextCeiling {
+    global: number;
+    perTool: number;
+}
 export interface ServerManifest {
     name: string;
     version: string;
@@ -15,8 +24,10 @@ export interface ServerManifest {
     transport: Record<string, unknown>;
     /** Feature switches. Every value is a boolean; a lane adds its own key. */
     features: Record<string, boolean>;
+    /** The per-server context ceiling. A number cannot ride in `features` (booleans only). */
+    contextCeiling: ContextCeiling;
 }
-type Expectation = "string" | "semver" | "object" | "boolean";
+type Expectation = "string" | "semver" | "object" | "boolean" | "positiveInteger" | "atLeastPerTool";
 /** Thrown when a manifest field cannot be read. `field` is the dotted path of the offender. */
 export declare class ServerManifestError extends Error {
     readonly field: string;

package/dist/serverManifest.js

@@ -28,11 +28,14 @@ const SEMVER = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isPositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
 /** Validates an already-parsed manifest document. `source` names it in the refusal. */
 export function parseServerManifest(document, source) {
     if (!isRecord(document))
         throw new ServerManifestError("(document)", source, "object");
-    const { name, version, capabilities, transport, features } = document;
+    const { name, version, capabilities, transport, features, contextCeiling } = document;
     if (typeof name !== "string" || name.length === 0) {
         throw new ServerManifestError("name", source, "string");
     }
@@ -50,7 +53,26 @@ export function parseServerManifest(document, source) {
             throw new ServerManifestError(`features.${key}`, source, "boolean");
         }
     }
-    return { name, version, capabilities, transport, features: features };
+    if (!isRecord(contextCeiling))
+        throw new ServerManifestError("contextCeiling", source, "object");
+    const { global, perTool } = contextCeiling;
+    if (!isPositiveInteger(global)) {
+        throw new ServerManifestError("contextCeiling.global", source, "positiveInteger");
+    }
+    if (!isPositiveInteger(perTool)) {
+        throw new ServerManifestError("contextCeiling.perTool", source, "positiveInteger");
+    }
+    if (global < perTool) {
+        throw new ServerManifestError("contextCeiling.global", source, "atLeastPerTool");
+    }
+    return {
+        name,
+        version,
+        capabilities,
+        transport,
+        features: features,
+        contextCeiling: { global, perTool },
+    };
 }
 /**
  * Reads `mcp-server.json` from the package root. `src/` and `dist/` both sit one level under

package/dist/stdio.js

@@ -8,11 +8,14 @@
  */
 import { serveStdio } from "@modelcontextprotocol/server/stdio";
 import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+import { loadServerManifest } from "./serverManifest.js";
 export function startStdioServer() {
     // `requireTenant` is otherwise only reachable from the OAuth-tier HTTP transport (see
     // httpApp.ts). This env toggle exists solely so the eval suite (evals/evals.json
     // "list-items-requires-tenant-refusal") can exercise the existing `list_items`
     // tenant-refusal branch through the real stdio transport. Unset by default.
+    // Refuses at start, naming the field, a manifest without a readable context ceiling (G6).
+    loadServerManifest();
     const requireTenant = process.env.MCP_BOILERPLATE_REQUIRE_TENANT === "1";
     const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
     // No verified person on stdio, by design: there is no bearer and no verified session on this

package/dist/toolRecord.d.ts

@@ -1,3 +1,4 @@
+import type { ContextCeiling } from "./serverManifest.js";
 /**
  * The typed tool record (mcp-standard C-4, C-8, C-9, C-10, C-11, C-12, C-13, C-15): everything
  * a caller reads from `tools/list` WITHOUT reading the source, declared once per tool as a
@@ -26,8 +27,13 @@ export type ToolVerb = "list" | "get" | "search" | "aggregate" | "create" | "upd
 /**
  * mcp-standard.md §3 point 3 — search mechanisms, closed set. `unindexed-scan` is deliberately
  * absent: it is refused at publication, so the type refuses it at compile time.
+ *
+ * `upstream-delegated(<upstream>)` is the honest value for a tool answered by a LIVE call to a
+ * third-party API: this server keeps no index for it, and the upstream is named. It is allowed
+ * only together with `openWorldHint: true`, and a list/search tool with `openWorldHint: true`
+ * must declare it (`checkToolRecord`).
  */
-export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf";
+export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf" | `upstream-delegated(${string})`;
 /** The four behavioural annotations (C-15), explicit booleans on every tool. */
 interface BehaviourHints {
     readOnlyHint: boolean;
@@ -87,8 +93,32 @@ export declare const LIST_ITEMS_ANNOTATIONS: {
     readonly paginationMax: 100;
     readonly tokensEstimeContexte: 640;
 };
-export declare const CONTEXT_CEILING: {
-    readonly global: 1200;
-    readonly perTool: 700;
-};
+/** One tool's declared context cost, as `checkContextCeiling` reads it. */
+export interface ContextEstimate {
+    name: string;
+    tokens: number;
+}
+/** Every problem found, each naming the tool; empty when the ceiling holds. Never skips a tool. */
+export declare function checkContextCeiling(estimates: readonly ContextEstimate[], ceiling: ContextCeiling): string[];
+/**
+ * Problems with ONE tool's served record; empty when it is sound. Reads a loose record because the
+ * same check runs on the declared literals and on the annotations as served.
+ *
+ * A list/search tool must declare a mechanism of the closed set: an indexed one when it reads
+ * data this server holds (`openWorldHint: false`), `upstream-delegated(<upstream>)` when it calls
+ * out (`openWorldHint: true`). The two slots must agree, so a live-call tool cannot pass for an
+ * indexed one, nor an indexed one claim to be delegated. `unindexed-scan` and any other value are
+ * refused. A tool that is not a list/search is not asked for a mechanism.
+ */
+export declare function checkToolRecord(name: string, record: Record<string, unknown>): string[];
+/** Thrown at start when a tool record or the ceiling is unsound. `problems` name every tool. */
+export declare class ToolRecordError extends Error {
+    readonly problems: readonly string[];
+    constructor(problems: readonly string[]);
+}
+/**
+ * Refuses at start: every record passes `checkToolRecord`, and the declared estimates fit the
+ * server's own ceiling (from its manifest). A derived server passes ALL its tools' records.
+ */
+export declare function assertToolRecords(records: Readonly<Record<string, Record<string, unknown>>>, ceiling: ContextCeiling): void;
 export {};

package/dist/toolRecord.js

@@ -1,24 +1,4 @@
-/**
- * The typed tool record (mcp-standard C-4, C-8, C-9, C-10, C-11, C-12, C-13, C-15): everything
- * a caller reads from `tools/list` WITHOUT reading the source, declared once per tool as a
- * literal object and served as its `annotations`.
- *
- *   authRead, authWrite     C-8   the (read, write) pair, from the closed five-tier set, distinct
- *   verb                    C-9   the operation, from the closed verb set (`rpc` is not a verb)
- *   table                   C-12  the data it touches, beside the verb
- *   searchMechanism         C-10  how a list/search is served; `unindexed-scan` does not publish
- *   paginationCursor/Default/Max  C-11  declared here, applied by src/pagination.ts
- *   tokensEstimeContexte    C-13  the estimated context cost of the served tool
- *
- * The sets are closed UNIONS, so a value outside them is a compile error, and the verb decides
- * which other slots are required (a list/search tool cannot omit its mechanism or its pagination).
- * Each tool's record is a plain `const` object of string/number/boolean literals on purpose:
- * mcp-doctor reads the registration site statically and resolves `annotations: NAME` to the
- * literals below; a computed or spread value would read as "could not judge".
- *
- * SDK 2.3.1 serves unknown annotation keys on the wire (tests/toolAuthorityDeclared.test.ts
- * reads them there); its `Client` drops them, which is why those tests read the raw result.
- */
+import { tBoth } from "./i18n.js";
 // Authority decisions (C-8). The seed tools read; none writes anything, so the write side
 // is `master`, the strictest tier: no caller gains a write through them. `ping` touches no data
 // and is `public`; the item tool is scoped to the caller's organisation on the OAuth tier.
@@ -47,6 +27,88 @@ export const LIST_ITEMS_ANNOTATIONS = {
     paginationMax: 100,
     tokensEstimeContexte: 640,
 };
-// Context ceiling (C-13), global AND per tool, in estimated tokens. The sum of the per-tool
-// estimates above must not pass `global`; no single estimate may pass `perTool`.
-export const CONTEXT_CEILING = { global: 1200, perTool: 700 };
+/** Every problem found, each naming the tool; empty when the ceiling holds. Never skips a tool. */
+export function checkContextCeiling(estimates, ceiling) {
+    const problems = [];
+    let sum = 0;
+    for (const { name, tokens } of estimates) {
+        if (!Number.isInteger(tokens) || tokens < 0) {
+            problems.push(`${name}: tokensEstimeContexte ${String(tokens)} is not a non-negative integer`);
+            continue;
+        }
+        sum += tokens;
+        if (tokens > ceiling.perTool) {
+            problems.push(`${name}: ${tokens} tokens pass the per-tool ceiling ${ceiling.perTool}`);
+        }
+    }
+    if (sum > ceiling.global) {
+        problems.push(`global: ${sum} tokens pass the global ceiling ${ceiling.global}`);
+    }
+    return problems;
+}
+const LIST_VERBS = ["list", "search"];
+// The closed indexed set, exactly: the three parameterless forms, and `indexed-vector(<metric>)`.
+const INDEXED_EXACT = ["indexed-range", "indexed-bm25", "indexed-hybrid-rrf"];
+const INDEXED_VECTOR = /^indexed-vector\([^()\s][^()]*\)$/;
+const DELEGATED = /^upstream-delegated\(\s*[^\s)][^)]*\)$/;
+/** True for a mechanism of the closed indexed set, matched whole (no prefix, no open paren). */
+function isIndexedMechanism(value) {
+    return INDEXED_EXACT.includes(value) || INDEXED_VECTOR.test(value);
+}
+/**
+ * Problems with ONE tool's served record; empty when it is sound. Reads a loose record because the
+ * same check runs on the declared literals and on the annotations as served.
+ *
+ * A list/search tool must declare a mechanism of the closed set: an indexed one when it reads
+ * data this server holds (`openWorldHint: false`), `upstream-delegated(<upstream>)` when it calls
+ * out (`openWorldHint: true`). The two slots must agree, so a live-call tool cannot pass for an
+ * indexed one, nor an indexed one claim to be delegated. `unindexed-scan` and any other value are
+ * refused. A tool that is not a list/search is not asked for a mechanism.
+ */
+export function checkToolRecord(name, record) {
+    if (!LIST_VERBS.includes(record.verb))
+        return [];
+    const mechanism = record.searchMechanism;
+    if (typeof mechanism !== "string") {
+        return [`${name}: a ${String(record.verb)} tool declares no searchMechanism`];
+    }
+    const openWorld = record.openWorldHint === true;
+    if (DELEGATED.test(mechanism)) {
+        return openWorld
+            ? []
+            : [`${name}: ${mechanism} is a live upstream call, but openWorldHint is not true`];
+    }
+    if (isIndexedMechanism(mechanism)) {
+        return openWorld
+            ? [
+                `${name}: ${mechanism} claims an index, but openWorldHint is true (a live call must declare upstream-delegated(<upstream>))`,
+            ]
+            : [];
+    }
+    return [`${name}: searchMechanism "${mechanism}" is not in the closed set`];
+}
+/** Thrown at start when a tool record or the ceiling is unsound. `problems` name every tool. */
+export class ToolRecordError extends Error {
+    problems;
+    constructor(problems) {
+        super(tBoth("toolRecord.unsound", { problems: problems.join("; ") }));
+        this.name = "ToolRecordError";
+        this.problems = problems;
+    }
+}
+/**
+ * Refuses at start: every record passes `checkToolRecord`, and the declared estimates fit the
+ * server's own ceiling (from its manifest). A derived server passes ALL its tools' records.
+ */
+export function assertToolRecords(records, ceiling) {
+    const problems = Object.entries(records).flatMap(([name, record]) => [
+        ...checkToolRecord(name, record),
+    ]);
+    const estimates = Object.entries(records).map(([name, record]) => ({
+        name,
+        tokens: record.tokensEstimeContexte,
+    }));
+    problems.push(...checkContextCeiling(estimates, ceiling));
+    if (problems.length > 0)
+        throw new ToolRecordError(problems);
+}

package/mcp-server.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-boilerplate",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "capabilities": {
     "tools": {},
     "resources": {}
@@ -9,5 +9,6 @@
     "stdio": { "bin": "mcp-boilerplate" },
     "streamableHttp": { "path": "/mcp", "stateless": true }
   },
-  "features": {}
+  "features": {},
+  "contextCeiling": { "global": 1200, "perTool": 700 }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Clonable MCP server skeleton on the official @modelcontextprotocol/server SDK v2 (protocol 2026-07-28 + 2025 legacy, stdio + stateless Streamable HTTP), with its own OAuth 2.1 authorization server (Clerk person + organisation, cloud-identity), MCP Apps UI, tenant scoping, FR/EN i18n and a declarative eval harness.",
   "description_fr": "Squelette de serveur MCP clonable sur le SDK officiel @modelcontextprotocol/server v2 (protocole 2026-07-28 + héritage 2025, stdio + Streamable HTTP sans état), avec son propre serveur d'autorisation OAuth 2.1 (personne + organisation Clerk, cloud-identity), UI MCP Apps, scoping tenant, i18n FR/EN et un harnais d'évaluations déclaratif.",
   "type": "module",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vantage-mcp-boilerplate",
-  "version": "0.3.0",
+  "version": "0.4.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"