mcp-context-card 0.5.0

package/docs/MECHANISMS.md

@@ -0,0 +1,137 @@
+# Mechanisms
+
+`mcp-context-card` exposes three concerns — context, memory, identity — through two
+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
+`.fafa`. Everything below is about the *shape* — swap the artifacts and the
+mechanism is unchanged.
+
+---
+
+## Mechanism 1 — the Server Card `_meta` block
+
+A **Server Card**
+([SEP‑2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127))
+describes a server. It is *not* a field on the `initialize` result — the SDK
+client keeps only `serverInfo` / `capabilities` / `instructions` and discards a
+top‑level `_meta`. So the card is served the two ways a client can consume it:
+
+```
+resources/read  mcp-context-card://server-card       # in band
+GET /.well-known/mcp/server-card                 # out of band (http transport)
+```
+
+Both return:
+
+```jsonc
+{
+  "name": "mcp-context-card",
+  "version": "0.2.0",
+  "_meta": {
+    "io.github.wolfe-jam.mcp-context-card/context": {
+      "source": "AGENTS.md",
+      "mediaType": "text/markdown"
+    },
+    "io.github.wolfe-jam.mcp-context-card/memory": {
+      "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"
+    },
+    "io.github.wolfe-jam.mcp-context-card/identity": {
+      "source": ".well-known/fafa",
+      "mediaType": "application/vnd.fafa+yaml",
+      "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"
+    }
+  }
+}
+```
+
+**Why it looks like this:**
+
+- **`_meta` is the extension point.** SEP‑2127 defines it as
+  `additionalProperties: {}`. A consumer that doesn't know a key ignores it.
+- **Keys are reverse‑DNS‑namespaced to the publisher**
+  (`io.github.wolfe-jam.mcp-context-card/context`, not `context`). No collisions, and
+  the key's owner is unambiguous. Use a domain or GitHub identity you control.
+- **One key per concern**, each self‑describing: the source file, its media
+  type, and — where the media type is IANA‑registered — the anchor. `context`
+  carries no `iana` field because `text/markdown` needs none.
+- **`note` is honest.** There is no de‑facto memory format the way `AGENTS.md`
+  is for instructions; the block says so rather than implying `.fafm` is a
+  standard.
+
+Built by `trinityMeta()` in [`src/identity.ts`](../src/identity.ts).
+
+---
+
+## Mechanism 2 — `ai-catalog.json` sibling entries
+
+[ai-catalog](https://github.com/Agent-Card/ai-catalog) is a discovery format: a
+publisher lists artifacts, each entry keyed by its **media type** (`type`).
+`mcp-context-card` publishes one entry per concern.
+
+```
+GET /.well-known/ai-catalog.json
+```
+
+```jsonc
+{
+  "specVersion": "1.0",
+  "host": { "displayName": "mcp-context-card", "identifier": "https://github.com/Wolfe-Jam/mcp-context-card" },
+  "entries": [
+    {
+      "identifier": "urn:air:mcp-context-card:context",
+      "type": "text/markdown",
+      "mediaType": "text/markdown",
+      "description": "…derived from the real AGENTS.md — section count + headings…",
+      "url": "./AGENTS.md"
+    },
+    { "identifier": "urn:air:mcp-context-card:memory",   "type": "application/vnd.fafm+yaml", "…": "…" },
+    { "identifier": "urn:air:mcp-context-card:identity", "type": "application/vnd.fafa+yaml", "…": "…" }
+  ]
+}
+```
+
+**Why it looks like this:**
+
+- **`type` is the routing key.** A consumer scanning catalogs for
+  `text/markdown` context, or `application/vnd.fafm+yaml` memory, finds the
+  entry without knowing this publisher.
+- **`identifier` is a `urn:air:` URN** scoped to the publisher
+  (`urn:air:<host>:<concern>`). In ai-catalog's
+  [trust‑manifest ADRs](https://github.com/Agent-Card/ai-catalog/tree/main/adr),
+  `urn:air` identifiers carry a publisher‑domain‑aligned trust manifest — the
+  entries here align to `github.com/Wolfe-Jam/mcp-context-card`.
+- **`description` is derived from real content** — the live AGENTS.md heading
+  list, the current fact count, the agent's own description — not a blurb that
+  drifts. See `buildCatalog()` in [`src/catalog-gen.ts`](../src/catalog-gen.ts).
+- **`url` is relative.** Served over HTTP it resolves against the origin; in a
+  repo browser, against the tree.
+
+---
+
+## The invariant
+
+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.
+
+The same three sources back **both** discovery mechanisms:
+
+```
+AGENTS.md      ─┐
+project.fafm   ─┼─→  Server Card _meta   (context · memory · identity)
+.well-known/   ─┘ └─→ ai-catalog.json     (3 sibling entries, keyed by media type)
+  fafa
+```
+
+`catalog-gen.ts` reads exactly the files `trinityMeta()` names. The CI job
+`npm run catalog:check` regenerates `ai-catalog.json` and fails on any drift —
+change a source, both surfaces move together.
+
+**Describe the artifacts once; expose them through whatever mechanism the
+consumer speaks.**

package/docs/TRANSPORT.md

@@ -0,0 +1,86 @@
+# Transport
+
+`mcp-context-card` runs the same server over two transports. The tool surface,
+the Server Card `_meta` block, and the memory file are identical either way
+— only the wire changes.
+
+```
+mcp-context-card              → stdio                 (default; an MCP host spawns this)
+mcp-context-card --http       → Streamable HTTP :3000
+PORT=8080 mcp-context-card    → Streamable HTTP :8080 (a hosted deploy sets PORT)
+mcp-context-card --stdio      → force stdio even when PORT is set
+```
+
+## stdio
+
+`StdioServerTransport` — one process, one client, JSON-RPC over stdin/stdout.
+This is what Claude Desktop, Cursor, and `npx`-style hosts use. `stdout` is
+the wire, so all logging goes to `stderr`.
+
+```jsonc
+// claude_desktop_config.json
+{
+  "mcpServers": {
+    "context-card": { "command": "npx", "args": ["-y", "mcp-context-card"] }
+  }
+}
+```
+
+## Streamable HTTP — stateless
+
+`POST /mcp` is the MCP endpoint. It runs **stateless**:
+
+- `sessionIdGenerator: undefined` — no session IDs issued, no session
+  validation, no `Mcp-Session-Id` header.
+- `enableJsonResponse: true` — every response is a complete JSON body. No
+  SSE stream is opened, so there is nothing to hold open and nothing to
+  leak.
+- A **fresh `Server` + transport per request**. Two concurrent requests
+  never share state or collide on JSON-RPC ids.
+
+```
+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/ai-catalog.json   → the three sibling entries
+GET  /.well-known/fafa              → the agent identity card
+```
+
+```jsonc
+{
+  "mcpServers": {
+    "context-card": { "url": "https://your-host.example/mcp" }
+  }
+}
+```
+
+### Why stateless
+
+The default should be the one that scales and can't rot. Stateless
+Streamable HTTP:
+
+- **scales horizontally** — any replica can serve any request; no sticky
+  sessions, no shared session store.
+- **has no per-connection state** to grow unbounded or leak on a dropped
+  client.
+- **is trivial to reason about** — request in, response out.
+
+### When you'd want stateful instead
+
+Set a `sessionIdGenerator` and keep transports in a `Map<sessionId, …>`
+when the server needs to:
+
+- **push** server-initiated notifications to a specific client mid-session
+  (`notifications/*` over a held-open SSE stream), or
+- support **resumability** — a client reconnecting with `Last-Event-ID` to
+  replay missed events (needs an `EventStore`).
+
+`mcp-context-card` needs neither: its tools are request/response, and its
+"memory" is a file on disk, not a live subscription. A fork that adds
+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`.

package/docs/WIRING.md

@@ -0,0 +1,97 @@
+# Wiring
+
+1. [Running it in a host](#1-running-it-in-a-host)
+2. [The tools in practice](#2-the-tools-in-practice)
+3. [Adapting it for your own artifacts](#3-adapting-it)
+
+---
+
+## 1. Running it in a host
+
+### stdio (local)
+
+```jsonc
+// claude_desktop_config.json  ·  ~/.cursor/mcp.json  ·  etc.
+{
+  "mcpServers": {
+    "context-card": {
+      "command": "npx",
+      "args": ["-y", "mcp-context-card"],
+      "env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }
+    }
+  }
+}
+```
+
+- **`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`.
+
+### Streamable HTTP (remote)
+
+```bash
+PORT=8080 npx mcp-context-card        # or:  npx mcp-context-card --http
+```
+
+```jsonc
+{ "mcpServers": { "context-card": { "url": "https://your-host.example/mcp" } } }
+```
+
+Stateless — any replica serves any request, no session store. Rationale in
+[TRANSPORT.md](./TRANSPORT.md).
+
+---
+
+## 2. The tools in practice
+
+A client that just connected wants the project's conventions — but not the whole
+`AGENTS.md` in its context window:
+
+```ts
+// what's documented?
+await client.callTool({ name: "list_agents_md_sections", arguments: {} });
+// → [{ "heading": "Setup", "level": 2 }, { "heading": "Test", "level": 2 }, …]
+
+// pull just the one it needs
+await client.callTool({ name: "read_agents_md", arguments: { section: "Test" } });
+// → "## Test\n\n```bash\nnpm test\n```\n…"
+```
+
+Between sessions, carry a fact forward:
+
+```ts
+await client.callTool({ name: "remember", arguments: { id: "db-migration", text: "run `npm run migrate` before tests since #412" } });
+// next session, different process:
+await client.callTool({ name: "recall", arguments: { id: "db-migration" } });
+// → "run `npm run migrate` before tests since #412"
+```
+
+And to discover what a server offers before committing to it:
+
+```ts
+await client.callTool({ name: "list_context_sources", arguments: {} });
+// → { context: { source: "AGENTS.md", mediaType: "text/markdown", present: true, sections: 9 },
+//     memory:  { … }, identity: { … },
+//     surfaces: { serverCard: [...], aiCatalog: [...] } }
+```
+
+---
+
+## 3. Adapting it
+
+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
+   `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
+   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
+   round‑trip, `npm test` for the suite.
+
+---

package/docs/card.html

@@ -0,0 +1,121 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>mcp-context-card — context card</title>
+<style>
+:root{
+  --accent:#FF702D;
+  --bg:#f4f4f5; --card:#fff; --fg:#0a0a0a; --muted:#6b6b70;
+  --line:rgba(0,0,0,.09); --chip:rgba(0,0,0,.05);
+}
+:root[data-theme="dark"]{
+  --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+  --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+}
+@media (prefers-color-scheme:dark){
+  :root:not([data-theme="light"]){
+    --bg:#000; --card:#0d0d0d; --fg:#fafafa; --muted:#9a9aa0;
+    --line:rgba(255,255,255,.13); --chip:rgba(255,255,255,.07);
+  }
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--fg);
+  font:15px/1.6 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+  padding:40px 18px}
+.card{max-width:760px;margin:0 auto;background:var(--card);border:1px solid var(--line);
+  border-radius:14px;overflow:hidden}
+.card>*{padding:26px 30px}
+.top{border-top:4px solid var(--accent);border-bottom:1px solid var(--line)}
+h1{margin:0 0 10px;font-size:1.7rem;letter-spacing:-.02em}
+.pills{display:flex;flex-wrap:wrap;gap:6px}
+.pill{font-size:.74rem;font-weight:600;padding:3px 9px;border-radius:20px;background:var(--chip);color:var(--muted)}
+.pill.accent{background:color-mix(in srgb,var(--accent) 16%,transparent);color:var(--accent)}
+section{border-bottom:1px solid var(--line)}
+section:last-child{border-bottom:0}
+.label{font-size:.7rem;font-weight:700;letter-spacing:.16em;text-transform:uppercase;
+  color:var(--accent);margin:0 0 14px}
+.toc{display:flex;flex-wrap:wrap;gap:6px 14px;margin:0 0 20px;padding:0;list-style:none}
+.toc a{font-size:.82rem;color:var(--muted);text-decoration:none}
+.toc a:hover{color:var(--accent)}
+.md h1,.md h2,.md h3,.md h4{margin:22px 0 8px;font-size:1rem;letter-spacing:-.01em}
+.md h1{font-size:1.15rem}
+.md p{margin:8px 0}
+.md ul,.md ol{margin:8px 0;padding-left:22px}
+.md li{margin:3px 0}
+.md code{background:var(--chip);padding:1px 5px;border-radius:5px;
+  font:.86em ui-monospace,SFMono-Regular,Menlo,monospace}
+.md pre{background:var(--chip);padding:14px 16px;border-radius:9px;overflow:auto}
+.md pre code{background:none;padding:0}
+.md table{border-collapse:collapse;width:100%;margin:12px 0;font-size:.88rem;display:block;overflow:auto}
+.md th,.md td{border:1px solid var(--line);padding:6px 10px;text-align:left}
+.md blockquote{margin:10px 0;padding-left:14px;border-left:3px solid var(--line);color:var(--muted)}
+.md a{color:var(--accent)}
+.fact{padding:12px 0;border-bottom:1px solid var(--line)}
+.fact:last-child{border-bottom:0}
+.fact p{margin:0 0 7px}
+.meta{display:flex;flex-wrap:wrap;gap:6px;align-items:center}
+.tag{font-size:.72rem;padding:2px 8px;border-radius:5px;background:var(--chip);color:var(--muted)}
+.dot{width:7px;height:7px;border-radius:50%;background:var(--accent);display:inline-block}
+.dot.pending{background:var(--muted)}
+.disc{width:100%;border-collapse:collapse;font-size:.84rem}
+.disc th,.disc td{text-align:left;padding:6px 10px;border-bottom:1px solid var(--line)}
+.disc th{color:var(--muted);font-weight:600}
+.disc code{font:.86em ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted)}
+.fetch{margin:14px 0 0;font-size:.82rem;color:var(--muted)}
+.fetch code{background:var(--chip);padding:1px 5px;border-radius:5px}
+.foot{color:var(--muted);font-size:.78rem;text-align:center;border-top:1px solid var(--line)}
+.none{color:var(--muted);font-style:italic}
+</style>
+</head>
+<body>
+<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>
+  <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>
+<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>
+<p>Node 22 or newer. No other system dependencies.</p>
+<h2 id="build">Build</h2>
+<pre><code class="language-bash">npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/</code></pre>
+<h2 id="test">Test</h2>
+<pre><code class="language-bash">npm test              # node:test — every test/*.test.ts
+npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
+npm run demo          # end to end: all tools over stdio, then over stateless HTTP</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>
+<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>
+<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>
+<h2 id="safety">Safety</h2>
+<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>
+<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>
+  </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>
+  </section>
+  <section>
+    <p class="label">Discovery</p>
+    <table class="disc"><thead><tr><th>concern</th><th>source</th><th>media type</th></tr></thead><tbody><tr><td>context</td><td><code>AGENTS.md</code></td><td><code>text/markdown</code></td></tr><tr><td>memory</td><td><code>project.fafm</code></td><td><code>application/vnd.fafm+yaml</code></td></tr><tr><td>identity</td><td><code>.well-known/fafa</code></td><td><code>application/vnd.fafa+yaml</code></td></tr></tbody></table>
+    <p class="fetch">A machine reads this over <b>MCP</b> from the
+      <code>mcp-context-card://server-card</code> resource; over <b>HTTP</b> also
+      from <code>GET /.well-known/mcp/server-card</code> and
+      <code>GET /.well-known/ai-catalog.json</code>.</p>
+  </section>
+  <div class="foot">mcp-context-card · context card</div>
+</main>
+</body>
+</html>

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "mcp-context-card",
+  "version": "0.5.0",
+  "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).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "server-card",
+    "ai-catalog",
+    "project-context",
+    "agent-memory",
+    "agent-identity"
+  ],
+  "author": "wolfejam",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "mcp-context-card": "dist/bin.js"
+  },
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "exports": {
+    ".": "./dist/server.js",
+    "./server": "./dist/server.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "AGENTS.md",
+    "project.faf",
+    "project.fafm",
+    ".well-known",
+    "server.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm test",
+    "start": "node dist/bin.js",
+    "start:http": "node dist/bin.js --http",
+    "dev": "tsx src/bin.ts",
+    "demo": "tsx demo.ts",
+    "catalog": "tsx src/catalog-gen.ts",
+    "catalog:check": "tsx src/catalog-gen.ts && git diff --exit-code -- .well-known/ai-catalog.json",
+    "card": "tsx src/card-gen.ts",
+    "card:check": "tsx src/card-gen.ts && git diff --exit-code -- docs/card.html",
+    "test": "node --import tsx --test \"test/*.test.ts\"",
+    "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude=\"test/**\" --test-coverage-exclude=\"demo.ts\" --test-coverage-lines=90 --test-coverage-functions=85 --test-coverage-branches=80 \"test/*.test.ts\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.19.17",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "agents-md-facts": "^0.1.0",
+    "hono": "^4.13.5",
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wolfe-Jam/mcp-context-card.git"
+  },
+  "homepage": "https://github.com/Wolfe-Jam/mcp-context-card"
+}

