mcp-context-card 1.1.0 → 1.2.0

package/.well-known/fafa

@@ -9,7 +9,7 @@ agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
   vendor: "io.github.Wolfe-Jam"
-  version: "1.1.0"
+  version: "1.2.0"
   description: >-
     The essential MCP components for a project's context (AGENTS.md),
     cross-session memory, and identity — a base MCP on its own, or a

package/AGENTS.md

@@ -15,7 +15,7 @@ connection.
 npm ci
 ```
 
-Node 22 or newer. No other system dependencies.
+Node 20 or newer. No other system dependencies.
 
 ## Build
 
@@ -45,7 +45,7 @@ code's shape moved without `project.faf`) on Linux.
 
 | Path | What |
 |---|---|
-| `src/server.ts` | the MCP server — the nine tools + the Server Card resource |
+| `src/server.ts` | the MCP server — the ten tools + the Server Card and card resources |
 | `src/agents-md.ts` | reads and section-splits this file |
 | `src/author.ts` | `author_agents_md` — BETTER via `agents-md-facts`, BEST when `project.faf` exists |
 | `src/md.ts` | a minimal dependency-free Markdown → HTML renderer |

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.2.0
+
+The card reaches people in any host: inline where the host supports MCP
+Apps, and as text in the chat plus the full card in the browser everywhere
+else.
+
+- **MCP App.** `render_context_card` links a `ui://mcp-context-card/card.html`
+  resource (`text/html;profile=mcp-app`). Hosts that support MCP Apps render
+  the card inline, and the model gets a one-line summary instead of the
+  whole HTML page. Hosts without MCP Apps get the full HTML, as before.
+- **New tool: `save_context_card`.** Writes the card to `context-card.html`
+  in the project and replies with:
+  - the card as Markdown: identity, `AGENTS.md` section headings, memory,
+    discovery. About 1.2k characters for this repo, instead of about 17k of
+    HTML;
+  - a link to the full card, plus its `file://` address in a code block,
+    which hosts give a copy button (many won't follow a `file://` link).
+
+  When the server runs locally (stdio), it also opens the saved card in the
+  browser; `open: false` skips that, and over HTTP it never opens anything.
+  Same `theme`, `accent` and `expanded` inputs as `render_context_card`.
+  Marked `destructiveHint: true`, because it replaces an earlier
+  `context-card.html`.
+- **A tl;dr by default.** The Markdown shows five facts, each cut to its
+  first sentence exactly as stored (or a word-boundary cut marked … when
+  that sentence is long), and counts the rest. It stays under about 3k
+  characters however much a project remembers. `detail: "full"` lists
+  every fact whole. The saved file always has everything.
+- **Server instructions.** Sent at initialize: when the host can't display
+  the card, save it and show the user the Markdown card and its link,
+  not paste HTML into the chat.
+- **`list_context_sources`** now lists the card resource under
+  `surfaces.mcp`.
+
+Ten tools now. The nine existing tools keep their names, inputs and
+behaviour. 117 tests, all green.
+
+## 1.1.1
+
+Every tool now says what it is and what it does to your project.
+
+Each of the nine tools carries a human-readable `title` and MCP tool
+annotations, so a host can label it properly and decide whether to ask
+before running it:
+
+- **Read-only (7):** `read_agents_md`, `list_agents_md_sections`,
+  `author_agents_md` (returns a draft, writes nothing), `recall`, `whoami`,
+  `list_context_sources`, `render_context_card`.
+- **Writes the memory file (2):** `remember` and `forget` are marked
+  `destructiveHint: true`. `remember` replaces a fact when an id is reused;
+  `forget` removes one.
+- All nine are `idempotentHint: true` (repeating a call changes nothing more)
+  and `openWorldHint: false` (they only touch the local project).
+
+A new test checks every tool's title and hints against what it actually does,
+so a tool added later can't ship without them. 106 tests, all green on
+Linux, macOS, and Windows.
+
+No API change to the nine tools: same names, same inputs, same behaviour.
+
 ## 1.1.0
 
 The card scans in one screen — AGENTS.md sections collapse by default.

package/README.md

@@ -13,6 +13,13 @@ rendered as one card you can read.
 |---|---|
 | ![the context card, light theme](./docs/img/card-light.png) | ![the context card, dark theme](./docs/img/card-dark.png) |
 
+**See your own project's card** — run this in its folder. It writes
+`context-card.html` and opens it in your browser:
+
+```
+npx mcp-context-card card
+```
+
 **context** — the project's `AGENTS.md`, served whole or one section at a time.
 
 ![the card's context section — AGENTS.md, section nav, read_agents_md](./docs/img/card-context.png)
@@ -52,7 +59,7 @@ say what it is. `mcp-context-card` is those three, done once:
   gains context, memory, and identity discovery it didn't have. Nothing to
   migrate; it composes.
 
-Nine tools, two discovery surfaces already in the ecosystem (Server Card
+Ten tools, two discovery surfaces already in the ecosystem (Server Card
 `_meta`, `ai-catalog.json`), and a rendered [card](#the-card). MIT, on npm.
 
 It composes:
@@ -63,8 +70,9 @@ It composes:
 
 Vendor-free — context is plain Markdown (`AGENTS.md`); the memory and
 identity formats are swappable examples. It reads and writes only its own
-three files (`AGENTS.md`, `project.fafm`, `.well-known/fafa`) — no general
-file access, no shell, no search.
+three files (`AGENTS.md`, `project.fafm`, `.well-known/fafa`), plus the
+`context-card.html` it saves on request — no general file access, no shell,
+no search.
 
 ## The card
 
@@ -87,6 +95,18 @@ GET /card                            # live, on the HTTP transport
 GET /card?expand=all&theme=light&accent=%230066cc
 ```
 
+In a chat, hosts that support [MCP Apps](https://modelcontextprotocol.io/extensions/apps)
+show the card inline when `render_context_card` runs; the model gets a short
+summary instead of the page. Everywhere else, `save_context_card` writes
+`context-card.html` into the project, opens it in your browser when the
+server runs locally, and replies with the card as Markdown (identity, the
+`AGENTS.md` sections, memory, discovery), a link to the full card, and its
+address to copy. The Markdown is a tl;dr by default: five facts, each cut to
+its first sentence as stored, so it stays small however much a project
+remembers. `detail: "full"` lists every fact whole. The server's
+instructions tell the model to show that rather than paste the HTML into
+the chat.
+
 Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
 This repo's own card, live: [auto](https://wolfe-jam.github.io/mcp-context-card/) ·
 [light](https://wolfe-jam.github.io/mcp-context-card/card-light.html) ·
@@ -191,11 +211,18 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 | `forget` | drop or correct a stale fact |
 | `whoami` | this server's name, vendor, version, status, license |
 | `list_context_sources` | what this project publishes, in what media types, via which surface |
-| `render_context_card` | the whole card as one self‑contained HTML page (also `GET /card`) |
+| `render_context_card` | the whole card as one self‑contained HTML page (also `GET /card`); hosts that support MCP Apps show it inline |
+| `save_context_card` | write the card to `context-card.html` in the project and open it in your browser; returns the card as Markdown plus a link to the full version |
+
+Seven tools only read. `remember` and `forget` write the memory file, and
+`save_context_card` writes `context-card.html`, so those three are marked
+destructive and a host can ask before running them. Every tool carries a
+title and MCP tool annotations.
 
 ## The demo
 
-`npm run demo` runs every tool over both transports:
+`npm run demo` walks through context, memory, identity and discovery, live,
+over both transports:
 
 1. **Context** — list the `AGENTS.md` sections, then pull just `## Test`.
 2. **Memory** — `remember()` a fact, stop the server process, start a new one,
@@ -205,16 +232,17 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-104 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+117 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
 child process and check a remembered fact survives the restart — one against
 an existing `project.fafm`, one starting from a project that has never had
-one; another checks the stdio and HTTP tool surfaces match.
+one; another checks the stdio and HTTP tool surfaces match, and another checks
+every tool's title and behaviour hints against what it actually does.
 
 ## Layout
 
 | Path | What |
 |---|---|
-| `src/server.ts` | the nine tools + the Server Card resource |
+| `src/server.ts` | the ten tools + the Server Card and card resources |
 | `src/agents-md.ts` | reads and section‑splits `AGENTS.md` |
 | `src/author.ts` | `author_agents_md` — BETTER via [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts), BEST when `project.faf` exists |
 | `src/md.ts` | a minimal dependency‑free Markdown → HTML renderer |

package/dist/bin.d.ts

@@ -8,7 +8,7 @@ export interface Launch {
     root: string;
 }
 /** what a bare `--help` / `help` prints. */
-export declare const HELP = "mcp-context-card 1.1.0\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --stdout\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
+export declare const HELP = "mcp-context-card 1.2.0\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n  mcp-context-card                  stdio MCP server \u2014 what an MCP host spawns (default)\n  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)\n  mcp-context-card --stdio          force stdio even when PORT is set\n  mcp-context-card card             this dir's context card \u2014 opens it in your browser\n                                    at a terminal; HTML to stdout when piped ( > f.html )\n                                      --theme light|dark   --accent #hex\n                                      --expanded (all sections open)   --stdout\n  mcp-context-card --help           this text\n  mcp-context-card --version        print version\n\nENV\n  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here\n  PORT                    if set, run HTTP instead of stdio\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.

package/dist/bin.js

@@ -121,17 +121,10 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
         else {
             const { writeFileSync } = await import("node:fs");
             const { join } = await import("node:path");
-            const { spawn } = await import("node:child_process");
+            const { openInBrowser } = await import("./open.js");
             const out = join(process.cwd(), "context-card.html");
             writeFileSync(out, html);
-            const opener = process.platform === "darwin"
-                ? ["open", [out]]
-                : process.platform === "win32"
-                    ? ["cmd", ["/c", "start", "", out]]
-                    : ["xdg-open", [out]];
-            spawn(opener[0], opener[1], { stdio: "ignore", detached: true })
-                .on("error", () => { })
-                .unref();
+            openInBrowser(out);
             process.stderr.write(`${NAME} · wrote ${out} — opening in your browser  (--stdout for raw HTML)\n`);
         }
     }
@@ -146,6 +139,8 @@ if (entryPath && import.meta.url === pathToFileURL(entryPath).href) {
         // stderr so it never touches the JSON-RPC wire on stdout; a bare run at a
         // terminal otherwise looks hung.
         console.error(`${NAME} · stdio · waiting for an MCP host on stdin  (--help for usage · Ctrl-C to exit)`);
-        await serve(new StdioServerTransport(), root);
+        // stdio = a host on this machine, so save_context_card can open the card.
+        const { openInBrowser } = await import("./open.js");
+        await serve(new StdioServerTransport(), root, { openFile: openInBrowser });
     }
 }

package/dist/constants.d.ts

@@ -1,5 +1,11 @@
 /** 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.1.0";
+export declare const VERSION = "1.2.0";
 export declare const SERVER_CARD_URI = "mcp-context-card://server-card";
+/** 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";

package/dist/constants.js

@@ -1,5 +1,11 @@
 /** 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.1.0";
+export const VERSION = "1.2.0";
 export const SERVER_CARD_URI = "mcp-context-card://server-card";
+/** 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";

package/dist/open.d.ts

@@ -0,0 +1 @@
+export declare function openInBrowser(path: string): void;

package/dist/open.js

@@ -0,0 +1,17 @@
+/**
+ * Open a local file in the default browser — what `mcp-context-card card`
+ * does at a terminal, and what save_context_card does when the server runs
+ * locally over stdio. Fire and forget: no display (SSH, CI) just means
+ * nothing opens, never an error.
+ */
+import { spawn } from "node:child_process";
+export function openInBrowser(path) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [path]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", path]]
+            : ["xdg-open", [path]];
+    spawn(cmd, args, { stdio: "ignore", detached: true })
+        .on("error", () => { })
+        .unref();
+}

package/dist/render-card.d.ts

@@ -14,3 +14,24 @@ export interface CardOptions {
 export declare const AAIF_ACCENT = "#FF702D";
 export declare function safeAccent(a?: string): string;
 export declare function renderCard(root: string, opts?: CardOptions): string;
+/** tl;dr: the first few facts, each cut to about a line. `full`: every fact, whole. */
+export type Detail = "tldr" | "full";
+/**
+ * Shorten a fact for the tl;dr without rewording it. The whole first sentence
+ * when it fits in `max` (a stored sentence, verbatim, so a model has no ragged
+ * end to "tidy"); otherwise a word-boundary cut marked with …. A dot inside a
+ * word (AGENTS.md, v1.2) is not a sentence end: it must be followed by space.
+ */
+export declare function clip(s: string, max: number): string;
+/**
+ * The same card as Markdown, for chats that can't display HTML: identity,
+ * the AGENTS.md section headings (bodies stay in the full card), memory,
+ * and the discovery table. Same sources as renderCard.
+ *
+ * The default tl;dr stays small however much memory a project holds: five
+ * facts, each cut short, and a count of the rest. `detail: "full"` lists
+ * every fact whole. The saved HTML card always has everything.
+ */
+export declare function renderCardText(root: string, opts?: {
+    detail?: Detail;
+}): string;

package/dist/render-card.js

@@ -236,3 +236,64 @@ const TOGGLE_SCRIPT = `<script>
   sync();
 })();
 </script>`;
+const TLDR_FACTS = 5;
+const TLDR_CHARS = 160;
+/**
+ * Shorten a fact for the tl;dr without rewording it. The whole first sentence
+ * when it fits in `max` (a stored sentence, verbatim, so a model has no ragged
+ * end to "tidy"); otherwise a word-boundary cut marked with …. A dot inside a
+ * word (AGENTS.md, v1.2) is not a sentence end: it must be followed by space.
+ */
+export function clip(s, max) {
+    if (s.length <= max)
+        return s;
+    const first = /^(.+?[.!?])(?=\s)/.exec(s)?.[1];
+    if (first && first.length <= max)
+        return first;
+    const cut = s.slice(0, max);
+    const space = cut.lastIndexOf(" ");
+    return `${(space > max / 2 ? cut.slice(0, space) : cut).replace(/[\s,;:.—-]+$/, "")}…`;
+}
+/**
+ * The same card as Markdown, for chats that can't display HTML: identity,
+ * the AGENTS.md section headings (bodies stay in the full card), memory,
+ * and the discovery table. Same sources as renderCard.
+ *
+ * The default tl;dr stays small however much memory a project holds: five
+ * facts, each cut short, and a count of the rest. `detail: "full"` lists
+ * every fact whole. The saved HTML card always has everything.
+ */
+export function renderCardText(root, opts = {}) {
+    const agents = parseAgentsMd(join(root, "AGENTS.md"));
+    const mem = parseFafm(join(root, "project.fafm"));
+    const id = resolveIdentity(root);
+    const meta = serverCardMeta();
+    const name = id?.displayName ?? id?.name ?? NAME;
+    const plural = (n, w) => `${n} ${w}${n === 1 ? "" : "s"}`;
+    const out = [`### ${name} — context card`];
+    const pills = [
+        id?.vendor && id.vendor !== id.status ? id.vendor : null,
+        id?.agentVersion ? `v${id.agentVersion}` : null,
+        id?.status,
+        id?.license,
+    ].filter(Boolean);
+    if (pills.length)
+        out.push(pills.join(" · "));
+    if (id?.description)
+        out.push(id.description);
+    const sections = agents?.sections.filter((s) => s.level > 1) ?? [];
+    out.push(agents
+        ? `**Context — AGENTS.md** · ${plural(sections.length, "section")}\n${sections.map((s) => s.heading).join(" · ")}`
+        : "**Context — AGENTS.md** · none in this project");
+    const full = opts.detail === "full";
+    const shown = full ? mem.facts : mem.facts.slice(0, TLDR_FACTS);
+    const rest = mem.facts.length - shown.length;
+    out.push(mem.facts.length
+        ? `**Memory** · ${plural(mem.facts.length, "fact")}\n${shown
+            .map((f) => `- ${full ? f.text : clip(f.text, TLDR_CHARS)}${f.verification_status === "verified" ? " ✓" : ""}`)
+            .join("\n")}${rest ? `\n\n…and ${plural(rest, "more fact")}, in the full card` : ""}`
+        : "**Memory** · no facts yet");
+    const rows = Object.entries(meta).map(([k, v]) => `| ${k.slice(META_NS.length + 1)} | \`${v.source}\` | \`${v.mediaType}\` |`);
+    out.push(["**Discovery**", "| concern | source | media type |", "|---|---|---|", ...rows].join("\n"));
+    return out.join("\n\n");
+}

package/dist/server.d.ts

@@ -5,7 +5,7 @@
  *   context   — read_agents_md · list_agents_md_sections · author_agents_md   (this project's AGENTS.md)
  *   memory    — remember · recall · forget                                    (a .fafm file)
  *   identity  — whoami                                                        (this server's .fafa)
- *   discovery — list_context_sources · render_context_card                    (what's published, and how)
+ *   discovery — list_context_sources · render_context_card · save_context_card (what's published, and how)
  *
  * ...exposed through the two mechanisms already in the ecosystem:
  *
@@ -46,11 +46,15 @@ export declare function serverCard(): {
         };
     };
 };
-/**
- * @param root  directory holding `AGENTS.md`, `project.fafm`, `.well-known/`.
- *              Defaults to the package root; a deploy points `MCP_CONTEXT_CARD_ROOT`
- *              at a real project, a test points it at a fixture.
- */
-export declare function createServer(root?: string): Server;
+/** 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. */
+export declare const INSTRUCTIONS: string;
+export interface ServerOptions {
+    /** Open a saved file for the person. Set only for a local (stdio) server;
+     *  over HTTP the browser would open on the server, so it stays unset. */
+    openFile?: (path: string) => void;
+}
+export declare function createServer(root?: string, opts?: ServerOptions): Server;
 /** Connect a server instance to a transport (stdio or http). */
-export declare function serve(transport: Transport, root?: string): Promise<Server>;
+export declare function serve(transport: Transport, root?: string, opts?: ServerOptions): Promise<Server>;

package/dist/server.js

@@ -5,7 +5,7 @@
  *   context   — read_agents_md · list_agents_md_sections · author_agents_md   (this project's AGENTS.md)
  *   memory    — remember · recall · forget                                    (a .fafm file)
  *   identity  — whoami                                                        (this server's .fafa)
- *   discovery — list_context_sources · render_context_card                    (what's published, and how)
+ *   discovery — list_context_sources · render_context_card · save_context_card (what's published, and how)
  *
  * ...exposed through the two mechanisms already in the ecosystem:
  *
@@ -17,15 +17,16 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { findSection, parseAgentsMd } from "./agents-md.js";
 import { authorAgentsMd } from "./author.js";
 import { forget, parseFafm, recall, remember } from "./memory.js";
 import { identity, serverCardMeta, whoami } from "./identity.js";
-import { renderCard, safeAccent } from "./render-card.js";
+import { renderCard, renderCardText, safeAccent } from "./render-card.js";
 export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
-import { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
+import { NAME, VERSION, SERVER_CARD_URI, CARD_UI_URI, MCP_APP_MIME, UI_EXTENSION } from "./constants.js";
 const here = dirname(fileURLToPath(import.meta.url));
 /** Default package root — `dist/` at runtime, `src/` under tsx. Both are one up. */
 export const ROOT = join(here, "..");
@@ -39,16 +40,46 @@ export function serverCard() {
     return { name: NAME, version: VERSION, _meta: serverCardMeta() };
 }
 const text = (s) => ({ content: [{ type: "text", text: s }] });
+/** 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. */
+export const INSTRUCTIONS = "This server publishes a project's context (AGENTS.md), memory (project.fafm) and identity (.well-known/fafa). " +
+    "Read them with read_agents_md, recall and whoami; list_context_sources says what is published and where. " +
+    "When the user wants to see the context card: hosts that support MCP Apps display it inline from render_context_card. " +
+    "Otherwise, don't paste the card's HTML into the conversation. Call save_context_card: it writes context-card.html " +
+    "into the project, opens it in the user's browser when this server runs locally, and returns the card as Markdown " +
+    "with a link to the saved file. Show the user that Markdown as returned, including the link, so they see the card " +
+    "in the chat and can open the full version in a browser.";
+/** Theme / accent / expanded from tool arguments, shared by render and save. */
+function cardOptions(args) {
+    const theme = args.theme;
+    return {
+        theme: (["light", "dark", "auto"].includes(theme) ? theme : "auto"),
+        accent: safeAccent(args.accent),
+        expanded: args.expanded === true || args.expanded === "true",
+    };
+}
+const CARD_ARGS = {
+    theme: { type: "string", enum: ["light", "dark", "auto"], description: "default: auto" },
+    accent: { type: "string", description: "CSS hex colour, e.g. #FF702D (default: the AAIF palette)" },
+    expanded: { type: "boolean", description: "render every AGENTS.md section open (default: collapsed)" },
+};
 /**
  * @param root  directory holding `AGENTS.md`, `project.fafm`, `.well-known/`.
  *              Defaults to the package root; a deploy points `MCP_CONTEXT_CARD_ROOT`
  *              at a real project, a test points it at a fixture.
  */
-export function createServer(root = ROOT) {
+/** True when the connected client declared MCP Apps support
+ *  (capabilities.extensions["io.modelcontextprotocol/ui"].mimeTypes). */
+function hostRendersApps(server) {
+    const ext = server.getClientCapabilities()?.extensions?.[UI_EXTENSION];
+    return Array.isArray(ext?.mimeTypes) && ext.mimeTypes.includes(MCP_APP_MIME);
+}
+export function createServer(root = ROOT, opts = {}) {
     const AGENTS = join(root, "AGENTS.md");
     const FAFM = join(root, "project.fafm");
     const FAFA = join(root, ".well-known/fafa");
-    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {}, resources: {} } });
+    const server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS });
     // ── Mechanism 1: the Server Card resource + its _meta context block ───
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
         resources: [
@@ -58,9 +89,23 @@ export function createServer(root = ROOT) {
                 description: "This server's identity + the _meta context block.",
                 mimeType: "application/json",
             },
+            {
+                uri: CARD_UI_URI,
+                name: "Context Card",
+                description: "The context card as an MCP App: identity, AGENTS.md, memory and discovery, rendered inline by hosts that support MCP Apps.",
+                mimeType: MCP_APP_MIME,
+            },
         ],
     }));
     server.setRequestHandler(ReadResourceRequestSchema, async (req) => {
+        if (req.params.uri === CARD_UI_URI) {
+            // Rendered at read time from the project's own files. The card is
+            // self-contained (inline CSS, no external requests), and its one script
+            // is progressive enhancement, so it still works in a strict sandbox.
+            return {
+                contents: [{ uri: CARD_UI_URI, mimeType: MCP_APP_MIME, text: renderCard(root, { theme: "auto" }) }],
+            };
+        }
         if (req.params.uri !== SERVER_CARD_URI) {
             throw new Error(`unknown resource: ${req.params.uri}`);
         }
@@ -82,6 +127,8 @@ export function createServer(root = ROOT) {
         tools: [
             {
                 name: "read_agents_md",
+                title: "Read AGENTS.md",
+                annotations: { title: "Read AGENTS.md", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Return this project's AGENTS.md — the whole file, or one section by heading. The instructions a client would otherwise have to know to look for and read wholesale.",
                 inputSchema: {
                     type: "object",
@@ -95,16 +142,22 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "author_agents_md",
+                title: "Draft an AGENTS.md",
+                annotations: { title: "Draft an AGENTS.md", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Author an AGENTS.md for this project and return the draft — BETTER from repo facts alone (via agents-md-facts: real build/test commands, entry points, toolchain conventions, nothing invented), or BEST when a project.faf exists (facts plus its structured goal/who/why as a second managed block ahead of them). Does not write a file.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "list_agents_md_sections",
+                title: "List AGENTS.md Sections",
+                annotations: { title: "List AGENTS.md Sections", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "List the headings in this project's AGENTS.md, so a client can pull one section instead of spending context on the whole file.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "remember",
+                title: "Remember a Fact",
+                annotations: { title: "Remember a Fact", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Persist a fact past the session boundary — written to a .fafm file, not held in memory. Reusing an existing id replaces that fact's text in place (no duplicate); a new id appends. Facts are written verification_status: unverified.",
                 inputSchema: {
                     type: "object",
@@ -123,6 +176,8 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "recall",
+                title: "Recall a Fact",
+                annotations: { title: "Recall a Fact", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Retrieve a fact stored in a previous session by id. Exact lookup — not fuzzy or substring.",
                 inputSchema: {
                     type: "object",
@@ -137,6 +192,8 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "forget",
+                title: "Forget a Fact",
+                annotations: { title: "Forget a Fact", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Remove a fact by id — to correct or drop something stale. A missing id is reported, not an error.",
                 inputSchema: {
                     type: "object",
@@ -151,23 +208,46 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "whoami",
+                title: "Who Am I",
+                annotations: { title: "Who Am I", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "This server's own identity — name, vendor, version, status, license — from its .fafa card.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "list_context_sources",
+                title: "List Context Sources",
+                annotations: { title: "List Context Sources", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "What context does this project publish (AGENTS.md, memory, identity), in what media types, and through which discovery surface. For a client connecting cold.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
                 name: "render_context_card",
+                title: "Render Context Card",
+                // MCP Apps: hosts that support it render the card inline from this
+                // resource. Both key forms, as the official ext-apps helper writes them.
+                _meta: { ui: { resourceUri: CARD_UI_URI }, "ui/resourceUri": CARD_UI_URI },
+                annotations: { title: "Render Context Card", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
                 description: "Render the whole card — identity, AGENTS.md, memory, discovery — as one self-contained HTML page a person can read or screenshot. AGENTS.md sections collapse by default; pass expanded:true for the full render. Also served at GET /card (?expand=all) over the HTTP transport.",
+                inputSchema: { type: "object", properties: CARD_ARGS },
+            },
+            {
+                name: "save_context_card",
+                title: "Save Context Card",
+                annotations: { title: "Save Context Card", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+                description: "Write the context card to context-card.html in the project and, when this server runs locally, open it in the person's browser. Returns the card as Markdown (identity, AGENTS.md sections, memory, discovery) plus a clickable link to the saved file. Use this instead of pasting render_context_card's HTML into a chat that can't display it. Replaces any earlier context-card.html.",
                 inputSchema: {
                     type: "object",
                     properties: {
-                        theme: { type: "string", enum: ["light", "dark", "auto"], description: "default: auto" },
-                        accent: { type: "string", description: "CSS hex colour, e.g. #FF702D (default: the AAIF palette)" },
-                        expanded: { type: "boolean", description: "render every AGENTS.md section open (default: collapsed)" },
+                        ...CARD_ARGS,
+                        open: {
+                            type: "boolean",
+                            description: "open the saved card in the person's browser when the server runs locally (default: true)",
+                        },
+                        detail: {
+                            type: "string",
+                            enum: ["tldr", "full"],
+                            description: "the Markdown reply: tldr (default) shows five facts, each cut short; full shows every fact whole. The saved file always has everything.",
+                        },
                     },
                 },
             },
@@ -217,19 +297,33 @@ export function createServer(root = ROOT) {
             case "whoami":
                 return text(whoami(root));
             case "render_context_card": {
-                const rawExpanded = args.expanded;
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: renderCard(root, {
-                                theme: (["light", "dark", "auto"].includes(args.theme) ? args.theme : "auto"),
-                                accent: safeAccent(args.accent),
-                                expanded: rawExpanded === true || rawExpanded === "true",
-                            }),
-                        },
-                    ],
-                };
+                if (hostRendersApps(server)) {
+                    // The host renders the card itself from CARD_UI_URI, so the model
+                    // gets a short summary instead of a whole HTML page.
+                    const doc = parseAgentsMd(AGENTS);
+                    const mem = parseFafm(FAFM);
+                    const sections = doc?.sections.length ?? 0;
+                    const facts = mem.facts.length;
+                    return text(`Showing the context card for ${NAME}: AGENTS.md with ${sections} section${sections === 1 ? "" : "s"}, ` +
+                        `${facts} remembered fact${facts === 1 ? "" : "s"}, and this server's identity. ` +
+                        "The card is displayed to the user; call read_agents_md or recall for the text itself.");
+                }
+                return text(renderCard(root, cardOptions(args)));
+            }
+            case "save_context_card": {
+                const out = join(root, "context-card.html");
+                writeFileSync(out, renderCard(root, cardOptions(args)));
+                // Many hosts won't follow a file:// link, so a local server opens it.
+                const raw = args.open;
+                const opened = !!opts.openFile && raw !== false && raw !== "false";
+                if (opened)
+                    opts.openFile(out);
+                return text(`${renderCardText(root, { detail: args.detail === "full" ? "full" : "tldr" })}\n\n` +
+                    "_In a host that supports MCP Apps, this card shows inline._\n\n---\n\n" +
+                    (opened ? "Opened the full card in your browser.\n\n" : "") +
+                    `**[Open the full card in your browser](${pathToFileURL(out).href})**\n\n` +
+                    // Some hosts won't follow a file:// link; a code block gets a copy button.
+                    `Or copy this into your browser's address bar:\n\n\`\`\`\n${pathToFileURL(out).href}\n\`\`\`\n\nSaved to ${out}`);
             }
             case "list_context_sources": {
                 const doc = parseAgentsMd(AGENTS);
@@ -253,7 +347,10 @@ export function createServer(root = ROOT) {
                         present: identity(root) !== null,
                     },
                     surfaces: {
-                        mcp: { serverCard: `resource ${SERVER_CARD_URI}` },
+                        mcp: {
+                            serverCard: `resource ${SERVER_CARD_URI}`,
+                            card: `resource ${CARD_UI_URI} (MCP App, ${MCP_APP_MIME})`,
+                        },
                         http: {
                             serverCard: "GET /.well-known/mcp/server-card",
                             aiCatalog: "GET /.well-known/ai-catalog.json",
@@ -269,13 +366,14 @@ export function createServer(root = ROOT) {
     return server;
 }
 /** Connect a server instance to a transport (stdio or http). */
-export async function serve(transport, root = ROOT) {
-    const server = createServer(root);
+export async function serve(transport, root = ROOT, opts = {}) {
+    const server = createServer(root, opts);
     await server.connect(transport);
     return server;
 }
 // Direct run (incl. the demo's spawned child) → stdio. pathToFileURL keeps
 // this correct on Windows, where argv[1] is a `C:\...` path.
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-    await serve(new StdioServerTransport());
+    const { openInBrowser } = await import("./open.js");
+    await serve(new StdioServerTransport(), ROOT, { openFile: openInBrowser });
 }

package/docs/MECHANISMS.md

@@ -29,7 +29,7 @@ Both return:
 ```jsonc
 {
   "name": "mcp-context-card",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "_meta": {
     "io.github.Wolfe-Jam.mcp-context-card/context": {
       "source": "AGENTS.md",
@@ -118,7 +118,9 @@ GET /.well-known/ai-catalog.json
 
 The same three sources also render as **the card** — `GET /card` /
 `render_context_card` / `docs/card.html` — the human view of exactly what a
-machine reads below.
+machine reads below. Hosts that support MCP Apps show it inline from the
+`ui://mcp-context-card/card.html` resource; elsewhere `save_context_card`
+writes it to `context-card.html` and returns it as Markdown.
 
 The same three sources back **both** discovery mechanisms:
 

package/docs/WIRING.md

@@ -83,7 +83,8 @@ And to discover what a server offers before committing to it:
 await client.callTool({ name: "list_context_sources", arguments: {} });
 // → { context: { source: "AGENTS.md", mediaType: "text/markdown", present: true, sections: 10 },
 //     memory:  { … }, identity: { … },
-//     surfaces: { mcp: { serverCard: "resource mcp-context-card://server-card" },
+//     surfaces: { mcp: { serverCard: "resource mcp-context-card://server-card",
+//                        card: "resource ui://mcp-context-card/card.html (MCP App, text/html;profile=mcp-app)" },
 //                 http: { serverCard: "GET /.well-known/mcp/server-card",
 //                         aiCatalog: "GET /.well-known/ai-catalog.json",
 //                         card: "GET /card" } } }

package/docs/card-dark.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.2.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -108,13 +108,13 @@ details.ctx-section>.md{padding:0 0 16px}
     <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
 <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
     <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
-<p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
 npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
 npm run demo          # end to end: all tools over stdio, then over stateless HTTP
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
+<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the ten tools + the Server Card and card resources</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>

package/docs/card-light.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.2.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -108,13 +108,13 @@ details.ctx-section>.md{padding:0 0 16px}
     <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
 <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
     <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
-<p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
 npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
 npm run demo          # end to end: all tools over stdio, then over stateless HTTP
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
+<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the ten tools + the Server Card and card resources</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>

package/docs/card.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.2.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -108,13 +108,13 @@ details.ctx-section>.md{padding:0 0 16px}
     <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
 <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
     <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
-<p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
 npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
 npm run demo          # end to end: all tools over stdio, then over stateless HTTP
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
+<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the ten tools + the Server Card and card resources</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>

package/docs/index.html

@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.2.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -108,13 +108,13 @@ details.ctx-section>.md{padding:0 0 16px}
     <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
 <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
     <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
-<p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+<p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
 npm run typecheck   # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
 npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
 npm run demo          # end to end: all tools over stdio, then over stateless HTTP
 npm run version:check # every version-bearing spot agrees with package.json
 npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project</code></pre>
-<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the nine tools + the Server Card resource</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
+<p>CI runs <code>version:check → faf:check → typecheck → build → test:coverage → demo</code> on Linux, macOS, and Windows for every push and PR to <code>main</code> (<code>.github/workflows/ci.yml</code>), plus <code>catalog:check</code> / <code>card:check</code>, <code>faf-cli check project.faf --strict</code> (the repo dogfoods a <code>project.faf</code> — this keeps it Trophy), and <code>faf:nudge</code> (PR-only, non-blocking — warns if the code's shape moved without <code>project.faf</code>) on Linux.</p></div></details><details class="ctx-section" id="layout"><summary>Layout</summary><div class="md"><table><thead><tr><th>Path</th><th>What</th></tr></thead><tbody><tr><td><code>src/server.ts</code></td><td>the MCP server — the ten tools + the Server Card and card resources</td></tr><tr><td><code>src/agents-md.ts</code></td><td>reads and section-splits this file</td></tr><tr><td><code>src/author.ts</code></td><td><code>author_agents_md</code> — BETTER via <code>agents-md-facts</code>, BEST when <code>project.faf</code> exists</td></tr><tr><td><code>src/md.ts</code></td><td>a minimal dependency-free Markdown → HTML renderer</td></tr><tr><td><code>src/render-card.ts</code></td><td>the card — identity + this file + memory + discovery, as one HTML page</td></tr><tr><td><code>src/memory.ts</code> → <code>src/faf/parse-fafm.ts</code></td><td>file-backed <code>remember</code> / <code>recall</code> / <code>forget</code></td></tr><tr><td><code>src/identity.ts</code></td><td><code>whoami</code> (<code>.fafa</code> → <code>package.json</code> fallback) + the <code>_meta</code> context block</td></tr><tr><td><code>src/catalog-gen.ts</code></td><td>writes <code>.well-known/ai-catalog.json</code> from the same three sources</td></tr><tr><td><code>src/transport/http.ts</code></td><td>the stateless Streamable HTTP app (Hono)</td></tr><tr><td><code>src/bin.ts</code></td><td>the entry point (<code>resolveLaunch</code>) — <code>stdio</code> · <code>--http</code> · <code>card</code> · <code>--help</code> · <code>--version</code></td></tr><tr><td><code>src/faf/parse-fafm.ts</code> · <code>parse-fafa.ts</code></td><td>the <code>.fafm</code> / <code>.fafa</code> parsers</td></tr></tbody></table></div></details><details class="ctx-section" id="conventions"><summary>Conventions</summary><div class="md"><ul><li>TypeScript strict, ESM only (<code>&quot;type&quot;: &quot;module&quot;</code>, <code>.js</code> import specifiers).</li><li>Tests use <code>node:test</code> + <code>node:assert/strict</code> — no test framework.</li><li>Every source file opens with a comment stating what it is and why.</li><li>Conventional Commit messages (<code>feat:</code>, <code>fix:</code>, <code>chore:</code>, <code>test:</code>, <code>docs:</code>).</li></ul></div></details><details class="ctx-section" id="the-invariant"><summary>The invariant</summary><div class="md"><p><code>src/identity.ts</code>, <code>src/catalog-gen.ts</code>, and <code>src/render-card.ts</code> all describe the <strong>same three sources</strong>: this file, <code>project.fafm</code>, <code>.well-known/fafa</code>. Change what one exposes and you must change the others. <code>npm run catalog:check</code> and <code>npm run card:check</code> enforce it in CI — each regenerates its surface and fails on any diff.</p></div></details><details class="ctx-section" id="safety"><summary>Safety</summary><div class="md"><ul><li>Branch off <code>main</code>; CI must be green before merge.</li><li><code>npm run demo</code> writes a fact to <code>project.fafm</code> and restores the file on exit — don't kill it mid-run.</li><li>No secrets live in this repo; never add any.</li></ul></div></details><details class="ctx-section" id="definition-of-done"><summary>Definition of done</summary><div class="md"><p><code>npm run typecheck &amp;&amp; npm run build &amp;&amp; npm test &amp;&amp; npm run demo</code> all green, plus <code>npm run catalog:check</code> and <code>npm run card:check</code> clean if you touched <code>AGENTS.md</code>, <code>project.fafm</code>, or <code>.well-known/fafa</code>, and <code>npm run faf:check</code> green if you changed the layout, a dependency, or the identity. On a version bump, <code>npm run version:check</code> green (it lists every spot that must move together) and <code>project.faf</code> still Trophy (<code>faf-cli check project.faf --strict</code>). If CI's <code>faf:nudge</code> warns on your PR, reconcile <code>project.faf</code> (and re-check <code>project.fafm</code> facts if <code>AGENTS.md</code> moved) or say why it's fine.</p></div></details><details class="ctx-section" id="authoring-this-file"><summary>Authoring this file</summary><div class="md"><p><code>AGENTS.md</code> here is maintained by hand. The <code>author_agents_md</code> tool (or <code>faf export --agents</code>) would draft a BEST version straight from this repo's own <code>project.faf</code> plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div></details></div>
   </section>
   <section>
     <p class="label">Memory — 4 facts</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-context-card",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "mcpName": "io.github.Wolfe-Jam/mcp-context-card",
   "description": "The essential MCP components for a project's context (AGENTS.md), cross-session memory, and identity — a base MCP on its own, or a drop-in extension for any existing MCP server. Discoverable through the Server Card _meta block and ai-catalog.json sibling entries.",
   "keywords": [

package/project.faf

@@ -20,7 +20,7 @@ stack:
 tech_stack: [TypeScript, "@modelcontextprotocol/sdk", "agents-md-facts", hono, "@hono/node-server", yaml]
 human_context:
   who: MCP host and server implementers who want a project's AGENTS.md, memory, and identity available over MCP without inventing an ad-hoc shape for each.
-  what: The essential context, memory, and identity components for MCP — usable as a base MCP on its own, or dropped into any existing MCP server as an extension. Nine tools — read_agents_md / list_agents_md_sections / author_agents_md (context), remember / recall / forget (memory), whoami (identity), list_context_sources / render_context_card (discovery) — exposed through the Server Card _meta block and a self-published ai-catalog.json. Dual transport (stdio + stateless Streamable HTTP).
+  what: The essential context, memory, and identity components for MCP — usable as a base MCP on its own, or dropped into any existing MCP server as an extension. Ten tools — read_agents_md / list_agents_md_sections / author_agents_md (context), remember / recall / forget (memory), whoami (identity), list_context_sources / render_context_card / save_context_card (discovery) — exposed through the Server Card _meta block and a self-published ai-catalog.json. Dual transport (stdio + stateless Streamable HTTP).
   why: AGENTS.md is the de-facto standard for agent instructions, but a client has to know the file exists and read it whole. There is no standard way for a server to publish "here is my AGENTS.md, here is what I remember, here is who I am" — every server that wants this grows its own shape, or does without. This does it once, through mechanisms that already exist — as a base MCP, or dropped into what you've already built.
   where: github.com/Wolfe-Jam/mcp-context-card
   when: "2026-08-12"

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.Wolfe-Jam/mcp-context-card",
   "title": "mcp-context-card",
   "description": "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "repository": {
     "url": "https://github.com/Wolfe-Jam/mcp-context-card",
     "source": "github"
@@ -13,7 +13,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "mcp-context-card",
-      "version": "1.1.0",
+      "version": "1.2.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"