@vantageos/mcp-boilerplate 0.3.0 → 0.5.0

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.",
@@ -181,7 +187,7 @@ export function createBoilerplateMcpServer(deps = {}) {
         try {
             const tenantId = deps.tenant?.tenantId;
             const scope = tenantId === undefined ? undefined : { tenantId };
-            const { items, ...page } = await readPage(lake, args, PAGINATION, scope);
+            const { items, ...page } = await readPage(lake, args, PAGINATION, scope, deps.cursorSigner);
             // 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) {
@@ -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/pagination.d.ts

@@ -4,8 +4,11 @@
  * 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;
+ *   - the cursor carries the last key served, so it is stable: rows added or removed elsewhere do
+ *     not shift the next page. It is SIGNED (src/signedCursor.ts: HMAC-SHA256 under a server
+ *     key), so a caller can read it but not edit or mint one: an edited key is `invalid_cursor`.
+ *     The default signer's key is drawn once per process: a restart invalidates outstanding
+ *     cursors, and a multi-instance deployment injects one shared signer (`cursorSigner`);
  *   - 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);
@@ -14,6 +17,8 @@
  *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor.
  */
 import { type LakeReader, type LakeScope } from "./lake/reader.js";
+import { type CursorSigner } from "./signedCursor.js";
+export { INVALID_CURSOR_CODE, InvalidCursorError } from "./signedCursor.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).
@@ -22,15 +27,8 @@ export declare const PAGINATION: {
     readonly default: 20;
     readonly max: 100;
 };
-/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
-export declare const INVALID_CURSOR_CODE = "invalid_cursor";
-/** The cursor did not decode to a position in the collection. */
-export declare class InvalidCursorError extends Error {
-    readonly code = "invalid_cursor";
-    constructor();
-}
-export declare function encodeCursor(afterKey: string): string;
-export declare function decodeCursor(cursor: string): string;
+export declare function encodeCursor(afterKey: string, signer?: CursorSigner): string;
+export declare function decodeCursor(cursor: string, signer?: CursorSigner): string;
 export interface Page<T> {
     items: T[];
     /** Present exactly when the page was truncated. */
@@ -51,16 +49,17 @@ export declare function paginate<T extends {
 }>(sortedRows: readonly T[], request: PageRequest, bounds: {
     default: number;
     max: number;
-}): Page<T>;
+}, signer?: CursorSigner): Page<T>;
 /**
  * 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).
+ * the in-memory reader, the result is exactly `paginate`'s (tests/lakeReader.test.ts). `signer`
+ * signs and verifies the cursor; default: the process-wide signer.
  */
 export declare function readPage<Row>(reader: LakeReader<Row>, request: PageRequest, bounds: {
     default: number;
     max: number;
-}, scope?: LakeScope): Promise<Page<Row>>;
+}, scope?: LakeScope, signer?: CursorSigner): Promise<Page<Row>>;

package/dist/pagination.js

@@ -4,8 +4,11 @@
  * 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;
+ *   - the cursor carries the last key served, so it is stable: rows added or removed elsewhere do
+ *     not shift the next page. It is SIGNED (src/signedCursor.ts: HMAC-SHA256 under a server
+ *     key), so a caller can read it but not edit or mint one: an edited key is `invalid_cursor`.
+ *     The default signer's key is drawn once per process: a restart invalidates outstanding
+ *     cursors, and a multi-instance deployment injects one shared signer (`cursorSigner`);
  *   - 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);
@@ -15,7 +18,9 @@
  */
 import { rangeAfter } from "./exampleItems.js";
 import { checkLakePage } from "./lake/reader.js";
+import { InvalidCursorError, createCursorSigner } from "./signedCursor.js";
 import { LIST_ITEMS_ANNOTATIONS } from "./toolRecord.js";
