@vantageos/mcp-boilerplate 0.2.4 → 0.4.0

package/dist/pagination.js

@@ -0,0 +1,100 @@
+/**
+ * Cursor pagination applied by the tool (mcp-standard C-11, S-12, §3 point 4). A list tool
+ * declares a cursor, a default and a finite maximum (src/toolRecord.ts) and THIS module applies
+ * them, so the bound never depends on the store behind:
+ *
+ *   - the page size is the caller's `limit`, else the default, never above the maximum;
+ *   - the cursor is OPAQUE (base64url of a small JSON object) and carries the last key served,
+ *     so it is stable: rows added or removed elsewhere do not shift the next page;
+ *   - exhausted and truncated are told apart: a truncated page carries `nextCursor` and
+ *     `exhausted: false`; the last page carries `exhausted: true` and no `nextCursor` (an exact
+ *     fit is exhausted, never a false truncation);
+ *   - an invalid or expired cursor is refused with the stable code `invalid_cursor`, never read as
+ *     "page one". It is a TOOL INPUT error (a result with `isError: true`, spec 2025-11-25
+ *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor.
+ */
+import { rangeAfter } from "./exampleItems.js";
+import { checkLakePage } from "./lake/reader.js";
+import { LIST_ITEMS_ANNOTATIONS } from "./toolRecord.js";
+/**
+ * The applied bounds, taken from the tool's own declaration so the number is typed once
+ * (tests/paginationApplied.test.ts proves the served annotations agree).
+ */
+export const PAGINATION = {
+    default: LIST_ITEMS_ANNOTATIONS.paginationDefault,
+    max: LIST_ITEMS_ANNOTATIONS.paginationMax,
+};
+const CURSOR_VERSION = 1;
+/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
+export const INVALID_CURSOR_CODE = "invalid_cursor";
+/** The cursor did not decode to a position in the collection. */
+export class InvalidCursorError extends Error {
+    code = INVALID_CURSOR_CODE;
+    constructor() {
+        super("invalid cursor");
+        this.name = "InvalidCursorError";
+    }
+}
+export function encodeCursor(afterKey) {
+    return Buffer.from(JSON.stringify({ v: CURSOR_VERSION, after: afterKey })).toString("base64url");
+}
+export function decodeCursor(cursor) {
+    let decoded;
+    try {
+        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    }
+    catch {
+        throw new InvalidCursorError();
+    }
+    if (typeof decoded !== "object" ||
+        decoded === null ||
+        decoded.v !== CURSOR_VERSION ||
+        typeof decoded.after !== "string" ||
+        decoded.after.length === 0) {
+        throw new InvalidCursorError();
+    }
+    return decoded.after;
+}
+/**
+ * One page of `sortedRows` (sorted ascending by `id`, the collection key). The read is a key
+ * range (src/exampleItems.ts `rangeAfter`: binary search on the key), so its cost follows the
+ * page, not the collection.
+ */
+export function paginate(sortedRows, request, bounds) {
+    const afterKey = request.cursor === undefined ? undefined : decodeCursor(request.cursor);
+    const wanted = request.limit ?? bounds.default;
+    const size = Math.max(1, Math.min(Math.floor(wanted), bounds.max));
+    // One row more than the page: its existence is what separates truncated from exhausted.
+    const window = rangeAfter(sortedRows, afterKey, size + 1);
+    const items = window.slice(0, size);
+    const last = items[items.length - 1];
+    if (window.length > size && last) {
+        return { items, nextCursor: encodeCursor(last.id), exhausted: false };
+    }
+    return { items, exhausted: true };
+}
+/**
+ * One page read through a lake reader (src/lake/reader.ts): the same bounds and cursor as
+ * `paginate`, the range read delegated to the reader. The cursor is decoded BEFORE the reader is
+ * asked anything (an invalid cursor never costs a read), the page size is the caller's `limit`,
+ * else the default, never above the maximum, and the reader's answer is checked against the page
+ * contract (`checkLakePage`): an unreadable page is a `LakeReadError`, never an empty page. With
+ * the in-memory reader, the result is exactly `paginate`'s (tests/lakeReader.test.ts).
+ */
+export async function readPage(reader, request, bounds, scope) {
+    const after = request.cursor === undefined ? undefined : decodeCursor(request.cursor);
+    const wanted = request.limit ?? bounds.default;
+    const limit = Math.max(1, Math.min(Math.floor(wanted), bounds.max));
+    const lakeRequest = {
+        ...(after === undefined ? {} : { after }),
+        limit,
+        ...(scope === undefined ? {} : { scope }),
+    };
+    const page = checkLakePage(reader, lakeRequest, await reader.listPage(lakeRequest));
+    const items = [...page.rows];
+    const last = items[items.length - 1];
+    if (!page.exhausted && last !== undefined) {
+        return { items, nextCursor: encodeCursor(reader.keyOf(last)), exhausted: false };
+    }
+    return { items, exhausted: true };
+}

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

