@vantageos/mcp-boilerplate 0.2.4 → 0.4.0

package/dist/lake/reader.js

@@ -0,0 +1,120 @@
+/**
+ * Data-lake reader: the READ-ONLY interface through which a server derived from this boilerplate
+ * reads its client's data lake (the single persisted source). The tools never know which store is
+ * behind it; the store is chosen by injection (`AppDeps.lake` / `McpServerDeps.lake`).
+ *
+ * The contract mirrors the cursor contract of src/pagination.ts:
+ *   - rows are keyed by a STABLE, non-empty string key (`keyOf`), served in strictly ascending key
+ *     order, so the last key served is the cursor;
+ *   - `listPage({ after, limit, scope })` returns at most `limit` rows whose key is strictly after
+ *     `after` (all rows when it is undefined), and `exhausted: true` exactly when no row follows
+ *     them (an exact fit is exhausted, never a false truncation); a truncated page has at least one
+ *     row;
+ *   - `scope` (the caller's resolved tenant) is applied INSIDE the range read — a compound
+ *     (tenant, key) index — never as a filter after the limit, which would shorten a page and make
+ *     its cursor lie;
+ *   - `get(key, scope)` returns the row with that key, or undefined.
+ *
+ * What a derived server adds: its own filters (a status, a date window, a person's portfolio) as
+ * arguments of its own adapter or query functions, and its own row type. What is out of scope, by
+ * design: writes. The interface has no write method, and the Convex adapter (src/lake/convex.ts)
+ * only ever calls queries.
+ *
+ * Fail closed: `readPage` (src/pagination.ts) checks every page against this contract with
+ * `checkLakePage`; a page it cannot read is a `LakeReadError`, never an empty or partial page.
+ * Its message names the contract clause broken, never a row value.
+ *
+ * The in-memory adapter below wraps the boilerplate's seed (src/exampleItems.ts) and is the
+ * default reader, so a server with no lake injected behaves exactly as before.
+ */
+import { EXAMPLE_ITEMS, rangeAfter } from "../exampleItems.js";
+import { scopeRowsForTenant } from "../tenancy.js";
+/** The stable machine code of a tool result refused because the lake answer was unreadable. */
+export const LAKE_UNREADABLE_CODE = "lake_unreadable";
+export class LakeReadError extends Error {
+    code;
+    constructor(code, message) {
+        super(`lake read: ${message}`);
+        this.name = "LakeReadError";
+        this.code = code;
+    }
+}
+/** The row's key, or a `malformed_row` refusal when it is not a non-empty string. */
+function readKey(keyOf, row) {
+    let key;
+    try {
+        key = keyOf(row);
+    }
+    catch {
+        key = undefined;
+    }
+    if (typeof key !== "string" || key === "") {
+        throw new LakeReadError("malformed_row", "a row has no readable key (a non-empty string)");
+    }
+    return key;
+}
+/**
+ * Checks that `keys` are strictly ascending and all strictly after `after`. Shared by
+ * `checkLakePage` and by adapters that read a raw answer.
+ */
+export function assertOrderedKeys(keys, after) {
+    let previous = after;
+    for (const key of keys) {
+        if (previous !== undefined && !(key > previous)) {
+            throw new LakeReadError("malformed_page", after !== undefined && previous === after
+                ? "a row key is not after the cursor"
+                : "row keys are not strictly ascending");
+        }
+        previous = key;
+    }
+}
+/** Checks a page against the contract above; returns it, or throws a `LakeReadError`. */
+export function checkLakePage(reader, request, page) {
+    if (typeof page !== "object" || page === null) {
+        throw new LakeReadError("malformed_page", "the page is not an object");
+    }
+    const { rows, exhausted } = page;
+    if (!Array.isArray(rows))
+        throw new LakeReadError("malformed_page", "rows is not a list");
+    if (typeof exhausted !== "boolean") {
+        throw new LakeReadError("malformed_page", "exhausted is not a boolean");
+    }
+    if (rows.length > request.limit) {
+        throw new LakeReadError("malformed_page", "the page holds more rows than its limit");
+    }
+    if (!exhausted && rows.length === 0) {
+        throw new LakeReadError("malformed_page", "a truncated page holds no row (no cursor to give)");
+    }
+    const keys = rows.map((row) => readKey(reader.keyOf, row));
+    assertOrderedKeys(keys, request.after);
+    return { rows: rows, exhausted };
+}
+/**
+ * An in-memory reader over rows SORTED strictly ascending by `id` (refused otherwise, at
+ * creation: the range read relies on the order). The scope keeps the rows stamped with the
+ * caller's organisation (tenancy.ts `scopeRowsForTenant`) BEFORE the range, so a page is never
+ * shortened afterwards. A store-backed reader reads the same range from a (tenant, key) index.
+ */
+export function createInMemoryLakeReader(sortedRows) {
+    for (let i = 1; i < sortedRows.length; i += 1) {
+        const previous = sortedRows[i - 1]?.id ?? "";
+        const current = sortedRows[i]?.id ?? "";
+        if (!(current > previous)) {
+            throw new Error("in-memory lake reader: rows must be sorted strictly ascending by id (unique keys)");
+        }
+    }
+    const scoped = (scope) => scope ? scopeRowsForTenant(scope.tenantId, sortedRows) : sortedRows;
+    return Object.freeze({
+        keyOf: (row) => row.id,
+        async listPage(request) {
+            // One row more than the page: its existence separates truncated from exhausted.
+            const window = rangeAfter(scoped(request.scope), request.after, request.limit + 1);
+            return { rows: window.slice(0, request.limit), exhausted: window.length <= request.limit };
+        },
+        async get(key, scope) {
+            return scoped(scope).find((row) => row.id === key);
+        },
+    });
+}
+/** The default reader behind `list_items`: the in-memory seed. */
+export const EXAMPLE_ITEMS_READER = createInMemoryLakeReader(EXAMPLE_ITEMS);