package/project.faf

@@ -0,0 +1,28 @@
+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.
+  main_language: TypeScript
+  type: mcp
+stack:
+  runtime: Node.js
+  build: TypeScript (tsc)
+  backend: Node.js (MCP server, dual transport)
+  api_type: MCP (JSON-RPC 2.0 — stdio + stateless Streamable HTTP)
+  frontend: slotignored  # no UI layer
+  css_framework: slotignored  # no UI
+  ui_library: slotignored  # no UI
+  state_management: slotignored  # stateless server; memory is a file
+  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]
+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.
+  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]

package/project.fafm

@@ -0,0 +1,46 @@
+# application/vnd.fafm+yaml — mcp-context-card project memory
+# Real, dogfooded memory about this repo's own build — not a static example.
+# This file itself is one of the three sources the server exposes:
+# `remember` / `recall` read and write it, and the demo proves a fact
+# survives a full server-process restart (then restores this file exactly).
+version: "1.1"
+profile: "knowledge"
+namepoint: "@mcp-context-card:public"
+created: "2026-08-12T00:00:00Z"
+last_etched: "2026-08-12T00:00:00Z"
+retention: "forever"
+
+index:
+  - "mcp-context-card — an MCP server that publishes a project's context, memory & identity"
+  - "context concern leads with AGENTS.md (text/markdown); memory & identity use .fafm/.fafa as worked examples"
+  - "two exposure surfaces: Server Card _meta block + self-published ai-catalog.json"
+
+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."
+      id: "mcp-context-card-scope"
+      type: "reference"
+      priority: "high"
+      tags: ["scope", "agents-md"]
+      source: "README.md"
+      verification_status: "verified"
+
+    - 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"
+      priority: "high"
+      tags: ["mcp", "server-card", "ai-catalog"]
+      links: ["mcp-context-card-scope"]
+      source: "docs/MECHANISMS.md"
+      verification_status: "verified"
+
+    - 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"
+      priority: "standard"
+      tags: ["distribution", "mit", "npm"]
+      source: "README.md"
+      verification_status: "verified"
+  sessions: []
+  preferences: {}
+  custom: {}

package/server.json

@@ -0,0 +1,49 @@
+{
+  "$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",
+  "repository": {
+    "url": "https://github.com/Wolfe-Jam/mcp-context-card",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "mcp-context-card",
+      "version": "0.5.0",
+      "runtimeHint": "npx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "MCP_CONTEXT_CARD_ROOT",
+          "description": "Directory holding project.faf / project.fafm / .well-known/fafa. Omitted → the server's own bundled reference copies.",
+          "isRequired": false
+        }
+      ]
+    }
+  ],
+  "_meta": {
+    "io.modelcontextprotocol.registry/publisher-provided": {
+      "io.github.wolfe-jam.mcp-context-card/context": {
+        "source": "./AGENTS.md",
+        "mediaType": "text/markdown"
+      },
+      "io.github.wolfe-jam.mcp-context-card/memory": {
+        "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"
+      },
+      "io.github.wolfe-jam.mcp-context-card/identity": {
+        "source": "./.well-known/fafa",
+        "mediaType": "application/vnd.fafa+yaml",
+        "iana": "https://www.iana.org/assignments/media-types/application/vnd.fafa+yaml"
+      }
+    }
+  }
+}