@vantageos/mcp-boilerplate 0.6.3 → 0.8.0

package/dist/landingPage.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The public setup page at the MCP URL (mcp-server-standard S-50, Manufact "Setup instructions at
+ * the MCP URL"). A person who pastes the MCP URL into a browser gets a short bilingual page
+ * saying what the server is and how to connect, instead of a bare 405 or 401.
+ *
+ * The page is static text built from src/serverIdentity.ts and the locale files: it reads no
+ * credential, calls no backend and grants nothing. Only a request that cannot be an MCP request
+ * is answered with it (`isBrowserLandingRequest`); every other request on /mcp goes on to the
+ * Origin check, the auth gate and the MCP handler exactly as before, including the
+ * 401 + WWW-Authenticate that OAuth discovery depends on.
+ */
+import type { AuthMode } from "./config.js";
+import type { ServerIdentity } from "./serverIdentity.js";
+/**
+ * True only for a browser-style GET: no Authorization header, an Accept that does not include
+ * text/event-stream, and an Accept that includes text/html, or is exactly `*` `/` `*`, or is
+ * absent. RFC 9110 §12.5.1: an absent Accept means any media type; an MCP client opening the SSE
+ * stream always sends `Accept: text/event-stream`, so none of these is an MCP request.
+ */
+export declare function isBrowserLandingRequest(req: Request): boolean;
+/** The page for the server whose MCP endpoint is `mcpUrl`: English, then French. */
+export declare function renderLandingPage(identity: ServerIdentity, mcpUrl: string, authMode: AuthMode): string;
+/** The setup page as an HTTP response. `cacheable`: see serverCardResponse (src/serverCard.ts). */
+export declare function landingPageResponse(identity: ServerIdentity, mcpUrl: string, authMode: AuthMode, cacheable: boolean): Response;

package/dist/landingPage.js

@@ -0,0 +1,109 @@
+/**
+ * The public setup page at the MCP URL (mcp-server-standard S-50, Manufact "Setup instructions at
+ * the MCP URL"). A person who pastes the MCP URL into a browser gets a short bilingual page
+ * saying what the server is and how to connect, instead of a bare 405 or 401.
+ *
+ * The page is static text built from src/serverIdentity.ts and the locale files: it reads no
+ * credential, calls no backend and grants nothing. Only a request that cannot be an MCP request
+ * is answered with it (`isBrowserLandingRequest`); every other request on /mcp goes on to the
+ * Origin check, the auth gate and the MCP handler exactly as before, including the
+ * 401 + WWW-Authenticate that OAuth discovery depends on.
+ */
+import { t } from "./i18n.js";
+/** The media ranges of an Accept header, lower-cased, parameters dropped. */
+function mediaRanges(accept) {
+    return accept
+        .split(",")
+        .map((part) => (part.split(";")[0] ?? "").trim().toLowerCase())
+        .filter((part) => part.length > 0);
+}
+/**
+ * True only for a browser-style GET: no Authorization header, an Accept that does not include
+ * text/event-stream, and an Accept that includes text/html, or is exactly `*` `/` `*`, or is
+ * absent. RFC 9110 §12.5.1: an absent Accept means any media type; an MCP client opening the SSE
+ * stream always sends `Accept: text/event-stream`, so none of these is an MCP request.
+ */
+export function isBrowserLandingRequest(req) {
+    if (req.method !== "GET")
+        return false;
+    if (req.headers.has("authorization"))
+        return false;
+    const accept = req.headers.get("accept");
+    if (accept === null)
+        return true;
+    const ranges = mediaRanges(accept);
+    if (ranges.includes("text/event-stream"))
+        return false;
+    if (ranges.includes("text/html"))
+        return true;
+    return ranges.length === 1 && ranges[0] === "*/*";
+}
+function escapeHtml(value) {
+    return value
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+function section(locale, identity, mcpUrl, authMode) {
+    const tx = (key) => escapeHtml(t(locale, `landing.${key}`));
+    const endpoint = escapeHtml(mcpUrl);
+    const site = escapeHtml(identity.websiteUrl);
+    const add = escapeHtml(`claude mcp add --transport http ${identity.name} ${mcpUrl}`);
+    return `<section lang="${locale}">
+<h1>${escapeHtml(identity.title)}</h1>
+<p>${escapeHtml(identity.description[locale])}</p>
+<p>${tx("intro")}</p>
+<p><code>${endpoint}</code></p>
+<ul>
+<li>${tx("claudeAi")}</li>
+<li>${tx("chatgpt")}</li>
+<li>${tx("claudeCode")} <code>${add}</code></li>
+<li>${tx("other")}</li>
+</ul>
+<p>${tx(authMode === "oauth" ? "authOauth" : "authPublic")}</p>
+<p>${tx("website")} <a href="${site}">${site}</a></p>
+</section>`;
+}
+/** The page for the server whose MCP endpoint is `mcpUrl`: English, then French. */
+export function renderLandingPage(identity, mcpUrl, authMode) {
+    const title = escapeHtml(t("en", "landing.pageTitle").replace("{title}", () => identity.title));
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${title}</title>
+<link rel="icon" href="icon.svg" type="image/svg+xml">
+<style>
+  body { font: 16px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; max-width: 42rem; margin: 3rem auto; padding: 0 1.25rem; color: #1f2328; background: #ffffff; }
+  code { background: #f6f8fa; padding: 0.1rem 0.35rem; border-radius: 4px; overflow-wrap: anywhere; }
+  h1 { font-size: 1.6rem; margin-bottom: 0.25rem; }
+  li { margin: 0.4rem 0; }
+  section + section { border-top: 1px solid #d0d7de; margin-top: 2rem; padding-top: 1rem; }
+  @media (prefers-color-scheme: dark) { body { background: #0d1117; color: #e6edf3; } code { background: #161b22; } a { color: #58a6ff; } section + section { border-color: #30363d; } }
+</style>
+</head>
+<body>
+<main>
+${section("en", identity, mcpUrl, authMode)}
+${section("fr", identity, mcpUrl, authMode)}
+</main>
+</body>
+</html>`;
+}
+/** The setup page as an HTTP response. `cacheable`: see serverCardResponse (src/serverCard.ts). */
+export function landingPageResponse(identity, mcpUrl, authMode, cacheable) {
+    return new Response(renderLandingPage(identity, mcpUrl, authMode), {
+        status: 200,
+        headers: {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": cacheable ? "public, max-age=300" : "no-store",
+            "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'; img-src 'self'; base-uri 'none'; form-action 'none'; frame-ancestors 'none'",
+            "x-content-type-options": "nosniff",
+            // The same URL answers MCP requests differently by method, Accept and credential.
+            vary: "Accept, Authorization",
+        },
+    });
+}

package/dist/listCursor.d.ts

@@ -0,0 +1,10 @@
+import { type McpServer } from "@modelcontextprotocol/server";
+/**
+ * C-11 (a) (mcp-standard): an invalid cursor sent to a protocol list method is JSON-RPC -32602 Invalid params, never a
+ * silent first page. The SDK serves `tools/list`, `resources/list`, `resources/templates/list` and `prompts/list` as
+ * ONE page and issues no `nextCursor`, so every cursor such a request carries is one this server never issued: invalid.
+ * The SDK itself ignores the cursor and answers page 1, so each of these handlers is wrapped in place (the SDK keeps them
+ * in a map) to refuse first. A list that cannot be wrapped refuses the start: it must not answer a cursor silently.
+ */
+export declare const SINGLE_PAGE_LISTS: readonly ["tools/list", "resources/list", "resources/templates/list", "prompts/list"];
+export declare function rejectCursorOnSinglePageLists(server: McpServer): void;

package/dist/listCursor.js

@@ -0,0 +1,37 @@
+import { ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";
+/**
+ * C-11 (a) (mcp-standard): an invalid cursor sent to a protocol list method is JSON-RPC -32602 Invalid params, never a
+ * silent first page. The SDK serves `tools/list`, `resources/list`, `resources/templates/list` and `prompts/list` as
+ * ONE page and issues no `nextCursor`, so every cursor such a request carries is one this server never issued: invalid.
+ * The SDK itself ignores the cursor and answers page 1, so each of these handlers is wrapped in place (the SDK keeps them
+ * in a map) to refuse first. A list that cannot be wrapped refuses the start: it must not answer a cursor silently.
+ */
+export const SINGLE_PAGE_LISTS = [
+    "tools/list",
+    "resources/list",
+    "resources/templates/list",
+    // The seed registers no prompt, so it serves no prompts/list; a fork that registers one gets it guarded.
+    "prompts/list",
+];
+export function rejectCursorOnSinglePageLists(server) {
+    const handlers = server.server
+        ._requestHandlers;
+    if (!handlers)
+        throw new Error("C-11 (a): the SDK's request handlers were not found; list cursors cannot be checked");
+    for (const method of SINGLE_PAGE_LISTS) {
+        const inner = handlers.get(method);
+        if (typeof inner !== "function")
+            continue; // a list this server does not serve (no resources) has no handler
+        handlers.set(method, async (req, ctx) => {
+            const cursor = req?.params?.cursor;
+            if (cursor !== undefined)
+                throw new ProtocolError(ProtocolErrorCode.InvalidParams, `invalid cursor: ${method} is served as one page and issues no cursor`);
+            const result = (await inner(req, ctx));
+            // The refusal above rests on the SDK serving one page. If it ever returns a nextCursor, cursors become valid
+            // and refusing them all would be wrong: fail loud instead of answering a page with a cursor we would refuse.
+            if (result?.nextCursor !== undefined)
+                throw new Error(`C-11 (a): ${method} now returns a nextCursor; src/listCursor.ts must accept its cursors`);
+            return result;
+        });
+    }
+}

package/dist/mcpServerFactory.d.ts

@@ -32,8 +32,11 @@ 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 RateLimiter } from "./rateLimit.js";
+import { type ServedToolRecords } from "./servedToolRecords.js";
 import type { CursorSigner } from "./signedCursor.js";
 import { type ResolvedTenant } from "./tenancy.js";
+import { type ToolRolesContext } from "./toolRoleGate.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[];
@@ -65,8 +68,15 @@ export interface McpServerDeps {
      */
     locale?: McpLocale;
     /**
-     * Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`). Host-dependent; set
-     * only when the deployment has one (MCP_UI_DOMAIN). Omitted from the resource when unset.
+     * The base URL (ending in `/`) the HTTP transport is reached at, resolved per request by
+     * src/httpApp.ts: the serverInfo icon is served under it. Absent (stdio): the icon travels inline.
+     */
+    baseUrl?: string;
+    /** The tool invocation limiter (S-24); default the process-wide `toolRateLimiter`. A test injects its own. */
+    rateLimiter?: RateLimiter;
+    /**
+     * Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`), derived from the served MCP URL by
+     * `claudeSandboxDomain` (src/ui/sandboxDomain.ts, A-11). Omitted from the resource when there is no served URL.
      */
     uiDomain?: string;
     /**
@@ -75,6 +85,11 @@ export interface McpServerDeps {
      * before. A derived server injects its own (e.g. `@vantageos/mcp-boilerplate/lake/convex`).
      */
     lake?: LakeReader<ExampleItem>;
+    /**
+     * Agent tool roles for this request (src/toolRoleGate.ts): on the OAuth tier, the caller's role lookup and member
+     * scope, resolved by httpApp before the server is built; elsewhere `{ applicable: false }`. Default: not applicable.
+     */
+    toolRoles?: ToolRolesContext;
     /**
      * Signs and verifies the `list_items` cursor (src/signedCursor.ts). Default: the process-wide
      * signer of src/pagination.ts, whose key is random per process. A multi-instance deployment
@@ -83,3 +98,8 @@ export interface McpServerDeps {
     cursorSigner?: CursorSigner;
 }
 export declare function createBoilerplateMcpServer(deps?: McpServerDeps): McpServer;
+/**
+ * The tools a server built by this factory registered (name, title, description), for the public
+ * server card (src/serverCard.ts): read from the registrations, never a second list.
+ */
+export declare function registeredToolSummaries(server: McpServer): ServedToolRecords["summaries"];

package/dist/mcpServerFactory.js

@@ -31,19 +31,25 @@
 import { registerAppResource } from "@modelcontextprotocol/ext-apps/server";
 import { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
-import { getBuildIdentity } from "./buildIdentity.js";
+import { getBuildCommit, getBuildIdentity } from "./buildIdentity.js";
 import { t } from "./i18n.js";
 import { EXAMPLE_ITEMS_READER, LAKE_UNREADABLE_CODE, LakeReadError, } from "./lake/reader.js";
+import { rejectCursorOnSinglePageLists } from "./listCursor.js";
 import { INVALID_CURSOR_CODE, InvalidCursorError, PAGINATION, readPage } from "./pagination.js";
+import { RATE_LIMITED_CODE, toolRateLimiter } from "./rateLimit.js";
 import { trackToolRecords } from "./servedToolRecords.js";
+import { getServerIdentity, serverInstructions, serverPresentation } from "./serverIdentity.js";
 import { loadServerManifest } from "./serverManifest.js";
 import { scopeRowsForTenant } from "./tenancy.js";
-import { LIST_ITEMS_ANNOTATIONS, PING_ANNOTATIONS } from "./toolRecord.js";
+import { LIST_ITEMS_ANNOTATIONS, PING_ANNOTATIONS, WHOAMI_ANNOTATIONS } from "./toolRecord.js";
+import { grantedToolNames, installToolRoleGate } from "./toolRoleGate.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"];
-const itemSchema = z.object({
+// S-44: output objects stay open (z.looseObject): a field added in a later release must not fail a client that
+// validated against the schema it read at connect time.
+const itemSchema = z.looseObject({
     id: z.string(),
     name: z.string(),
     orgId: z.string(),
@@ -54,7 +60,21 @@ const localeSchema = z.enum(["en", "fr"]);
 const pingInput = z.object({
     message: z.string().optional().describe("Optional message echoed back verbatim"),
 });
-const pingOutput = z.object({ reply: z.string() });
+const pingOutput = z.looseObject({ reply: z.string() });
+/** The identity tool takes no argument (C-33): the identity never arrives as an argument. */
+const whoamiInput = z.object({});
+const whoamiOutput = z.looseObject({
+    /** The verified subject behind the credentials; null where there is no caller (public HTTP, stdio). */
+    id: z.string().nullable(),
+    /** The caller's role, or null: no role, or roles not applicable. */
+    role: z.looseObject({ id: z.string(), name: z.string() }).nullable(),
+    /** The tools the caller's role grants, by the same decision as tools/list. */
+    grantedTools: z.array(z.string()),
+    /** False on the public HTTP tier and stdio: there is no caller, so no role is decided. */
+    rolesApplicable: z.boolean(),
+});
+/** The identity tool, outside the role gate (rule 6). */
+const IDENTITY_TOOL = "whoami";
 // 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 = {
@@ -66,7 +86,8 @@ const pageInput = {
         .number()
         .int()
         .min(1)
-        .optional()
+        // Served in the inputSchema (C-11): the default is declared where a caller reads it, not only applied.
+        .default(PAGINATION.default)
         .describe(`Page size; default ${PAGINATION.default}, capped at ${PAGINATION.max}`),
 };
 const pageOutput = {
@@ -79,7 +100,7 @@ const listItemsInput = z.object({
         .describe("Widget and fallback language; defaults to the caller's X-MCP-Locale"),
     ...pageInput,
 });
-const listItemsOutput = z.object({
+const listItemsOutput = z.looseObject({
     items: z.array(itemSchema),
     locale: localeSchema,
     ...pageOutput,
@@ -100,18 +121,26 @@ export function createBoilerplateMcpServer(deps = {}) {
     // 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).
+    // The identity the server announces (S-49): name, version, title, description (in the caller's
+    // locale), websiteUrl and icons, all from src/serverIdentity.ts (package.json or environment),
+    // plus the build identity (C-25): buildId = the git commit the tree was built from, buildHash =
+    // the hash of the files this process runs from (src/buildIdentity.ts). The SDK sends
+    // `serverInfo` as given, on `server/discover` (2026-07-28,
+    // `_meta["io.modelcontextprotocol/serverInfo"]`) and on `initialize` (2025-era). The build keys
+    // are not modelled `Implementation` keys, hence the spread (no excess-key check).
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
-        ...{ buildId: getBuildIdentity() },
+        ...serverPresentation(getServerIdentity(), locale, deps.baseUrl),
+        ...{
+            buildId: getBuildCommit(),
+            buildHash: 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",
+        // How an agent uses this server, in the caller's locale (src/serverIdentity.ts).
+        instructions: serverInstructions(locale),
         supportedProtocolVersions: SUPPORTED_LEGACY_PROTOCOL_VERSIONS,
         cacheHints: {
             "tools/list": { ttlMs: 60_000, cacheScope: "public" },
@@ -121,26 +150,51 @@ export function createBoilerplateMcpServer(deps = {}) {
         },
     });
     const served = trackToolRecords(server);
+    // Agent tool roles: every tool registered below is gated (call refused) and the list filtered, both by the same
+    // decision; the identity tool is the one exemption.
+    const roles = deps.toolRoles ?? { applicable: false };
+    const gate = installToolRoleGate(server, roles, locale, new Set([IDENTITY_TOOL]));
+    // S-24: every tool invocation takes a token from the caller's bucket (keyed by the resolved organisation, or
+    // "public" on the unscoped tier); an empty bucket is a tool error with a stable code and the wait, never a silent drop.
+    const limiter = deps.rateLimiter ?? toolRateLimiter;
+    const rateKey = deps.tenant?.tenantId ?? "public";
+    const withRateLimit = (handler) => async (args) => {
+        const d = limiter.consume(rateKey);
+        if (d.ok)
+            return handler(args);
+        const message = t(locale, "rateLimit.exceeded").replace("{seconds}", () => String(Math.ceil(d.retryAfterMs / 1000)));
+        return {
+            content: [{ type: "text", text: message }],
+            structuredContent: {
+                error: { code: RATE_LIMITED_CODE, retryAfterMs: d.retryAfterMs, message },
+            },
+            isError: true,
+        };
+    };
     server.registerTool("ping", {
         title: "Ping",
-        description: "Echoes the given message (or 'pong' if none given). Proves the MCP handshake end to end.",
+        // C-19: served in both languages in the one description field ("<en> / <fr>"), with its trigger phrase.
+        description: "Echoes the given message (or 'pong' if none given) and proves the MCP handshake end to end. " +
+            "Use this whenever you need to check that this server answers, even if they don't say 'ping'. / " +
+            "Renvoie le message donné (ou 'pong' sans message) et prouve la poignée de main MCP de bout en bout. " +
+            "À utiliser pour vérifier que ce serveur répond, même sans le mot 'ping'.",
         inputSchema: pingInput,
         outputSchema: pingOutput,
         annotations: PING_ANNOTATIONS,
-    }, async (args) => {
+    }, withRateLimit(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.
         if (args.message !== undefined && args.message.length > 200) {
             return refusal(t(locale, "validation.messageTooLong"));
         }
         return structuredResult({ reply: args.message ?? "pong" });
-    });
+    }));
     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.)
+    // list methods' cursor: src/listCursor.ts refuses it there, since the SDK ignores it.)
     const invalidCursor = () => {
         const message = t(locale, "pagination.invalidCursor");
         return {
@@ -166,10 +220,15 @@ export function createBoilerplateMcpServer(deps = {}) {
     // MCP Apps (mcp-app-standard A-1). The widget renders THIS result.
     server.registerTool("list_items", {
         title: "List items",
-        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.",
+        // C-19: served in both languages in the one description field ("<en> / <fr>"), with its trigger phrase.
+        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, even if they " +
+            "don't say 'list'. On the OAuth tier, results are scoped to the caller's organisation; on the public " +
+            "tier (no auth gate), they are unscoped. / " +
+            "Liste les éléments d'exemple, une page à la fois, et les affiche en widget interactif dans les hôtes " +
+            "MCP Apps. À utiliser quand l'utilisateur demande de lister, voir ou afficher les éléments, même sans " +
+            "le mot 'lister'. Sur le niveau OAuth, les résultats sont limités à l'organisation de l'appelant ; sur " +
+            "le niveau public (sans authentification), ils ne le sont pas.",
         inputSchema: listItemsInput,
         outputSchema: listItemsOutput,
         annotations: LIST_ITEMS_ANNOTATIONS,
@@ -178,7 +237,7 @@ export function createBoilerplateMcpServer(deps = {}) {
             ...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) => {
+    }, withRateLimit(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.
@@ -202,7 +261,7 @@ export function createBoilerplateMcpServer(deps = {}) {
                 return lakeUnreadable(error.code);
             throw error;
         }
-    });
+    }));
     // 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"]`
@@ -218,7 +277,51 @@ export function createBoilerplateMcpServer(deps = {}) {
     }, async () => ({
         contents: [buildUiResource({ domain: deps.uiDomain })],
     }));
+    server.registerTool(IDENTITY_TOOL, {
+        title: "Who am I",
+        // C-19: both languages in the one served field ("<en> / <fr>") with its trigger phrase; no separate
+        // `_meta.description_fr`, which would only repeat the French half.
+        description: "Returns who you are to this server: your verified subject, the role your tools are decided by, " +
+            "and the tools it grants. Use this whenever you need to know what you may call, even if they don't " +
+            "say 'whoami'. / Renvoie qui vous êtes pour ce serveur : sujet vérifié, rôle qui décide de vos " +
+            "outils, outils accordés. À utiliser pour savoir ce que vous pouvez appeler, même sans le mot 'whoami'.",
+        inputSchema: whoamiInput,
+        outputSchema: whoamiOutput,
+        annotations: WHOAMI_ANNOTATIONS,
+    }, withRateLimit(async () => {
+        const person = deps.caller?.ok ? deps.caller.person : undefined;
+        const lookup = roles.applicable ? roles.lookup : undefined;
+        const role = lookup?.status === "resolved" && roles.applicable
+            ? {
+                id: lookup.role.roleId,
+                name: roles.roleName(lookup.role.roleId) ?? lookup.role.roleId,
+            }
+            : null;
+        return structuredResult({
+            id: person?.subject ?? null,
+            role,
+            grantedTools: grantedToolNames(roles, gate.declarations),
+            rolesApplicable: roles.applicable,
+        });
+    }));
+    // tools/list narrowed to the granted tools (and the identity tool), once every tool is registered.
+    gate.filterList();
+    // C-11 (a): a cursor sent to a single-page protocol list method is -32602 (src/listCursor.ts). Installed after the
+    // role filter, so it wraps it: the cursor is refused before any list is built (tests/toolRoles.test.ts).
+    rejectCursorOnSinglePageLists(server);
     // Start refusal: every registered tool's record, as registered, must be sound.
     served.assertServed(manifest.contextCeiling);
+    SUMMARIES.set(server, served.summaries);
     return server;
 }
+const SUMMARIES = new WeakMap();
+/**
+ * The tools a server built by this factory registered (name, title, description), for the public
+ * server card (src/serverCard.ts): read from the registrations, never a second list.
+ */
+export function registeredToolSummaries(server) {
+    const summaries = SUMMARIES.get(server);
+    if (!summaries)
+        throw new Error("registeredToolSummaries: not a server built by this factory");
+    return summaries;
+}

package/dist/oauth/authorizationServer.js

@@ -20,13 +20,15 @@
  * FAIL-CLOSED: any missing configuration value answers 503 `temporarily_unavailable`.
  * No refresh tokens are issued; access tokens live one hour.
  */
-import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resolveClerkSessionFromRequest, resumeAuthorize, startAuthorize, } from "@vantageos/cloud-identity";
+import { buildDiscoveryDocument, buildUserInfo, exchangeAuthorizationCode, oauthErrorFor, resolveClerkSessionFromRequest, resumeAuthorize, startAuthorize, verifyMcpAccessToken, } from "@vantageos/cloud-identity";
+// The private_key_jwt client-assertion verifier lives in the identity layer (DLocalIdentity), as a subpath: it uses
+// node:net / node:dns for its SSRF guard, which the root entry stays free of.
+import { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier, } from "@vantageos/cloud-identity/client-assertion";
 import { getCookie } from "hono/cookie";
 import { cors } from "hono/cors";
 import { flagKnob, integerKnob, originListKnob } from "../envKnobs.js";
 import { detectLocale, detectLocaleFromAcceptLanguage, t } from "../i18n.js";
 import { createClerkBackendCollaborators } from "./clerk.js";
-import { ASSERTION_SIGNING_ALGS, createClientAssertionVerifier } from "./clientAssertion.js";
 import { RegistryFullError, createInMemoryClientRegistry, isAllowedRedirectUri, isUrlShapedClientId, resolveCimdClient, } from "./clientRegistry.js";
 import { createInMemoryCodeStore } from "./codeStore.js";
 import { HANDOFF_CSP, pickerContentSecurityPolicy, renderHandoff, renderOrgPicker, } from "./picker.js";
@@ -36,6 +38,8 @@ import { ACCESS_TOKEN_TTL_SECONDS, createTokenIssuer } from "./tokenIssuer.js";
 const REGISTER_LIMIT_PER_MINUTE = 20;
 /** Default of OAUTH_ENV.registerLimitPer48: five /64 budgets for a whole /48. */
 const REGISTER_LIMIT_PER_48_PER_MINUTE = 100;
+/** Default of OAUTH_ENV.tokenLimitPerMinute: /token requests per client address per minute. */
+const TOKEN_LIMIT_PER_MINUTE = 60;
 const MAX_REDIRECT_URIS = 10;
 const REGISTRY_FULL_RETRY_AFTER_SECONDS = 300;
 function noStore(c) {
@@ -89,6 +93,7 @@ export function createAuthorizationServer(deps = {}) {
     // Operator knobs are validated here, at construction: a bad value stops the boot.
     const trustedProxyCount = integerKnob(env, OAUTH_ENV.trustedProxyCount, 0, 10) ?? 0;
     const registerLimitPer48 = integerKnob(env, OAUTH_ENV.registerLimitPer48, 1) ?? REGISTER_LIMIT_PER_48_PER_MINUTE;
+    const tokenLimitPerMinute = integerKnob(env, OAUTH_ENV.tokenLimitPerMinute, 1) ?? TOKEN_LIMIT_PER_MINUTE;
     const registerOrigins = originListKnob(env, OAUTH_ENV.registerCorsOrigins);
     const allowInMemory = flagKnob(env, OAUTH_ENV.allowInMemoryStores) === true;
     const now = deps.now ?? (() => Date.now());
@@ -270,6 +275,14 @@ export function createAuthorizationServer(deps = {}) {
         prefix48LimitPerMinute: registerLimitPer48,
         now,
     });
+    // /token is unauthenticated until the client is verified, and each private_key_jwt assertion it verifies occupies a
+    // single-use jti slot until it expires: an unbounded caller could fill the jti store. The same address-keyed
+    // limiter as /register (an IPv6 client on its /64, and its /48 at five budgets) bounds every caller.
+    const tokenLimiter = createRegisterLimiter({
+        limitPerMinute: tokenLimitPerMinute,
+        prefix48LimitPerMinute: tokenLimitPerMinute * 5,
+        now,
+    });
     return {
         async resourceServer() {
             const result = await settingsNow();
@@ -513,6 +526,10 @@ export function createAuthorizationServer(deps = {}) {
                 return respond(c, outcome, result.settings);
             });
             app.post("/token", async (c) => {
+                if (!tokenLimiter.allow(clientKeyOf(c, trustedProxyCount))) {
+                    c.header("Retry-After", "60");
+                    return c.json({ error: "too_many_requests" }, 429);
+                }
                 const result = await settingsNow();
                 if (!result.ok)
                     return unavailable(c, result.missing);
@@ -590,22 +607,26 @@ export function createAuthorizationServer(deps = {}) {
                 const result = await settingsNow();
                 if (!result.ok)
                     return unavailable(c, result.missing);
-                const header = c.req.header("authorization") ?? "";
-                const token = header.toLowerCase().startsWith("bearer ") ? header.slice(7).trim() : "";
                 const invalid = () => {
                     c.header("WWW-Authenticate", 'Bearer error="invalid_token"');
                     return c.json({ error: "invalid_token" }, 401);
                 };
-                if (!token)
-                    return invalid();
+                // Our own access token is verified by the identity layer, never here (DLocalIdentity):
+                // issuer = this server, audience = the protected resource, key set = our published JWKS.
                 const issuer = await issuerFor(result.settings);
-                let claims;
-                try {
-                    claims = await issuer.verify(token, result.settings.baseUrl, result.settings.resource);
-                }
-                catch {
+                const verified = await verifyMcpAccessToken(c.req.header("authorization"), {
+                    realm: "mcp",
+                    resourceMetadataUrl: `${result.settings.baseUrl}/.well-known/oauth-protected-resource`,
+                    issuer: result.settings.baseUrl,
+                    audience: result.settings.resource,
+                    jwks: issuer.jwks,
+                }, now());
+                if (!verified.ok)
                     return invalid();
-                }
+                const claims = {
+                    sub: verified.session.userId,
+                    scope: String(verified.session.claims.scope ?? ""),
+                };
                 let user;
                 try {
                     user = await clerkFor().getUser(claims.sub);

package/dist/oauth/picker.js

@@ -92,6 +92,7 @@ function formActionSources(redirectUris) {
  */
 export async function pickerContentSecurityPolicy(redirectUris) {
     const formAction = ["'self'", ...formActionSources(redirectUris)].join(" ");
+    // allow-local-identity: CSP hash of the picker's own constant stylesheet; no credential, caller or tenant
     const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(PICKER_STYLE));
     const hash = btoa(String.fromCharCode(...new Uint8Array(digest)));
     return [

package/dist/oauth/settings.d.ts

@@ -18,6 +18,8 @@ export declare const OAUTH_ENV: {
     readonly trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT";
     /** /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). */
     readonly registerLimitPer48: "MCP_REGISTER_LIMIT_PER_48_PER_MINUTE";
+    /** /token requests per client address per minute (default 60); its /48 gets five times that. */
+    readonly tokenLimitPerMinute: "MCP_TOKEN_LIMIT_PER_MINUTE";
     /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
     readonly registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS";
     /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */

package/dist/oauth/settings.js

@@ -18,6 +18,8 @@ export const OAUTH_ENV = {
     trustedProxyCount: "MCP_TRUSTED_PROXY_COUNT",
     /** /register budget shared by every /64 inside one IPv6 /48, per minute (default 100). */
     registerLimitPer48: "MCP_REGISTER_LIMIT_PER_48_PER_MINUTE",
+    /** /token requests per client address per minute (default 60); its /48 gets five times that. */
+    tokenLimitPerMinute: "MCP_TOKEN_LIMIT_PER_MINUTE",
     /** Comma-separated browser origins allowed to call /register cross-origin (default: none). */
     registerCorsOrigins: "MCP_REGISTER_CORS_ORIGINS",
     /** Exactly "1" lets NODE_ENV=production run on the in-memory stores (single instance only). */

package/dist/oauth/tokenIssuer.d.ts

@@ -15,7 +15,6 @@ export interface TokenIssuer {
         keys: JWK[];
     };
     sign(claims: AuthorizedTokenClaims, issuer: string, nowMs: number): Promise<string>;
-    verify(token: string, issuer: string, audience: string): Promise<AuthorizedTokenClaims>;
 }
 export declare function createTokenIssuer(privateJwk: JWK & {
     kid: string;