@vantageos/mcp-boilerplate 0.6.3 → 0.8.0

package/dist/oauth/tokenIssuer.js

@@ -4,7 +4,7 @@
  * deployment's key. The resource server (@vantageos/cloud-identity `verifyMcpAccessToken`)
  * verifies the result against the public half published at /.well-known/jwks.json.
  */
-import { SignJWT, createLocalJWKSet, importJWK, jwtVerify } from "jose";
+import { SignJWT, importJWK } from "jose";
 export const ACCESS_TOKEN_TTL_SECONDS = 3600;
 export async function createTokenIssuer(privateJwk) {
     const key = await importJWK(privateJwk, "RS256");
@@ -18,7 +18,6 @@ export async function createTokenIssuer(privateJwk) {
         use: "sig",
     };
     const jwks = { keys: [publicJwk] };
-    const verifyKey = createLocalJWKSet(jwks);
     return {
         kid: privateJwk.kid,
         publicJwk,
@@ -41,21 +40,5 @@ export async function createTokenIssuer(privateJwk) {
                 .setJti(crypto.randomUUID())
                 .sign(key);
         },
-        async verify(token, issuer, audience) {
-            const { payload } = await jwtVerify(token, verifyKey, {
-                issuer,
-                audience,
-                algorithms: ["RS256"],
-            });
-            return {
-                sub: String(payload.sub),
-                org_id: String(payload.org_id),
-                org_slug: payload.org_slug ?? null,
-                org_role: String(payload.org_role),
-                aud: audience,
-                client_id: String(payload.client_id),
-                scope: String(payload.scope),
-            };
-        },
     };
 }

package/dist/pagination.d.ts

@@ -14,7 +14,8 @@
  *     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.
+ *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor
+ *     (src/listCursor.ts).
  */
 import { type LakeReader, type LakeScope } from "./lake/reader.js";
 import { type CursorSigner } from "./signedCursor.js";

package/dist/pagination.js

@@ -14,7 +14,8 @@
  *     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.
+ *     SEP-1303), not a JSON-RPC error: -32602 stays with the protocol list methods' cursor
+ *     (src/listCursor.ts).
  */
 import { rangeAfter } from "./exampleItems.js";
 import { checkLakePage } from "./lake/reader.js";

package/dist/rateLimit.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Tool invocation rate limiting (mcp-server-standard S-24: every published tool applies rate limiting to its
+ * invocation, a MUST at the rank of input validation). A token bucket per caller: `capacity` calls may burst, then
+ * the bucket refills at `perMinute`. The buckets live for the process, not for one request: the HTTP tier builds a
+ * server per request, so a per-server bucket would never fill.
+ *
+ * Configuration (environment, read once at start): TOOL_RATE_LIMIT_PER_MINUTE (default 60) and TOOL_RATE_LIMIT_BURST
+ * (default 30). A value that is not a positive integer refuses the start, naming the variable.
+ */
+export type RateDecision = {
+    ok: true;
+} | {
+    ok: false;
+    retryAfterMs: number;
+};
+export interface RateLimiter {
+    /** Takes one token from `key`'s bucket, or says how long until one is available. */
+    consume(key: string): RateDecision;
+}
+export declare function createTokenBucketLimiter(opts: {
+    capacity: number;
+    perMinute: number;
+    now?: () => number;
+}): RateLimiter;
+/** The limits read from the environment. */
+export declare function loadToolRateLimit(env?: NodeJS.ProcessEnv): {
+    capacity: number;
+    perMinute: number;
+};
+/** The process-wide limiter every tool invocation goes through, unless a test injects its own. */
+export declare const toolRateLimiter: RateLimiter;
+/** The stable machine code of a refused invocation (beside a message localized per X-MCP-Locale). */
+export declare const RATE_LIMITED_CODE = "rate_limited";

package/dist/rateLimit.js

