@vantageos/mcp-boilerplate 0.7.0 → 0.9.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/lake/convex.d.ts

@@ -29,6 +29,10 @@
  *     rows whose key field is strictly after `after`, ascending by that key. The adapter asks for
  *     ONE row more than the page: its presence tells a truncated page from an exhausted one.
  *     `tenantId` is present only on a scoped read; the function applies it in its index range.
+ *     `filter` (a flat record, see `LakeFilterValue`: a scalar means equality, a list means
+ *     membership, `{ gte?, lte? }` means inclusive bounds, keys ANDed) is present only when the request carries a non-empty one; the function
+ *     applies it in the same range read, never over the rows it returns (a store-side filter keeps
+ *     pages full and cursors true). Absent, the arguments are exactly those without it.
  *   - get `{ key: string, tenantId?: string }` -> the row with that key, or null.
  *   With `tokenArg`, every call also carries the read token under that argument name, for a
  *   function that checks a shared read key. Without it, the token goes through `setAuth`

package/dist/lake/convex.js

@@ -29,6 +29,10 @@
  *     rows whose key field is strictly after `after`, ascending by that key. The adapter asks for
  *     ONE row more than the page: its presence tells a truncated page from an exhausted one.
  *     `tenantId` is present only on a scoped read; the function applies it in its index range.
+ *     `filter` (a flat record, see `LakeFilterValue`: a scalar means equality, a list means
+ *     membership, `{ gte?, lte? }` means inclusive bounds, keys ANDed) is present only when the request carries a non-empty one; the function
+ *     applies it in the same range read, never over the rows it returns (a store-side filter keeps
+ *     pages full and cursors true). Absent, the arguments are exactly those without it.
  *   - get `{ key: string, tenantId?: string }` -> the row with that key, or null.
  *   With `tokenArg`, every call also carries the read token under that argument name, for a
  *   function that checks a shared read key. Without it, the token goes through `setAuth`
@@ -50,7 +54,7 @@ import { ConvexHttpClient } from "convex/browser";
 import { makeFunctionReference } from "convex/server";
 import { defineVariables, isSecureUrl, loadVariables } from "../declaredVariables.js";
 import { boundedFetch, configuredUpstreamTimeoutMs } from "../upstream/timeout.js";
-import { LakeReadError, assertOrderedKeys } from "./reader.js";
+import { LakeReadError, assertLakeFilter, assertOrderedKeys, hasLakeFilter, } from "./reader.js";
 const ARGUMENT_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function configurationError(message) {
     return new Error(`convex lake reader: ${message}`);
@@ -84,7 +88,7 @@ function checkOptions(options) {
         }
         if (options.token === undefined)
             throw configurationError("tokenArg is named but no token");
-        if (["after", "limit", "tenantId", "key"].includes(options.tokenArg)) {
+        if (["after", "limit", "tenantId", "key", "filter"].includes(options.tokenArg)) {
             throw configurationError("tokenArg collides with an argument the adapter sends");
         }
     }
@@ -169,12 +173,15 @@ export function createConvexLakeReader(options) {
             }
             return key;
         },
