mcp-context-card 1.7.0 → 1.8.0

package/dist/card-gen.js

@@ -1,7 +1,10 @@
 /**
  * card-gen - write docs/card.html from the three sources, so the card is
  * browsable on GitHub and screenshot-able for the README. Same renderer as
- * GET /card and the render_context_card tool.
+ * GET /card, the CLI, and render_context_card for a client without MCP Apps:
+ * the plain card, without the MCP Apps helper. The ui:// resource is
+ * rendered at read time and is not one of these files. A plain card over
+ * 64 KB fails here, which fails card:check.
  *
  * Also writes two theme-pinned siblings (docs/card-light.html,
  * docs/card-dark.html) — docs/card.html stays "auto" (follows the viewer's
@@ -15,13 +18,19 @@
 import { writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
-import { renderCard } from "./render-card.js";
+import { PLAIN_CARD_LIMIT_BYTES, plainCardExceedsLimit, renderCard } from "./render-card.js";
+function writePlain(path, html) {
+    if (plainCardExceedsLimit(html)) {
+        throw new Error(`card:check: ${path} is ${Buffer.byteLength(html)} bytes; a plain card must not exceed ${PLAIN_CARD_LIMIT_BYTES} bytes (64 KB)`);
+    }
+    writeFileSync(path, html);
+}
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const root = join(dirname(fileURLToPath(import.meta.url)), "..");
     const auto = renderCard(root);
-    writeFileSync(join(root, "docs/card.html"), auto);
-    writeFileSync(join(root, "docs/index.html"), auto);
-    writeFileSync(join(root, "docs/card-light.html"), renderCard(root, { theme: "light" }));
-    writeFileSync(join(root, "docs/card-dark.html"), renderCard(root, { theme: "dark" }));
+    writePlain(join(root, "docs/card.html"), auto);
+    writePlain(join(root, "docs/index.html"), auto);
+    writePlain(join(root, "docs/card-light.html"), renderCard(root, { theme: "light" }));
+    writePlain(join(root, "docs/card-dark.html"), renderCard(root, { theme: "dark" }));
     console.log("wrote docs/card.html + docs/index.html (auto) + card-light.html + card-dark.html — the context card, rendered from AGENTS.md / project.fafm / .well-known/fafa");
 }

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
 /** 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.7.0";
+export declare const VERSION = "1.8.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
@@ -32,9 +32,25 @@ 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;
+/** What the ui:// card carries for an MCP Apps host. `helper` (the default):
+ *  the official MCP Apps helper, so the card reports its size (~700 KB).
+ *  `plain`: the plain card (~30 KB), no MCP Apps messages; the host's default
+ *  frame. Only the ui:// resource changes: tool text, save_context_card,
+ *  GET /card and the CLI are always the plain card. */
+export declare const CARD_APP_ENV = "MCP_CONTEXT_CARD_APP";
+export type CardApp = "helper" | "plain";
+/** A setting value as a CardApp: trimmed, any case. Anything else: undefined. */
+export declare function toCardApp(value: unknown): CardApp | undefined;
+/** Unset or empty = `helper`. `plain`/`helper` in any case. Any other value:
+ *  one stderr line per distinct value (a server builds an instance per HTTP
+ *  request; warn once), then `helper`. */
+export declare function cardAppFromEnv(env?: NodeJS.ProcessEnv, warn?: (line: string) => void): CardApp;
 /** 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. */
 export declare const CARD_UI_URI = "ui://mcp-context-card/card.html";
 export declare const MCP_APP_MIME = "text/html;profile=mcp-app";
 export declare const UI_EXTENSION = "io.modelcontextprotocol/ui";
+/** Protocol revisions served beside the SDK's 2025-era list (SUPPORTED_PROTOCOL_VERSIONS):
+ *  createMcpHandler / serveStdio answer 2026-07-28 too. The SDK exports no constant for it. */
+export declare const MODERN_PROTOCOL_VERSIONS: readonly ["2026-07-28"];

package/dist/constants.js