package/dist/locales/en.json

@@ -6,6 +6,11 @@
     "tenant": {
       "permissionDenied": "permission denied: no tenant resolved for this caller"
     },
+    "person": {
+      "identityNotConfigured": "permission denied: this tool needs the verified person, and this server resolves no person (identity is not configured)",
+      "noVerifiedSession": "permission denied: this tool needs the verified person, and this call carries no verified session",
+      "refused": "permission denied: the verified person behind this call could not be resolved"
+    },
     "validation": {
       "messageTooLong": "message exceeds the maximum length of 200 characters"
     },
@@ -20,7 +25,49 @@
       "deny": "Deny",
       "denied": "The request was denied; you can close this window.",
       "unavailable": "Authorization is not configured on this server.",
+      "inMemoryWarning": "Running on in-memory OAuth stores: codes and registered clients are lost on restart and not shared between instances. Fine for development; set {knob}=1 to acknowledge, or inject durable adapters.",
+      "consentTokenRequired": "The consent token is missing: reload the page and try again.",
+      "registryFull": "Client registration is temporarily unavailable: the registry is full. Retry later.",
       "devInstanceRemote": "Development Clerk instance on a remote server: its hosted sign-in page redirects only to localhost or to the instance Home URL. Set the development instance's Home URL (development origin) to this server's origin for a remote test and revert it afterwards, or use a Clerk production instance (see README, \"Sign-in with ChatGPT and Claude\")."
+    },
+    "manifest": {
+      "unreadableField": "cannot read field \"{field}\" of {source} (expected: {expected})",
+      "expect": {
+        "string": "a non-empty string",
+        "semver": "a semantic version (x.y.z)",
+        "object": "an object",
+        "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"
+    },
+    "lake": {
+      "unreadable": "the data source answered something this server cannot read; no row is shown rather than a partial or wrong page"
+    },
+    "buildIdentity": {
+      "unreadable": "cannot compute the build identity: {dir} is unreadable ({reason})",
+      "empty": "cannot compute the build identity: {dir} is empty (no file), nothing was built"
+    },
+    "config": {
+      "refused": "configuration refused: {problems}",
+      "missing": "{env} is missing (expected: {expected})",
+      "invalid": "{env} is set but invalid (expected: {expected}; value not shown)",
+      "expect": {
+        "string": "a non-empty string",
+        "integer": "an integer from {min} to {max}",
+        "integerAtLeast": "an integer of at least {min}",
+        "boolean": "\"0\" or \"1\"",
+        "url": "an https URL (http on loopback only)",
+        "originList": "a comma-separated list of origins (scheme://host[:port], no path)",
+        "enum": "one of: {values}",
+        "json": "a JSON object or array"
+      }
     }
   }
 }