@@ -0,0 +1,48 @@
+/**
+ * Tool invocation rate limiting (mcp-server-standard S-24: every published tool applies rate limiting to its
+ * invocation, a MUST at the rank of input validation). A token bucket per caller: `capacity` calls may burst, then
+ * the bucket refills at `perMinute`. The buckets live for the process, not for one request: the HTTP tier builds a
+ * server per request, so a per-server bucket would never fill.
+ *
+ * Configuration (environment, read once at start): TOOL_RATE_LIMIT_PER_MINUTE (default 60) and TOOL_RATE_LIMIT_BURST
+ * (default 30). A value that is not a positive integer refuses the start, naming the variable.
+ */
+export function createTokenBucketLimiter(opts) {
+    const now = opts.now ?? Date.now;
+    const refillPerMs = opts.perMinute / 60_000;
+    const buckets = new Map();
+    return {
+        consume(key) {
+            const t = now();
+            const b = buckets.get(key) ?? { tokens: opts.capacity, at: t };
+            b.tokens = Math.min(opts.capacity, b.tokens + (t - b.at) * refillPerMs);
+            b.at = t;
+            buckets.set(key, b);
+            if (b.tokens >= 1) {
+                b.tokens -= 1;
+                return { ok: true };
+            }
+            return { ok: false, retryAfterMs: Math.ceil((1 - b.tokens) / refillPerMs) };
+        },
+    };
+}
+function positiveInt(env, name, fallback) {
+    const raw = env[name];
+    if (raw === undefined || raw === "")
+        return fallback;
+    const n = Number(raw);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new Error(`${name} must be a positive integer (got a value that is not)`);
+    return n;
+}
+/** The limits read from the environment. */
+export function loadToolRateLimit(env = process.env) {
+    return {
+        capacity: positiveInt(env, "TOOL_RATE_LIMIT_BURST", 30),
+        perMinute: positiveInt(env, "TOOL_RATE_LIMIT_PER_MINUTE", 60),
+    };
+}
+/** The process-wide limiter every tool invocation goes through, unless a test injects its own. */
+export const toolRateLimiter = createTokenBucketLimiter(loadToolRateLimit());
+/** The stable machine code of a refused invocation (beside a message localized per X-MCP-Locale). */
+export const RATE_LIMITED_CODE = "rate_limited";

package/dist/servedToolRecords.d.ts

@@ -12,6 +12,12 @@ import type { ContextCeiling } from "./serverManifest.js";
 export interface ServedToolRecords {
     /** The annotations of every tool registered so far, by tool name. */
     readonly records: Readonly<Record<string, Record<string, unknown>>>;
+    /** Each registered tool's name, title and description, in registration order (the server card). */
+    readonly summaries: ReadonlyArray<{
+        name: string;
+        title?: string;
+        description?: string;
+    }>;
     /** Throws `ToolRecordError` naming every unsound tool; same check as the wire test. */
     assertServed(ceiling: ContextCeiling): void;
 }

package/dist/servedToolRecords.js

@@ -1,10 +1,20 @@
 import { assertToolRecords } from "./toolRecord.js";
 export function trackToolRecords(server) {
     const records = {};
+    const summaries = [];
     const register = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => {
         records[name] = { ...(config.annotations ?? {}) };
+        summaries.push({
+            name,
+            ...(config.title !== undefined ? { title: config.title } : {}),
+            ...(config.description !== undefined ? { description: config.description } : {}),
+        });
         return register(name, config, callback);
     });
-    return { records, assertServed: (ceiling) => assertToolRecords(records, ceiling) };
+    return {
+        records,
+        summaries,
+        assertServed: (ceiling) => assertToolRecords(records, ceiling),
+    };
 }

package/dist/serverCard.d.ts