@@ -0,0 +1,43 @@
+/**
+ * The server manifest loader (mcp-standard C-18). `mcp-server.json`, at the package root, is the
+ * ONE file that carries the server's capabilities, transport, version and feature switches
+ * (`mcp.json` is the OpenAI plugin config in this repository, so the manifest takes the other
+ * name). The factory reads its capabilities from here; later lanes read their switches here.
+ *
+ * Fail-closed: a field that cannot be read is refused BY NAME, in French and English in one
+ * 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;
+    capabilities: Record<string, unknown>;
+    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" | "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;
+    constructor(field: string, source: string, expected: Expectation);
+}
+/** Validates an already-parsed manifest document. `source` names it in the refusal. */
+export declare function parseServerManifest(document: unknown, source: string): ServerManifest;
+/**
+ * Reads `mcp-server.json` from the package root. `src/` and `dist/` both sit one level under
+ * the root, so the same relative URL resolves in source mode (vitest) and in the built output.
+ */
+export declare function loadServerManifest(path?: string): ServerManifest;
+export {};

package/dist/serverManifest.js

@@ -0,0 +1,90 @@
+/**
+ * The server manifest loader (mcp-standard C-18). `mcp-server.json`, at the package root, is the
+ * ONE file that carries the server's capabilities, transport, version and feature switches
+ * (`mcp.json` is the OpenAI plugin config in this repository, so the manifest takes the other
+ * name). The factory reads its capabilities from here; later lanes read their switches here.
+ *
+ * Fail-closed: a field that cannot be read is refused BY NAME, in French and English in one
+ * message. Nothing is defaulted — a manifest that silently falls back hides the very drift
+ * C-18 exists to catch.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { tBoth } from "./i18n.js";
+/** Thrown when a manifest field cannot be read. `field` is the dotted path of the offender. */
+export class ServerManifestError extends Error {
+    field;
+    constructor(field, source, expected) {
+        super(tBoth("manifest.unreadableField", {
+            field,
+            source,
+            expected: { key: `manifest.expect.${expected}` },
+        }));
+        this.name = "ServerManifestError";
+        this.field = field;
+    }
+}
+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, contextCeiling } = document;
+    if (typeof name !== "string" || name.length === 0) {
+        throw new ServerManifestError("name", source, "string");
+    }
+    if (typeof version !== "string" || !SEMVER.test(version)) {
+        throw new ServerManifestError("version", source, "semver");
+    }
+    if (!isRecord(capabilities))
+        throw new ServerManifestError("capabilities", source, "object");
+    if (!isRecord(transport))
+        throw new ServerManifestError("transport", source, "object");
+    if (!isRecord(features))
+        throw new ServerManifestError("features", source, "object");
+    for (const [key, value] of Object.entries(features)) {
+        if (typeof value !== "boolean") {
+            throw new ServerManifestError(`features.${key}`, source, "boolean");
+        }
+    }
+    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
+ * the root, so the same relative URL resolves in source mode (vitest) and in the built output.
+ */
+export function loadServerManifest(path = fileURLToPath(new URL("../mcp-server.json", import.meta.url))) {
+    let document;
+    try {
+        document = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        throw new ServerManifestError("(document)", path, "object");
+    }
+    return parseServerManifest(document, path);
+}