+export { INVALID_CURSOR_CODE, InvalidCursorError } from "./signedCursor.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).
@@ -25,33 +30,30 @@ export const PAGINATION = {
     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");
+/**
+ * The process-wide signer of tool cursors, used when none is injected. One per process (not per
+ * server): the HTTP transport builds a server per request, and a cursor must outlive the request
+ * that issued it.
+ */
+const DEFAULT_SIGNER = createCursorSigner();
+export function encodeCursor(afterKey, signer = DEFAULT_SIGNER) {
+    return signer.sign(JSON.stringify({ v: CURSOR_VERSION, after: afterKey }));
 }
-export function decodeCursor(cursor) {
+export function decodeCursor(cursor, signer = DEFAULT_SIGNER) {
+    const payload = signer.verify(cursor);
     let decoded;
     try {
-        decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        decoded = JSON.parse(payload);
     }
     catch {
-        throw new InvalidCursorError();
+        throw new InvalidCursorError("malformed_payload");
     }
     if (typeof decoded !== "object" ||
         decoded === null ||
         decoded.v !== CURSOR_VERSION ||
         typeof decoded.after !== "string" ||
         decoded.after.length === 0) {
-        throw new InvalidCursorError();
+        throw new InvalidCursorError("malformed_payload");
     }
     return decoded.after;
 }
@@ -60,8 +62,8 @@ export function decodeCursor(cursor) {
  * 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);
+export function paginate(sortedRows, request, bounds, signer = DEFAULT_SIGNER) {
+    const afterKey = request.cursor === undefined ? undefined : decodeCursor(request.cursor, signer);
     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.
@@ -69,7 +71,7 @@ export function paginate(sortedRows, request, bounds) {
     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, nextCursor: encodeCursor(last.id, signer), exhausted: false };
     }
     return { items, exhausted: true };
 }
@@ -79,10 +81,11 @@ export function paginate(sortedRows, request, bounds) {
  * 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).
+ * the in-memory reader, the result is exactly `paginate`'s (tests/lakeReader.test.ts). `signer`
+ * signs and verifies the cursor; default: the process-wide signer.
  */
-export async function readPage(reader, request, bounds, scope) {
-    const after = request.cursor === undefined ? undefined : decodeCursor(request.cursor);
+export async function readPage(reader, request, bounds, scope, signer = DEFAULT_SIGNER) {
+    const after = request.cursor === undefined ? undefined : decodeCursor(request.cursor, signer);
     const wanted = request.limit ?? bounds.default;
     const limit = Math.max(1, Math.min(Math.floor(wanted), bounds.max));
     const lakeRequest = {
@@ -94,7 +97,7 @@ export async function readPage(reader, request, bounds, scope) {
     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, nextCursor: encodeCursor(reader.keyOf(last), signer), 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

@@ -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/settings.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The HTTP transport's operator configuration, declared through the declared-variables mechanism
+ * (src/declaredVariables.ts). Evaluated by the Node entry (src/http.ts) at start.
+ *
+ * `MCP_ALLOWED_ORIGINS` (S-22, MCP Streamable HTTP spec: validate `Origin` to stop DNS rebinding):
+ * the browser origins allowed to call `/mcp`. Data, never a constant. Default: empty, which
+ * refuses every browser origin (a request with no `Origin` header is not a browser and is not
+ * subject to it). A wildcard or an entry with a path is a `ConfigurationError` naming the variable.
+ *
+ * `UPSTREAM_TIMEOUT_MS` (S-13: every request the server emits carries a configured timeout):
+ * the time budget, in milliseconds, of one outbound request to an upstream (API page, API call
+ * through the token source, external-issuer JWKS, lake read). Default 30 000: long enough for a
+ * slow paginated read, short enough that the server answers with a typed error before an MCP
+ * client's own request timeout (commonly 60 s) fires. Range 1 000 to 300 000, enforced at start:
+ * below 1 s every healthy upstream times out, above 5 min a hung upstream pins a worker. An
+ * out-of-range or non-integer value is a `ConfigurationError` naming the variable.
+ */
+export declare const httpVariables: import("./declaredVariables.js").DeclaredVariables<{
+    readonly allowedOrigins: {
+        readonly env: "MCP_ALLOWED_ORIGINS";
+        readonly type: "originList";
+        readonly required: false;
+        readonly default: readonly [];
+        readonly description: {
+            readonly en: "Browser origins allowed to call /mcp (comma-separated, scheme://host[:port]); empty refuses every browser origin";
+            readonly fr: "Origines de navigateur autorisées à appeler /mcp (séparées par des virgules, schéma://hôte[:port]) ; vide refuse toute origine de navigateur";
+        };
+    };
+}>;
+export declare function loadHttpSettings(env?: NodeJS.ProcessEnv): import("./declaredVariables.js").VariablesOf<{
+    readonly allowedOrigins: {
+        readonly env: "MCP_ALLOWED_ORIGINS";
+        readonly type: "originList";
+        readonly required: false;
+        readonly default: readonly [];
+        readonly description: {
+            readonly en: "Browser origins allowed to call /mcp (comma-separated, scheme://host[:port]); empty refuses every browser origin";
+            readonly fr: "Origines de navigateur autorisées à appeler /mcp (séparées par des virgules, schéma://hôte[:port]) ; vide refuse toute origine de navigateur";
+        };
+    };
+}>;
+export declare const UPSTREAM_TIMEOUT_DEFAULT_MS = 30000;
+export declare const UPSTREAM_TIMEOUT_MIN_MS = 1000;
+export declare const UPSTREAM_TIMEOUT_MAX_MS = 300000;
+export declare const upstreamVariables: import("./declaredVariables.js").DeclaredVariables<{
+    readonly upstreamTimeoutMs: {
+        readonly env: "UPSTREAM_TIMEOUT_MS";
+        readonly type: "integer";
+        readonly required: false;
+        readonly min: 1000;
+        readonly max: 300000;
+        readonly default: 30000;
+        readonly description: {
+            readonly en: "Time budget in milliseconds of one outbound request to an upstream (1000 to 300000, default 30000)";
+            readonly fr: "Budget de temps en millisecondes d'une requête sortante vers un amont (1000 à 300000, 30000 par défaut)";
+        };
+    };
+}>;
+export declare function loadUpstreamSettings(env?: NodeJS.ProcessEnv): import("./declaredVariables.js").VariablesOf<{
+    readonly upstreamTimeoutMs: {
+        readonly env: "UPSTREAM_TIMEOUT_MS";
+        readonly type: "integer";
+        readonly required: false;
+        readonly min: 1000;
+        readonly max: 300000;
+        readonly default: 30000;
+        readonly description: {
+            readonly en: "Time budget in milliseconds of one outbound request to an upstream (1000 to 300000, default 30000)";
+            readonly fr: "Budget de temps en millisecondes d'une requête sortante vers un amont (1000 à 300000, 30000 par défaut)";
+        };
+    };
+}>;

package/dist/settings.js

@@ -0,0 +1,53 @@
+/**
+ * The HTTP transport's operator configuration, declared through the declared-variables mechanism
+ * (src/declaredVariables.ts). Evaluated by the Node entry (src/http.ts) at start.
+ *
+ * `MCP_ALLOWED_ORIGINS` (S-22, MCP Streamable HTTP spec: validate `Origin` to stop DNS rebinding):
+ * the browser origins allowed to call `/mcp`. Data, never a constant. Default: empty, which
+ * refuses every browser origin (a request with no `Origin` header is not a browser and is not
+ * subject to it). A wildcard or an entry with a path is a `ConfigurationError` naming the variable.
+ *
+ * `UPSTREAM_TIMEOUT_MS` (S-13: every request the server emits carries a configured timeout):
+ * the time budget, in milliseconds, of one outbound request to an upstream (API page, API call
+ * through the token source, external-issuer JWKS, lake read). Default 30 000: long enough for a
+ * slow paginated read, short enough that the server answers with a typed error before an MCP
+ * client's own request timeout (commonly 60 s) fires. Range 1 000 to 300 000, enforced at start:
+ * below 1 s every healthy upstream times out, above 5 min a hung upstream pins a worker. An
+ * out-of-range or non-integer value is a `ConfigurationError` naming the variable.
+ */
+import { defineVariables, loadVariables } from "./declaredVariables.js";
+export const httpVariables = defineVariables({
+    allowedOrigins: {
+        env: "MCP_ALLOWED_ORIGINS",
+        type: "originList",
+        required: false,
+        default: [],
+        description: {
+            en: "Browser origins allowed to call /mcp (comma-separated, scheme://host[:port]); empty refuses every browser origin",
+            fr: "Origines de navigateur autorisées à appeler /mcp (séparées par des virgules, schéma://hôte[:port]) ; vide refuse toute origine de navigateur",
+        },
+    },
+});
+export function loadHttpSettings(env = process.env) {
+    return loadVariables(httpVariables, env);
+}
+export const UPSTREAM_TIMEOUT_DEFAULT_MS = 30_000;
+export const UPSTREAM_TIMEOUT_MIN_MS = 1_000;
+export const UPSTREAM_TIMEOUT_MAX_MS = 300_000;
+export const upstreamVariables = defineVariables({
+    upstreamTimeoutMs: {
+        env: "UPSTREAM_TIMEOUT_MS",
+        type: "integer",
+        required: false,
+        min: UPSTREAM_TIMEOUT_MIN_MS,
+        max: UPSTREAM_TIMEOUT_MAX_MS,
+        default: UPSTREAM_TIMEOUT_DEFAULT_MS,
+        description: {
+            en: "Time budget in milliseconds of one outbound request to an upstream (1000 to 300000, default 30000)",
+            fr: "Budget de temps en millisecondes d'une requête sortante vers un amont (1000 à 300000, 30000 par défaut)",
+        },
+    },
+});
+export function loadUpstreamSettings(env = process.env) {
+    return loadVariables(upstreamVariables, env);
+}

package/dist/signedCursor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Signed cursors. Every cursor this boilerplate issues (the `list_items` tool cursor in
+ * `src/pagination.ts`, the upstream offset cursor in `src/upstream/paginatedClient.ts`) is a
+ * token `<payload>.<tag>`: the payload is base64url of the cursor's own text, the tag is base64url
+ * of HMAC-SHA256(key, payload part). A caller can read a cursor; it cannot edit one and have it
+ * accepted, because recomputing the tag needs the key.
+ *
+ * `verify` refuses with `InvalidCursorError` (code `invalid_cursor`) and a `reason` naming the
+ * form it met: `empty`, `missing_separator`, `extra_separator`, `empty_part`, `not_base64url`
+ * (a part outside the strict base64url alphabet, or not in its canonical encoding), `tag_length`
+ * (a tag that is not 32 bytes, e.g. truncated) and `tag_mismatch` (an edited payload, or a tag
+ * made under another key). A verified payload the caller cannot read is refused by the caller as
+ * `malformed_payload`, and one issued for another request as `other_request`. There is no unsigned
+ * fallback: a token that does not verify is never read.
+ *
+ * Declared limit. The default key is 32 random bytes drawn once per signer, so per process for
+ * the module-level signers: a process restart invalidates every outstanding cursor (the caller
+ * gets `invalid_cursor` and starts again without one), and two instances behind a load balancer
+ * reject each other's cursors. A multi-instance deployment injects one shared key of at least 32
+ * bytes into every instance (`createCursorSigner({ key })`).
+ */
+/** The stable machine code of an invalid or expired cursor, in `structuredContent.error.code`. */
+export declare const INVALID_CURSOR_CODE = "invalid_cursor";
+/** Why a cursor was refused. Operator-facing: the caller only ever sees `invalid_cursor`. */
+export type InvalidCursorReason = "empty" | "missing_separator" | "extra_separator" | "empty_part" | "not_base64url" | "tag_length" | "tag_mismatch" | "malformed_payload" | "other_request";
+/** The cursor did not decode to a position this server issued. */
+export declare class InvalidCursorError extends Error {
+    readonly code = "invalid_cursor";
+    /** The form the refused token took. */
+    readonly reason: InvalidCursorReason;
+    constructor(reason: InvalidCursorReason);
+}
+/** Minimum (and default) key length, in bytes: the HMAC-SHA256 output size. */
+export declare const CURSOR_KEY_BYTES = 32;
+export interface CursorSigner {
+    /** Returns `<base64url payload>.<base64url tag>`. */
+    sign(payload: string): string;
+    /** Returns the payload `sign` was given, or throws `InvalidCursorError`. */
+    verify(token: string): string;
+}
+export interface CursorSignerOptions {
+    /**
+     * The HMAC key, at least 32 bytes. Default: 32 random bytes, drawn once for this signer. Inject
+     * the same key into every instance of a multi-instance deployment.
+     */
+    key?: Uint8Array;
+}
+export declare function createCursorSigner(options?: CursorSignerOptions): CursorSigner;

package/dist/signedCursor.js

@@ -0,0 +1,98 @@
+/**
+ * Signed cursors. Every cursor this boilerplate issues (the `list_items` tool cursor in
+ * `src/pagination.ts`, the upstream offset cursor in `src/upstream/paginatedClient.ts`) is a
+ * token `<payload>.<tag>`: the payload is base64url of the cursor's own text, the tag is base64url
+ * of HMAC-SHA256(key, payload part). A caller can read a cursor; it cannot edit one and have it
+ * accepted, because recomputing the tag needs the key.
+ *
+ * `verify` refuses with `InvalidCursorError` (code `invalid_cursor`) and a `reason` naming the
+ * form it met: `empty`, `missing_separator`, `extra_separator`, `empty_part`, `not_base64url`
+ * (a part outside the strict base64url alphabet, or not in its canonical encoding), `tag_length`
+ * (a tag that is not 32 bytes, e.g. truncated) and `tag_mismatch` (an edited payload, or a tag
+ * made under another key). A verified payload the caller cannot read is refused by the caller as
+ * `malformed_payload`, and one issued for another request as `other_request`. There is no unsigned
+ * fallback: a token that does not verify is never read.
+ *
+ * Declared limit. The default key is 32 random bytes drawn once per signer, so per process for
+ * the module-level signers: a process restart invalidates every outstanding cursor (the caller
+ * gets `invalid_cursor` and starts again without one), and two instances behind a load balancer
+ * reject each other's cursors. A multi-instance deployment injects one shared key of at least 32
+ * bytes into every instance (`createCursorSigner({ key })`).
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+/** 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 this server issued. */
+export class InvalidCursorError extends Error {
+    code = INVALID_CURSOR_CODE;
+    /** The form the refused token took. */
+    reason;
+    constructor(reason) {
+        super("invalid cursor");
+        this.name = "InvalidCursorError";
+        this.reason = reason;
+    }
+}
+/** Minimum (and default) key length, in bytes: the HMAC-SHA256 output size. */
+export const CURSOR_KEY_BYTES = 32;
+const TAG_BYTES = 32;
+const BASE64URL = /^[A-Za-z0-9_-]+$/;
+/** Strict base64url: the alphabet only, and the canonical encoding of what it decodes to. */
+function decodeStrict(part) {
+    if (!BASE64URL.test(part))
+        throw new InvalidCursorError("not_base64url");
+    const bytes = Buffer.from(part, "base64url");
+    if (bytes.toString("base64url") !== part)
+        throw new InvalidCursorError("not_base64url");
+    return bytes;
+}
+export function createCursorSigner(options = {}) {
+    const supplied = options.key;
+    if (supplied !== undefined && !(supplied instanceof Uint8Array)) {
+        throw new Error(`cursor signer: key must be a Uint8Array of at least ${CURSOR_KEY_BYTES} bytes`);
+    }
+    if (supplied !== undefined && supplied.length < CURSOR_KEY_BYTES) {
+        throw new Error(`cursor signer: key must be at least ${CURSOR_KEY_BYTES} bytes (got ${supplied.length})`);
+    }
+    // A copy: the caller zeroing or reusing its buffer must not change what this signer accepts.
+    const key = supplied === undefined ? randomBytes(CURSOR_KEY_BYTES) : Buffer.from(supplied);
+    const tagOf = (payloadPart) => createHmac("sha256", key).update(payloadPart).digest();
+    const sign = (payload) => {
+        // A cursor always says something; an empty one would encode to an empty part, which `verify`
+        // refuses. Refused here, loudly, rather than issued and then rejected.
+        if (typeof payload !== "string" || payload.length === 0) {
+            throw new Error("cursor signer: the payload to sign must be a non-empty string");
+        }
+        const payloadPart = Buffer.from(payload, "utf8").toString("base64url");
+        return `${payloadPart}.${tagOf(payloadPart).toString("base64url")}`;
+    };
+    const verify = (token) => {
+        if (typeof token !== "string" || token.length === 0)
+            throw new InvalidCursorError("empty");
+        const parts = token.split(".");
+        if (parts.length < 2)
+            throw new InvalidCursorError("missing_separator");
+        if (parts.length > 2)
+            throw new InvalidCursorError("extra_separator");
+        const [payloadPart, tagPart] = parts;
+        if (payloadPart.length === 0 || tagPart.length === 0)
+            throw new InvalidCursorError("empty_part");
+        if (!BASE64URL.test(tagPart))
+            throw new InvalidCursorError("not_base64url");
+        // Length before canonical form, so a truncated tag is named as such.
+        const tag = Buffer.from(tagPart, "base64url");
+        if (tag.length !== TAG_BYTES)
+            throw new InvalidCursorError("tag_length");
+        if (tag.toString("base64url") !== tagPart)
+            throw new InvalidCursorError("not_base64url");
+        // The payload is checked for its alphabet before the tag; its content is trusted only once
+        // the tag matches. Equal lengths (32 bytes each, checked above): timingSafeEqual cannot throw.
+        if (!BASE64URL.test(payloadPart))
+            throw new InvalidCursorError("not_base64url");
+        if (!timingSafeEqual(tagOf(payloadPart), tag))
+            throw new InvalidCursorError("tag_mismatch");
+        // Signed by us, so canonical; re-checked so a decode is never lenient.
+        return decodeStrict(payloadPart).toString("utf8");
+    };
+    return { sign, verify };
+}

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