@@ -0,0 +1,68 @@
+/**
+ * The public MCP Server Card (mcp-server-standard S-50, Manufact "mcp.json or MCP Server Card
+ * served"). Served by src/httpApp.ts, before every gate, at each path in `SERVER_CARD_PATHS`.
+ *
+ * Shape: the `ServerCard` of the MCP Server Card extension (SEP-2127,
+ * modelcontextprotocol/experimental-ext-server-card `schema.json` at commit
+ * 526201bbc80231daa40ffcdecfc9da4e54e5dc93, sha256
+ * 2c772b51edb367f154771d84ddbae87ddba00a624422c8e46f218a9ac03bf042), vendored at
+ * tests/fixtures/server-card.schema.json and validated in tests/serverMetadata.test.ts.
+ *
+ * Declared divergence: the extension says a card does not enumerate primitives, while Manufact's
+ * check and mcp-doctor S-50 read `capabilities` and a tool summary (`tools`) on the card. The
+ * schema allows additional members, so the card carries both: the capabilities of
+ * mcp-server.json (the same object `initialize` serves) and each served tool's name, title and
+ * description, read from the tools as registered — never a second list to keep in step.
+ *
+ * The card is public metadata and grants nothing. Every string comes from src/serverIdentity.ts
+ * (the source of the serverInfo), and the URLs from the origin the server is reached at.
+ */
+import type { Icon } from "@modelcontextprotocol/server";
+import { type ServerIdentity } from "./serverIdentity.js";
+export declare const SERVER_CARD_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export declare const SERVER_CARD_MEDIA_TYPE = "application/mcp-server-card+json";
+/**
+ * Where the card is served: `/mcp/server-card` is the location the extension reserves
+ * (`<streamable-http-url>/server-card`); the others are the origin-level paths Manufact and
+ * mcp-doctor S-50 probe. Manufact also reads `/.well-known/ai-catalog.json` and the parent
+ * domain; an AI Catalog lists cards rather than being one, so it is not served here.
+ */
+export declare const SERVER_CARD_PATHS: readonly ["/mcp/server-card", "/.well-known/mcp/server-card.json", "/.well-known/mcp-server-card", "/mcp.json", "/.well-known/mcp.json"];
+/** One served tool, as summarised on the card. */
+export interface CardTool {
+    name: string;
+    title?: string;
+    description?: string;
+}
+export interface ServerCard {
+    $schema: string;
+    name: string;
+    version: string;
+    description: string;
+    title: string;
+    websiteUrl: string;
+    icons: Icon[];
+    remotes: Array<{
+        type: "streamable-http";
+        url: string;
+    }>;
+    capabilities: Record<string, unknown>;
+    tools: CardTool[];
+}
+export interface CardInput {
+    identity: ServerIdentity;
+    /** The served MCP endpoint URL. */
+    mcpUrl: string;
+    /** The base URL the icon is served under (ends in `/`). */
+    baseUrl: string;
+    capabilities: Record<string, unknown>;
+    tools: CardTool[];
+}
+export declare function buildServerCard(input: CardInput): ServerCard;
+/**
+ * The card as an HTTP response: the card media type when the client asks for it, JSON otherwise.
+ * `cacheable` is false when the origin was read from the
+ * request (no configured public base URL): a shared cache must not keep a card naming a Host
+ * header another client sent.
+ */
+export declare function serverCardResponse(req: Request, card: ServerCard, cacheable: boolean): Response;

package/dist/serverCard.js

