@vantageos/mcp-boilerplate 0.7.0 → 0.8.0

package/dist/httpApp.js

@@ -26,18 +26,28 @@ import { createMcpHandler } from "@modelcontextprotocol/server";
 import { unauthorizedChallenge } from "@vantageos/cloud-identity";
 import { Hono } from "hono";
 import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
-import { getBuildIdentity } from "./buildIdentity.js";
+import { getBuildCommit, getBuildIdentity } from "./buildIdentity.js";
 import { registerHostVerification } from "./hostVerification.js";
 import { detectLocale, t, tBoth } from "./i18n.js";
-import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+import { isBrowserLandingRequest, landingPageResponse } from "./landingPage.js";
+import { createBoilerplateMcpServer, registeredToolSummaries } from "./mcpServerFactory.js";
 import { createAuthorizationServer, } from "./oauth/authorizationServer.js";
 import { MCP_SCOPE } from "./oauth/settings.js";
+import { SERVER_CARD_PATHS, buildServerCard, serverCardResponse } from "./serverCard.js";
+import { SERVER_ICON_MIME_TYPE, SERVER_ICON_PATH, SERVER_ICON_SVG } from "./serverIcon.js";
+import { getServerIdentity } from "./serverIdentity.js";
 import { loadServerManifest } from "./serverManifest.js";
 import { resolveTenantFromJwtPayload } from "./tenancy.js";
 import { callerScopeOf } from "./toolRoleGate.js";
 import { ToolRolesConfigError, loadToolRoles } from "./toolRoles.js";
+import { servedMcpUrl } from "./ui/sandboxDomain.js";
 import { assertIdentityDeps, resolveVerifiedPerson, } from "./verifiedPerson.js";
 import { SERVER_VERSION } from "./version.js";
+function servedLocation(publicBaseUrl, requestUrl) {
+    const configured = publicBaseUrl ? servedMcpUrl({ PUBLIC_BASE_URL: publicBaseUrl }) : undefined;
+    const mcpUrl = configured ?? new URL("/mcp", requestUrl).href;
+    return { mcpUrl, baseUrl: new URL("./", mcpUrl).href, configured: configured !== undefined };
+}
 const PRM_PATHS = [
     "/.well-known/oauth-protected-resource",
     "/.well-known/oauth-protected-resource/mcp",
@@ -94,9 +104,45 @@ export function buildHttpApp(deps = {}) {
             return config;
         })()
         : { applicable: false };
-    // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25), so a
-    // deployment is proven from what the server returns, not from what the deploy printed.
-    app.get("/health", (c) => c.json({ status: "ok", version: SERVER_VERSION, buildId: getBuildIdentity() }));
+    // The public identity (S-49), read once at start: a value neither the environment nor
+    // package.json carries stops the server here, naming it, instead of serving a placeholder.
+    const identity = getServerIdentity();
+    // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25): buildId is
+    // the git commit the tree was built from, buildHash the hash of the files this process runs
+    // from, so a deployment is proven from what the server returns, not from what the deploy printed.
+    app.get("/health", (c) => c.json({
+        status: "ok",
+        version: SERVER_VERSION,
+        buildId: getBuildCommit(),
+        buildHash: getBuildIdentity(),
+    }));
+    // Discoverability (S-49 icon, S-50), public and registered BEFORE the auth gate below: a route
+    // that answers ends the chain, so none of them is ever gated. They read no credential and grant
+    // nothing. The setup page at /mcp sits after the Origin check (S-22 holds on every /mcp method).
+    //  - the serverInfo icon, as SVG, under a CSP that forbids script and external references;
+    app.get(`/${SERVER_ICON_PATH}`, (c) => c.body(SERVER_ICON_SVG, 200, {
+        "content-type": `${SERVER_ICON_MIME_TYPE}; charset=utf-8`,
+        "cache-control": "public, max-age=86400",
+        "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
+        "x-content-type-options": "nosniff",
+    }));
+    //  - the MCP Server Card at every path a scanner probes (src/serverCard.ts), its tool summary
+    //    read from the tools a server built by the factory registers (computed once, on first read);
+    let cardTools;
+    for (const path of SERVER_CARD_PATHS) {
+        app.get(path, (c) => {
+            cardTools ??= registeredToolSummaries(createBoilerplateMcpServer({ locale: "en" }));
+            const where = servedLocation(deps.publicBaseUrl, c.req.url);
+            const card = buildServerCard({
+                identity,
+                mcpUrl: where.mcpUrl,
+                baseUrl: where.baseUrl,
+                capabilities: manifest.capabilities,
+                tools: [...cardTools],
+            });
+            return serverCardResponse(c.req.raw, card, where.configured);
+        });
+    }
     // S-45: the verification path of every declared target host, served from configuration.
     registerHostVerification(app, manifest.distribution.targets);
     // S-22 Origin validation, on /mcp ONLY and registered BEFORE the auth gate: a request that carries
