mcp-context-card 0.5.0

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

@@ -0,0 +1,39 @@
+{
+  "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",
+      "displayName": "mcp-context-card — project context (AGENTS.md)",
+      "type": "text/markdown",
+      "mediaType": "text/markdown",
+      "description": "Agent instructions for this project — 9 section(s): Setup, Build, Test, Layout, Conventions, The invariant, ….",
+      "url": "./AGENTS.md"
+    },
+    {
+      "identifier": "urn:air:mcp-context-card:memory",
+      "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.",
+      "url": "./project.fafm",
+      "_meta": {
+        "io.github.wolfe-jam.mcp-context-card/iana": "https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml"
+      }
+    },
+    {
+      "identifier": "urn:air:mcp-context-card:identity",
+      "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.",
+      "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

@@ -0,0 +1,18 @@
+# Agent identity card (.fafa) — mcp-context-card's own identity
+# Media type: application/vnd.fafa+yaml
+# This is the identity concern's worked example: `whoami` reads this file,
+# and it's the third entry in the Server Card _meta block and ai-catalog.
+# A deployment pointed at a real project replaces it with that agent's identity.
+
+version: "1.0"
+agent:
+  name: "mcp-context-card"
+  displayName: "mcp-context-card"
+  vendor: "reference"
+  version: "0.5.0"
+  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"
+  license: "MIT"

package/AGENTS.md

@@ -0,0 +1,85 @@
+# 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.
+
+`read_agents_md` serves this file, section by section, over the same MCP
+connection.
+
+## Setup
+
+```bash
+npm ci
+```
+
+Node 22 or newer. No other system dependencies.
+
+## Build
+
+```bash
+npm run build       # tsc -p tsconfig.build.json  →  dist/
+npm run typecheck   # tsc --noEmit over src/ + test/
+```
+
+## Test
+
+```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
+```
+
+CI runs `typecheck → build → test:coverage → demo` on Linux, macOS, and
+Windows for every push and PR to `main` (`.github/workflows/ci.yml`).
+
+## Layout
+
+| Path | What |
+|---|---|
+| `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/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/faf/parse-fafm.ts` · `parse-fafa.ts` | the `.fafm` / `.fafa` parsers |
+
+## Conventions
+
+- TypeScript strict, ESM only (`"type": "module"`, `.js` import specifiers).
+- Tests use `node:test` + `node:assert/strict` — no test framework.
+- Every source file opens with a comment stating what it is and why.
+- Conventional Commit messages (`feat:`, `fix:`, `chore:`, `test:`, `docs:`).
+
+## The invariant
+
+`src/identity.ts`, `src/catalog-gen.ts`, and `src/render-card.ts` all describe
+the **same three sources**: this file, `project.fafm`, `.well-known/fafa`.
+Change what one exposes and you must change the others. `npm run catalog:check`
+and `npm run card:check` enforce it in CI — each regenerates its surface and
+fails on any diff.
+
+## Safety
+
+- Branch off `main`; CI must be green before merge.
+- `npm run demo` writes a fact to `project.fafm` and restores the file on
+  exit — don't kill it mid-run.
+- No secrets live in this repo; never add any.
+
+## Definition of done
+
+`npm run typecheck && npm run build && npm test && npm run demo` all green,
+plus `npm run catalog:check` and `npm run card:check` clean if you touched
+`AGENTS.md`, `project.fafm`, or `.well-known/fafa`.
+
+## 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.

package/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
+
+## 0.5.0
+
+The first public release — installable, and settling in the open before a
+`1.0.0` cut. `faf-trinity` v0.1.0 was a private demo; this is the versioned,
+tested server.
+
+### The tools
+
+- **context** — `read_agents_md` (whole file or one section by heading),
+  `list_agents_md_sections`, and `author_agents_md` (draft one when there
+  isn't one, via `agents-md-facts`). The register the other two serve is
+  `AGENTS.md`.
+- **memory** — `remember`, `recall`, `forget`. File-backed against a `.fafm`;
+  a fact survives a full server-process restart.
+- **identity** — `whoami`. From the server's `.well-known/fafa`, or
+  `package.json` when there isn't one.
+- **discovery** — `list_context_sources`. What the project publishes, in what
+  media types, through which surface.
+- **the card** — `render_context_card`, `GET /card`, and `npx mcp-context-card
+  card` (renders the current directory's card to stdout — no host, no config).
+  Identity + `AGENTS.md` + memory + discovery as one self-contained HTML page
+  (inline CSS, no JS, no external anything). Light / dark / auto; the accent
+  defaults to the AAIF palette and takes any hex. `npm run card` writes
+  `docs/card.html`; `card:check` fails on drift, in CI. Rendered by `src/md.ts`
+  — a ~200-line dependency-free Markdown renderer.
+
+### Exposure
+
+- Server Card `_meta` block — publisher-namespaced keys
+  (`io.github.wolfe-jam.mcp-context-card/{context,memory,identity}`), one per
+  concern. `context` points at `AGENTS.md` / `text/markdown`.
+- `mcp-context-card://server-card` MCP resource (in-band) +
+  `GET /.well-known/mcp/server-card` (out-of-band, HTTP transport).
+- `GET /.well-known/ai-catalog.json` — three sibling entries, keyed by media
+  type, derived from the same three sources. `npm run catalog:check` fails on
+  drift, in CI.
+
+### Transport
+
+- stdio (default) and stateless Streamable HTTP (`--http` / `PORT`);
+  `src/bin.ts` `resolveLaunch()` selects the mode. `MCP_CONTEXT_CARD_ROOT` points
+  the server at any project.
+
+### Engineering
+
+- 88 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.
+- Build emits `dist/` (`tsconfig.build.json`); `exports` map, shipped type
+  declarations. `docs/MECHANISMS.md`, `docs/WIRING.md`, `docs/TRANSPORT.md`;
+  `examples/` (Dockerfile, compose, client configs). `server.json` registry
+  manifest.
+- `author_agents_md` wraps [`agents-md-facts`](https://github.com/Wolfe-Jam/agents-md-facts)
+  — a published, standalone AGENTS.md authoring engine (real commands / entry
+  points / conventions, nothing invented; `--check` keeps it true).
+- `whoami` falls back to `package.json` when a project has no `.well-known/fafa`.
+
+### Since v0.1.0
+
+- Renamed `faf-trinity` → `mcp-context-card`.
+- Context concern now leads with `AGENTS.md`, not a FAF format; the FAF formats
+  are the worked examples for memory and identity, where no standard exists.
+- The `_meta` block and `catalog-gen` carry real data, not a `console.log` and
+  a hardcoded object.
+
+## v0.1.0 (2026-08-12)
+
+- Initial private reference 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Wolfe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# mcp-context-card
+
+[![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.
+
+- **context** — the project's `AGENTS.md`, served whole or one section at a time
+- **memory** — facts that persist across sessions, in a file
+- **identity** — what this server is, from its own agent card
+
+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
+
+**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.
+
+**It is not**
+
+- 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
+
+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)
+- **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.
+
+## The card
+
+![the context card](./docs/img/card.png)
+
+The same three sources render as one self‑contained HTML page — identity,
+`AGENTS.md`, memory, and how a machine fetches it. The view for people:
+screenshot it, drop it in a PR, put it on a status page.
+
+```
+GET /card                      # live, on the HTTP transport
+GET /card?theme=light&accent=%230066cc
+npx mcp-context-card card       # or:  npm run card  →  docs/card.html
+```
+
+Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
+[docs/card.html](./docs/card.html) is this repo's, rendered.
+
+## Who it's for
+
+| 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) |
+| 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` |
+| the two‑surface discovery pattern to copy into your own server | read `src/` |
+
+## Add it to your setup
+
+### 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:
+
+```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:
+
+```bash
+npx mcp-context-card card > card.html
+```
+
+### Wire it into a host
+
+Claude Desktop, Cursor, or any stdio host:
+
+```jsonc
+{
+  "mcpServers": {
+    "context-card": {
+      "command": "npx",
+      "args": ["-y", "mcp-context-card"],
+      "env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }
+    }
+  }
+}
+```
+
+`MCP_CONTEXT_CARD_ROOT` points at the directory with your `AGENTS.md`. The
+memory tools work with or without it; identity is optional. Over HTTP instead:
+`PORT=8080 npx mcp-context-card`. Full wiring is in
+[docs/WIRING.md](./docs/WIRING.md); transport choice in
+[docs/TRANSPORT.md](./docs/TRANSPORT.md).
+
+## Why
+
+`AGENTS.md` is the de-facto standard for telling a coding agent how to work in a
+repo. But a client has to *know the file exists* and read the whole thing into
+context. There is no standard way for a server to say "here is my AGENTS.md,
+here is what I remember, here is who I am" — so every server that wants this
+grows its own shape.
+
+`mcp-context-card` answers all three through mechanisms that already exist:
+
+1. **Server Card `_meta`** ([SEP‑2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127)) —
+   one reverse‑DNS‑namespaced key per concern, readable in‑band as an MCP
+   resource and at `GET /.well-known/mcp/server-card`.
+2. **`ai-catalog.json`** — sibling entries keyed by media type, at
+   `GET /.well-known/ai-catalog.json`.
+
+The context concern points at `AGENTS.md` (`text/markdown`). Memory and identity
+have no de‑facto standard yet, so the examples here use
+[`.fafm`](https://doi.org/10.5281/zenodo.20348942) and
+[`.fafa`](https://doi.org/10.5281/zenodo.21951641) — one instantiation each,
+swap in your own.
+
+The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
+
+## Tools
+
+| 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 |
+| `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 |
+| `recall` | read a fact stored in a previous session |
+| `forget` | drop or correct a stale fact |
+| `whoami` | this server's name, vendor, version, status, license |
+| `list_context_sources` | what this project publishes, in what media types, via which surface |
+| `render_context_card` | the whole card as one self‑contained HTML page (also `GET /card`) |
+
+## The demo
+
+`npm run demo` runs every tool over both transports:
+
+1. **Context** — list the `AGENTS.md` sections, then pull just `## Test`.
+2. **Memory** — `remember()` a fact, stop the server process, start a new one,
+   `recall()` the same fact. Only the file carries it across.
+3. **Identity** — `whoami()`, and the Server Card `_meta` block read back from a
+   live client.
+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.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `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/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` |
+
+## Related
+
+- [Server Card SEP‑2127](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2127) · [ai-catalog](https://github.com/Agent-Card/ai-catalog) · [AGENTS.md](https://agents.md)
+- [`mcp-project-context`](https://github.com/Wolfe-Jam/mcp-project-context) — an earlier take on the context concern alone
+- `text/markdown` (AGENTS.md) · `application/vnd.fafm+yaml` · `application/vnd.fafa+yaml`
+
+## License
+
+MIT.
+
+This repo dogfoods what it serves — its `AGENTS.md` is a real, current file, and
+it ships a `project.faf` as the structured source behind it.

package/dist/agents-md.d.ts

@@ -0,0 +1,22 @@
+export interface AgentsSection {
+    /** heading text, verbatim, without the leading `#`s */
+    heading: string;
+    /** heading depth, 1–6 */
+    level: number;
+    /** everything under this heading up to the next heading, trimmed */
+    body: string;
+}
+export interface AgentsMd {
+    /** the file, byte-for-byte */
+    raw: string;
+    /** any text before the first heading (often a one-line intro) */
+    preamble: string;
+    sections: AgentsSection[];
+}
+export declare function parseAgentsMd(path: string): AgentsMd | null;
+export declare function fromString(raw: string): AgentsMd;
+/**
+ * Resolve a section by heading: exact (case-insensitive) first, then prefix,
+ * then substring. Returns null if nothing matches.
+ */
+export declare function findSection(doc: AgentsMd, query: string): AgentsSection | null;

package/dist/agents-md.js

@@ -0,0 +1,65 @@
+/**
+ * agents-md — read a project's AGENTS.md.
+ *
+ * AGENTS.md is the de-facto standard for telling a coding agent how to work
+ * in a repo: setup, build, test, conventions, safety. It is plain Markdown.
+ *
+ * A client today has to know the file exists and read the whole thing into
+ * context. This splits it into addressable sections by heading so a client
+ * can pull just "## Testing" on demand. No Markdown-parser dependency —
+ * a heading is a `^#{1,6} ` line outside a fenced code block.
+ */
+import { readFileSync } from "node:fs";
+const HEADING = /^(#{1,6})\s+(.+?)\s*#*\s*$/;
+const FENCE = /^\s*(```|~~~)/;
+export function parseAgentsMd(path) {
+    try {
+        return fromString(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export function fromString(raw) {
+    const sections = [];
+    const preamble = [];
+    let cur = null;
+    let inFence = false;
+    const flush = () => {
+        if (cur) {
+            sections.push({ heading: cur.heading, level: cur.level, body: cur.body.join("\n").trim() });
+            cur = null;
+        }
+    };
+    for (const line of raw.split(/\r?\n/)) {
+        if (FENCE.test(line))
+            inFence = !inFence;
+        const m = inFence ? null : line.match(HEADING);
+        if (m) {
+            flush();
+            cur = { heading: m[2].trim(), level: m[1].length, body: [] };
+        }
+        else if (cur) {
+            cur.body.push(line);
+        }
+        else {
+            preamble.push(line);
+        }
+    }
+    flush();
+    return { raw, preamble: preamble.join("\n").trim(), sections };
+}
+/**
+ * Resolve a section by heading: exact (case-insensitive) first, then prefix,
+ * then substring. Returns null if nothing matches.
+ */
+export function findSection(doc, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return null;
+    const h = (s) => s.heading.toLowerCase();
+    return (doc.sections.find((s) => h(s) === q) ??
+        doc.sections.find((s) => h(s).startsWith(q)) ??
+        doc.sections.find((s) => h(s).includes(q)) ??
+        null);
+}

package/dist/author.d.ts

@@ -0,0 +1,11 @@
+/** 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 -->";
+export interface Authored {
+    /** the AGENTS.md text — a managed block, ready to drop in */
+    markdown: string;
+    /** whether an AGENTS.md already exists at the target */
+    exists: boolean;
+}
+/** Author a managed AGENTS.md block for `root`, from its repo facts. */
+export declare function authorAgentsMd(root: string): Authored;

package/dist/author.js

@@ -0,0 +1,27 @@
+/**
+ * author — author an AGENTS.md for a project from its repo facts.
+ *
+ * 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.
+ *
+ * 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.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+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. */
+export function authorAgentsMd(root) {
+    const block = authorBlock(buildRepoContext(root)).trim();
+    return {
+        markdown: `${BLOCK_START}\n${block}\n${BLOCK_END}\n`,
+        exists: existsSync(join(root, "AGENTS.md")),
+    };
+}

package/dist/bin.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+export type Mode = "stdio" | "http" | "card";
+export interface Launch {
+    mode: Mode;
+    /** port for http mode (ignored otherwise). */
+    port: number;
+    /** directory to read from — cwd for `card`, else MCP_CONTEXT_CARD_ROOT ?? package root. */
+    root: string;
+}
+/**
+ * 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
+ */
+export declare function resolveLaunch(argv: readonly string[], env?: NodeJS.ProcessEnv): Launch;
+/** value of `--flag <value>` in argv, or undefined. */
+export declare function flagValue(argv: readonly string[], flag: string): string | undefined;

package/dist/bin.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * bin — the entry point.
+ *
+ *   mcp-context-card              → stdio  (the default; what an MCP host spawns)
+ *   mcp-context-card --http       → stateless Streamable HTTP on PORT (default 3000)
+ *   PORT=8080 mcp-context-card    → HTTP too (a hosted deploy sets PORT)
+ *   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_ROOT=/path/to/project → read AGENTS.md / project.fafm /
+ *   .well-known/ from there instead of the package's own bundled copies.
+ */
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ROOT, serve } from "./server.js";
+/**
+ * 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
+ */
+export function resolveLaunch(argv, env = process.env) {
+    if (argv[0] === "card") {
+        return {
+            mode: "card",
+            port: 0,
+            root: env.MCP_CONTEXT_CARD_ROOT ? resolve(env.MCP_CONTEXT_CARD_ROOT) : process.cwd(),
+        };
+    }
+    const n = Number(env.PORT);
+    const portEnv = env.PORT && Number.isFinite(n) && n > 0 ? n : undefined;
+    const forceStdio = argv.includes("--stdio");
+    const http = !forceStdio && (argv.includes("--http") || portEnv !== undefined);
+    const root = env.MCP_CONTEXT_CARD_ROOT ? resolve(env.MCP_CONTEXT_CARD_ROOT) : ROOT;
+    return { mode: http ? "http" : "stdio", port: portEnv ?? 3000, root };
+}
+/** value of `--flag <value>` in argv, or undefined. */
+export function flagValue(argv, flag) {
+    const i = argv.indexOf(flag);
+    return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined;
+}
+/** Direct run only — importing this module (e.g. from a test) must not launch. */
+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") {
+        const { renderCard, safeAccent } = await import("./render-card.js");
+        const theme = flagValue(argv, "--theme");
+        process.stdout.write(renderCard(root, {
+            theme: theme === "light" || theme === "dark" ? theme : "auto",
+            accent: safeAccent(flagValue(argv, "--accent")),
+        }));
+    }
+    else if (mode === "http") {
+        const { httpApp } = await import("./transport/http.js");
+        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/*)`);
+    }
+    else {
+        await serve(new StdioServerTransport(), root);
+    }
+}

package/dist/card-gen.d.ts

@@ -0,0 +1 @@
+export {};