mcp-context-card 0.5.0 → 0.5.2

package/.well-known/ai-catalog.json

@@ -18,7 +18,7 @@
       "displayName": "mcp-context-card — persistent memory (.fafm)",
       "type": "application/vnd.fafm+yaml",
       "mediaType": "application/vnd.fafm+yaml",
-      "description": "Cross-session memory — 3 fact(s), profile \"knowledge\". Recall survives a process restart. No de-facto standard for this concern yet.",
+      "description": "Cross-session memory — 4 fact(s), profile \"knowledge\". Recall survives a process restart. No de-facto standard for this concern yet.",
       "url": "./project.fafm",
       "_meta": {
         "io.github.wolfe-jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml"
@@ -29,7 +29,7 @@
       "displayName": "mcp-context-card — agent identity (.fafa)",
       "type": "application/vnd.fafa+yaml",
       "mediaType": "application/vnd.fafa+yaml",
-      "description": "Reference MCP server that makes a project's context (AGENTS.md), memory, and identity discoverable to any MCP client, through the Server Card _meta block and a self-published ai-catalog.json.",
+      "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 a self-published ai-catalog.json.",
       "url": "./.well-known/fafa",
       "_meta": {
         "io.github.wolfe-jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"

package/.well-known/fafa

@@ -8,11 +8,12 @@ version: "1.0"
 agent:
   name: "mcp-context-card"
   displayName: "mcp-context-card"
-  vendor: "reference"
-  version: "0.5.0"
+  vendor: "io.github.wolfe-jam"
+  version: "0.5.2"
   description: >-
-    Reference MCP server that makes a project's context (AGENTS.md), memory,
-    and identity discoverable to any MCP client, through the Server Card _meta
-    block and a self-published ai-catalog.json.
-  status: "reference"
+    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 a self-published ai-catalog.json.
+  status: "published"
   license: "MIT"

package/AGENTS.md

@@ -1,9 +1,10 @@
 # AGENTS.md
 
-`mcp-context-card` is an MCP server that makes a project's **context**
-(this file), **memory**, and **identity** discoverable to any MCP client —
-through the two surfaces already in the ecosystem: the Server Card `_meta`
-block and `ai-catalog.json` sibling entries.
+`mcp-context-card` is the essential MCP server for a project's **context**
+(this file), **memory**, and **identity** — usable as your base MCP, or
+dropped into any existing MCP server as an extension. Discoverable to any
+MCP client through the two surfaces already in the ecosystem: the Server
+Card `_meta` block and `ai-catalog.json` sibling entries.
 
 `read_agents_md` serves this file, section by section, over the same MCP
 connection.
@@ -40,14 +41,14 @@ Windows for every push and PR to `main` (`.github/workflows/ci.yml`).
 |---|---|
 | `src/server.ts` | the MCP server — the nine tools + the Server Card resource |
 | `src/agents-md.ts` | reads and section-splits this file |
-| `src/author.ts` | `author_agents_md` — wraps `agents-md-facts` (the AGENTS.md authoring engine) |
+| `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 |
 | `src/render-card.ts` | the card — identity + this file + memory + discovery, as one HTML page |
 | `src/memory.ts` → `src/faf/parse-fafm.ts` | file-backed `remember` / `recall` / `forget` |
 | `src/identity.ts` | `whoami` (`.fafa` → `package.json` fallback) + the `_meta` context block |
 | `src/catalog-gen.ts` | writes `.well-known/ai-catalog.json` from the same three sources |
 | `src/transport/http.ts` | the stateless Streamable HTTP app (Hono) |
-| `src/bin.ts` | the entry point (`resolveLaunch`) — `stdio` · `--http` · `card` |
+| `src/bin.ts` | the entry point (`resolveLaunch`) — `stdio` · `--http` · `card` · `--help` · `--version` |
 | `src/faf/parse-fafm.ts` · `parse-fafa.ts` | the `.fafm` / `.fafa` parsers |
 
 ## Conventions
@@ -80,6 +81,7 @@ plus `npm run catalog:check` and `npm run card:check` clean if you touched
 
 ## Authoring this file
 
-`AGENTS.md` here is maintained by hand. It can also be generated from the
-repo's `project.faf` with `faf export --agents` — the server doesn't care how
-the file was authored, only that it's valid Markdown.
+`AGENTS.md` here is maintained by hand. The `author_agents_md` tool (or
+`faf export --agents`) would draft a BEST version straight from this repo's
+own `project.faf` plus its detected facts — the server doesn't care how the
+file was authored, only that it's valid Markdown.

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
 
+## 0.5.2
+
+The soak, closed out. Two Cursor host checks — a real bug found and fixed, a
+real gap found and fixed, both confirmed against a real independent MCP host
+on the current build.
+
+- **`author_agents_md` now authors BEST, not just BETTER, when it can.**
+  BETTER is the facts-only draft from `agents-md-facts` (build/test
+  commands, entry points, conventions — nothing invented). **BEST** is that
+  plus a `## Project` section ahead of it — goal, who it's for, why, and a
+  "start here" file list — read straight from `project.faf` when one
+  exists. This is the point of the app: give the best AGENTS.md the
+  project has the material for, not a fixed floor. The tool's response
+  names the tier it produced.
+- **Fix:** `remember` on a project that had never had a `project.fafm`
+  threw `ENOENT` instead of starting one — the single most common
+  first-use case. `remember` now creates a fresh `.fafm` on first write;
+  `forget` / `parseFafm` were already safe and are unchanged. A real
+  child-process e2e test (a cold root, two separate OS processes) makes
+  this a permanent regression guard, not just a fix.
+- `docs/WIRING.md`: a note on hosts whose spawn `PATH` lacks `npx`
+  (`spawn npx ENOENT`, observed in Cursor) — point `command` at `node` +
+  the installed `dist/bin.js` instead.
+- **The README / AGENTS.md / `project.faf` / manifest reframe** — dropped
+  "Small, MIT…" / "a piece, not the toolbox" for the real positioning:
+  essential context, memory, and identity components, usable as a base MCP
+  on their own, or a drop-in extension for any existing MCP server.
+- An accuracy pass across every shipped surface, caught by re-reading
+  rather than by any check: stale test/tool counts (README, CHANGELOG,
+  and `project.faf`'s own `human_context.what` — it undercounted its own
+  tools), 3-release-old version strings sitting in two hand-shown examples
+  (`examples/README.md`, `docs/MECHANISMS.md`), a pre-rename
+  docker-compose service name (`trinity` → `context-card`), an internal
+  function that still carried the pre-rename product name (`trinityMeta` →
+  `serverCardMeta` — not a public export). `project.faf` itself rechecked
+  against the current architecture (`tech_stack`, `key_files`, `cicd`).
+- 102 tests, coverage gate held, `card:check` / `catalog:check` green,
+  `faf-cli check`: ✪ Trophy 100%, 15/15 slots.
+
+## 0.5.1
+
+First-hour ergonomics and wording, from the 0.5.0 soak.
+
+- `--help` / `-h` and `--version` / `-V` (and the `help` / `version` subcommands)
+  — a bare `mcp-context-card` is a stdio server that waits on stdin, so at a
+  terminal it looked idle with no way to ask what it was.
+- stdio mode now prints one line to **stderr** on start
+  (`… · stdio · waiting for an MCP host on stdin`) — mirrors what `--http`
+  already did. stdout stays clean for the JSON-RPC wire.
+- The npm and `server.json` descriptions no longer open with "Reference MCP
+  server" — they now match the README ("An MCP server that makes a project's
+  context, memory, and identity discoverable…"). Same in `.well-known/fafa`;
+  the three `project.fafm` facts are `type: fact`. `package.json` `author` set
+  to the LICENSE holder.
+- `.well-known/fafa` — `vendor: io.github.wolfe-jam`, `status: published`
+  (were both `reference`). Shows in `whoami` and as the card's pills.
+
 ## 0.5.0
 
 The first public release — installable, and settling in the open before a
@@ -47,7 +104,7 @@ tested server.
 
 ### Engineering
 
-- 88 tests across Linux / macOS / Windows, coverage-gated
+- 90 tests across Linux / macOS / Windows, coverage-gated
   (lines 90 / funcs 85 / branches 80, `src/` only). A real `child_process`
   spawn proves memory across a genuine process boundary; stdio/HTTP
   tool-surface parity is asserted.
@@ -70,6 +127,6 @@ tested server.
 
 ## v0.1.0 (2026-08-12)
 
-- Initial private reference implementation (as `faf-trinity`): project context,
+- Initial private implementation (as `faf-trinity`): project context,
   persistent memory, and agent identity in one MCP server, through two
   mechanisms already live in production. `demo.ts` proved all three.

package/README.md

@@ -3,8 +3,8 @@
 [![CI](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/mcp-context-card/actions/workflows/ci.yml)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-An MCP server that makes a project's context, memory, and identity discoverable
-to any MCP client — and renders them as one card you can read.
+The essential MCP server for a project's context, memory, and identity —
+discoverable to any MCP client, and rendered as one card you can read.
 
 - **context** — the project's `AGENTS.md`, served whole or one section at a time
 - **memory** — facts that persist across sessions, in a file
@@ -13,26 +13,34 @@ to any MCP client — and renders them as one card you can read.
 Discovery goes through two surfaces already in the ecosystem: the Server Card
 `_meta` block and `ai-catalog.json` sibling entries.
 
-## What it is / what it is not
+## A base MCP — or an extension for any other
 
-**It is** — an MCP server for a project's `AGENTS.md`, memory, and identity: nine
-tools, two discovery surfaces (Server Card `_meta`, `ai-catalog.json`), and a
-rendered [card](#the-card). Small, MIT — read it, `npx` it, or fork it.
+Context, memory, and identity are essential — every MCP host needs an agent
+that knows a project's instructions, remembers facts across sessions, and can
+say what it is. `mcp-context-card` is those three, done once:
 
-**It is not**
+- **Stand it up as your base MCP.** Point a host at it and an agent already
+  has `AGENTS.md` served section‑by‑section, `remember` / `recall` / `forget`
+  memory that survives a restart, and a `whoami` identity — before a single
+  tool of your own is written.
+- **Or extend any existing MCP with it.** Run it alongside a server you
+  already have — filesystem, git, a database, your own — and that agent
+  gains context, memory, and identity discovery it didn't have. Nothing to
+  migrate; it composes.
 
-- a framework or a platform — three concerns, nothing more
-- a file, shell, or search tool — it never touches your files or runs commands
-- tied to FAF — context is plain Markdown (`AGENTS.md`); the memory and identity
-  formats are swappable examples
+Nine 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:
 
 - **serve · discover · render** — this server
-- **author · keep true** — [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) (the `author_agents_md` tool wraps it)
+- **author BETTER, keep true** — [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) (`author_agents_md` wraps it for the facts layer; adds a BEST layer of its own from `project.faf` when one exists)
 - **files · shell · git** — [`server-filesystem`](https://github.com/modelcontextprotocol/servers), [`server-git`](https://github.com/modelcontextprotocol/servers) / github‑mcp‑server, your test runner's MCP
 
-A piece, not the toolbox.
+Not a framework or a platform — three concerns, nothing more. Not a file,
+shell, or search tool — it never touches your files or runs commands. Not
+tied to FAF — context is plain Markdown (`AGENTS.md`); the memory and identity
+formats are swappable examples.
 
 ## The card
 
@@ -55,7 +63,7 @@ Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
 
 | You want… | Reach for |
 |---|---|
-| an `AGENTS.md` and you don't have one | `author_agents_md` — or [`npx agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) |
+| an `AGENTS.md` and you don't have one | `author_agents_md` — BEST with a `project.faf`, BETTER without |
 | your agent to pull *one* `AGENTS.md` section on demand, not the whole file | `read_agents_md` · `list_agents_md_sections` |
 | a persistent notepad for your agent — survives restarts, no setup | `remember` · `recall` · `forget` |
 | a shareable view of what your MCP server exposes to agents | `GET /card` · `npx mcp-context-card card` |
@@ -65,20 +73,21 @@ Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
 
 ### No `AGENTS.md` yet?
 
-The `author_agents_md` tool authors one from your repo's facts — real
-build/test commands, entry points, toolchain conventions — and hands the agent
-the draft. It's a thin wrapper over
-[`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts); to author or
-keep one true outside a session:
+The `author_agents_md` tool authors one — **BETTER** from your repo's real
+facts (build/test commands, entry points, toolchain conventions, via
+[`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts)), or
+**BEST** when a `project.faf` exists: the same facts, plus its structured
+goal, who it's for, and why, as a section ahead of them. Nothing to
+configure — the tier follows what's actually there.
+([The ladder this follows.](https://github.com/Wolfe-Jam/agents-md-facts/blob/main/docs/BETTER-BEST.md))
+
+To author or keep the facts layer true outside a session:
 
 ```bash
 npx agents-md-facts          # author / refresh AGENTS.md
 npx agents-md-facts --check  # fail if missing or stale (CI, pre-commit)
 ```
 
-A `project.faf` is the next rung — a structured source that refreshes the file.
-Short model: [`agents-md-facts/docs/BETTER-BEST.md`](https://github.com/Wolfe-Jam/agents-md-facts/blob/main/docs/BETTER-BEST.md).
-
 ### See the card
 
 One command, no host, no config:
@@ -109,6 +118,11 @@ memory tools work with or without it; identity is optional. Over HTTP instead:
 [docs/WIRING.md](./docs/WIRING.md); transport choice in
 [docs/TRANSPORT.md](./docs/TRANSPORT.md).
 
+Extending an MCP you already run: most hosts accept more than one
+`mcpServers` entry — add `context-card` alongside `server-filesystem`,
+`server-git`, or your own, and every agent in that host gains context,
+memory, and identity discovery without anything else changing.
+
 ## Why
 
 `AGENTS.md` is the de-facto standard for telling a coding agent how to work in a
@@ -137,7 +151,7 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 
 | Tool | What it's for |
 |---|---|
-| `author_agents_md` | draft an `AGENTS.md` from the repo's facts (via `agents-md-facts`) — a managed block, ready to drop in |
+| `author_agents_md` | draft an `AGENTS.md` — BETTER from the repo's facts (via `agents-md-facts`), BEST when a `project.faf` exists — ready to drop in |
 | `read_agents_md` | return the project's `AGENTS.md` — whole, or one section by heading |
 | `list_agents_md_sections` | the headings, so a client pulls one section instead of the whole file |
 | `remember` | write a fact that will still be there next session |
@@ -159,9 +173,10 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
 4. **Discovery** — `list_context_sources()`, then the same server over stateless
    HTTP with its `.well-known` routes and `GET /card`.
 
-88 tests on Linux, macOS, and Windows, coverage‑gated in CI. One spawns a real
-child process and checks a remembered fact survives the restart; another checks
-the stdio and HTTP tool surfaces match.
+99 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.
 
 ## Layout
 
@@ -169,14 +184,14 @@ the stdio and HTTP tool surfaces match.
 |---|---|
 | `src/server.ts` | the nine tools + the Server Card resource |
 | `src/agents-md.ts` | reads and section‑splits `AGENTS.md` |
-| `src/author.ts` | `author_agents_md` — wraps [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts) |
+| `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 |
 | `src/render-card.ts` | the card — identity + `AGENTS.md` + memory + discovery, as one HTML page |
 | `src/memory.ts` | file‑backed `remember` / `recall` / `forget` |
 | `src/identity.ts` | `whoami` (`.fafa` → `package.json` fallback) + the `_meta` block |
 | `src/catalog-gen.ts` | writes `ai-catalog.json` from the same three sources |
 | `src/transport/http.ts` | the stateless Streamable HTTP app (Hono) |
-| `src/bin.ts` | the entry point — `stdio` · `--http` · `card` |
+| `src/bin.ts` | the entry point — `stdio` · `--http` · `card` · `--help` · `--version` |
 
 ## Related
 

package/dist/author.d.ts

@@ -1,11 +1,20 @@
 /** The markers `agents-md-facts` uses to bound its managed block. */
 export declare const BLOCK_START = "<!-- agents:from-facts:start -->";
 export declare const BLOCK_END = "<!-- agents:from-facts:end -->";
+/** The markers this file uses to bound the project.faf-sourced intent block. */
+export declare const FAF_BLOCK_START = "<!-- context:from-faf:start -->";
+export declare const FAF_BLOCK_END = "<!-- context:from-faf:end -->";
 export interface Authored {
-    /** the AGENTS.md text — a managed block, ready to drop in */
+    /** the AGENTS.md text — one or two managed blocks, ready to drop in */
     markdown: string;
     /** whether an AGENTS.md already exists at the target */
     exists: boolean;
+    /** which tier was authored — BEST only when a readable project.faf was found */
+    tier: "better" | "best";
 }
-/** Author a managed AGENTS.md block for `root`, from its repo facts. */
+/**
+ * Author AGENTS.md for `root`. BETTER from repo facts alone; BEST — facts
+ * plus the project.faf intent block, ahead of it — when a project.faf with
+ * real content exists.
+ */
 export declare function authorAgentsMd(root: string): Authored;

package/dist/author.js

@@ -1,27 +1,86 @@
 /**
- * author — author an AGENTS.md for a project from its repo facts.
+ * author — author an AGENTS.md for a project, at the tier the project earns.
  *
- * The engine is `agents-md-facts` (a published, standalone tool, AGENTS.md
- * BETTER tier): it detects real build/test commands, entry points, toolchain
- * conventions and nothing invented. This wraps it in the managed-block
- * markers so `agents-md-facts --check` (or its Action / pre-commit hook) can
- * keep the result true afterwards.
+ * BETTER: the engine is `agents-md-facts` (a published, standalone tool) —
+ * it detects real build/test commands, entry points, toolchain conventions
+ * and nothing invented. Every project gets at least this.
  *
- * A `project.faf` is the BEST tier — the same discipline plus a structured
- * source of truth that refreshes the file. This wrapper stays at BETTER; the
- * README points at the BEST path.
+ * BEST: when `project.faf` exists, its structured intent — goal, who it's
+ * for, why it exists, the files that matter most — is real, human-authored
+ * truth that no amount of repo-scanning can detect. A project with a
+ * `project.faf` gets BOTH: the facts block, unchanged, plus this intent as
+ * its own managed block ahead of it. This is the whole point of the app:
+ * give the BEST AGENTS.md when the structured source to build it from is
+ * sitting right there.
  */
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { parse } from "yaml";
 import { authorAgentsMd as authorBlock, buildRepoContext } from "agents-md-facts";
 /** The markers `agents-md-facts` uses to bound its managed block. */
 export const BLOCK_START = "<!-- agents:from-facts:start -->";
 export const BLOCK_END = "<!-- agents:from-facts:end -->";
-/** Author a managed AGENTS.md block for `root`, from its repo facts. */
+/** The markers this file uses to bound the project.faf-sourced intent block. */
+export const FAF_BLOCK_START = "<!-- context:from-faf:start -->";
+export const FAF_BLOCK_END = "<!-- context:from-faf:end -->";
+/** Read the structured intent out of `root`'s project.faf, or null if there isn't one to read. */
+function readFafIntent(root) {
+    const path = join(root, "project.faf");
+    if (!existsSync(path))
+        return null;
+    try {
+        const doc = (parse(readFileSync(path, "utf8")) ?? {});
+        const project = doc.project ?? {};
+        const humanContext = doc.human_context ?? {};
+        const intent = {
+            name: str(project.name),
+            goal: str(project.goal),
+            who: str(humanContext.who),
+            why: str(humanContext.why),
+            keyFiles: Array.isArray(doc.key_files) ? doc.key_files.map(String).filter(Boolean) : undefined,
+        };
+        // A .faf with nothing usable in it isn't a real intent source.
+        return intent.goal || intent.who || intent.why ? intent : null;
+    }
+    catch {
+        return null;
+    }
+}
+function str(v) {
+    const s = typeof v === "string" ? v.trim() : "";
+    return s || undefined;
+}
+/** Render the project.faf-sourced intent as its own managed block. */
+function fafIntentBlock(intent) {
+    const lines = ["## Project", ""];
+    if (intent.goal)
+        lines.push(intent.goal, "");
+    if (intent.who)
+        lines.push(`**Who it's for:** ${intent.who}`, "");
+    if (intent.why)
+        lines.push(`**Why:** ${intent.why}`, "");
+    if (intent.keyFiles?.length) {
+        lines.push("**Start here:**", "");
+        for (const f of intent.keyFiles)
+            lines.push(`- \`${f}\``);
+        lines.push("");
+    }
+    return `${FAF_BLOCK_START}\n${lines.join("\n").trimEnd()}\n${FAF_BLOCK_END}\n`;
+}
+/**
+ * Author AGENTS.md for `root`. BETTER from repo facts alone; BEST — facts
+ * plus the project.faf intent block, ahead of it — when a project.faf with
+ * real content exists.
+ */
 export function authorAgentsMd(root) {
-    const block = authorBlock(buildRepoContext(root)).trim();
+    const factsBlock = `${BLOCK_START}\n${authorBlock(buildRepoContext(root)).trim()}\n${BLOCK_END}\n`;
+    const exists = existsSync(join(root, "AGENTS.md"));
+    const intent = readFafIntent(root);
+    if (!intent)
+        return { markdown: factsBlock, exists, tier: "better" };
     return {
-        markdown: `${BLOCK_START}\n${block}\n${BLOCK_END}\n`,
-        exists: existsSync(join(root, "AGENTS.md")),
+        markdown: `${fafIntentBlock(intent)}\n${factsBlock}`,
+        exists,
+        tier: "best",
     };
 }

package/dist/bin.d.ts

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-export type Mode = "stdio" | "http" | "card";
+export type Mode = "stdio" | "http" | "card" | "help" | "version";
 export interface Launch {
     mode: Mode;
     /** port for http mode (ignored otherwise). */
@@ -7,14 +7,18 @@ export interface Launch {
     /** directory to read from — cwd for `card`, else MCP_CONTEXT_CARD_ROOT ?? package root. */
     root: string;
 }
+/** what a bare `--help` / `help` prints. */
+export declare const HELP = "mcp-context-card 0.5.2\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 [> f.html]  render this directory's context card to stdout\n                                      --theme light|dark    --accent #hex\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` or `--http` to see output directly.\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.
  *
- *   card               → render the cwd's card to stdout
- *   (nothing)          → stdio
- *   --http | PORT=<n>  → http
- *   --stdio            → stdio, even when PORT is set
+ *   --help  | -h  | help     → print usage
+ *   --version | -V | version → print version
+ *   card                     → render the cwd's card to stdout
+ *   (nothing)                → stdio
+ *   --http | PORT=<n>        → http
+ *   --stdio                  → stdio, even when PORT is set
  */
 export declare function resolveLaunch(argv: readonly string[], env?: NodeJS.ProcessEnv): Launch;
 /** value of `--flag <value>` in argv, or undefined. */

package/dist/bin.js

@@ -8,6 +8,8 @@
  *   mcp-context-card --stdio      → force stdio even when PORT is set
  *   mcp-context-card card         → render THIS directory's context card to stdout
  *                                   ( > card.html · --theme light|dark · --accent #hex )
+ *   mcp-context-card --help       → usage
+ *   mcp-context-card --version    → version
  *
  * MCP_CONTEXT_CARD_ROOT=/path/to/project → read AGENTS.md / project.fafm /
  *   .well-known/ from there instead of the package's own bundled copies.
@@ -15,17 +17,46 @@
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { NAME, VERSION } from "./constants.js";
 import { ROOT, serve } from "./server.js";
+/** what a bare `--help` / `help` prints. */
+export const HELP = `${NAME} ${VERSION}
+Serve a project's context (AGENTS.md), memory, and identity over MCP.
+
+USAGE
+  mcp-context-card                  stdio MCP server — what an MCP host spawns (default)
+  mcp-context-card --http           stateless Streamable HTTP on PORT (default 3000)
+  mcp-context-card --stdio          force stdio even when PORT is set
+  mcp-context-card card [> f.html]  render this directory's context card to stdout
+                                      --theme light|dark    --accent #hex
+  mcp-context-card --help           this text
+  mcp-context-card --version        print version
+
+ENV
+  MCP_CONTEXT_CARD_ROOT   read AGENTS.md / project.fafm / .well-known/ from here
+  PORT                    if set, run HTTP instead of stdio
+
+A bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,
+so it looks idle at a terminal. Try \`card\` or \`--http\` to see output directly.
+https://github.com/Wolfe-Jam/mcp-context-card
+`;
 /**
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
  * tested without spawning a process.
  *
- *   card               → render the cwd's card to stdout
- *   (nothing)          → stdio
- *   --http | PORT=<n>  → http
- *   --stdio            → stdio, even when PORT is set
+ *   --help  | -h  | help     → print usage
+ *   --version | -V | version → print version
+ *   card                     → render the cwd's card to stdout
+ *   (nothing)                → stdio
+ *   --http | PORT=<n>        → http
+ *   --stdio                  → stdio, even when PORT is set
  */
 export function resolveLaunch(argv, env = process.env) {
+    const has = (...flags) => flags.some((f) => argv.includes(f));
+    if (argv[0] === "help" || has("--help", "-h"))
+        return { mode: "help", port: 0, root: ROOT };
+    if (argv[0] === "version" || has("--version", "-V"))
+        return { mode: "version", port: 0, root: ROOT };
     if (argv[0] === "card") {
         return {
             mode: "card",
@@ -49,7 +80,13 @@ export function flagValue(argv, flag) {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
     const argv = process.argv.slice(2);
     const { mode, port, root } = resolveLaunch(argv);
-    if (mode === "card") {
+    if (mode === "help") {
+        process.stdout.write(HELP);
+    }
+    else if (mode === "version") {
+        process.stdout.write(`${VERSION}\n`);
+    }
+    else if (mode === "card") {
         const { renderCard, safeAccent } = await import("./render-card.js");
         const theme = flagValue(argv, "--theme");
         process.stdout.write(renderCard(root, {
@@ -62,9 +99,12 @@ if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href)
         const { serve: serveHttp } = await import("@hono/node-server");
         serveHttp({ fetch: httpApp(root).fetch, port });
         // stderr, not stdout — stdout is the MCP wire in stdio mode.
-        console.error(`mcp-context-card · http · :${port}  (POST /mcp · GET /card · GET /.well-known/*)`);
+        console.error(`${NAME} · http · :${port}  (POST /mcp · GET /card · GET /.well-known/*)`);
     }
     else {
+        // 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);
     }
 }

package/dist/constants.d.ts

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

package/dist/constants.js

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

package/dist/faf/parse-fafm.js

@@ -27,8 +27,29 @@ function factMap(entries) {
         m.set(k, q(v));
     return m;
 }
+/** A brand-new .fafm — what `remember()` writes the first time a project has none. */
+const FRESH_FAFM = `version: "1.1"
+memory:
+  facts: []
+  sessions: []
+  preferences: {}
+  custom: {}
+`;
+/**
+ * Load the .fafm at `path`. A missing file is not an error here — it means
+ * "no memory yet", and remember()/forget() need a document to edit even
+ * before anything has ever been written. Any other read error (permissions,
+ * a directory in the way, …) still throws.
+ */
 function load(path) {
-    return parseDocument(readFileSync(path, "utf8"));
+    try {
+        return parseDocument(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return parseDocument(FRESH_FAFM);
+        throw err;
+    }
 }
 export function parseFafm(path) {
     let doc;

package/dist/identity.d.ts

@@ -16,7 +16,7 @@ export declare function whoami(root: string): string;
  * other two point at their worked-example artifacts; `memory` carries a note
  * because there is no de-facto standard for it yet.
  */
-export declare function trinityMeta(): {
+export declare function serverCardMeta(): {
     readonly "io.github.wolfe-jam.mcp-context-card/context": {
         readonly source: "AGENTS.md";
         readonly mediaType: "text/markdown";

package/dist/identity.js

@@ -61,7 +61,7 @@ export function whoami(root) {
  * other two point at their worked-example artifacts; `memory` carries a note
  * because there is no de-facto standard for it yet.
  */
-export function trinityMeta() {
+export function serverCardMeta() {
     return {
         [`${META_NS}/context`]: {
             source: "AGENTS.md",

package/dist/render-card.js

@@ -12,7 +12,7 @@
 import { join } from "node:path";
 import { parseAgentsMd } from "./agents-md.js";
 import { parseFafm } from "./memory.js";
-import { resolveIdentity, trinityMeta, META_NS } from "./identity.js";
+import { resolveIdentity, serverCardMeta, META_NS } from "./identity.js";
 import { NAME, SERVER_CARD_URI } from "./constants.js";
 import { escapeHtml, renderInline, renderMarkdown, slug } from "./md.js";
 /** AAIF brand orange (aaif.io). The default accent. */
@@ -92,7 +92,7 @@ export function renderCard(root, opts = {}) {
     const agents = parseAgentsMd(join(root, "AGENTS.md"));
     const mem = parseFafm(join(root, "project.fafm"));
     const id = resolveIdentity(root);
-    const meta = trinityMeta();
+    const meta = serverCardMeta();
     const name = id?.displayName ?? id?.name ?? NAME;
     const pills = [
         id?.vendor && id.vendor !== id.status && `<span class="pill">${escapeHtml(id.vendor)}</span>`,

package/dist/server.d.ts

@@ -2,10 +2,10 @@
  * mcp-context-card server — makes a project's context, memory, and identity
  * discoverable to any MCP client.
  *
- *   context   — read_agents_md · list_agents_md_sections   (this project's AGENTS.md)
- *   memory    — remember · recall · forget                 (a .fafm file)
- *   identity  — whoami                                     (this server's .fafa)
- *   discovery — list_context_sources                       (what's published, and how)
+ *   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)
  *
  * ...exposed through the two mechanisms already in the ecosystem:
  *

package/dist/server.js

@@ -2,10 +2,10 @@
  * mcp-context-card server — makes a project's context, memory, and identity
  * discoverable to any MCP client.
  *
- *   context   — read_agents_md · list_agents_md_sections   (this project's AGENTS.md)
- *   memory    — remember · recall · forget                 (a .fafm file)
- *   identity  — whoami                                     (this server's .fafa)
- *   discovery — list_context_sources                       (what's published, and how)
+ *   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)
  *
  * ...exposed through the two mechanisms already in the ecosystem:
  *
@@ -22,7 +22,7 @@ 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, trinityMeta, whoami } from "./identity.js";
+import { identity, serverCardMeta, whoami } from "./identity.js";
 import { renderCard, safeAccent } from "./render-card.js";
 export { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
 import { NAME, VERSION, SERVER_CARD_URI } from "./constants.js";
@@ -36,7 +36,7 @@ export const ROOT = join(here, "..");
  * `/.well-known/mcp/server-card`.
  */
 export function serverCard() {
-    return { name: NAME, version: VERSION, _meta: trinityMeta() };
+    return { name: NAME, version: VERSION, _meta: serverCardMeta() };
 }
 const text = (s) => ({ content: [{ type: "text", text: s }] });
 /**
@@ -88,7 +88,7 @@ export function createServer(root = ROOT) {
             },
             {
                 name: "author_agents_md",
-                description: "Author an AGENTS.md for this project from its repo facts (via agents-md-facts) and return the draft — a managed block, ready to drop in. Detects real build/test commands, entry points, and toolchain conventions; nothing invented. Does not write a file.",
+                description: "Author an AGENTS.md for this project and return the draft — BETTER from repo facts alone (via agents-md-facts: real build/test commands, entry points, toolchain conventions, nothing invented), or BEST when a project.faf exists (facts plus its structured goal/who/why as a second managed block ahead of them). Does not write a file.",
                 inputSchema: { type: "object", properties: {} },
             },
             {
@@ -170,9 +170,10 @@ export function createServer(root = ROOT) {
             }
             case "author_agents_md": {
                 const a = authorAgentsMd(root);
+                const tier = a.tier === "best" ? "BEST (project.faf + facts)" : "BETTER (facts only)";
                 const note = a.exists
-                    ? "AGENTS.md already exists — diff this managed block in, don't overwrite"
-                    : "no AGENTS.md yet — write this, then `npx agents-md-facts --check` keeps it true";
+                    ? `${tier} — AGENTS.md already exists, diff this in, don't overwrite`
+                    : `${tier} — no AGENTS.md yet, write this, then \`npx agents-md-facts --check\` keeps the facts block true`;
                 return text(`<!-- ${note} -->\n\n${a.markdown}`);
             }
             case "remember": {

package/dist/transport/http.js

@@ -4,14 +4,14 @@
  * A Hono app. `POST /mcp` is the MCP endpoint, run **stateless**: a fresh
  * server + transport per request, `sessionIdGenerator: undefined`, and
  * `enableJsonResponse` so every response is a complete JSON body (no SSE
- * stream, nothing to keep open). That's the right default for a reference
- * server — it scales horizontally, needs no sticky sessions, and there's
- * no per-connection state to leak. A server that needs server-streamed
+ * stream, nothing to keep open). That's the right default here — it scales
+ * horizontally, needs no sticky sessions, and there's no per-connection
+ * state to leak. A server that needs server-streamed
  * notifications or resumability would set a `sessionIdGenerator` and hold
  * transports in a map; this one deliberately does not.
  *
  * Alongside the MCP endpoint it serves the discovery documents:
- *   GET /.well-known/mcp/server-card   — the Server Card + _meta trinity
+ *   GET /.well-known/mcp/server-card   — the Server Card + _meta block
  *   GET /.well-known/ai-catalog.json   — the three sibling entries
  *   GET /.well-known/fafa              — the agent identity card
  */

package/docs/MECHANISMS.md

@@ -5,7 +5,7 @@ mechanisms that already exist in the MCP ecosystem. This is the wire‑level
 detail.
 
 The **context** concern points at `AGENTS.md` (`text/markdown`). Memory and
-identity have no de‑facto standard, so the reference points them at `.fafm` and
+identity have no de‑facto standard, so this server points them at `.fafm` and
 `.fafa`. Everything below is about the *shape* — swap the artifacts and the
 mechanism is unchanged.
 
@@ -29,7 +29,7 @@ Both return:
 ```jsonc
 {
   "name": "mcp-context-card",
-  "version": "0.2.0",
+  "version": "0.5.2",
   "_meta": {
     "io.github.wolfe-jam.mcp-context-card/context": {
       "source": "AGENTS.md",
@@ -39,7 +39,7 @@ Both return:
       "source": "project.fafm",
       "mediaType": "application/vnd.fafm+yaml",
       "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml",
-      "note": "no de-facto standard for agent memory yet — one instantiation"
+      "note": "no de-facto standard for agent memory yet — this is one instantiation"
     },
     "io.github.wolfe-jam.mcp-context-card/identity": {
       "source": ".well-known/fafa",
@@ -64,7 +64,7 @@ Both return:
   is for instructions; the block says so rather than implying `.fafm` is a
   standard.
 
-Built by `trinityMeta()` in [`src/identity.ts`](../src/identity.ts).
+Built by `serverCardMeta()` in [`src/identity.ts`](../src/identity.ts).
 
 ---
 
@@ -129,7 +129,7 @@ project.fafm   ─┼─→  Server Card _meta   (context · memory · identity)
   fafa
 ```
 
-`catalog-gen.ts` reads exactly the files `trinityMeta()` names. The CI job
+`catalog-gen.ts` reads exactly the files `serverCardMeta()` names. The CI job
 `npm run catalog:check` regenerates `ai-catalog.json` and fails on any drift —
 change a source, both surfaces move together.
 

package/docs/TRANSPORT.md

@@ -41,7 +41,7 @@ the wire, so all logging goes to `stderr`.
 ```
 GET  /                          → index (endpoints)
 POST /mcp                       → MCP (initialize, tools/list, tools/call, …)
-GET  /.well-known/mcp/server-card   → the Server Card + _meta trinity block
+GET  /.well-known/mcp/server-card   → the Server Card + _meta block
 GET  /.well-known/ai-catalog.json   → the three sibling entries
 GET  /.well-known/fafa              → the agent identity card
 ```
@@ -81,6 +81,6 @@ streaming tools would flip this. See `src/transport/http.ts`.
 
 ### DNS-rebinding protection
 
-Off by default (a reference server should run anywhere with no config). For
-a real deployment, pass `allowedHosts` / `allowedOrigins` to the transport
-and set `enableDnsRebindingProtection: true`.
+Off by default (the server should run anywhere with no config). For a real
+deployment, pass `allowedHosts` / `allowedOrigins` to the transport and set
+`enableDnsRebindingProtection: true`.

package/docs/WIRING.md

@@ -26,6 +26,13 @@
 - **`MCP_CONTEXT_CARD_ROOT`** — directory holding `AGENTS.md`, `project.fafm`, and
   `.well-known/fafa`. Omit it and the server uses its own bundled copies.
 - `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,
+  even though a login shell does. Observed with Cursor. Fix: point `command`
+  at an absolute path to `node`, with the installed package's `dist/bin.js` as
+  the arg — e.g. `command: "node"`, `args: ["/path/to/node_modules/mcp-context-card/dist/bin.js"]`
+  (or wherever `npm install -g` / your package manager put it; find it with
+  `npm root -g` or `which mcp-context-card` after a global install).
 
 ### Streamable HTTP (remote)
 
@@ -72,7 +79,10 @@ 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: 9 },
 //     memory:  { … }, identity: { … },
-//     surfaces: { serverCard: [...], aiCatalog: [...] } }
+//     surfaces: { mcp: { serverCard: "resource mcp-context-card://server-card" },
+//                 http: { serverCard: "GET /.well-known/mcp/server-card",
+//                         aiCatalog: "GET /.well-known/ai-catalog.json",
+//                         card: "GET /card" } } }
 ```
 
 ---
@@ -84,11 +94,11 @@ To serve *your* artifacts:
 1. **Replace the three files** — `AGENTS.md`, `project.fafm`, `.well-known/fafa`
    — with your own, or point `MCP_CONTEXT_CARD_ROOT` at a directory that has them.
    `AGENTS.md` is the one with a real standard; the other two are swappable.
-2. **Rename the namespace.** `trinityMeta()` in `src/identity.ts` uses
+2. **Rename the namespace.** `serverCardMeta()` in `src/identity.ts` uses
    `io.github.wolfe-jam.mcp-context-card/*` keys, and `buildCatalog()` in
    `src/catalog-gen.ts` uses `urn:air:mcp-context-card:*` identifiers. Change both to
    a domain or GitHub identity you control ([MECHANISMS.md](./MECHANISMS.md)).
-3. **Swap the media types** in `trinityMeta()` if your memory / identity
+3. **Swap the media types** in `serverCardMeta()` if your memory / identity
    artifacts aren't `.fafm` / `.fafa`. Drop the `iana` field for any that isn't
    a registered type.
 4. `npm run catalog` to regenerate, `npm run demo` to confirm all three still

package/docs/card.html

@@ -73,11 +73,11 @@ section:last-child{border-bottom:0}
 <main class="card">
   <div class="top">
     <h1>mcp-context-card</h1>
-    <div class="pills"><span class="pill">v0.5.0</span><span class="pill accent">reference</span><span class="pill">MIT</span></div>
+    <div class="pills"><span class="pill">io.github.wolfe-jam</span><span class="pill">v0.5.2</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
   </div>
   <section>
     <p class="label">Context — AGENTS.md</p>
-    <ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><div class="md"><p><code>mcp-context-card</code> is an MCP server that makes a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> discoverable to any MCP client — through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
+    <ul class="toc"><li><a href="#setup">Setup</a></li><li><a href="#build">Build</a></li><li><a href="#test">Test</a></li><li><a href="#layout">Layout</a></li><li><a href="#conventions">Conventions</a></li><li><a href="#the-invariant">The invariant</a></li><li><a href="#safety">Safety</a></li><li><a href="#definition-of-done">Definition of done</a></li><li><a href="#authoring-this-file">Authoring this file</a></li></ul><div class="md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
 <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p>
 <h2 id="setup">Setup</h2>
 <pre><code class="language-bash">npm ci</code></pre>
@@ -91,7 +91,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</code></pre>
 <p>CI runs <code>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>).</p>
 <h2 id="layout">Layout</h2>
-<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> — wraps <code>agents-md-facts</code> (the AGENTS.md authoring engine)</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></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>
+<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>
 <h2 id="conventions">Conventions</h2>
 <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>
 <h2 id="the-invariant">The invariant</h2>
@@ -101,11 +101,11 @@ npm run demo          # end to end: all tools over stdio, then over stateless HT
 <h2 id="definition-of-done">Definition of done</h2>
 <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>.</p>
 <h2 id="authoring-this-file">Authoring this file</h2>
-<p><code>AGENTS.md</code> here is maintained by hand. It can also be generated from the repo's <code>project.faf</code> with <code>faf export --agents</code> — the server doesn't care how the file was authored, only that it's valid Markdown.</p></div>
+<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>
   </section>
   <section>
-    <p class="label">Memory — 3 facts</p>
-    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so the reference uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div>
+    <p class="label">Memory — 4 facts</p>
+    <div class="fact"><p>The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.</p><div class="meta"><span class="tag">scope</span><span class="tag">agents-md</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.</p><div class="meta"><span class="tag">mcp</span><span class="tag">server-card</span><span class="tag">ai-catalog</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>Distribution: a published npm package (bin <code>mcp-context-card</code>, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.</p><div class="meta"><span class="tag">distribution</span><span class="tag">mit</span><span class="tag">npm</span><span class="dot" title="verified"></span></div></div><div class="fact"><p>author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.</p><div class="meta"><span class="tag">agents-md</span><span class="tag">author_agents_md</span><span class="tag">faf</span><span class="dot" title="verified"></span></div></div>
   </section>
   <section>
     <p class="label">Discovery</p>

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "mcp-context-card",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "mcpName": "io.github.wolfe-jam/mcp-context-card",
-  "description": "Reference MCP server: project context, persistent memory, and agent identity — through the two exposure surfaces already in the ecosystem (Server Card _meta, ai-catalog sibling entries).",
+  "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": [
     "mcp",
     "model-context-protocol",
+    "agents-md",
     "server-card",
     "ai-catalog",
     "project-context",
     "agent-memory",
     "agent-identity"
   ],
-  "author": "wolfejam",
+  "author": "James Wolfe",
   "license": "MIT",
   "type": "module",
   "private": false,

package/project.faf

@@ -1,7 +1,7 @@
 faf_version: "3.0"
 project:
   name: mcp-context-card
-  goal: An MCP server that makes a project's context (its AGENTS.md), memory, and identity discoverable to any MCP client — through the Server Card _meta block and ai-catalog.json sibling entries, the two surfaces already in the ecosystem.
+  goal: The essential MCP server for a project's context (its AGENTS.md), memory, and identity — usable as a base MCP on its own, or as a drop-in extension for any existing MCP server. Discoverable to any MCP client through the Server Card _meta block and ai-catalog.json sibling entries, the two surfaces already in the ecosystem.
   main_language: TypeScript
   type: mcp
 stack:
@@ -16,13 +16,13 @@ stack:
   database: slotignored  # memory is a file, not a DB
   connection: slotignored  # no database
   hosting: Docker / any Node host — stdio for local, stateless Streamable HTTP for remote
-  cicd: GitHub Actions (typecheck + build + test + demo, 3 OSes)
-tech_stack: [TypeScript, "@modelcontextprotocol/sdk", hono, yaml]
+  cicd: GitHub Actions — typecheck + build + test:coverage + demo on 3 OSes; catalog:check + card:check on Linux
+tech_stack: [TypeScript, "@modelcontextprotocol/sdk", "agents-md-facts", hono, 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: An MCP server with seven tools — read_agents_md / list_agents_md_sections (context), remember / recall / forget (memory), whoami (identity), list_context_sources (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". This does it through mechanisms that already exist.
+  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).
+  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"
   how: TypeScript on the MCP SDK. Dual transport in src/bin.ts. The Server Card _meta block and ai-catalog.json are generated from the same three sources (AGENTS.md, project.fafm, .well-known/fafa) — a CI check fails on drift. remember/recall are real file-backed reads/writes proven across a process boundary in demo.ts and the test suite. See docs/MECHANISMS.md, docs/WIRING.md, docs/TRANSPORT.md.
-key_files: [package.json, README.md, AGENTS.md, docs/MECHANISMS.md, src/server.ts, src/agents-md.ts, src/catalog-gen.ts, src/transport/http.ts]
+key_files: [package.json, README.md, AGENTS.md, docs/MECHANISMS.md, src/server.ts, src/identity.ts, src/render-card.ts, src/author.ts, src/agents-md.ts, src/catalog-gen.ts, src/transport/http.ts]

package/project.fafm

@@ -17,9 +17,9 @@ index:
 
 memory:
   facts:
-    - text: "The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so the reference uses .fafm and .fafa as one instantiation each."
+    - text: "The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each."
       id: "mcp-context-card-scope"
-      type: "reference"
+      type: "fact"
       priority: "high"
       tags: ["scope", "agents-md"]
       source: "README.md"
@@ -27,7 +27,7 @@ memory:
 
     - text: "Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart."
       id: "mechanisms-already-proven"
-      type: "reference"
+      type: "fact"
       priority: "high"
       tags: ["mcp", "server-card", "ai-catalog"]
       links: ["mcp-context-card-scope"]
@@ -36,11 +36,20 @@ memory:
 
     - text: "Distribution: a published npm package (bin `mcp-context-card`, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project."
       id: "distribution-model"
-      type: "reference"
+      type: "fact"
       priority: "standard"
       tags: ["distribution", "mit", "npm"]
       source: "README.md"
       verification_status: "verified"
+
+    - text: "author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER."
+      id: "author-agents-md-best-not-just-better"
+      type: "fact"
+      priority: "high"
+      tags: ["agents-md", "author_agents_md", "faf"]
+      links: ["mcp-context-card-scope"]
+      source: "src/author.ts"
+      verification_status: "verified"
   sessions: []
   preferences: {}
   custom: {}

package/server.json

@@ -2,8 +2,8 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.wolfe-jam/mcp-context-card",
   "title": "mcp-context-card",
-  "description": "Reference MCP server that makes a project's context (AGENTS.md), memory, and identity discoverable to any MCP client — through the Server Card _meta block and ai-catalog.json sibling entries.",
-  "version": "0.5.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 drop-in extension for any existing MCP server. Discoverable through the Server Card _meta block and ai-catalog.json sibling entries.",
+  "version": "0.5.2",
   "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": "0.5.0",
+      "version": "0.5.2",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"
@@ -21,7 +21,7 @@
       "environmentVariables": [
         {
           "name": "MCP_CONTEXT_CARD_ROOT",
-          "description": "Directory holding project.faf / project.fafm / .well-known/fafa. Omitted → the server's own bundled reference copies.",
+          "description": "Directory holding project.faf / project.fafm / .well-known/fafa. Omitted → the server's own bundled copies.",
           "isRequired": false
         }
       ]
@@ -37,7 +37,7 @@
         "source": "./project.fafm",
         "mediaType": "application/vnd.fafm+yaml",
         "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml",
-        "note": "no de-facto standard for agent memory yet — one instantiation"
+        "note": "no de-facto standard for agent memory yet — this is one instantiation"
       },
       "io.github.wolfe-jam.mcp-context-card/identity": {
         "source": "./.well-known/fafa",