@@ -0,0 +1,68 @@
+/**
+ * The public MCP Server Card (mcp-server-standard S-50, Manufact "mcp.json or MCP Server Card
+ * served"). Served by src/httpApp.ts, before every gate, at each path in `SERVER_CARD_PATHS`.
+ *
+ * Shape: the `ServerCard` of the MCP Server Card extension (SEP-2127,
+ * modelcontextprotocol/experimental-ext-server-card `schema.json` at commit
+ * 526201bbc80231daa40ffcdecfc9da4e54e5dc93, sha256
+ * 2c772b51edb367f154771d84ddbae87ddba00a624422c8e46f218a9ac03bf042), vendored at
+ * tests/fixtures/server-card.schema.json and validated in tests/serverMetadata.test.ts.
+ *
+ * Declared divergence: the extension says a card does not enumerate primitives, while Manufact's
+ * check and mcp-doctor S-50 read `capabilities` and a tool summary (`tools`) on the card. The
+ * schema allows additional members, so the card carries both: the capabilities of
+ * mcp-server.json (the same object `initialize` serves) and each served tool's name, title and
+ * description, read from the tools as registered — never a second list to keep in step.
+ *
+ * The card is public metadata and grants nothing. Every string comes from src/serverIdentity.ts
+ * (the source of the serverInfo), and the URLs from the origin the server is reached at.
+ */
+import { cardDescription, cardName, serverIcons } from "./serverIdentity.js";
+export const SERVER_CARD_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export const SERVER_CARD_MEDIA_TYPE = "application/mcp-server-card+json";
+/**
+ * Where the card is served: `/mcp/server-card` is the location the extension reserves
+ * (`<streamable-http-url>/server-card`); the others are the origin-level paths Manufact and
+ * mcp-doctor S-50 probe. Manufact also reads `/.well-known/ai-catalog.json` and the parent
+ * domain; an AI Catalog lists cards rather than being one, so it is not served here.
+ */
+export const SERVER_CARD_PATHS = [
+    "/mcp/server-card",
+    "/.well-known/mcp/server-card.json",
+    "/.well-known/mcp-server-card",
+    "/mcp.json",
+    "/.well-known/mcp.json",
+];
+export function buildServerCard(input) {
+    const { identity } = input;
+    return {
+        $schema: SERVER_CARD_SCHEMA_URL,
+        name: cardName(identity.websiteUrl, identity.name),
+        version: identity.version,
+        description: cardDescription(identity.description.en),
+        title: identity.title,
+        websiteUrl: identity.websiteUrl,
+        icons: serverIcons(input.baseUrl),
+        remotes: [{ type: "streamable-http", url: input.mcpUrl }],
+        capabilities: input.capabilities,
+        tools: input.tools,
+    };
+}
+/**
+ * The card as an HTTP response: the card media type when the client asks for it, JSON otherwise.
+ * `cacheable` is false when the origin was read from the
+ * request (no configured public base URL): a shared cache must not keep a card naming a Host
+ * header another client sent.
+ */
+export function serverCardResponse(req, card, cacheable) {
+    const accept = req.headers.get("accept") ?? "";
+    const headers = new Headers({
+        "content-type": accept.includes(SERVER_CARD_MEDIA_TYPE)
+            ? SERVER_CARD_MEDIA_TYPE
+            : "application/json",
+        "cache-control": cacheable ? "public, max-age=3600" : "no-store",
+        "access-control-allow-origin": "*",
+        "x-content-type-options": "nosniff",
+    });
+    return new Response(JSON.stringify(card), { status: 200, headers });
+}

package/dist/serverIcon.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The server icon (MCP `Implementation.icons`, Manufact "Scalable or high-resolution icon"). A
+ * vector, so it is sharp at every size a host renders and needs no `sizes` beyond `"any"`.
+ *
+ * A fork replaces `SERVER_ICON_SVG` with its own mark. Keep it a self-contained SVG: no script,
+ * no external reference (the route serves it under a CSP that forbids both), because a host may
+ * render it in its own page.
+ *
+ * Served by src/httpApp.ts at `SERVER_ICON_PATH`, before any authentication, and inlined as a
+ * `data:` URI where there is no HTTP origin (stdio).
+ */
+/** Where the HTTP transport serves the icon, relative to the public base URL. */
+export declare const SERVER_ICON_PATH = "icon.svg";
+export declare const SERVER_ICON_MIME_TYPE = "image/svg+xml";
+export declare const SERVER_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 128 128\" role=\"img\" aria-label=\"MCP server\">\n<rect width=\"128\" height=\"128\" rx=\"28\" fill=\"#1f2a44\"/>\n<path d=\"M40 44 L88 44 M40 44 L64 88 M88 44 L64 88\" stroke=\"#8fb3ff\" stroke-width=\"8\" stroke-linecap=\"round\" fill=\"none\"/>\n<circle cx=\"40\" cy=\"44\" r=\"12\" fill=\"#ffffff\"/>\n<circle cx=\"88\" cy=\"44\" r=\"12\" fill=\"#ffffff\"/>\n<circle cx=\"64\" cy=\"88\" r=\"12\" fill=\"#ffffff\"/>\n</svg>\n";
+/** The icon as a `data:` URI, for a transport with no HTTP origin to serve it from. */
+export declare function serverIconDataUri(): string;