package/dist/locales/fr.json

@@ -6,6 +6,11 @@
     "tenant": {
       "permissionDenied": "permission refusée : aucun tenant résolu pour cet appelant"
     },
+    "person": {
+      "identityNotConfigured": "permission refusée : cet outil exige la personne vérifiée, et ce serveur ne résout aucune personne (identité non configurée)",
+      "noVerifiedSession": "permission refusée : cet outil exige la personne vérifiée, et cet appel ne porte aucune session vérifiée",
+      "refused": "permission refusée : la personne vérifiée derrière cet appel n'a pas pu être résolue"
+    },
     "validation": {
       "messageTooLong": "le message dépasse la longueur maximale de 200 caractères"
     },
@@ -20,7 +25,49 @@
       "deny": "Refuser",
       "denied": "La demande a été refusée ; vous pouvez fermer cette fenêtre.",
       "unavailable": "L'autorisation n'est pas configurée sur ce serveur.",
+      "inMemoryWarning": "Stores OAuth en mémoire : les codes et les clients enregistrés sont perdus au redémarrage et non partagés entre instances. Acceptable en développement ; définissez {knob}=1 pour l'accepter, ou injectez des adaptateurs durables.",
+      "consentTokenRequired": "Le jeton de consentement est absent : rechargez la page et réessayez.",
+      "registryFull": "L'enregistrement de clients est temporairement indisponible : le registre est plein. Réessayez plus tard.",
       "devInstanceRemote": "Instance Clerk de développement sur un serveur distant : sa page de connexion hébergée ne redirige que vers localhost ou vers l'URL d'accueil (Home URL) de l'instance. Pour un test distant, réglez l'URL d'accueil (origine de développement) de l'instance sur l'origine de ce serveur, puis rétablissez-la ; sinon utilisez une instance Clerk de production (voir README, « Connexion avec ChatGPT et Claude »)."
+    },
+    "manifest": {
+      "unreadableField": "champ \"{field}\" illisible dans {source} (attendu : {expected})",
+      "expect": {
+        "string": "une chaîne non vide",
+        "semver": "une version sémantique (x.y.z)",
+        "object": "un objet",
+        "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"
+    },
+    "lake": {
+      "unreadable": "la source de données a renvoyé une réponse illisible pour ce serveur ; aucune ligne n'est affichée plutôt qu'une page partielle ou fausse"
+    },
+    "buildIdentity": {
+      "unreadable": "identité de build incalculable : {dir} est illisible ({reason})",
+      "empty": "identité de build incalculable : {dir} est vide (aucun fichier), rien n'a été construit"
+    },
+    "config": {
+      "refused": "configuration refusée : {problems}",
+      "missing": "{env} est manquante (attendu : {expected})",
+      "invalid": "{env} est définie mais invalide (attendu : {expected} ; valeur non affichée)",
+      "expect": {
+        "string": "une chaîne non vide",
+        "integer": "un entier de {min} à {max}",
+        "integerAtLeast": "un entier d'au moins {min}",
+        "boolean": "\"0\" ou \"1\"",
+        "url": "une URL https (http seulement sur la boucle locale)",
+        "originList": "une liste d'origines séparées par des virgules (schéma://hôte[:port], sans chemin)",
+        "enum": "une valeur parmi : {values}",
+        "json": "un objet ou un tableau JSON"
+      }
     }
   }
 }

package/dist/mcpServerFactory.d.ts

@@ -13,27 +13,29 @@
  *    handler override, no private-field access, no hand-written discover schema;
  *  - the advertised version is `SERVER_VERSION`, derived from package.json.
  *