package/dist/stdio.js

@@ -8,15 +8,22 @@
  */
 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
+    // transport, so `caller` is deliberately left unset and a tool wrapped with
+    // `withVerifiedPerson` is refused as `no_verified_session` (src/verifiedPerson.ts). The local
+    // process is trusted as the caller, never impersonated as a person.
     serveStdio(() => createBoilerplateMcpServer({ requireTenant, uiDomain }));
-    process.stderr.write("[mcp-boilerplate] stdio server started — 3 tools available\n");
+    process.stderr.write("[mcp-boilerplate] stdio server started — 2 tools available\n");
 }
 try {
     startStdioServer();

package/dist/tenancy.d.ts

@@ -41,4 +41,4 @@ export interface TenantOwned {
  * selected rows by a creator NAME (backend standard R-53 clause 1 forbids that); identifiers
  * are compared byte for byte, a slug is never compared against an id.
  */
-export declare function scopeRowsForTenant<T extends TenantOwned>(tenantId: string, rows: T[]): T[];
+export declare function scopeRowsForTenant<T extends TenantOwned>(tenantId: string, rows: readonly T[]): T[];

package/dist/toolRecord.d.ts

@@ -0,0 +1,124 @@
+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
+ * 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.
+ */
+/** mcp-standard.md §3 point 1 — authority tiers, closed set. */
+export type AuthTier = "public" | "org-member" | "org-admin" | "fleet-internal" | "master";
+/** mcp-standard.md §3 point 2 — operation verbs, closed set. `rpc` is deliberately absent. */
+export type ToolVerb = "list" | "get" | "search" | "aggregate" | "create" | "update" | "delete" | "upsert" | "transition" | "bulk-write" | "pure" | "introspect" | "external-effect";
+/**
+ * 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" | `upstream-delegated(${string})`;
+/** The four behavioural annotations (C-15), explicit booleans on every tool. */
+interface BehaviourHints {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+interface CommonSlots extends BehaviourHints {
+    authRead: AuthTier;
+    authWrite: AuthTier;
+    /** Estimated context tokens of the served tool (C-13); tests/contextCeiling.test.ts checks it. */
+    tokensEstimeContexte: number;
+}
+/** A tool that touches no table. */
+export interface PureToolSlots extends CommonSlots {
+    verb: "pure" | "introspect";
+}
+/** A tool that lists or searches: mechanism and pagination are required, not optional. */
+export interface ListToolSlots extends CommonSlots {
+    verb: "list" | "search";
+    table: string;
+    searchMechanism: SearchMechanism;
+    paginationCursor: true;
+    /** Page size when the caller gives none. */
+    paginationDefault: number;
+    /** Finite maximum page size; the tool caps a larger request at this. */
+    paginationMax: number;
+}
+/** Any other data tool (get, create, update ...): the verb and the table are required. */
+export interface DataToolSlots extends CommonSlots {
+    verb: Exclude<ToolVerb, "list" | "search" | "pure" | "introspect">;
+    table: string;
+}
+export type ToolSlots = PureToolSlots | ListToolSlots | DataToolSlots;
+export declare const PING_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+    readonly authRead: "public";
+    readonly authWrite: "master";
+    readonly verb: "pure";
+    readonly tokensEstimeContexte: 200;
+};
+export declare const LIST_ITEMS_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+    readonly idempotentHint: true;
+    readonly openWorldHint: false;
+    readonly authRead: "org-member";
+    readonly authWrite: "master";
+    readonly verb: "list";
+    readonly table: "items";
+    readonly searchMechanism: "indexed-range";
+    readonly paginationCursor: true;
+    readonly paginationDefault: 20;
+    readonly paginationMax: 100;
+    readonly tokensEstimeContexte: 640;
+};
+/** 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

@@ -0,0 +1,114 @@
+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.
+export const PING_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    authRead: "public",
+    authWrite: "master",
+    verb: "pure",
+    tokensEstimeContexte: 200,
+};
+export const LIST_ITEMS_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+    authRead: "org-member",
+    authWrite: "master",
+    verb: "list",
+    table: "items",
+    searchMechanism: "indexed-range",
+    paginationCursor: true,
+    paginationDefault: 20,
+    paginationMax: 100,
+    tokensEstimeContexte: 640,
+};
+/** 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/dist/ui/uiResource.d.ts

@@ -17,9 +17,11 @@ export declare function readUiBundle(): string;
  * (the spec says consult each host), so it is set only when the deployment supplies one.
  */
 export declare function buildItemsUiResourceMeta(domain?: string): McpUiResourceMeta;
+/**
+ * The widget template. It carries no row: the widget renders the `list_items` RESULT it is given,
+ * so the template is the same for every caller and every page.
+ */
 export declare function buildUiResource(props: {
-    items: ExampleItem[];
-    locale: "en" | "fr";
     domain?: string;
 }): {
     uri: string;
@@ -42,7 +44,7 @@ export declare const ITEMS_TOOL_META: {
     readonly "openai/toolInvocation/invoking": "Rendering items…";
     readonly "openai/toolInvocation/invoked": "Items ready.";
 };
-export interface RenderItemsUiResult {
+export interface ListItemsResult {
     [key: string]: unknown;
     content: Array<{
         type: "text";
@@ -54,6 +56,8 @@ export interface RenderItemsUiResult {
     structuredContent: {
         items: ExampleItem[];
         locale: "en" | "fr";
+        nextCursor?: string;
+        exhausted?: boolean;
     };
     _meta: {
         ui: McpUiToolMeta;
@@ -64,4 +68,7 @@ export interface RenderItemsUiResult {
  * A-1: it stays first, as before); content[1] mirrors `structuredContent` as JSON text (clients
  * that only read text still get the data); content[2] is the embedded ui:// resource.
  */
-export declare function buildRenderItemsUiResult(items: ExampleItem[], locale: "en" | "fr", domain?: string): RenderItemsUiResult;
+export declare function buildListItemsResult(items: ExampleItem[], locale: "en" | "fr", domain?: string, page?: {
+    nextCursor?: string;
+    exhausted: boolean;
+}): ListItemsResult;

package/dist/ui/uiResource.js

@@ -1,5 +1,5 @@
 /**
- * MCP Apps UI resource for the `render_items_ui` tool — GA `_meta.ui`
+ * MCP Apps UI resource for the `list_items` tool — GA `_meta.ui`
  * nested form (`io.modelcontextprotocol/ui`, stable 2026-01-26), built via
  * the official `@modelcontextprotocol/ext-apps/server` helpers.
  *
@@ -65,6 +65,10 @@ export function buildItemsUiResourceMeta(domain) {
         prefersBorder: true,
     };
 }
+/**
+ * The widget template. It carries no row: the widget renders the `list_items` RESULT it is given,
+ * so the template is the same for every caller and every page.
+ */
 export function buildUiResource(props) {
     return {
         uri: ITEMS_UI_RESOURCE_URI,
@@ -94,13 +98,13 @@ export const ITEMS_TOOL_META = {
  * A-1: it stays first, as before); content[1] mirrors `structuredContent` as JSON text (clients
  * that only read text still get the data); content[2] is the embedded ui:// resource.
  */
-export function buildRenderItemsUiResult(items, locale, domain) {
-    const structuredContent = { items, locale };
+export function buildListItemsResult(items, locale, domain, page = { exhausted: true }) {
+    const structuredContent = { items, locale, ...page };
     return {
         content: [
             { type: "text", text: renderMarkdownFallback(items, locale) },
             { type: "text", text: JSON.stringify(structuredContent) },
-            { type: "resource", resource: buildUiResource({ items, locale, domain }) },
+            { type: "resource", resource: buildUiResource({ domain }) },
         ],
         structuredContent,
         _meta: { ui: ITEMS_UI_META },