mcp-context-card 1.1.1 → 1.3.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.1"
+  version: "1.3.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

@@ -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,73 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 1.3.0
+
+Your project, with nothing to configure.
+
+- **Finds your project from the host.** With no `MCP_CONTEXT_CARD_ROOT`, a
+  local (stdio) server asks the host which project you're in, through MCP
+  roots (goose sends its session's working directory), and follows it when
+  it changes. It falls back to the directory it was started in if that has
+  an `AGENTS.md`, then to its own folder, as before. An explicit
+  `MCP_CONTEXT_CARD_ROOT` always wins; HTTP is unchanged.
+- **`list_context_sources`** reports `project: { path, from }`: which
+  project the server is reading, and how it found it.
+- **`save_context_card`** opens its reply with what it did, as a plain fact:
+  `New file:` (with one line on what the file is) or `Updated:`, and the
+  path.
+- **An empty project gets next steps, not dead ends,** on both the HTML and
+  the text card: no `AGENTS.md` yet → ask your agent to draft one
+  (`author_agents_md`, from the repo's real build and test commands); no
+  facts yet → ask it to remember something. The placeholder "MCP context
+  card" pill is gone.
+- **A project with no identity file** (no `.well-known/fafa`, no
+  `package.json`) is named after its folder on the card, not after this
+  server.
+
+- **HTML comments in `AGENTS.md` are hidden** on the card, as GitHub hides
+  them. `agents-md-facts` marks its managed block with comments, and the
+  card showed them as text. Comments inside code stay, as content.
+
+No API change. 134 tests, all green.
+
+## 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.

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) ·
@@ -126,22 +146,25 @@ or redirected (`> card.html`, a script, CI) it writes raw HTML to stdout instead
 
 ### Wire it into a host
 
-Claude Desktop, Cursor, or any stdio host:
+goose, Claude Desktop, Cursor, or any stdio host:
 
 ```jsonc
 {
   "mcpServers": {
     "context-card": {
       "command": "npx",
-      "args": ["-y", "mcp-context-card"],
-      "env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }
+      "args": ["-y", "mcp-context-card"]
     }
   }
 }
 ```
 
-`MCP_CONTEXT_CARD_ROOT` points at the directory with your `AGENTS.md`. The
-memory tools work with or without it; identity is optional. Over HTTP instead:
+No path to configure: the server asks the host which project you're in (MCP
+roots — goose sends its session's working directory), then falls back to the
+directory it was started in if that has an `AGENTS.md`. `list_context_sources`
+reports which project it picked and how. To pin one project instead, set
+`"env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }`; that always
+wins. Identity is optional. Over HTTP instead:
 `PORT=8080 npx mcp-context-card`. Requires Node ≥20.
 
 If `command: "npx"` fails to spawn (`spawn npx ENOENT` — seen on Cursor, whose
@@ -191,15 +214,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, so they're
-marked destructive and a host can ask before running them. Every tool carries a
+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,
@@ -209,7 +235,7 @@ title and MCP tool annotations.
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-106 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
+134 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, and another checks
@@ -219,7 +245,7 @@ every tool's title and behaviour hints against what it actually does.
 
 | 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.1\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.3.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,13 @@ 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.
+        // With no MCP_CONTEXT_CARD_ROOT, find the user's project: the host's MCP
+        // roots, then the start directory. So a host needs no config to show yours.
+        const { openInBrowser } = await import("./open.js");
+        await serve(new StdioServerTransport(), root, {
+            openFile: openInBrowser,
+            detectRoot: !process.env.MCP_CONTEXT_CARD_ROOT,
+        });
     }
 }

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.1";
+export declare const VERSION = "1.3.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.1";
+export const VERSION = "1.3.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/md.js

@@ -58,8 +58,70 @@ const TABLE_SEP = /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/;
 function tableRow(line) {
     return line.trim().replace(/^\|/, "").replace(/\|$/, "").split("|").map((c) => c.trim());
 }