@@ -104,8 +150,9 @@ export function buildHttpApp(deps = {}) {
     // insensitive), else 403 before any token is looked at. No Origin header (server-to-server, Claude
     // Code, a connector backend) passes as before. `null`, an empty value and near-misses such as
     // `https://claude.ai.evil.example` are not in the list, so they are refused.
-    // Declared divergence: /health and the OAuth/discovery routes (/.well-known/*, /authorize, /token,
-    // /register) are NOT covered — they are browser navigations or CORS calls of the sign-in flow
+    // Declared divergence: /health, the icon, the server card paths (/mcp/server-card included, served
+    // above) and the OAuth/discovery routes (/.well-known/*, /authorize, /token, /register) are NOT
+    // covered — they are public metadata, browser navigations or CORS calls of the sign-in flow
     // (/register has its own MCP_REGISTER_CORS_ORIGINS allowlist) and S-22 guards the MCP endpoint.
     const allowedOrigins = new Set((deps.allowedOrigins ?? []).map((o) => o.toLowerCase()));
     app.use("/mcp", async (c, next) => {
@@ -118,6 +165,15 @@ export function buildHttpApp(deps = {}) {
             message_fr: t("fr", "auth.originNotAllowed"),
         }, 403);
     });
+    // S-50 setup page at the MCP URL, after the Origin check and BEFORE the auth gate: a request that
+    // cannot be an MCP request (a browser GET: no Authorization, no text/event-stream) gets the
+    // public page (src/landingPage.ts); every other request continues to the gate unchanged.
+    app.get("/mcp", async (c, next) => {
+        if (!isBrowserLandingRequest(c.req.raw))
+            return next();
+        const where = servedLocation(deps.publicBaseUrl, c.req.url);
+        return landingPageResponse(identity, where.mcpUrl, authMode, where.configured);
+    });
     if (authMode === "oauth") {
         // Resolves the resource-server configuration per request: the own-AS tier reads its
         // environment lazily, so a missing value is a 503 on the request, not a crash at boot.
@@ -211,6 +267,7 @@ export function buildHttpApp(deps = {}) {
             caller,
             locale,
             uiDomain: deps.uiDomain,
+            baseUrl: servedLocation(deps.publicBaseUrl, c.req.url).baseUrl,
             lake: deps.lake,
             cursorSigner: deps.cursorSigner,
             rateLimiter: deps.rateLimiter,

package/dist/i18n.js

@@ -18,23 +18,13 @@
  * (§Bilingual, l.234): "fr" selects the French resource, anything else
  * (including a missing header) defaults to English.
  */
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-// Loaded via fs + JSON.parse, not a JSON module import: Node's ESM loader
-// (the runtime the compiled dist/stdio.js and dist/http.js run under)
-// requires an explicit import attribute for a JSON module import, which the
-// project's current `tsconfig.json` `module` target does not emit. This
-// project's `resolveJsonModule` + a plain JSON import already work for
-// bundler-processed code (e.g. src/ui/Widget.tsx, inlined by Vite at build
-// time and never hitting Node's loader at all) but not for tsc's own Node
-// ESM output, so the two resources here are read as plain files instead.
-function loadLocaleResource(fileName) {
-    const path = fileURLToPath(new URL(`./locales/${fileName}`, import.meta.url));
-    return JSON.parse(readFileSync(path, "utf8"));
-}
+import { EMBEDDED_LOCALES } from "./embedded.generated.js";
+// The two resources are module values (src/embedded.generated.ts, generated from src/locales/{en,fr}.json by
+// scripts/embed-static.mjs at build), never a file read at import: a bundled consumer (the Convex bundler,
+// esbuild) carries this module and no `locales/` folder beside it (task k17aj33ks3ndyxgt7jch68rpwx8hz9x5).
 const RESOURCES = {
-    en: loadLocaleResource("en.json"),
-    fr: loadLocaleResource("fr.json"),
+    en: EMBEDDED_LOCALES.en,
+    fr: EMBEDDED_LOCALES.fr,
 };
 /**
  * Resolves the caller's locale from the `X-MCP-Locale` request header.

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

@@ -33,6 +33,7 @@ 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";
@@ -66,6 +67,11 @@ export interface McpServerDeps {
      * httpApp.ts). Defaults to "en"; the stdio transport (no HTTP headers) uses the default.
      */
     locale?: McpLocale;
+    /**
+     * 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;
     /**
@@ -92,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,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")}`;
+}