mcp-context-card 1.4.0 → 1.6.0

package/dist/conformance/discovery.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 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 declare const SERVER_CARD_SCHEMA_URL = "https://static.modelcontextprotocol.io/schemas/v1/server-card.schema.json";
+export declare const SERVER_CARD_TYPE = "application/mcp-server-card+json";
+export declare const AI_CATALOG_TYPE = "application/ai-catalog+json";
+export type Tier = "card" | "hosting" | "catalog" | "transport";
+export type Level = "must" | "should";
+export type Status = "pass" | "fail" | "skip";
+export interface CheckResult {
+    id: string;
+    tier: Tier;
+    level: Level;
+    title: string;
+    status: Status;
+    detail?: string;
+}
+export interface DiscoveryTarget {
+    /** The server's Streamable HTTP endpoint, e.g. `https://ctx.example.com/mcp`. */
+    mcpUrl: string;
+    /** Where to read the card. Default: `<mcpUrl>/server-card`, then the catalog's card entry. */
+    cardUrl?: string;
+    /** Where to read the catalog. Default: `<origin>/.well-known/ai-catalog.json`. */
+    catalogUrl?: string;
+}
+export interface DiscoveryOptions {
+    fetch?: typeof fetch;
+    /** Returns null when the card is valid, else a short error. */
+    validateCard?: (card: unknown) => string | null;
+    /** Per-request timeout in milliseconds (default 10000). */
+    timeoutMs?: number;
+    /** POST with exact headers (Host included); returns the status, or null. Default: node:http. */
+    rawStatus?: (url: string, headers: Record<string, string>, body: string, timeoutMs: number) => Promise<number | null>;
+}
+export interface DiscoveryReport {
+    mcpUrl: string;
+    cardUrl: string | null;
+    catalogUrl: string;
+    results: CheckResult[];
+    passed: number;
+    failed: number;
+    skipped: number;
+    /** Failed MUST checks: zero means nothing the spec requires is broken. */
+    mustFailures: number;
+}
+export declare function checkDiscovery(target: DiscoveryTarget, opts?: DiscoveryOptions): Promise<DiscoveryReport>;

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.6.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.6.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/faf/parse-fafa.js

@@ -23,6 +23,7 @@ export function parseFafa(path) {
         description: str(agent.description),
         status: str(agent.status),
         license: str(agent.license),
+        ...extras(doc),
     };
 }
 function str(v) {
@@ -31,3 +32,23 @@ function str(v) {
     const s = String(v).trim().replace(/\s+/g, " ");
     return s.length ? s : undefined;
 }
+/** Where it runs, what it can do, and what installs it: `.fafa` fields outside `agent`. */
+function extras(doc) {
+    const list = (v) => Array.isArray(v) ? v.filter((x) => !!x && typeof x === "object") : [];
+    const endpoints = list(doc.endpoints)
+        .filter((e) => typeof e.protocol === "string" && e.protocol.trim())
+        .map((e) => ({ protocol: String(e.protocol).trim().toLowerCase(), ...(typeof e.location === "string" ? { location: e.location } : {}) }));
+    const skills = list(doc.capabilities)
+        .filter((c) => typeof c.name === "string" && c.name.trim())
+        .map((c) => ({ name: String(c.name), ...(typeof c.description === "string" ? { description: c.description } : {}) }));
+    const meta = doc.metadata && typeof doc.metadata === "object" ? doc.metadata : {};
+    const cards = meta.cards && typeof meta.cards === "object" ? meta.cards : {};
+    const packages = list(cards.packages)
+        .filter((p) => typeof p.registryType === "string" && typeof p.identifier === "string")
+        .map((p) => ({ registryType: String(p.registryType), identifier: String(p.identifier) }));
+    return {
+        ...(endpoints.length ? { endpoints } : {}),
+        ...(skills.length ? { skills } : {}),
+        ...(packages.length ? { packages } : {}),
+    };
+}

package/dist/faf/types.d.ts

@@ -33,4 +33,19 @@ export interface AgentIdentity {
     description?: string;
     status?: string;
     license?: string;
+    /** Where it runs (`.fafa` `endpoints`), as `faf card init` writes them: protocol `a2a` or `mcp`. */
+    endpoints?: {
+        protocol: string;
+        location?: string;
+    }[];
+    /** What it can do (`.fafa` `capabilities`). */
+    skills?: {
+        name: string;
+        description?: string;
+    }[];
+    /** Installable packages (`.fafa` `metadata.cards.packages`), e.g. an npm MCP server. */
+    packages?: {
+        registryType: string;
+        identifier: string;
+    }[];
 }

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

@@ -1,3 +1,4 @@
+import type { AgentIdentity } from "./faf/types.js";
 export type Theme = "light" | "dark" | "auto";
 export interface CardOptions {
     theme?: Theme;
@@ -9,11 +10,61 @@ 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";
+    /** Business-card view. Default `landscape`; the reader can switch it too. */
+    layout?: "landscape" | "portrait";
 }
 /** AAIF brand orange (aaif.io). The default accent. */
 export declare const AAIF_ACCENT = "#FF702D";
 export declare function safeAccent(a?: string): string;
+/** What the front calls this thing, from where it runs: "MCP server", "A2A agent", or both. */
+export declare function cardKind(id: AgentIdentity | null): string[];
+/** The front's title line: what it is, then its version. Empty when nothing is known. */
+export declare function cardTitle(id: AgentIdentity | null): string;
+/** The front's logo: the first letters of the name's first two words ("mcp-context-card" → "MC"). */
+export declare function cardInitials(name: string): string;
+/** The front's one-liner: the first sentence of the description. */
+export declare function cardOneLiner(id: AgentIdentity | null, max?: number): string;
+/**
+ * A business card, independent of where its facts came from: everything the
+ * renderer draws. `readCard` builds one from a project's files; another reader
+ * (an A2A Agent Card, an MCP Server Card, a person's card) can build one too,
+ * and `renderBusinessCard` draws any of them the same way.
+ */
+export interface BusinessCard {
+    name: string;
+    /** What it is (and its version): "MCP server · v1.5.0", or a person's role. */
+    title?: string;
+    oneLiner?: string;
+    /** Shown bottom-left on the front, e.g. the publisher domain. */
+    domain?: string;
+    /** Footer chips; `accent` highlights one (e.g. the status). Plain text. */
+    chips: {
+        text: string;
+        accent?: boolean;
+    }[];
+    /** The back's tabs, in order. `key` is [a-z0-9-]; `html` is already-safe markup. */
+    tabs: {
+        key: string;
+        label: string;
+        heading: string;
+        html: string;
+    }[];
+    /** The (i) panel, as already-safe markup. */
+    about: string;
+}
+/** How to draw a card: the owner's colour and accent, the view, and the flat (print) layout. */
+export type RenderOptions = Pick<CardOptions, "theme" | "accent" | "layout" | "expanded">;
+/** The project's card: read its files, then draw. */
 export declare function renderCard(root: string, opts?: CardOptions): string;
+/** Read a project's AGENTS.md, memory and identity into a business card. */
+export declare function readCard(root: string, opts?: Pick<CardOptions, "expanded" | "memory">): BusinessCard;
+/** Draw any business card as one self-contained HTML page. */
+export declare function renderBusinessCard(card: BusinessCard, opts?: RenderOptions): string;
 /** tl;dr: the first few facts, each cut to about a line. `full`: every fact, whole. */
 export type Detail = "tldr" | "full";
 /**