+/**
+ * Drop HTML comments, as GitHub does when it renders Markdown: tools such as
+ * agents-md-facts mark their managed blocks with them. A comment may span
+ * lines. Inside a fenced block or an inline `code` span it's content, so kept.
+ */
+function stripComments(src) {
+    const out = [];
+    let inFence = null;
+    let inComment = false;
+    for (const line of src.split("\n")) {
+        if (inFence) {
+            out.push(line);
+            if (inFence.test(line))
+                inFence = null;
+            continue;
+        }
+        const fence = !inComment && line.match(FENCE);
+        if (fence) {
+            inFence = fence[2][0] === "`" ? /^\s*```+\s*$/ : /^\s*~~~+\s*$/;
+            out.push(line);
+            continue;
+        }
+        // outside code: split on inline code spans, strip comments only between them
+        let kept = "";
+        const parts = line.split(/(`+[^`]*`+)/);
+        for (let k = 0; k < parts.length; k++) {
+            let part = parts[k];
+            if (k % 2 === 1 && !inComment) {
+                kept += part;
+                continue;
+            }
+            while (part.length) {
+                if (inComment) {
+                    const end = part.indexOf("-->");
+                    if (end < 0) {
+                        part = "";
+                    }
+                    else {
+                        part = part.slice(end + 3);
+                        inComment = false;
+                    }
+                }
+                else {
+                    const start = part.indexOf("<!--");
+                    if (start < 0) {
+                        kept += part;
+                        part = "";
+                    }
+                    else {
+                        kept += part.slice(0, start);
+                        part = part.slice(start + 4);
+                        inComment = true;
+                    }
+                }
+            }
+        }
+        // a line that held only a comment disappears, rather than leaving a blank gap
+        if (kept.trim() || !line.includes("<!--") && !line.includes("-->"))
+            out.push(kept);
+    }
+    return out.join("\n");
+}
 export function renderMarkdown(src) {
-    const lines = src.replace(/\r\n/g, "\n").split("\n");
+    const lines = stripComments(src.replace(/\r\n/g, "\n")).split("\n");
     const out = [];
     let i = 0;
     const flushPara = (buf) => {

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

@@ -10,11 +10,11 @@
  * is the expand-all / print helper (TOGGLE_SCRIPT) — a progressive enhancement;
  * every section still opens on its own without it. Renders anywhere.
  */
-import { join } from "node:path";
+import { basename, join, resolve } from "node:path";
 import { parseAgentsMd } from "./agents-md.js";
 import { parseFafm } from "./memory.js";
 import { resolveIdentity, serverCardMeta, META_NS } from "./identity.js";
-import { NAME, SERVER_CARD_URI } from "./constants.js";
+import { SERVER_CARD_URI } from "./constants.js";
 import { escapeHtml, renderInline, renderMarkdown, slug } from "./md.js";
 /** AAIF brand orange (aaif.io). The default accent. */
 export const AAIF_ACCENT = "#FF702D";
@@ -121,7 +121,7 @@ export function renderCard(root, opts = {}) {
     const mem = parseFafm(join(root, "project.fafm"));
     const id = resolveIdentity(root);
     const meta = serverCardMeta();
-    const name = id?.displayName ?? id?.name ?? NAME;
+    const name = id?.displayName ?? id?.name ?? basename(resolve(root));
     const pills = [
         id?.vendor && id.vendor !== id.status && `<span class="pill">${escapeHtml(id.vendor)}</span>`,
         id?.agentVersion && `<span class="pill">v${escapeHtml(id.agentVersion)}</span>`,
@@ -152,7 +152,7 @@ export function renderCard(root, opts = {}) {
             : ""}</div>
     ${preamble ? `<div class="ctx-preamble md">${renderMarkdown(preamble)}</div>` : ""}
     <div class="ctx-body">${sections}</div>`
-        : `<p class="none">No AGENTS.md in this project.</p>`;
+        : `<p class="none">No AGENTS.md yet. Ask your agent to draft one: <code>author_agents_md</code> builds it from this repo's real build and test commands, nothing invented.</p>`;
     // MEMORY
     const memoryBody = mem.facts.length
         ? mem.facts
@@ -164,7 +164,7 @@ export function renderCard(root, opts = {}) {
             return `<div class="fact"><p>${renderInline(f.text)}</p><div class="meta">${tags}<span class="dot${verified ? "" : " pending"}" title="${verified ? "verified" : f.verification_status ?? "unverified"}"></span></div></div>`;
         })
             .join("")
-        : `<p class="none">No facts yet.</p>`;
+        : `<p class="none">No facts yet. Ask your agent to remember something, and it lands here.</p>`;
     // DISCOVERY
     const rows = Object.entries(meta)
         .map(([k, v]) => {
@@ -184,7 +184,7 @@ export function renderCard(root, opts = {}) {
 <main class="card">
   <div class="top">
     <h1>${escapeHtml(name)}</h1>
-    <div class="pills">${pills || '<span class="pill">MCP context card</span>'}</div>
+    ${pills ? `<div class="pills">${pills}</div>` : ""}
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -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 ?? basename(resolve(root));
+    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 yet. `author_agents_md` drafts one from this repo's real build and test commands, nothing invented.");
+    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. Ask your agent to remember something, and it lands here.");
+    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,20 @@ 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;
+    /** No root was configured: find the user's project instead — the client's
+     *  MCP roots, then `cwd` if it holds an AGENTS.md, then `root`. Local only. */
+    detectRoot?: boolean;
+    /** The directory the server was started in (default: process.cwd()). */
+    cwd?: string;
+}
+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:
  *
@@ -16,16 +16,17 @@
  */
 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 { dirname, join } from "node:path";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, RootsListChangedNotificationSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { existsSync, statSync, writeFileSync } from "node:fs";
+import { basename, 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 { identity, resolveIdentity, serverCardMeta, whoami } from "./identity.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,95 @@ 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) {
-    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: {} } });
+/** 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 server = new Server({ name: NAME, version: VERSION }, { capabilities: { tools: {}, resources: {} }, instructions: INSTRUCTIONS });
+    // ── Which project? ────────────────────────────────────────────────────
+    // Resolved per call, not at startup: a client's roots are only known once
+    // it has connected, and they can change (goose sends its session's working
+    // directory, and notifies when it moves).
+    let found;
+    server.setNotificationHandler(RootsListChangedNotificationSchema, async () => {
+        found = undefined;
+    });
+    const isDir = (p) => {
+        try {
+            return statSync(p).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    };
+    async function fromClientRoots() {
+        if (!server.getClientCapabilities()?.roots)
+            return undefined;
+        try {
+            const { roots } = await server.listRoots(undefined, { timeout: 5000 });
+            for (const r of roots) {
+                if (!r.uri.startsWith("file:"))
+                    continue;
+                const dir = fileURLToPath(r.uri);
+                if (isDir(dir))
+                    return dir;
+            }
+        }
+        catch {
+            // a client that declares roots but doesn't answer: fall through
+        }
+        return undefined;
+    }
+    async function project() {
+        if (!opts.detectRoot)
+            return { root, from: root === ROOT ? "package" : "configured" };
+        if (found)
+            return found;
+        const fromRoots = await fromClientRoots();
+        const cwd = opts.cwd ?? process.cwd();
+        found = fromRoots
+            ? { root: fromRoots, from: "client roots" }
+            : existsSync(join(cwd, "AGENTS.md"))
+                ? { root: cwd, from: "start directory" }
+                : { root, from: "package" };
+        return found;
+    }
+    const files = (dir) => ({
+        AGENTS: join(dir, "AGENTS.md"),
+        FAFM: join(dir, "project.fafm"),
+    });
     // ── Mechanism 1: the Server Card resource + its _meta context block ───
     server.setRequestHandler(ListResourcesRequestSchema, async () => ({
         resources: [
@@ -58,9 +138,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((await project()).root, { theme: "auto" }) }],
+            };
+        }
         if (req.params.uri !== SERVER_CARD_URI) {
             throw new Error(`unknown resource: ${req.params.uri}`);
         }
@@ -178,14 +272,31 @@ export function createServer(root = ROOT) {
             {
                 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.",
+                        },
                     },
                 },
             },
@@ -193,6 +304,8 @@ export function createServer(root = ROOT) {
     }));
     server.setRequestHandler(CallToolRequestSchema, async (req) => {
         const args = (req.params.arguments ?? {});
+        const { root, from } = await project();
+        const { AGENTS, FAFM } = files(root);
         switch (req.params.name) {
             case "read_agents_md": {
                 const doc = parseAgentsMd(AGENTS);
@@ -235,24 +348,45 @@ 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 ${resolveIdentity(root)?.name ?? basename(root)}: 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");
+                const existed = existsSync(out);
+                writeFileSync(out, renderCard(root, cardOptions(args)));
+                // First line, plain fact: models tend to rewrite the end of a reply, not the start.
+                const saved = existed
+                    ? `**Updated:** \`context-card.html\` in your project, at ${out}.`
+                    : `**New file:** \`context-card.html\` in your project, at ${out}. A snapshot of the context your agent reads.`;
+                // 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(`${saved}\n\n` +
+                    `${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\`\`\``);
             }
             case "list_context_sources": {
                 const doc = parseAgentsMd(AGENTS);
                 const mem = parseFafm(FAFM);
                 return text(JSON.stringify({
+                    project: { path: root, from },
                     context: {
                         source: "AGENTS.md",
                         mediaType: "text/markdown",
@@ -271,7 +405,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",
@@ -287,13 +424,15 @@ 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");
+    const pinned = process.env.MCP_CONTEXT_CARD_ROOT;
+    await serve(new StdioServerTransport(), pinned ?? ROOT, { openFile: openInBrowser, detectRoot: !pinned });
 }

package/docs/MECHANISMS.md

@@ -29,7 +29,7 @@ Both return:
 ```jsonc
 {
   "name": "mcp-context-card",
-  "version": "1.1.1",
+  "version": "1.3.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

@@ -16,15 +16,20 @@
   "mcpServers": {
     "context-card": {
       "command": "npx",
-      "args": ["-y", "mcp-context-card"],
-      "env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }
+      "args": ["-y", "mcp-context-card"]
     }
   }
 }
 ```
 
-- **`MCP_CONTEXT_CARD_ROOT`** — directory holding `AGENTS.md`, `project.fafm`, and
-  `.well-known/fafa`. Omit it and the server uses its own bundled copies.
+- **Which project.** Unset, a stdio server finds it per call: the host's first
+  MCP root (a `file://` directory), then the start directory if it holds an
+  `AGENTS.md`, then the server's own bundled copies. A `roots/list_changed`
+  notification makes the next call look again. `list_context_sources` reports
+  `project: { path, from }`.
+- **`MCP_CONTEXT_CARD_ROOT`** — pins the project: a directory holding
+  `AGENTS.md`, `project.fafm`, and `.well-known/fafa`. Always wins over roots.
+  Over HTTP there are no roots, so it's the only way to pick a project there.
 - `stdout` is the JSON‑RPC wire; logging is on `stderr`.
 - **`command: "npx"` fails to spawn on some hosts** (`spawn npx ENOENT`) — the
   host's process spawn doesn't inherit a shell `PATH` that has `npx` on it,
@@ -83,7 +88,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.1</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.3.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -114,7 +114,7 @@ npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80,
 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.1</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.3.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -114,7 +114,7 @@ npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80,
 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.1</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.3.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -114,7 +114,7 @@ npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80,
 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.1</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.3.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
@@ -114,7 +114,7 @@ npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80,
 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.1",
+  "version": "1.3.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.1",
+  "version": "1.3.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.1",
+      "version": "1.3.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"