@@ -1,7 +1,7 @@
 /** 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.7.0";
+export const VERSION = "1.8.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
@@ -32,9 +32,43 @@ 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";
+/** What the ui:// card carries for an MCP Apps host. `helper` (the default):
+ *  the official MCP Apps helper, so the card reports its size (~700 KB).
+ *  `plain`: the plain card (~30 KB), no MCP Apps messages; the host's default
+ *  frame. Only the ui:// resource changes: tool text, save_context_card,
+ *  GET /card and the CLI are always the plain card. */
+export const CARD_APP_ENV = "MCP_CONTEXT_CARD_APP";
+const CARD_APP_VALUES = ["helper", "plain"];
+const warnedCardApp = new Set();
+/** A setting value as a CardApp: trimmed, any case. Anything else: undefined. */
+export function toCardApp(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const v = value.trim().toLowerCase();
+    return CARD_APP_VALUES.includes(v) ? v : undefined;
+}
+/** Unset or empty = `helper`. `plain`/`helper` in any case. Any other value:
+ *  one stderr line per distinct value (a server builds an instance per HTTP
+ *  request; warn once), then `helper`. */
+export function cardAppFromEnv(env = process.env, warn = (line) => console.error(line)) {
+    const raw = env[CARD_APP_ENV]?.trim();
+    if (!raw)
+        return "helper";
+    const known = toCardApp(raw);
+    if (known)
+        return known;
+    if (!warnedCardApp.has(raw)) {
+        warnedCardApp.add(raw);
+        warn(`${NAME} · ${CARD_APP_ENV}="${raw}" is not one of ${CARD_APP_VALUES.join(", ")}; using helper`);
+    }
+    return "helper";
+}
 /** 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. */
 export const CARD_UI_URI = "ui://mcp-context-card/card.html";
 export const MCP_APP_MIME = "text/html;profile=mcp-app";
 export const UI_EXTENSION = "io.modelcontextprotocol/ui";
+/** Protocol revisions served beside the SDK's 2025-era list (SUPPORTED_PROTOCOL_VERSIONS):
+ *  createMcpHandler / serveStdio answer 2026-07-28 too. The SDK exports no constant for it. */
+export const MODERN_PROTOCOL_VERSIONS = ["2026-07-28"];

package/dist/render-card.d.ts

@@ -1,5 +1,7 @@
 import type { AgentIdentity } from "./faf/types.js";
-export type Theme = "light" | "dark" | "auto";
+import { type BusinessCard, type Theme } from "agent-business-card";
+export { cardInitials, renderBusinessCard, safeAccent } from "agent-business-card";
+export type { BusinessCard, RenderOptions, Theme } from "agent-business-card";
 export interface CardOptions {
     theme?: Theme;
     /**
@@ -23,59 +25,28 @@ export interface CardOptions {
 }
 /** AAIF brand orange (aaif.io): this project's own card colour, declared in its `.fafa`. */
 export declare const AAIF_ACCENT = "#FF702D";
-/** A valid hex colour, or undefined. Nothing else ever reaches the stylesheet. */
-export declare function safeAccent(a?: string): string | undefined;
 /** 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 letter of the name's first meaningful word
- * (generic words like "mcp", "server", "sdk" skipped), plus a second letter
- * only when it's obvious: a known name (github → GH, typescript → TS) or a
- * word written with two capitals (GitHub, TypeScript). Never more than two.
- */
-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.
+ * A plain card (tool text, the saved file, GET /card, the CLI, docs/) must
+ * not exceed this. The ui:// resource is separate and is not checked here.
  */
-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;
-    /** The owner's colour, a hex. None = ink (black or white). */
-    accent?: 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 const PLAIN_CARD_LIMIT_BYTES: number;
+/** True when a plain card exceeds 64 KB. card:check fails on that. */
+export declare function plainCardExceedsLimit(html: string): boolean;
+/** The project's card: read its files and draw. No helper, no inline view. */
 export declare function renderCard(root: string, opts?: CardOptions): string;
+/**
+ * ui://mcp-context-card/card.html — the same card, plus the hidden inline
+ * view and the bundled MCP Apps helper. Nothing else calls this.
+ */
+export declare function renderAppsCard(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";
 /**