package/dist/serverIcon.js

@@ -0,0 +1,26 @@
+/**
+ * The server icon (MCP `Implementation.icons`, Manufact "Scalable or high-resolution icon"). A
+ * vector, so it is sharp at every size a host renders and needs no `sizes` beyond `"any"`.
+ *
+ * A fork replaces `SERVER_ICON_SVG` with its own mark. Keep it a self-contained SVG: no script,
+ * no external reference (the route serves it under a CSP that forbids both), because a host may
+ * render it in its own page.
+ *
+ * Served by src/httpApp.ts at `SERVER_ICON_PATH`, before any authentication, and inlined as a
+ * `data:` URI where there is no HTTP origin (stdio).
+ */
+/** Where the HTTP transport serves the icon, relative to the public base URL. */
+export const SERVER_ICON_PATH = "icon.svg";
+export const SERVER_ICON_MIME_TYPE = "image/svg+xml";
+export const SERVER_ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" role="img" aria-label="MCP server">
+<rect width="128" height="128" rx="28" fill="#1f2a44"/>
+<path d="M40 44 L88 44 M40 44 L64 88 M88 44 L64 88" stroke="#8fb3ff" stroke-width="8" stroke-linecap="round" fill="none"/>
+<circle cx="40" cy="44" r="12" fill="#ffffff"/>
+<circle cx="88" cy="44" r="12" fill="#ffffff"/>
+<circle cx="64" cy="88" r="12" fill="#ffffff"/>
+</svg>
+`;
+/** The icon as a `data:` URI, for a transport with no HTTP origin to serve it from. */
+export function serverIconDataUri() {
+    return `data:${SERVER_ICON_MIME_TYPE};base64,${Buffer.from(SERVER_ICON_SVG, "utf8").toString("base64")}`;
+}

package/dist/serverIdentity.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The server's public identity: the ONE source of every string a host reads about this server
+ * before or at connection — the `serverInfo` of `initialize` / `server/discover`
+ * (src/mcpServerFactory.ts), its `instructions`, the MCP Server Card (src/serverCard.ts) and the
+ * setup page at the MCP URL (src/landingPage.ts). No copy can drift from another.
+ *
+ * Every value is DERIVED, never a literal a fork must remember to edit:
+ *
+ * | Item           | Environment override          | Otherwise, package.json |
+ * |----------------|-------------------------------|-------------------------|
+ * | title          | `MCP_SERVER_TITLE`            | `displayName`           |
+ * | description EN | `MCP_SERVER_DESCRIPTION`      | `description`           |
+ * | description FR | `MCP_SERVER_DESCRIPTION_FR`   | `description_fr`        |
+ * | website        | `MCP_SERVER_WEBSITE_URL`      | `homepage`              |
+ *
+ * `name` and `version` keep their own sources (src/version.ts). The template's package.json
+ * carries the template's values; a fork edits package.json (or sets the variables) and every
+ * surface follows. A value neither source carries is refused at start, naming the variable AND
+ * the package.json field, in English and French: a served placeholder is what Manufact and
+ * mcp-doctor S-49 score as missing, so the server never invents one.
+ */
+import type { Icon, Implementation } from "@modelcontextprotocol/server";
+import { type McpLocale } from "./i18n.js";
+/** The package.json fields the identity reads. */
+export interface PackageIdentityFields {
+    displayName?: unknown;
+    description?: unknown;
+    description_fr?: unknown;
+    homepage?: unknown;
+}
+export interface ServerIdentity {
+    name: string;
+    version: string;
+    title: string;
+    description: Record<McpLocale, string>;
+    websiteUrl: string;
+}
+/** The environment variables, by identity item (documented in README and .env.example). */
+export declare const IDENTITY_ENV: {
+    readonly title: "MCP_SERVER_TITLE";
+    readonly description: "MCP_SERVER_DESCRIPTION";
+    readonly descriptionFr: "MCP_SERVER_DESCRIPTION_FR";
+    readonly websiteUrl: "MCP_SERVER_WEBSITE_URL";
+};
+/** Resolves the identity from `env` and the package.json fields. Throws, naming what is missing. */
+export declare function resolveServerIdentity(env: NodeJS.ProcessEnv, pkg: PackageIdentityFields): ServerIdentity;
+/**
+ * The identity of THIS process: the package fields embedded at build (src/embedded.generated.ts, from
+ * package.json; no file read, so a bundled server has them too) and process.env. Once.
+ */
+export declare function getServerIdentity(): ServerIdentity;
+/**
+ * The icons a host reads. With an HTTP base URL (the origin the server is reached at, ending in
+ * `/`), the icon is the URL src/httpApp.ts serves; without one (stdio), it travels inline.
+ */
+export declare function serverIcons(baseUrl?: string): Icon[];
+/**
+ * The `serverInfo` (MCP `Implementation`) items beyond name and version, for a caller's locale.
+ * The factory writes `name` and `version` beside them from src/version.ts, where the
+ * version-observability check (D16) reads them.
+ */
+export declare function serverPresentation(identity: ServerIdentity, locale: McpLocale, baseUrl?: string): Omit<Implementation, "name" | "version">;
+/**
+ * The server instructions (`InitializeResult.instructions` / `DiscoverResult.instructions`): how
+ * an agent should use THIS server, critical guidance first, from the locale files
+ * (`Mcp.server.instructions`). A fork rewrites them there for its own tools;
+ * tests/serverMetadata.test.ts fails when a served tool goes unnamed or the text passes Claude
+ * Code's 2048-byte field budget.
+ */
+export declare function serverInstructions(locale: McpLocale): string;
+/**
+ * The card's reverse-DNS name, derived from the website: `io.github.<owner>/<name>` for a GitHub
+ * website (the MCP Registry convention), the reversed host otherwise (`www.` dropped).
+ */
+export declare function cardName(websiteUrl: string, serverName: string): string;
+/** The card schema's `description` cap. */
+export declare const CARD_DESCRIPTION_MAX = 100;
+/**
+ * The card description: the English description whole when it fits the schema's 100 characters;
+ * otherwise cut on the last word boundary that leaves room for an ellipsis. Declared divergence:
+ * the card then carries a shortened text, the serverInfo the full one.
+ */
+export declare function cardDescription(description: string): string;

package/dist/serverIdentity.js

@@ -0,0 +1,130 @@
+/**
+ * The server's public identity: the ONE source of every string a host reads about this server
+ * before or at connection — the `serverInfo` of `initialize` / `server/discover`
+ * (src/mcpServerFactory.ts), its `instructions`, the MCP Server Card (src/serverCard.ts) and the
+ * setup page at the MCP URL (src/landingPage.ts). No copy can drift from another.
+ *
+ * Every value is DERIVED, never a literal a fork must remember to edit:
+ *
+ * | Item           | Environment override          | Otherwise, package.json |
+ * |----------------|-------------------------------|-------------------------|
+ * | title          | `MCP_SERVER_TITLE`            | `displayName`           |
+ * | description EN | `MCP_SERVER_DESCRIPTION`      | `description`           |
+ * | description FR | `MCP_SERVER_DESCRIPTION_FR`   | `description_fr`        |
+ * | website        | `MCP_SERVER_WEBSITE_URL`      | `homepage`              |
+ *
+ * `name` and `version` keep their own sources (src/version.ts). The template's package.json
+ * carries the template's values; a fork edits package.json (or sets the variables) and every
+ * surface follows. A value neither source carries is refused at start, naming the variable AND
+ * the package.json field, in English and French: a served placeholder is what Manufact and
+ * mcp-doctor S-49 score as missing, so the server never invents one.
+ */
+import { isSecureUrl } from "./declaredVariables.js";
+import { EMBEDDED_PACKAGE_IDENTITY } from "./embedded.generated.js";
+import { t, tBoth } from "./i18n.js";
+import { SERVER_ICON_MIME_TYPE, SERVER_ICON_PATH, serverIconDataUri } from "./serverIcon.js";
+import { SERVER_NAME, SERVER_VERSION } from "./version.js";
+/** The environment variables, by identity item (documented in README and .env.example). */
+export const IDENTITY_ENV = {
+    title: "MCP_SERVER_TITLE",
+    description: "MCP_SERVER_DESCRIPTION",
+    descriptionFr: "MCP_SERVER_DESCRIPTION_FR",
+    websiteUrl: "MCP_SERVER_WEBSITE_URL",
+};
+function pick(env, pkg, item, variable, field) {
+    const fromEnv = env[variable];
+    if (fromEnv !== undefined && fromEnv.trim() !== "")
+        return { value: fromEnv, source: variable };
+    const fromPkg = pkg[field];
+    if (typeof fromPkg === "string" && fromPkg.trim() !== "")
+        return { value: fromPkg, source: `package.json ${field}` };
+    throw new Error(tBoth("server.identityMissing", { item, variable, field }));
+}
+/** Resolves the identity from `env` and the package.json fields. Throws, naming what is missing. */
+export function resolveServerIdentity(env, pkg) {
+    const title = pick(env, pkg, "title", IDENTITY_ENV.title, "displayName");
+    const en = pick(env, pkg, "description", IDENTITY_ENV.description, "description");
+    const fr = pick(env, pkg, "description_fr", IDENTITY_ENV.descriptionFr, "description_fr");
+    const site = pick(env, pkg, "websiteUrl", IDENTITY_ENV.websiteUrl, "homepage");
+    if (!isSecureUrl(site.value))
+        throw new Error(tBoth("server.identityInvalid", { item: "websiteUrl", source: site.source }));
+    return {
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+        title: title.value,
+        description: { en: en.value, fr: fr.value },
+        websiteUrl: site.value,
+    };
+}
+let processIdentity;
+/**
+ * The identity of THIS process: the package fields embedded at build (src/embedded.generated.ts, from
+ * package.json; no file read, so a bundled server has them too) and process.env. Once.
+ */
+export function getServerIdentity() {
+    processIdentity ??= resolveServerIdentity(process.env, EMBEDDED_PACKAGE_IDENTITY);
+    return processIdentity;
+}
+/**
+ * The icons a host reads. With an HTTP base URL (the origin the server is reached at, ending in
+ * `/`), the icon is the URL src/httpApp.ts serves; without one (stdio), it travels inline.
+ */
+export function serverIcons(baseUrl) {
+    const src = baseUrl ? new URL(SERVER_ICON_PATH, baseUrl).href : serverIconDataUri();
+    return [{ src, mimeType: SERVER_ICON_MIME_TYPE, sizes: ["any"] }];
+}
+/**
+ * The `serverInfo` (MCP `Implementation`) items beyond name and version, for a caller's locale.
+ * The factory writes `name` and `version` beside them from src/version.ts, where the
+ * version-observability check (D16) reads them.
+ */
+export function serverPresentation(identity, locale, baseUrl) {
+    return {
+        title: identity.title,
+        description: identity.description[locale],
+        websiteUrl: identity.websiteUrl,
+        icons: serverIcons(baseUrl),
+    };
+}
+/**
+ * The server instructions (`InitializeResult.instructions` / `DiscoverResult.instructions`): how
+ * an agent should use THIS server, critical guidance first, from the locale files
+ * (`Mcp.server.instructions`). A fork rewrites them there for its own tools;
+ * tests/serverMetadata.test.ts fails when a served tool goes unnamed or the text passes Claude
+ * Code's 2048-byte field budget.
+ */
+export function serverInstructions(locale) {
+    return t(locale, "server.instructions");
+}
+/** The Server Card `name` pattern (experimental-ext-server-card schema). */
+const CARD_NAME = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+/**
+ * The card's reverse-DNS name, derived from the website: `io.github.<owner>/<name>` for a GitHub
+ * website (the MCP Registry convention), the reversed host otherwise (`www.` dropped).
+ */
+export function cardName(websiteUrl, serverName) {
+    const url = new URL(websiteUrl);
+    const host = url.hostname.toLowerCase().replace(/^www\./, "");
+    const owner = url.pathname.split("/").filter(Boolean)[0];
+    const namespace = host === "github.com" && owner
+        ? `io.github.${owner.toLowerCase()}`
+        : host.split(".").reverse().join(".");
+    const name = `${namespace}/${serverName}`;
+    if (!CARD_NAME.test(name))
+        throw new Error(`server card name ${JSON.stringify(name)} does not match ${CARD_NAME}`);
+    return name;
+}
+/** The card schema's `description` cap. */
+export const CARD_DESCRIPTION_MAX = 100;
+/**
+ * The card description: the English description whole when it fits the schema's 100 characters;
+ * otherwise cut on the last word boundary that leaves room for an ellipsis. Declared divergence:
+ * the card then carries a shortened text, the serverInfo the full one.
+ */
+export function cardDescription(description) {
+    if (description.length <= CARD_DESCRIPTION_MAX)
+        return description;
+    const room = description.slice(0, CARD_DESCRIPTION_MAX - 1);
+    const cut = room.lastIndexOf(" ");
+    return `${(cut > 0 ? room.slice(0, cut) : room).trimEnd()}…`;
+}

package/dist/serverManifest.d.ts

@@ -26,8 +26,16 @@ export interface ServerManifest {
     features: Record<string, boolean>;
     /** The per-server context ceiling. A number cannot ride in `features` (booleans only). */
     contextCeiling: ContextCeiling;
+    /**
+     * The hosts the server is distributed on (mcp-server-standard S-45 / S-46), read from `distribution.targets`.
+     * Absent in the manifest: no target, `[]`. The ids are not validated here: the closed set is the standard's,
+     * checked by mcp-doctor; a fork adds a host by data, never by code.
+     */
+    distribution: {
+        targets: readonly string[];
+    };
 }
-type Expectation = "string" | "semver" | "object" | "boolean" | "positiveInteger" | "atLeastPerTool";
+type Expectation = "string" | "semver" | "object" | "boolean" | "positiveInteger" | "atLeastPerTool" | "stringArray";
 /** 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

@@ -35,7 +35,7 @@ function isPositiveInteger(value) {
 export function parseServerManifest(document, source) {
     if (!isRecord(document))
         throw new ServerManifestError("(document)", source, "object");
-    const { name, version, capabilities, transport, features, contextCeiling } = document;
+    const { name, version, capabilities, transport, features, contextCeiling, distribution } = document;
     if (typeof name !== "string" || name.length === 0) {
         throw new ServerManifestError("name", source, "string");
     }
@@ -65,6 +65,14 @@ export function parseServerManifest(document, source) {
     if (global < perTool) {
         throw new ServerManifestError("contextCeiling.global", source, "atLeastPerTool");
     }
+    let targets = [];
+    if (distribution !== undefined) {
+        const raw = isRecord(distribution) ? distribution.targets : undefined;
+        if (!Array.isArray(raw) || raw.some((t) => typeof t !== "string" || t.length === 0)) {
+            throw new ServerManifestError("distribution.targets", source, "stringArray");
+        }
+        targets = raw;
+    }
     return {
         name,
         version,
@@ -72,6 +80,7 @@ export function parseServerManifest(document, source) {
         transport,
         features: features,
         contextCeiling: { global, perTool },
+        distribution: { targets },
     };
 }
 /**

package/dist/signedCursor.js

@@ -56,7 +56,11 @@ export function createCursorSigner(options = {}) {
     }
     // 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 tagOf = (payloadPart) => 
+    // allow-local-identity: HMAC proving a pagination cursor was issued by this server; it identifies no caller or tenant
+    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.
@@ -89,6 +93,7 @@ export function createCursorSigner(options = {}) {
         // the tag matches. Equal lengths (32 bytes each, checked above): timingSafeEqual cannot throw.
         if (!BASE64URL.test(payloadPart))
             throw new InvalidCursorError("not_base64url");
+        // allow-local-identity: constant-time check of the cursor's own HMAC tag; no credential a caller presented
         if (!timingSafeEqual(tagOf(payloadPart), tag))
             throw new InvalidCursorError("tag_mismatch");
         // Signed by us, so canonical; re-checked so a decode is never lenient.