@vantageos/mcp-boilerplate 0.2.3 → 0.3.0

package/dist/pagination.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { type LakeReader, type LakeScope } from "./lake/reader.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 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 interface Page<T> {
+    items: T[];
+    /** Present exactly when the page was truncated. */
+    nextCursor?: string;
+    exhausted: boolean;
+}
+export interface PageRequest {
+    cursor?: string;
+    limit?: number;
+}
+/**
+ * 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 declare function paginate<T extends {
+    id: string;
+}>(sortedRows: readonly T[], request: PageRequest, bounds: {
+    default: number;
+    max: number;
+}): 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).
+ */
+export declare function readPage<Row>(reader: LakeReader<Row>, request: PageRequest, bounds: {
+    default: number;
+    max: number;
+}, scope?: LakeScope): Promise<Page<Row>>;

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

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+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>;
+}
+type Expectation = "string" | "semver" | "object" | "boolean";
+/** 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,68 @@
+/**
+ * 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);
+}
+/** 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;
+    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");
+        }
+    }
+    return { name, version, capabilities, transport, features: features };
+}
+/**
+ * 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

@@ -15,8 +15,12 @@ export function startStdioServer() {
     // tenant-refusal branch through the real stdio transport. Unset by default.
     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,94 @@
+/**
+ * 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.
+ */
+export type SearchMechanism = "indexed-range" | "indexed-bm25" | `indexed-vector(${string})` | "indexed-hybrid-rrf";
+/** 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;
+};
+export declare const CONTEXT_CEILING: {
+    readonly global: 1200;
+    readonly perTool: 700;
+};
+export {};

package/dist/toolRecord.js

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+// 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,
+};
+// Context ceiling (C-13), global AND per tool, in estimated tokens. The sum of the per-tool
+// estimates above must not pass `global`; no single estimate may pass `perTool`.
+export const CONTEXT_CEILING = { global: 1200, perTool: 700 };

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 },

package/dist/upstream/clientCredentials.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Outbound OAuth 2 `client_credentials` token source (RFC 6749 §4.4), for a server derived from
+ * this boilerplate that reads a third-party upstream API. It is the client side only: the inbound
+ * authorization server in `src/oauth/` is unrelated and untouched.
+ *
+ * CREATE IT ONCE, AT MODULE SCOPE. The MCP server is rebuilt per request, so a token source built
+ * inside the factory or a tool handler would fetch a fresh token on every request and defeat the
+ * cache. Build it once per process and reuse it from every request:
+ *
+ * ```ts
+ * // src/upstream.ts — evaluated once per process
+ * import { clientCredentialsFromEnv, createClientCredentialsTokenSource } from "./upstream/clientCredentials.js";
+ *
+ * export const upstream = createClientCredentialsTokenSource(
+ *   clientCredentialsFromEnv({
+ *     clientIdVar: "UPSTREAM_CLIENT_ID",
+ *     clientSecretVar: "UPSTREAM_CLIENT_SECRET",
+ *     tokenUrlVar: "UPSTREAM_TOKEN_URL",
+ *     scopeVar: "UPSTREAM_SCOPE",
+ *   })
+ * );
+ *
+ * // in a tool handler, on any request
+ * const res = await upstream.fetchWithToken("https://api.upstream.example/v1/things");
+ * ```
+ *
+ * The variable names above are examples: the caller chooses them, nothing here hardcodes one.
+ *
+ * Behaviour:
+ * - The token is cached until `expires_in − refreshSkewSeconds` (default skew 60 s), measured from
+ *   the moment the token was REQUESTED, on the injectable `now()` clock.
+ * - Concurrent callers while a token is being fetched share ONE in-flight request (single-flight).
+ *   A failed fetch rejects every waiter and is never cached: the next call fetches again.
+ * - `fetchWithToken` attaches `Authorization: Bearer`; on a 401 it invalidates the token, fetches a
+ *   new one ONCE and retries ONCE. A second 401 is returned to the caller, never looped.
+ * - Every failure of the token endpoint is an `UpstreamTokenError` naming the HTTP status and the
+ *   OAuth `error` code. It never contains the client secret, the Basic header, an access token,
+ *   or the endpoint's `error_description` (free text an endpoint may fill with the request).
+ * - A response it cannot read is refused (fail closed); there is no fallback.
+ *
+ * Errors are operator-facing (configuration and upstream failures, logged server-side), so they
+ * stay in English like `src/oauth/` and `src/envKnobs.ts`; they never reach the MCP client as a
+ * localised tool message.
+ */
+export type ClientAuthMethod = "client_secret_basic" | "client_secret_post";
+export interface ClientCredentialsOptions {
+    /** The upstream token endpoint. https, or http on loopback only (local development). */
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    /** Space-separated scopes, sent as `scope` when set. */
+    scope?: string;
+    /** Sent as `audience` when set (an extension several providers require). */
+    audience?: string;
+    /** RFC 6749 §2.3.1. Default `client_secret_basic`. */
+    authMethod?: ClientAuthMethod;
+    /** Seconds before expiry at which the token is refreshed. Default 60. */
+    refreshSkewSeconds?: number;
+    /** Time budget of one token request. Default 10 s. */
+    timeoutMs?: number;
+    /** Default: the global fetch. Also used by `fetchWithToken` for the upstream API. */
+    fetchImpl?: typeof fetch;
+    /** Milliseconds since the epoch. Default `Date.now`. */
+    now?: () => number;
+}
+export interface ClientCredentialsTokenSource {
+    /** A valid access token, from the cache or from one (shared) token request. */
+    getToken(): Promise<string>;
+    /**
+     * Drops the cached token. With an argument, drops it only if it is still that token, so a stale
+     * 401 never discards a token another request has just refreshed.
+     */
+    invalidate(token?: string): void;
+    /** `fetch` with `Authorization: Bearer <token>`; one refetch + one retry on a 401. */
+    fetchWithToken(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+}
+/** A failure of the upstream token endpoint. Carries no credential and no token. */
+export declare class UpstreamTokenError extends Error {
+    /** HTTP status of the token endpoint, when it answered. */
+    readonly status: number | undefined;
+    /** The OAuth `error` code (RFC 6749 §5.2), when the endpoint sent a readable one. */
+    readonly oauthError: string | undefined;
+    constructor(message: string, details?: {
+        status?: number;
+        oauthError?: string;
+    });
+}
+export declare function createClientCredentialsTokenSource(options: ClientCredentialsOptions): ClientCredentialsTokenSource;
+/** Which environment variables hold the configuration. The caller names them. */
+export interface ClientCredentialsEnvVars {
+    clientIdVar: string;
+    clientSecretVar: string;
+    tokenUrlVar: string;
+    /** Optional: when the variable is unset or empty, no scope is sent. */
+    scopeVar?: string;
+    /** Optional: when the variable is unset or empty, no audience is sent. */
+    audienceVar?: string;
+}
+export type ClientCredentialsEnvOptions = Pick<ClientCredentialsOptions, "tokenUrl" | "clientId" | "clientSecret" | "scope" | "audience">;
+/**
+ * Reads the token source's configuration from the variables the caller names. Unset and empty
+ * are both missing. Every missing required variable is named in one error; no value is ever
+ * shown. Pass the result (plus any `fetchImpl`, `authMethod`, ...) to
+ * `createClientCredentialsTokenSource`.
+ */
+export declare function clientCredentialsFromEnv(vars: ClientCredentialsEnvVars, env?: NodeJS.ProcessEnv): ClientCredentialsEnvOptions;