mcp-context-card

io.github.Wolfe-Jamv0.6.2publishedMIT

Context — AGENTS.md

Setup
Build
Test
Layout
Conventions
The invariant
Safety
Definition of done
Authoring this file

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.

Setup

npm ci

Node 22 or newer. No other system dependencies.

Build

npm run build       # tsc -p tsconfig.build.json  →  dist/
npm run typecheck   # tsc --noEmit over src/ + test/

Test

npm test              # node:test — every test/*.test.ts
npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
npm run demo          # end to end: all tools over stdio, then over stateless HTTP
npm run version:check # every version-bearing spot agrees with package.json
npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project

CI runs version:check → faf:check → typecheck → build → test:coverage → demo on Linux, macOS, and Windows for every push and PR to main (.github/workflows/ci.yml), plus catalog:check / card:check, faf-cli check project.faf --strict (the repo dogfoods a project.faf — this keeps it Trophy), and faf:nudge (PR-only, non-blocking — warns if the code's shape moved without project.faf) on Linux.

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` — 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` · `--help` · `--version`
`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, and npm run faf:check green if you changed the layout, a dependency, or the identity. On a version bump, npm run version:check green (it lists every spot that must move together) and project.faf still Trophy (faf-cli check project.faf --strict). If CI's faf:nudge warns on your PR, reconcile project.faf (and re-check project.fafm facts if AGENTS.md moved) or say why it's fine.

Authoring this file

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.

Memory — 4 facts

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.

scopeagents-md

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.

mcpserver-cardai-catalog

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.

distributionmitnpm

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.

agents-mdauthor_agents_mdfaf

Discovery

concern	source	media type
context	`AGENTS.md`	`text/markdown`
memory	`project.fafm`	`application/vnd.fafm+yaml`
identity	`.well-known/fafa`	`application/vnd.fafa+yaml`

A machine reads this over MCP from the mcp-context-card://server-card resource; over HTTP also from GET /.well-known/mcp/server-card and GET /.well-known/ai-catalog.json.

mcp-context-card · context card