@vantageos/mcp-boilerplate 0.7.0 → 0.9.0

package/dist/mcpServerFactory.js

@@ -31,13 +31,14 @@
 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, WHOAMI_ANNOTATIONS } from "./toolRecord.js";
@@ -120,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" },
@@ -302,5 +311,17 @@ export function createBoilerplateMcpServer(deps = {}) {
     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/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/ui/uiResource.d.ts

@@ -21,6 +21,12 @@ export declare function buildItemsUiResourceMeta(domain?: string): McpUiResource
  * 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.
  */
+/**
+ * What the widget shows, for the host and the model, in both languages ("EN / FR"). Hosts read it
+ * under two keys: `_meta.ui.widgetDescription` and the ChatGPT hint `_meta["openai/widgetDescription"]`
+ * (Manufact's tool-resource-metadata-complete reads exactly these); the same text under both.
+ */
+export declare const WIDGET_DESCRIPTION: string;
 export declare function buildUiResource(props: {
     domain?: string;
 }): {
@@ -28,7 +34,14 @@ export declare function buildUiResource(props: {
     mimeType: string;
     text: string;
     _meta: {
-        ui: McpUiResourceMeta;
+        ui: {
+            widgetDescription: string;
+            csp?: import("@modelcontextprotocol/ext-apps").McpUiResourceCsp;
+            permissions?: import("@modelcontextprotocol/ext-apps").McpUiResourcePermissions;
+            domain?: string;
+            prefersBorder?: boolean;
+        };
+        "openai/widgetDescription": string;
     };
 };
 /**

package/dist/ui/uiResource.js

@@ -13,6 +13,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { RESOURCE_MIME_TYPE } from "@modelcontextprotocol/ext-apps/server";
+import { tBoth } from "../i18n.js";
 export const ITEMS_UI_RESOURCE_URI = "ui://mcp-boilerplate/items-widget.html";
 // dist/ui-bundle/ — NEVER dist/ui/ (that path is tsc's compiled-server
 // output for this very module; see vite.config.ts for the collision this
@@ -69,12 +70,21 @@ export function buildItemsUiResourceMeta(domain) {
  * 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.
  */
+/**
+ * What the widget shows, for the host and the model, in both languages ("EN / FR"). Hosts read it
+ * under two keys: `_meta.ui.widgetDescription` and the ChatGPT hint `_meta["openai/widgetDescription"]`
+ * (Manufact's tool-resource-metadata-complete reads exactly these); the same text under both.
+ */
+export const WIDGET_DESCRIPTION = tBoth("widget.description");
 export function buildUiResource(props) {
     return {
         uri: ITEMS_UI_RESOURCE_URI,
         mimeType: RESOURCE_MIME_TYPE,
         text: readUiBundle(),
-        _meta: { ui: buildItemsUiResourceMeta(props.domain) },
+        _meta: {
+            ui: { ...buildItemsUiResourceMeta(props.domain), widgetDescription: WIDGET_DESCRIPTION },
+            "openai/widgetDescription": WIDGET_DESCRIPTION,
+        },
     };
 }
 /**

package/dist/version.js

@@ -1,8 +1,9 @@
 /**
- * The advertised server version is DERIVED from package.json (never a literal).
- * `src/version.ts` and `dist/version.js` both sit one level under the package root,
- * so the same relative URL resolves in source mode (vitest) and in the built output.
+ * The advertised server version is DERIVED from package.json (never a literal): scripts/embed-static.mjs writes
+ * it into src/embedded.generated.ts at build, and `--check` (tests/embedded-static.test.ts) refuses a stale copy.
+ * It is a module value, not a file read at import: a bundled consumer carries no package.json beside this module
+ * (task k17aj33ks3ndyxgt7jch68rpwx8hz9x5).
  */
-import { readFileSync } from "node:fs";
+import { EMBEDDED_PACKAGE_VERSION } from "./embedded.generated.js";
 export const SERVER_NAME = "mcp-boilerplate";
-export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const SERVER_VERSION = EMBEDDED_PACKAGE_VERSION;