-        async listPage({ after, limit, scope }) {
+        async listPage({ after, limit, scope, filter }) {
+            if (filter !== undefined)
+                assertLakeFilter(filter);
             const asked = limit + 1;
             const raw = await call("page", {
                 ...(after === undefined ? {} : { after }),
                 limit: asked,
                 ...scoped(scope),
+                ...(hasLakeFilter(filter) ? { filter } : {}),
             });
             if (!Array.isArray(raw)) {
                 throw new LakeReadError("malformed_page", `${functions.page} did not return a list`);

package/dist/lake/reader.d.ts

@@ -13,6 +13,12 @@
  *   - `scope` (the caller's resolved tenant) is applied INSIDE the range read — a compound
  *     (tenant, key) index — never as a filter after the limit, which would shorten a page and make
  *     its cursor lie;
+ *   - `filter` (optional, a flat record of `LakeFilterValue`) is applied by the adapter INSIDE the
+ *     range read, exactly like `scope`: a scalar matches by equality, a list by membership (an IN
+ *     list), a `{ gte?, lte? }` object by inclusive bounds (number or string, same type as the
+ *     row value, a row of the other type never matches), several keys are ANDed, a key absent from a row never matches. It is never applied to
+ *     rows after a page was read (that shortens pages and makes cursors lie). `checkLakePage`
+ *     cannot verify that a store honoured it: a declared limit, held by each adapter's own tests;
  *   - `get(key, scope)` returns the row with that key, or undefined.
  *
  * What a derived server adds: its own filters (a status, a date window, a person's portfolio) as
@@ -33,12 +39,28 @@ import { type TenantOwned } from "../tenancy.js";
 export interface LakeScope {
     readonly tenantId: string;
 }
+/**
+ * Inclusive bounds on one field: at least one of `gte` / `lte`, both of the same primitive type
+ * when both are present. Numbers compare as numbers (the row value must be a finite number),
+ * strings lexicographically (ISO dates compare correctly; the row value must be a string).
+ */
+export interface LakeRange {
+    readonly gte?: string | number;
+    readonly lte?: string | number;
+}
+/**
+ * One filter value, three forms: a scalar (equality), a non-empty list of strings/numbers
+ * (membership), or a `LakeRange` object (bounds).
+ */
+export type LakeFilterValue = string | number | boolean | null | readonly (string | number)[] | LakeRange;
 export interface LakePageRequest {
     /** The last key already served; omitted for the first page. */
     readonly after?: string;
     /** At most this many rows. A positive integer, already bounded by the tool. */
     readonly limit: number;
     readonly scope?: LakeScope;
+    /** Applied inside the range read by the adapter, like `scope`. See `assertLakeFilter`. */
+    readonly filter?: Readonly<Record<string, LakeFilterValue>>;
 }
 export interface LakePage<Row> {
     readonly rows: readonly Row[];
@@ -57,17 +79,28 @@ export interface LakeReader<Row> {
  *  - `malformed_page`: the page breaks the contract (not a list, more rows than asked, keys out of
  *    order or not after the cursor, a truncated page with no row);
  *  - `malformed_row`: a row has no readable key, or the derived server's row parser refused it;
+ *  - `malformed_filter`: the request's filter is not a flat record of allowed values (the message
+ *    names the offending key, never its value);
  *  - `out_of_scope`: a row of another tenant came back from a scoped read;
  *  - `read_failed`: the store call itself failed (its message is not forwarded: it may carry a
  *    URL or a credential).
  */
-export type LakeReadErrorCode = "malformed_page" | "malformed_row" | "out_of_scope" | "read_failed";
+export type LakeReadErrorCode = "malformed_page" | "malformed_row" | "malformed_filter" | "out_of_scope" | "read_failed";
 /** The stable machine code of a tool result refused because the lake answer was unreadable. */
 export declare const LAKE_UNREADABLE_CODE = "lake_unreadable";
 export declare class LakeReadError extends Error {
     readonly code: LakeReadErrorCode;
     constructor(code: LakeReadErrorCode, message: string);
 }
+/**
+ * Refuses a filter that is not a flat record: keys `[A-Za-z_][A-Za-z0-9_]*`, at most 32; values a
+ * string, a finite number, a boolean, null, or a non-empty list (at most 100) of strings/numbers;
+ * no nested object, no undefined. A refusal is `malformed_filter`; its message names the key,
+ * never the value. Both adapters call it before reading.
+ */
+export declare function assertLakeFilter(filter: unknown): asserts filter is NonNullable<LakePageRequest["filter"]>;
+/** True when `request.filter` carries at least one key (an empty filter is no filter). */
+export declare function hasLakeFilter(filter: LakePageRequest["filter"]): filter is NonNullable<LakePageRequest["filter"]>;
 /**
  * Checks that `keys` are strictly ascending and all strictly after `after`. Shared by
  * `checkLakePage` and by adapters that read a raw answer.
@@ -78,7 +111,7 @@ export declare function checkLakePage<Row>(reader: Pick<LakeReader<Row>, "keyOf"
 /**
  * An in-memory reader over rows SORTED strictly ascending by `id` (refused otherwise, at
  * creation: the range read relies on the order). The scope keeps the rows stamped with the
- * caller's organisation (tenancy.ts `scopeRowsForTenant`) BEFORE the range, so a page is never
+ * caller's organisation (tenancy.ts `scopeRowsForTenant`) and the `filter` keep the matching rows BEFORE the range, so a page is never
  * shortened afterwards. A store-backed reader reads the same range from a (tenant, key) index.
  */
 export declare function createInMemoryLakeReader<Row extends {

package/dist/lake/reader.js

@@ -13,6 +13,12 @@
  *   - `scope` (the caller's resolved tenant) is applied INSIDE the range read — a compound
  *     (tenant, key) index — never as a filter after the limit, which would shorten a page and make
  *     its cursor lie;
+ *   - `filter` (optional, a flat record of `LakeFilterValue`) is applied by the adapter INSIDE the
+ *     range read, exactly like `scope`: a scalar matches by equality, a list by membership (an IN
+ *     list), a `{ gte?, lte? }` object by inclusive bounds (number or string, same type as the
+ *     row value, a row of the other type never matches), several keys are ANDed, a key absent from a row never matches. It is never applied to
+ *     rows after a page was read (that shortens pages and makes cursors lie). `checkLakePage`
+ *     cannot verify that a store honoured it: a declared limit, held by each adapter's own tests;
  *   - `get(key, scope)` returns the row with that key, or undefined.
  *
  * What a derived server adds: its own filters (a status, a date window, a person's portfolio) as
@@ -39,6 +45,93 @@ export class LakeReadError extends Error {
         this.code = code;
     }
 }
+const FILTER_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const FILTER_MAX_KEYS = 32;
+const FILTER_MAX_LIST = 100;
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isBound = (value) => typeof value === "string" || (typeof value === "number" && Number.isFinite(value));
+/** A well-formed `LakeRange`: only gte/lte, at least one, same type, gte <= lte. */
+function isLakeRange(candidate) {
+    const value = candidate;
+    const keys = Object.keys(value);
+    if (keys.length === 0 || !keys.every((k) => k === "gte" || k === "lte"))
+        return false;
+    const { gte, lte } = value;
+    if (keys.includes("gte") && !isBound(gte))
+        return false;
+    if (keys.includes("lte") && !isBound(lte))
+        return false;
+    if (gte !== undefined && lte !== undefined) {
+        if (typeof gte !== typeof lte)
+            return false;
+        if (gte > lte)
+            return false;
+    }
+    return true;
+}
+/** True when the row value satisfies the bounds (same type as the bound, else never). */
+function inRange(actual, range) {
+    for (const [bound, ok] of [
+        [range.gte, (a, b) => a >= b],
+        [range.lte, (a, b) => a <= b],
+    ]) {
+        if (bound === undefined)
+            continue;
+        if (typeof bound === "number"
+            ? typeof actual !== "number" || !Number.isFinite(actual)
+            : typeof actual !== "string") {
+            return false;
+        }
+        if (!ok(actual, bound))
+            return false;
+    }
+    return true;
+}
+const isFilterScalar = (value) => value === null ||
+    typeof value === "boolean" ||
+    typeof value === "string" ||
+    (typeof value === "number" && Number.isFinite(value));
+/**
+ * Refuses a filter that is not a flat record: keys `[A-Za-z_][A-Za-z0-9_]*`, at most 32; values a
+ * string, a finite number, a boolean, null, or a non-empty list (at most 100) of strings/numbers;
+ * no nested object, no undefined. A refusal is `malformed_filter`; its message names the key,
+ * never the value. Both adapters call it before reading.
+ */
+export function assertLakeFilter(filter) {
+    if (typeof filter !== "object" || filter === null || Array.isArray(filter)) {
+        throw new LakeReadError("malformed_filter", "the filter is not a record");
+    }
+    const keys = Object.keys(filter);
+    if (keys.length > FILTER_MAX_KEYS) {
+        throw new LakeReadError("malformed_filter", `the filter holds more than ${FILTER_MAX_KEYS} keys`);
+    }
+    for (const key of keys) {
+        if (!FILTER_KEY.test(key)) {
+            throw new LakeReadError("malformed_filter", `a filter key is not a plain name (${JSON.stringify(key)})`);
+        }
+        const value = filter[key];
+        if (Array.isArray(value)) {
+            const listOk = value.length > 0 &&
+                value.length <= FILTER_MAX_LIST &&
+                value.every((v) => typeof v === "string" || (typeof v === "number" && Number.isFinite(v)));
+            if (!listOk) {
+                throw new LakeReadError("malformed_filter", `filter "${key}" must be a list of 1 to ${FILTER_MAX_LIST} strings or numbers`);
+            }
+        }
+        else if (isPlainObject(value)) {
+            if (!isLakeRange(value)) {
+                throw new LakeReadError("malformed_filter", `filter "${key}" must be bounds { gte?, lte? }: at least one, the same type, gte not above lte`);
+            }
+        }
+        else if (!isFilterScalar(value)) {
+            throw new LakeReadError("malformed_filter", `filter "${key}" must be a string, number, boolean, null, a list of strings or numbers, or bounds { gte?, lte? }`);
+        }
+    }
+}
+/** True when `request.filter` carries at least one key (an empty filter is no filter). */
+export function hasLakeFilter(filter) {
+    return filter !== undefined && Object.keys(filter).length > 0;
+}
 /** The row's key, or a `malformed_row` refusal when it is not a non-empty string. */
 function readKey(keyOf, row) {
     let key;
@@ -92,7 +185,7 @@ export function checkLakePage(reader, request, page) {
 /**
  * An in-memory reader over rows SORTED strictly ascending by `id` (refused otherwise, at
  * creation: the range read relies on the order). The scope keeps the rows stamped with the
- * caller's organisation (tenancy.ts `scopeRowsForTenant`) BEFORE the range, so a page is never
+ * caller's organisation (tenancy.ts `scopeRowsForTenant`) and the `filter` keep the matching rows BEFORE the range, so a page is never
  * shortened afterwards. A store-backed reader reads the same range from a (tenant, key) index.
  */
 export function createInMemoryLakeReader(sortedRows) {
@@ -104,11 +197,29 @@ export function createInMemoryLakeReader(sortedRows) {
         }
     }
     const scoped = (scope) => scope ? scopeRowsForTenant(scope.tenantId, sortedRows) : sortedRows;
+    // The filter is a predicate over the scoped rows, applied BEFORE the range and the limit.
+    const matching = (rows, filter) => {
+        if (!hasLakeFilter(filter))
+            return rows;
+        const entries = Object.entries(filter);
+        return rows.filter((row) => entries.every(([key, wanted]) => {
+            if (!Object.hasOwn(row, key))
+                return false;
+            const actual = row[key];
+            if (Array.isArray(wanted))
+                return wanted.includes(actual);
+            if (isPlainObject(wanted))
+                return inRange(actual, wanted);
+            return actual === wanted;
+        }));
+    };
     return Object.freeze({
         keyOf: (row) => row.id,
         async listPage(request) {
+            if (request.filter !== undefined)
+                assertLakeFilter(request.filter);
             // One row more than the page: its existence separates truncated from exhausted.
-            const window = rangeAfter(scoped(request.scope), request.after, request.limit + 1);
+            const window = rangeAfter(matching(scoped(request.scope), request.filter), request.after, request.limit + 1);
             return { rows: window.slice(0, request.limit), exhausted: window.length <= request.limit };
         },
         async get(key, scope) {

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"];