mcp-context-card 1.4.0 → 1.5.0

package/dist/conformance/discovery.js

@@ -0,0 +1,281 @@
+/**
+ * conformance/discovery — a portable checker for MCP Server Card discovery
+ * (SEP-2127, Final), the AI Catalog (spec 1.0), and the Streamable HTTP
+ * transport's security rules, run against any server URL.
+ *
+ * Self-contained on purpose: no imports from this package, only the global
+ * `fetch` (and `node:http` for the one check that must forge a Host header,
+ * which `fetch` drops), so the file can be lifted into another tool as-is.
+ * The transport checks send one JSON-RPC `ping`, which changes nothing. Point it at a
+ * server's Streamable HTTP endpoint and it returns one result per requirement,
+ * each tagged MUST or SHOULD exactly as the spec words it. Requirements the
+ * spec leaves at MAY (where the card lives, whether a catalog exists) are
+ * never failures: a missing optional document turns its checks into skips.
+ *
+ * JSON Schema validation is optional: pass `validateCard` (for example Ajv
+ * against the official v1 schema) and it runs as one more card check.
+ */
+export const SERVER_CARD_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export const SERVER_CARD_TYPE = "application/mcp-server-card+json";
+export const AI_CATALOG_TYPE = "application/ai-catalog+json";
+const NAME_RE = /^[a-zA-Z0-9.-]+\/[a-zA-Z0-9._-]+$/;
+const EXT_KEY_RE = /^(https?:\/\/\S+|[a-zA-Z0-9-]+(\.[a-zA-Z0-9-]+)+)$/;
+const URN_RE = /^urn:air:[^:]+\.[^:]+:[^:]+:[^:]+$/i;
+const SECRET_RE = /(api[_-]?key|secret|password|bearer\s|token["']?\s*:)/i;
+const PRIVATE_HOST_RE = /\b(localhost|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+)\b/i;
+/** POST through node:http, which (unlike fetch) sends a Host header as given. */
+async function rawStatus(url, headers, body, timeoutMs) {
+    try {
+        const u = new URL(url);
+        const mod = u.protocol === "https:" ? await import("node:https") : await import("node:http");
+        return await new Promise((resolve) => {
+            const req = mod.request(u, { method: "POST", headers: { ...headers, "Content-Length": String(Buffer.byteLength(body)) }, timeout: timeoutMs }, (res) => {
+                res.resume();
+                resolve(res.statusCode ?? null);
+            });
+            req.on("error", () => resolve(null));
+            req.on("timeout", () => {
+                req.destroy();
+                resolve(null);
+            });
+            req.end(body);
+        });
+    }
+    catch {
+        return null;
+    }
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isLoopback = (u) => ["localhost", "127.0.0.1", "[::1]", "::1"].includes(u.hostname);
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function checkDiscovery(target, opts = {}) {
+    const doFetch = opts.fetch ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? 10_000;
+    const results = [];
+    const add = (tier, level, id, title, status, detail) => results.push({ id, tier, level, title, status, ...(detail ? { detail } : {}) });
+    const check = (tier, level, id, title, ok, detail) => add(tier, level, id, title, ok ? "pass" : "fail", ok ? undefined : detail);
+    const get = async (url, headers = {}, method = "GET") => {
+        try {
+            const r = await doFetch(url, { method, headers, signal: AbortSignal.timeout(timeoutMs) });
+            return { status: r.status, headers: r.headers, text: method === "OPTIONS" ? "" : await r.text() };
+        }
+        catch {
+            return null;
+        }
+    };
+    const mcp = new URL(target.mcpUrl);
+    const catalogUrl = target.catalogUrl ?? new URL("/.well-known/ai-catalog.json", mcp).href;
+    // ── Catalog first: it may be where the card is found ──────────────────────
+    const catRes = await get(catalogUrl, { Accept: AI_CATALOG_TYPE });
+    const catalog = catRes && catRes.status === 200 ? parseJson(catRes.text) : undefined;
+    const entries = isObject(catalog) && Array.isArray(catalog.entries) ? catalog.entries : [];
+    const cardEntry = entries.find((e) => isObject(e) && e.type === SERVER_CARD_TYPE);
+    // ── Find the card: explicit → <mcp>/server-card → catalog entry ──────────
+    const candidates = [
+        target.cardUrl,
+        `${target.mcpUrl.replace(/\/+$/, "")}/server-card`,
+        cardEntry && typeof cardEntry.url === "string" ? new URL(cardEntry.url, catalogUrl).href : undefined,
+    ].filter((u) => !!u);
+    let cardUrl = null;
+    let cardRes = null;
+    for (const u of [...new Set(candidates)]) {
+        const r = await get(u, { Accept: SERVER_CARD_TYPE });
+        if (r && r.status === 200) {
+            cardUrl = u;
+            cardRes = r;
+            break;
+        }
+    }
+    const inlineCard = !cardRes && cardEntry && isObject(cardEntry.data) ? cardEntry.data : undefined;
+    // ── Tier: card ────────────────────────────────────────────────────────────
+    const card = cardRes ? parseJson(cardRes.text) : inlineCard;
+    if (card === undefined && !cardRes) {
+        add("card", "should", "card.found", "A Server Card is published (hosted or in the catalog)", "fail", `none at ${candidates.join(", ")}`);
+    }
+    else {
+        add("card", "should", "card.found", "A Server Card is published (hosted or in the catalog)", "pass");
+        check("card", "must", "card.json", "The card is a JSON object", isObject(card), "body is not a JSON object");
+        if (isObject(card)) {
+            check("card", "must", "card.schema-url", "$schema is the v1 Server Card schema URL", card.$schema === SERVER_CARD_SCHEMA_URL, `got ${JSON.stringify(card.$schema)}`);
+            check("card", "must", "card.name", "name is reverse-DNS with one slash", typeof card.name === "string" && NAME_RE.test(card.name) && card.name.length >= 3 && card.name.length <= 200, `got ${JSON.stringify(card.name)}`);
+            check("card", "must", "card.version", "version is present", typeof card.version === "string" && card.version.length > 0 && card.version.length <= 255, `got ${JSON.stringify(card.version)}`);
+            check("card", "must", "card.description", "description is 1–100 characters", typeof card.description === "string" && card.description.length >= 1 && card.description.length <= 100, typeof card.description === "string" ? `${card.description.length} characters` : "missing");
+            if (opts.validateCard) {
+                const err = opts.validateCard(card);
+                check("card", "must", "card.schema-valid", "The card validates against the v1 JSON Schema", err === null, err ?? "");
+            }
+            else {
+                add("card", "must", "card.schema-valid", "The card validates against the v1 JSON Schema", "skip", "no schema validator supplied");
+            }
+            const text = JSON.stringify(card);
+            const leak = SECRET_RE.exec(text) ?? PRIVATE_HOST_RE.exec(text);
+            check("card", "must", "card.no-secrets", "No credentials or private endpoints in the card", !leak || isLoopback(mcp), `found "${leak?.[0]}"`);
+            const remotes = Array.isArray(card.remotes) ? card.remotes : [];
+            if (remotes.length) {
+                const urls = remotes.filter(isObject).map((r) => r.url);
+                check("card", "should", "card.remote-matches", "The card's remotes include the endpoint it was found for", urls.includes(target.mcpUrl), `remotes: ${urls.join(", ")}`);
+            }
+            else {
+                add("card", "should", "card.remote-matches", "The card's remotes include the endpoint it was found for", "skip", "the card declares no remotes");
+            }
+        }
+    }
+    // ── Tier: hosting (only for a hosted card) ───────────────────────────────
+    const hostingTitles = [
+        ["should", "hosting.content-type", `Served as ${SERVER_CARD_TYPE}`],
+        ["must", "hosting.cors-origin", "CORS: Access-Control-Allow-Origin is *"],
+        ["must", "hosting.cors-expose", "CORS: ETag is exposed"],
+        ["must", "hosting.cors-preflight", "CORS preflight allows GET with Content-Type and If-None-Match"],
+        ["should", "hosting.cache-control", "Cache-Control is public with a max-age"],
+        ["should", "hosting.etag", "An ETag is returned and If-None-Match gets 304"],
+        ["must", "hosting.https", "Served over HTTPS (HTTP only for local development)"],
+    ];
+    if (!cardRes || !cardUrl) {
+        for (const [level, id, title] of hostingTitles)
+            add("hosting", level, id, title, "skip", "no hosted card");
+    }
+    else {
+        const h = cardRes.headers;
+        const ct = h.get("content-type") ?? "";
+        check("hosting", "should", "hosting.content-type", hostingTitles[0][2], ct.split(";")[0].trim().toLowerCase() === SERVER_CARD_TYPE, `got "${ct}"`);
+        const withOrigin = await get(cardUrl, { Origin: "https://conformance.example" });
+        const acao = withOrigin?.headers.get("access-control-allow-origin") ?? "";
+        check("hosting", "must", "hosting.cors-origin", hostingTitles[1][2], acao === "*", `got "${acao}"`);
+        const expose = withOrigin?.headers.get("access-control-expose-headers") ?? "";
+        check("hosting", "must", "hosting.cors-expose", hostingTitles[2][2], /(^|,)\s*etag\s*(,|$)/i.test(expose), `got "${expose}"`);
+        const pre = await get(cardUrl, {
+            Origin: "https://conformance.example",
+            "Access-Control-Request-Method": "GET",
+            "Access-Control-Request-Headers": "content-type, if-none-match",
+        }, "OPTIONS");
+        const methods = (pre?.headers.get("access-control-allow-methods") ?? "").toUpperCase();
+        const allowed = (pre?.headers.get("access-control-allow-headers") ?? "").toLowerCase();
+        check("hosting", "must", "hosting.cors-preflight", hostingTitles[3][2], /(^|,)\s*GET\s*(,|$)/.test(methods) && allowed.includes("content-type") && allowed.includes("if-none-match"), `methods "${methods}", headers "${allowed}"`);
+        const cc = (h.get("cache-control") ?? "").toLowerCase();
+        check("hosting", "should", "hosting.cache-control", hostingTitles[4][2], /\bpublic\b/.test(cc) && /\bmax-age=\d+/.test(cc), `got "${cc}"`);
+        const etag = h.get("etag");
+        const again = etag ? await get(cardUrl, { "If-None-Match": etag }) : null;
+        check("hosting", "should", "hosting.etag", hostingTitles[5][2], !!etag && again?.status === 304, etag ? `If-None-Match answered ${again?.status}` : "no ETag header");
+        const u = new URL(cardUrl);
+        if (u.protocol === "https:")
+            add("hosting", "must", "hosting.https", hostingTitles[6][2], "pass");
+        else if (isLoopback(u))
+            add("hosting", "must", "hosting.https", hostingTitles[6][2], "skip", "local development");
+        else
+            add("hosting", "must", "hosting.https", hostingTitles[6][2], "fail", `served from ${u.protocol}//${u.host}`);
+    }
+    // ── Tier: catalog (optional: absent → skipped) ───────────────────────────
+    const catTitles = [
+        ["should", "catalog.content-type", `Served as ${AI_CATALOG_TYPE}`],
+        ["must", "catalog.spec-version", "specVersion is present"],
+        ["must", "catalog.entries", "entries is an array"],
+        ["must", "catalog.host", "host.displayName is present when host is"],
+        ["must", "catalog.entry-fields", "Every entry has identifier and type"],
+        ["must", "catalog.entry-one-of", "Every entry has exactly one of url or data"],
+        ["should", "catalog.identifiers", "Identifiers use urn:air:{publisher-domain}:{namespace}:{name}"],
+        ["should", "catalog.extensions", "Custom data sits in extensions under URL or reverse-DNS keys"],
+        ["should", "catalog.card-entry", "The catalog lists the Server Card"],
+        ["should", "catalog.card-entry-lean", "The card entry repeats no displayName, description or version"],
+        ["should", "catalog.links", "Every entry URL resolves with the type its entry declares"],
+    ];
+    if (!catRes || catRes.status !== 200 || !isObject(catalog)) {
+        const why = !catRes ? "unreachable" : catRes.status !== 200 ? `HTTP ${catRes.status}` : "not a JSON object";
+        for (const [level, id, title] of catTitles)
+            add("catalog", level, id, title, "skip", `no catalog (${why})`);
+    }
+    else {
+        const t = (i) => catTitles[i];
+        const ct = catRes.headers.get("content-type") ?? "";
+        check("catalog", t(0)[0], t(0)[1], t(0)[2], ct.split(";")[0].trim().toLowerCase() === AI_CATALOG_TYPE, `got "${ct}"`);
+        check("catalog", t(1)[0], t(1)[1], t(1)[2], typeof catalog.specVersion === "string", "missing");
+        check("catalog", t(2)[0], t(2)[1], t(2)[2], Array.isArray(catalog.entries), "missing or not an array");
+        check("catalog", t(3)[0], t(3)[1], t(3)[2], catalog.host === undefined || (isObject(catalog.host) && typeof catalog.host.displayName === "string"), "host without displayName");
+        const objs = entries.filter(isObject);
+        const bad = (pred) => objs.filter((e) => !pred(e)).map((e) => String(e.identifier ?? "(no identifier)"));
+        const noFields = bad((e) => typeof e.identifier === "string" && typeof e.type === "string");
+        check("catalog", t(4)[0], t(4)[1], t(4)[2], noFields.length === 0 && objs.length === entries.length, noFields.join(", ") || "non-object entry");
+        const notOne = bad((e) => (e.url !== undefined) !== (e.data !== undefined));
+        check("catalog", t(5)[0], t(5)[1], t(5)[2], notOne.length === 0, notOne.join(", "));
+        const notUrn = bad((e) => typeof e.identifier === "string" && URN_RE.test(e.identifier));
+        check("catalog", t(6)[0], t(6)[1], t(6)[2], notUrn.length === 0, notUrn.join(", "));
+        const badExt = objs.flatMap((e) => isObject(e.extensions) ? Object.keys(e.extensions).filter((k) => !EXT_KEY_RE.test(k)) : []);
+        check("catalog", t(7)[0], t(7)[1], t(7)[2], badExt.length === 0, badExt.join(", "));
+        check("catalog", t(8)[0], t(8)[1], t(8)[2], !!cardEntry, `no entry of type ${SERVER_CARD_TYPE}`);
+        if (cardEntry) {
+            const repeated = ["displayName", "description", "version"].filter((k) => cardEntry[k] !== undefined);
+            check("catalog", t(9)[0], t(9)[1], t(9)[2], repeated.length === 0, repeated.join(", "));
+        }
+        else {
+            add("catalog", t(9)[0], t(9)[1], t(9)[2], "skip", "no card entry");
+        }
+        const linked = objs.filter((e) => typeof e.url === "string");
+        if (!linked.length) {
+            add("catalog", t(10)[0], t(10)[1], t(10)[2], "skip", "no entry has a url");
+        }
+        else {
+            const broken = [];
+            for (const e of linked) {
+                const u = new URL(e.url, catalogUrl).href;
+                const r = await get(u, { Accept: String(e.type) });
+                const rt = (r?.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+                if (!r || r.status !== 200)
+                    broken.push(`${u} → ${r ? `HTTP ${r.status}` : "unreachable"}`);
+                else if (rt !== String(e.type).toLowerCase())
+                    broken.push(`${u} → "${rt}"`);
+            }
+            check("catalog", t(10)[0], t(10)[1], t(10)[2], broken.length === 0, broken.join("; "));
+        }
+    }
+    // ── Tier: transport (Streamable HTTP, Security Warning) ─────────────────
+    const ping = JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" });
+    const rpcHeaders = { "Content-Type": "application/json", Accept: "application/json, text/event-stream" };
+    let foreign = null;
+    try {
+        foreign = await doFetch(target.mcpUrl, {
+            method: "POST",
+            headers: { ...rpcHeaders, Origin: "https://conformance-check.invalid" },
+            body: ping,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        await foreign.body?.cancel();
+    }
+    catch {
+        foreign = null;
+    }
+    if (!foreign) {
+        add("transport", "must", "transport.origin-403", "A foreign Origin is refused with 403", "skip", "MCP endpoint unreachable");
+    }
+    else {
+        check("transport", "must", "transport.origin-403", "A foreign Origin is refused with 403", foreign.status === 403, `answered ${foreign.status}`);
+    }
+    if (!isLoopback(mcp)) {
+        add("transport", "should", "transport.rebinding", "A local server refuses a foreign Host (DNS rebinding)", "skip", "not a local server");
+    }
+    else {
+        const status = await (opts.rawStatus ?? rawStatus)(target.mcpUrl, { ...rpcHeaders, Host: "rebind.invalid" }, ping, timeoutMs);
+        if (status === null) {
+            add("transport", "should", "transport.rebinding", "A local server refuses a foreign Host (DNS rebinding)", "skip", "MCP endpoint unreachable");
+        }
+        else {
+            check("transport", "should", "transport.rebinding", "A local server refuses a foreign Host (DNS rebinding)", status === 403, `Host: rebind.invalid answered ${status}`);
+        }
+    }
+    const count = (s) => results.filter((r) => r.status === s).length;
+    return {
+        mcpUrl: target.mcpUrl,
+        cardUrl,
+        catalogUrl,
+        results,
+        passed: count("pass"),
+        failed: count("fail"),
+        skipped: count("skip"),
+        mustFailures: results.filter((r) => r.status === "fail" && r.level === "must").length,
+    };
+}

package/dist/constants.d.ts

@@ -1,8 +1,37 @@
 /** Server identity constants, in their own module so any file can import
  *  them without pulling in the whole server. */
 export declare const NAME = "mcp-context-card";
-export declare const VERSION = "1.4.0";
+export declare const VERSION = "1.5.0";
 export declare const SERVER_CARD_URI = "mcp-context-card://server-card";
+/** The server's registry identity: reverse-DNS, the same as server.json `name`.
+ *  It is also `serverInfo.name`, so a Server Card never contradicts the live
+ *  connection (MCP Server Cards, SEP-2127: "Consistency with Runtime Behavior"). */
+export declare const REGISTRY_NAME = "io.github.Wolfe-Jam/mcp-context-card";
+/** Human-readable name: `serverInfo.title` and the Server Card `title`. */
+export declare const TITLE = "MCP Context Card";
+/** Same text as server.json `description` (1–100 chars, required on a Server Card). */
+export declare const DESCRIPTION = "MCP server for a project's context (AGENTS.md), memory, and identity \u2014 base or drop-in extension.";
+export declare const REPOSITORY_URL = "https://github.com/Wolfe-Jam/mcp-context-card";
+/** MCP Server Cards (SEP-2127, Final): schema v1 and media types. */
+export declare const SERVER_CARD_SCHEMA = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export declare const SERVER_CARD_MEDIA_TYPE = "application/mcp-server-card+json";
+export declare const AI_CATALOG_MEDIA_TYPE = "application/ai-catalog+json";
+/** Where a card is hosted: the spec's reserved `<streamable-http-url>/server-card`. */
+export declare const MCP_PATH = "/mcp";
+export declare const SERVER_CARD_PATH = "/mcp/server-card";
+/** The 1.x location, kept as an alias so existing links keep working. */
+export declare const LEGACY_SERVER_CARD_PATH = "/.well-known/mcp/server-card";
+/**
+ * Set to `1` to publish the memory file (`project.fafm`) over HTTP and list it
+ * in the AI Catalog. Off by default: memory is written during sessions, and
+ * discovery documents must not carry user- or session-specific data (SEP-2127).
+ */
+export declare const PUBLISH_MEMORY_ENV = "MCP_CONTEXT_CARD_PUBLISH_MEMORY";
+/** Extra Host names the HTTP server accepts (comma-separated), e.g. a reverse proxy's public name. */
+export declare const ALLOWED_HOSTS_ENV = "MCP_CONTEXT_CARD_ALLOWED_HOSTS";
+/** Browser origins allowed to call the HTTP server (comma-separated). */
+export declare const ALLOWED_ORIGINS_ENV = "MCP_CONTEXT_CARD_ALLOWED_ORIGINS";
+export declare const publishMemoryFromEnv: (env?: NodeJS.ProcessEnv) => boolean;
 /** MCP Apps (io.modelcontextprotocol/ui): the card as an inline UI resource.
  *  A host that supports MCP Apps fetches this resource and renders it in a
  *  sandboxed iframe next to the conversation. */

package/dist/constants.js

@@ -1,8 +1,37 @@
 /** Server identity constants, in their own module so any file can import
  *  them without pulling in the whole server. */
 export const NAME = "mcp-context-card";
-export const VERSION = "1.4.0";
+export const VERSION = "1.5.0";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";
+/** The server's registry identity: reverse-DNS, the same as server.json `name`.
+ *  It is also `serverInfo.name`, so a Server Card never contradicts the live
+ *  connection (MCP Server Cards, SEP-2127: "Consistency with Runtime Behavior"). */
+export const REGISTRY_NAME = "io.github.Wolfe-Jam/mcp-context-card";
+/** Human-readable name: `serverInfo.title` and the Server Card `title`. */
+export const TITLE = "MCP Context Card";
+/** Same text as server.json `description` (1–100 chars, required on a Server Card). */
+export const DESCRIPTION = "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.";
+export const REPOSITORY_URL = "https://github.com/Wolfe-Jam/mcp-context-card";
+/** MCP Server Cards (SEP-2127, Final): schema v1 and media types. */
+export const SERVER_CARD_SCHEMA = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export const SERVER_CARD_MEDIA_TYPE = "application/mcp-server-card+json";
+export const AI_CATALOG_MEDIA_TYPE = "application/ai-catalog+json";
+/** Where a card is hosted: the spec's reserved `<streamable-http-url>/server-card`. */
+export const MCP_PATH = "/mcp";
+export const SERVER_CARD_PATH = `${MCP_PATH}/server-card`;
+/** The 1.x location, kept as an alias so existing links keep working. */
+export const LEGACY_SERVER_CARD_PATH = "/.well-known/mcp/server-card";
+/**
+ * Set to `1` to publish the memory file (`project.fafm`) over HTTP and list it
+ * in the AI Catalog. Off by default: memory is written during sessions, and
+ * discovery documents must not carry user- or session-specific data (SEP-2127).
+ */
+export const PUBLISH_MEMORY_ENV = "MCP_CONTEXT_CARD_PUBLISH_MEMORY";
+/** Extra Host names the HTTP server accepts (comma-separated), e.g. a reverse proxy's public name. */
+export const ALLOWED_HOSTS_ENV = "MCP_CONTEXT_CARD_ALLOWED_HOSTS";
+/** Browser origins allowed to call the HTTP server (comma-separated). */
+export const ALLOWED_ORIGINS_ENV = "MCP_CONTEXT_CARD_ALLOWED_ORIGINS";
+export const publishMemoryFromEnv = (env = process.env) => env[PUBLISH_MEMORY_ENV] === "1";
 /** MCP Apps (io.modelcontextprotocol/ui): the card as an inline UI resource.
  *  A host that supports MCP Apps fetches this resource and renders it in a
  *  sandboxed iframe next to the conversation. */

package/dist/identity.d.ts

@@ -13,6 +13,19 @@ export declare function identity(root: string): AgentIdentity | null;
  * `.fafa`). null only when neither exists.
  */
 export declare function resolveIdentity(root: string): AgentIdentity | null;
+/**
+ * Who publishes this project's catalog entries: the domain and short name from
+ * the project's own `.fafa`. `faf card init` writes them into `agent.id` as
+ * `urn:air:{domain}:agent:{short name}` (short name also in `agent.name`).
+ * No `.fafa` domain → `domain` is undefined; callers then fall back to the HTTP
+ * host or a plain identifier. A domain is never invented here: each project
+ * publishes under its own (AI Catalog: "the domain name of the organization
+ * publishing the artifact").
+ */
+export declare function catalogPublisher(root: string): {
+    domain?: string;
+    handle: string;
+};
 /** Human-readable one-liner for the `whoami` tool. */
 export declare function whoami(root: string): string;
 /**

package/dist/identity.js

@@ -55,6 +55,22 @@ function fromPackageJson(root) {
 export function resolveIdentity(root) {
     return identity(root) ?? fromPackageJson(root);
 }
+/**
+ * Who publishes this project's catalog entries: the domain and short name from
+ * the project's own `.fafa`. `faf card init` writes them into `agent.id` as
+ * `urn:air:{domain}:agent:{short name}` (short name also in `agent.name`).
+ * No `.fafa` domain → `domain` is undefined; callers then fall back to the HTTP
+ * host or a plain identifier. A domain is never invented here: each project
+ * publishes under its own (AI Catalog: "the domain name of the organization
+ * publishing the artifact").
+ */
+export function catalogPublisher(root) {
+    const id = identity(root);
+    const m = /^urn:air:([^:]+):/i.exec(id?.id ?? "");
+    const domain = m && m[1].includes(".") ? m[1].toLowerCase() : undefined;
+    const handle = (id?.name ?? "").trim() || "mcp-context-card";
+    return { domain, handle };
+}
 /** Human-readable one-liner for the `whoami` tool. */
 export function whoami(root) {
     const id = resolveIdentity(root);

package/dist/render-card.d.ts

@@ -9,6 +9,11 @@ export interface CardOptions {
      * `expanded` is the whole-page render, for a screenshot or a PR.
      */
     expanded?: boolean;
+    /**
+     * `private` shows how many facts memory holds but not the facts: for a card
+     * served beyond this machine without the publish opt-in. Default: `full`.
+     */
+    memory?: "full" | "private";
 }
 /** AAIF brand orange (aaif.io). The default accent. */
 export declare const AAIF_ACCENT = "#FF702D";

package/dist/render-card.js

@@ -14,7 +14,7 @@ import { basename, join, resolve } from "node:path";
 import { parseAgentsMd } from "./agents-md.js";
 import { parseFafm } from "./memory.js";
 import { resolveIdentity, serverCardMeta, META_NS } from "./identity.js";
-import { SERVER_CARD_URI } from "./constants.js";
+import { PUBLISH_MEMORY_ENV, SERVER_CARD_URI } from "./constants.js";
 import { escapeHtml, renderInline, renderMarkdown, slug } from "./md.js";
 /** AAIF brand orange (aaif.io). The default accent. */
 export const AAIF_ACCENT = "#FF702D";
@@ -154,17 +154,19 @@ export function renderCard(root, opts = {}) {
     <div class="ctx-body">${sections}</div>`
         : `<p class="none">No AGENTS.md yet. Ask your agent to draft one: <code>author_agents_md</code> builds it from this repo's real build and test commands, nothing invented.</p>`;
     // MEMORY
-    const memoryBody = mem.facts.length
-        ? mem.facts
-            .map((f) => {
-            const verified = f.verification_status === "verified";
-            const tags = (f.tags ?? [])
-                .map((t) => `<span class="tag">${escapeHtml(t)}</span>`)
-                .join("");
-            return `<div class="fact"><p>${renderInline(f.text)}</p><div class="meta">${tags}<span class="dot${verified ? "" : " pending"}" title="${verified ? "verified" : f.verification_status ?? "unverified"}"></span></div></div>`;
-        })
-            .join("")
-        : `<p class="none">No facts yet. Ask your agent to remember something, and it lands here.</p>`;
+    const memoryBody = opts.memory === "private" && mem.facts.length
+        ? `<p class="none">Kept private on this page. To show the facts, set <code>${PUBLISH_MEMORY_ENV}=1</code>.</p>`
+        : mem.facts.length
+            ? mem.facts
+                .map((f) => {
+                const verified = f.verification_status === "verified";
+                const tags = (f.tags ?? [])
+                    .map((t) => `<span class="tag">${escapeHtml(t)}</span>`)
+                    .join("");
+                return `<div class="fact"><p>${renderInline(f.text)}</p><div class="meta">${tags}<span class="dot${verified ? "" : " pending"}" title="${verified ? "verified" : f.verification_status ?? "unverified"}"></span></div></div>`;
+            })
+                .join("")
+            : `<p class="none">No facts yet. Ask your agent to remember something, and it lands here.</p>`;
     // DISCOVERY
     const rows = Object.entries(meta)
         .map(([k, v]) => {
@@ -191,7 +193,7 @@ export function renderCard(root, opts = {}) {
     ${contextBody}
   </section>
   <section>
-    <p class="label">Memory — ${mem.facts.length} fact${mem.facts.length === 1 ? "" : "s"}</p>
+    <p class="label">Memory — ${mem.facts.length} fact${mem.facts.length === 1 ? "" : "s"}${opts.memory === "private" && mem.facts.length ? ", kept private" : ""}</p>
     ${memoryBody}
   </section>
   <section>
@@ -199,7 +201,7 @@ export function renderCard(root, opts = {}) {
     <table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody>${rows}</tbody></table>
     <p class="fetch">A machine reads this over <b>MCP</b> from the
       <code>${escapeHtml(SERVER_CARD_URI)}</code> resource; over <b>HTTP</b> also
-      from <code>GET /.well-known/mcp/server-card</code> and
+      from <code>GET /mcp/server-card</code> and
       <code>GET /.well-known/ai-catalog.json</code>.</p>
   </section>
   <div class="foot">${escapeHtml(name)} · context card</div>

package/dist/server-card.d.ts

@@ -0,0 +1,39 @@
+export interface ServerCardOptions {
+    /** Public origin this server is reached at (e.g. `https://ctx.example.com`).
+     *  When set, the card advertises the streamable-HTTP endpoint at `<origin>/mcp`. */
+    origin?: string;
+}
+export declare function serverCard(opts?: ServerCardOptions): {
+    _meta: {
+        readonly "io.github.Wolfe-Jam.mcp-context-card/context": {
+            readonly source: "AGENTS.md";
+            readonly mediaType: "text/markdown";
+        };
+        readonly "io.github.Wolfe-Jam.mcp-context-card/memory": {
+            readonly source: "project.fafm";
+            readonly mediaType: "application/vnd.fafm+yaml";
+            readonly iana: string;
+            readonly note: "no de-facto standard for agent memory yet — this is one instantiation";
+        };
+        readonly "io.github.Wolfe-Jam.mcp-context-card/identity": {
+            readonly source: ".well-known/fafa";
+            readonly mediaType: "application/vnd.fafa+yaml";
+            readonly iana: string;
+        };
+    };
+    remotes?: {
+        type: "streamable-http";
+        url: string;
+        supportedProtocolVersions: string[];
+    }[] | undefined;
+    $schema: string;
+    name: string;
+    version: string;
+    title: string;
+    description: string;
+    websiteUrl: string;
+    repository: {
+        url: string;
+        source: string;
+    };
+};

package/dist/server-card.js

@@ -0,0 +1,38 @@
+/**
+ * server-card — this server's MCP Server Card (SEP-2127, Final; schema v1).
+ *
+ * Required: `$schema`, `name` (reverse-DNS), `version`, `description`.
+ * Optional fields carried here: `title`, `websiteUrl`, `repository`, `remotes`
+ * (only when the caller knows the public origin, i.e. served over HTTP) and the
+ * namespaced `_meta` context block. No tools, resources or prompts: a card
+ * describes identity and connectivity, and primitives stay runtime-listed.
+ *
+ * `name`, `title` and `version` are the same values the live connection reports
+ * in `serverInfo`, so the card never contradicts runtime.
+ */
+import { SUPPORTED_PROTOCOL_VERSIONS } from "@modelcontextprotocol/sdk/types.js";
+import { DESCRIPTION, MCP_PATH, REGISTRY_NAME, REPOSITORY_URL, SERVER_CARD_SCHEMA, TITLE, VERSION, } from "./constants.js";
+import { serverCardMeta } from "./identity.js";
+export function serverCard(opts = {}) {
+    return {
+        $schema: SERVER_CARD_SCHEMA,
+        name: REGISTRY_NAME,
+        version: VERSION,
+        title: TITLE,
+        description: DESCRIPTION,
+        websiteUrl: REPOSITORY_URL,
+        repository: { url: REPOSITORY_URL, source: "github" },
+        ...(opts.origin
+            ? {
+                remotes: [
+                    {
+                        type: "streamable-http",
+                        url: `${opts.origin}${MCP_PATH}`,
+                        supportedProtocolVersions: [...SUPPORTED_PROTOCOL_VERSIONS],
+                    },
+                ],
+            }
+            : {}),
+        _meta: serverCardMeta(),
+    };
+}

package/dist/server.d.ts

@@ -20,32 +20,13 @@ export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
 /** Default package root — `dist/` at runtime, `src/` under tsx. Both are one up. */
 export declare const ROOT: string;
 /**
- * The Server Card — this server's identity plus the `_meta` context block,
- * one namespaced key per concern. Served in-band as the
- * `mcp-context-card://server-card` resource and out-of-band at
- * `/.well-known/mcp/server-card`.
+ * The Server Card (SEP-2127, schema v1): this server's identity plus the `_meta`
+ * context block, one namespaced key per concern. Served in-band as the
+ * `mcp-context-card://server-card` resource and out-of-band at `/mcp/server-card`
+ * (the spec's reserved `<streamable-http-url>/server-card`; the 1.x path
+ * `/.well-known/mcp/server-card` is kept as an alias). Built in server-card.ts.
  */
-export declare function serverCard(): {
-    name: string;
-    version: string;
-    _meta: {
-        readonly "io.github.Wolfe-Jam.mcp-context-card/context": {
-            readonly source: "AGENTS.md";
-            readonly mediaType: "text/markdown";
-        };
-        readonly "io.github.Wolfe-Jam.mcp-context-card/memory": {
-            readonly source: "project.fafm";
-            readonly mediaType: "application/vnd.fafm+yaml";
-            readonly iana: string;
-            readonly note: "no de-facto standard for agent memory yet — this is one instantiation";
-        };
-        readonly "io.github.Wolfe-Jam.mcp-context-card/identity": {
-            readonly source: ".well-known/fafa";
-            readonly mediaType: "application/vnd.fafa+yaml";
-            readonly iana: string;
-        };
-    };
-};
+export { serverCard } from "./server-card.js";
 /** Sent to every client at initialize. Hosts that support MCP Apps show the
  *  card inline; for the rest, this steers the model to save the card as a
  *  file instead of pasting a whole HTML page into the chat. */