- * Tool records (mcp-standard C-4, C-15): every tool declares `title`, the four behavioural
- * annotations as explicit booleans, a typed input schema AND a typed output schema (Zod 4),
- * and returns `structuredContent` plus a text block carrying the same JSON.
- * tests/toolRecordComplete.test.ts walks `tools/list` and fails on any gap.
+ * Tool records (mcp-standard C-4, C-8..C-13, C-15): every tool declares `title`, a typed input
+ * schema AND a typed output schema (Zod 4), and the typed record of src/toolRecord.ts as its
+ * `annotations` (the four behavioural booleans, the (authRead, authWrite) pair, the verb, the
+ * table, the search mechanism, the pagination bounds and the context-cost estimate). It returns
+ * `structuredContent` plus a text block carrying the same JSON. tests/toolRecordComplete.test.ts
+ * and the C-8..C-13 suites walk `tools/list` and fail on any gap.
  *
- * `list_items` is the multi-tenant example (tenancy.ts): with a resolved tenant, rows are
- * filtered by stored `orgId` (cloud-identity `isRowInTenant`); on the public tier there is no
- * tenant gate at all, by design (it mirrors stdio's local-trust model).
+ * `list_items` is the multi-tenant example (tenancy.ts): it reads through the injected lake
+ * reader (src/lake/reader.ts, `deps.lake`; the in-memory seed when none is injected). With a
+ * resolved tenant, the tenant travels INTO the read as its scope, and every row that comes back
+ * is re-checked by stored `orgId` (cloud-identity `isRowInTenant`): a row of another tenant fails
+ * the call closed (`lake_unreadable`, reason `out_of_scope`), it is never filtered out silently.
+ * On the public tier there is no tenant gate at all, by design (it mirrors stdio's local-trust
+ * model).
  */
 import { McpServer } from "@modelcontextprotocol/server";
+import type { ExampleItem } from "./exampleItems.js";
 import { type McpLocale } from "./i18n.js";
+import { type LakeReader } from "./lake/reader.js";
 import { type ResolvedTenant } from "./tenancy.js";
+import type { CallerResolution } from "./verifiedPerson.js";
 /** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
 export declare const SUPPORTED_LEGACY_PROTOCOL_VERSIONS: string[];
-/** The four behavioural annotations, explicit on every tool (all three tools are pure reads). */
-export declare const TOOL_ANNOTATIONS: {
-    readonly readOnlyHint: true;
-    readonly destructiveHint: false;
-    readonly idempotentHint: true;
-    readonly openWorldHint: false;
-};
 export interface McpServerDeps {
     /**
      * The caller's resolved tenant (tenancy.ts), when the OAuth tier verified a JWT carrying an
@@ -47,6 +49,15 @@ export interface McpServerDeps {
      * `list_items` rather than silently falling through to an unscoped/master view.
      */
     requireTenant?: boolean;
+    /**
+     * The caller's verified person, resolved once per request by @vantageos/cloud-identity
+     * (src/verifiedPerson.ts) beside the tenant: `{ ok: true, person }` (frozen, exactly the
+     * package's fields), or `{ ok: false, reason }`. A tool reads it by wrapping its handler with
+     * `withVerifiedPerson(deps, handler)`, which refuses before the handler runs unless `ok`.
+     * Undefined on stdio: there is no verified session there, so a requiring tool is refused as
+     * `no_verified_session`, never given a default person.
+     */
+    caller?: CallerResolution;
     /**
      * The caller's locale, resolved from the `X-MCP-Locale` request header (see i18n.ts +
      * httpApp.ts). Defaults to "en"; the stdio transport (no HTTP headers) uses the default.
@@ -57,5 +68,11 @@ export interface McpServerDeps {
      * only when the deployment has one (MCP_UI_DOMAIN). Omitted from the resource when unset.
      */
     uiDomain?: string;
+    /**
+     * The data-lake reader `list_items` reads through (src/lake/reader.ts). Read-only by design.
+     * Default: the in-memory seed (`EXAMPLE_ITEMS_READER`), so a server with no lake behaves as
+     * before. A derived server injects its own (e.g. `@vantageos/mcp-boilerplate/lake/convex`).
+     */
+    lake?: LakeReader<ExampleItem>;
 }
 export declare function createBoilerplateMcpServer(deps?: McpServerDeps): McpServer;

package/dist/mcpServerFactory.js

@@ -13,32 +13,36 @@
  *    handler override, no private-field access, no hand-written discover schema;
  *  - the advertised version is `SERVER_VERSION`, derived from package.json.
  *
- * Tool records (mcp-standard C-4, C-15): every tool declares `title`, the four behavioural
- * annotations as explicit booleans, a typed input schema AND a typed output schema (Zod 4),
- * and returns `structuredContent` plus a text block carrying the same JSON.
- * tests/toolRecordComplete.test.ts walks `tools/list` and fails on any gap.
+ * Tool records (mcp-standard C-4, C-8..C-13, C-15): every tool declares `title`, a typed input
+ * schema AND a typed output schema (Zod 4), and the typed record of src/toolRecord.ts as its
+ * `annotations` (the four behavioural booleans, the (authRead, authWrite) pair, the verb, the
+ * table, the search mechanism, the pagination bounds and the context-cost estimate). It returns
+ * `structuredContent` plus a text block carrying the same JSON. tests/toolRecordComplete.test.ts
+ * and the C-8..C-13 suites walk `tools/list` and fail on any gap.
  *
- * `list_items` is the multi-tenant example (tenancy.ts): with a resolved tenant, rows are
- * filtered by stored `orgId` (cloud-identity `isRowInTenant`); on the public tier there is no
- * tenant gate at all, by design (it mirrors stdio's local-trust model).
+ * `list_items` is the multi-tenant example (tenancy.ts): it reads through the injected lake
+ * reader (src/lake/reader.ts, `deps.lake`; the in-memory seed when none is injected). With a
+ * resolved tenant, the tenant travels INTO the read as its scope, and every row that comes back
+ * is re-checked by stored `orgId` (cloud-identity `isRowInTenant`): a row of another tenant fails
+ * the call closed (`lake_unreadable`, reason `out_of_scope`), it is never filtered out silently.
+ * On the public tier there is no tenant gate at all, by design (it mirrors stdio's local-trust
+ * model).
  */
 import { registerAppResource } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
-import { EXAMPLE_ITEMS } from "./exampleItems.js";
+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 { ITEMS_TOOL_META, ITEMS_UI_RESOURCE_URI, buildItemsUiResourceMeta, buildRenderItemsUiResult, buildUiResource, } from "./ui/uiResource.js";
+import { LIST_ITEMS_ANNOTATIONS, PING_ANNOTATIONS } from "./toolRecord.js";
+import { ITEMS_TOOL_META, ITEMS_UI_RESOURCE_URI, buildItemsUiResourceMeta, buildListItemsResult, buildUiResource, } from "./ui/uiResource.js";
 import { SERVER_NAME, SERVER_VERSION } from "./version.js";
 /** Oldest 2025-era protocol revision served; the legacy `initialize` handshake never offers older. */
 export const SUPPORTED_LEGACY_PROTOCOL_VERSIONS = ["2025-11-25", "2025-06-18"];
-/** The four behavioural annotations, explicit on every tool (all three tools are pure reads). */
-export const TOOL_ANNOTATIONS = {
-    readOnlyHint: true,
-    destructiveHint: false,
-    idempotentHint: true,
-    openWorldHint: false,
-};
 const itemSchema = z.object({
     id: z.string(),
     name: z.string(),
@@ -51,14 +55,35 @@ const pingInput = z.object({
     message: z.string().optional().describe("Optional message echoed back verbatim"),
 });
 const pingOutput = z.object({ reply: z.string() });
-const listItemsInput = z.object({});
-const listItemsOutput = z.object({ items: z.array(itemSchema) });
-const renderInput = z.object({
+// Pagination (C-11): the bounds are declared in src/toolRecord.ts and applied in
+// src/pagination.ts; the schema only describes them to the caller.
+const pageInput = {
+    cursor: z
+        .string()
+        .optional()
+        .describe("Opaque cursor from a previous page's nextCursor; omit for the first page"),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .optional()
+        .describe(`Page size; default ${PAGINATION.default}, capped at ${PAGINATION.max}`),
+};
+const pageOutput = {
+    nextCursor: z.string().optional().describe("Present only when the page was truncated"),
+    exhausted: z.boolean().describe("True on the last page: no more rows follow"),
+};
+const listItemsInput = z.object({
     locale: localeSchema
         .optional()
-        .describe("Widget language; defaults to the caller's X-MCP-Locale"),
+        .describe("Widget and fallback language; defaults to the caller's X-MCP-Locale"),
+    ...pageInput,
+});
+const listItemsOutput = z.object({
+    items: z.array(itemSchema),
+    locale: localeSchema,
+    ...pageOutput,
 });
-const renderOutput = z.object({ items: z.array(itemSchema), locale: localeSchema });
 /** A text block carrying the same JSON as `structuredContent`. */
 function structuredResult(payload) {
     return {
@@ -71,8 +96,21 @@ function refusal(text) {
 }
 export function createBoilerplateMcpServer(deps = {}) {
     const locale = deps.locale ?? "en";
-    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, {
-        capabilities: { tools: {}, resources: {} },
+    // 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).
+    // `buildId` is not a modelled `Implementation` key, hence the spread (no excess-key check).
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        ...{ buildId: getBuildIdentity() },
+    }, {
+        // The capabilities come from the server manifest (mcp-server.json, C-18): one source.
+        capabilities: manifest.capabilities,
         instructions: "Clonable MCP server boilerplate — see README.md",
         supportedProtocolVersions: SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
         cacheHints: {
@@ -82,12 +120,13 @@ 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.",
         inputSchema: pingInput,
         outputSchema: pingOutput,
-        annotations: TOOL_ANNOTATIONS,
+        annotations: PING_ANNOTATIONS,
     }, async (args) => {
         // Application-level input validation beyond the Zod shape: an overly long echo message
         // is refused as an MCP tool-call error, localized per the caller's X-MCP-Locale.
@@ -96,23 +135,75 @@ export function createBoilerplateMcpServer(deps = {}) {
         }
         return structuredResult({ reply: args.message ?? "pong" });
     });
-    const scopedItems = () => deps.tenant ? scopeRowsForTenant(deps.tenant.tenantId, EXAMPLE_ITEMS) : EXAMPLE_ITEMS;
+    const lake = deps.lake ?? EXAMPLE_ITEMS_READER;
+    // An invalid or expired cursor is a TOOL INPUT error (spec 2025-11-25, SEP-1303: input
+    // validation errors are Tool Execution Errors, not Protocol Errors): a result with
+    // `isError: true` whose structuredContent carries a STABLE machine code beside a message
+    // localized per X-MCP-Locale. It is never a silent first page. (-32602 stays with the protocol
+    // list methods' cursor, which the SDK serves.)
+    const invalidCursor = () => {
+        const message = t(locale, "pagination.invalidCursor");
+        return {
+            content: [{ type: "text", text: message }],
+            structuredContent: { error: { code: INVALID_CURSOR_CODE, message } },
+            isError: true,
+        };
+    };
+    // The lake answered something this server cannot read (src/lake/reader.ts): a tool error with
+    // a STABLE code and the reason, a message localized per X-MCP-Locale, and no row. Never an empty
+    // or partial page passed off as the data.
+    const lakeUnreadable = (reason) => {
+        const message = t(locale, "lake.unreadable");
+        return {
+            content: [{ type: "text", text: message }],
+            structuredContent: { error: { code: LAKE_UNREADABLE_CODE, reason, message } },
+            isError: true,
+        };
+    };
+    // `list_items` is both the data tool and the UI tool (C-12: one operation on one table is one
+    // tool). It carries the `ui://` link (`_meta.ui.resourceUri`, plus the additive `openai/*`
+    // keys), returns `structuredContent`, and puts a markdown fallback first for hosts without
+    // MCP Apps (mcp-app-standard A-1). The widget renders THIS result.
     server.registerTool("list_items", {
         title: "List items",
-        description: "Lists example items. On the OAuth tier, results are scoped to the caller's organisation " +
+        description: "Lists example items, one page at a time, and shows them as an interactive widget in " +
+            "hosts that support MCP Apps. Use this whenever the user asks to list, see or render " +
+            "the items. On the OAuth tier, results are scoped to the caller's organisation " +
             "(@vantageos/cloud-identity); on the public tier (no auth gate), results are unscoped.",
         inputSchema: listItemsInput,
         outputSchema: listItemsOutput,
-        annotations: TOOL_ANNOTATIONS,
-    }, async () => {
+        annotations: LIST_ITEMS_ANNOTATIONS,
+        // `description_fr` (mcp-standard.md convention) lives alongside `ui` in `_meta`.
+        _meta: {
+            ...ITEMS_TOOL_META,
+            description_fr: "Liste les éléments d'exemple, une page à la fois, et les affiche en widget interactif dans les hôtes MCP Apps. Utilise cet outil quand l'utilisateur demande de lister, voir ou afficher les éléments.",
+        },
+    }, async (args) => {
         if (deps.requireTenant && !deps.tenant) {
             // Refuse explicitly — never fall through to an unscoped/master view just because the
             // caller's token had no organization.
             return refusal(t(locale, "tenant.permissionDenied"));
         }
-        return structuredResult({ items: scopedItems() });
+        try {
+            const tenantId = deps.tenant?.tenantId;
+            const scope = tenantId === undefined ? undefined : { tenantId };
+            const { items, ...page } = await readPage(lake, args, PAGINATION, scope);
+            // Defence in depth: the scope was applied inside the read; a row of another tenant that
+            // still comes back means the reader ignored it. Refuse the page, never filter it.
+            if (tenantId !== undefined && scopeRowsForTenant(tenantId, items).length !== items.length) {
+                throw new LakeReadError("out_of_scope", "a row of another tenant came back");
+            }
+            return buildListItemsResult(items, args.locale ?? locale, deps.uiDomain, page);
+        }
+        catch (error) {
+            if (error instanceof InvalidCursorError)
+                return invalidCursor();
+            if (error instanceof LakeReadError)
+                return lakeUnreadable(error.code);
+            throw error;
+        }
     });
-    // MCP Apps UI layer (io.modelcontextprotocol/ui, spec 2026-01-26). The tool is registered
+    // MCP Apps UI layer (io.modelcontextprotocol/ui, spec 2026-01-26). `list_items` is registered
     // with `server.registerTool` and the GA nested `_meta.ui` form, NOT with ext-apps'
     // `registerAppTool`: that helper back-fills the deprecated flat `_meta["ui/resourceUri"]`
     // key, which mcp-app-standard A-6 forbids writing (tests/mcpAppsMeta.test.ts asserts its
@@ -125,24 +216,9 @@ export function createBoilerplateMcpServer(deps = {}) {
         mimeType: "text/html;profile=mcp-app",
         _meta: { ui: resourceUiMeta },
     }, async () => ({
-        contents: [buildUiResource({ items: scopedItems(), locale, domain: deps.uiDomain })],
+        contents: [buildUiResource({ domain: deps.uiDomain })],
     }));
-    server.registerTool("render_items_ui", {
-        title: "Render items",
-        description: "Render the example items as an interactive widget. Use this whenever the user asks for a visual/rendered view of the items.",
-        inputSchema: renderInput,
-        outputSchema: renderOutput,
-        annotations: TOOL_ANNOTATIONS,
-        // `description_fr` (mcp-standard.md convention) lives alongside `ui` in `_meta`.
-        _meta: {
-            ...ITEMS_TOOL_META,
-            description_fr: "Affiche les éléments d'exemple sous forme de widget interactif. Utilise cet outil quand l'utilisateur demande une vue visuelle des éléments.",
-        },
-    }, async (args) => {
-        if (deps.requireTenant && !deps.tenant) {
-            return refusal(t(locale, "tenant.permissionDenied"));
-        }
-        return buildRenderItemsUiResult(scopedItems(), args.locale ?? locale, deps.uiDomain);
-    });
+    // Start refusal: every registered tool's record, as registered, must be sound.
+    served.assertServed(manifest.contextCeiling);
     return server;
 }