mcp-context-card
Get one. Or add it to yours. 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.
| Light | Dark |
|---|
 |  |
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 Server Card.
Discovery goes through two surfaces already in the ecosystem: the Server Card
_meta block and ai-catalog.json sibling entries.
Pick one
| You want to… | |
|---|
Add an AGENTS.md — you don't have one | author_agents_md drafts one from your repo's real facts |
Improve an AGENTS.md — you have one, make it the best it can be | the same tool, automatically — drop in a project.faf and it upgrades to BEST: goal, who it's for, why |
| Get a new MCP server base — context, memory, identity, wired | stand this up as-is; a host has all three before you write a tool of your own |
| Improve your MCP with context, memory, ID — you already run one | run it alongside your existing server; nothing to migrate, it composes |
A base MCP — or an extension for any other
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:
- 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.
Nine tools, two discovery surfaces already in the ecosystem (Server Card
_meta, ai-catalog.json), and a rendered card. MIT, on npm.
It composes:
- serve · discover · render — this server
- author BETTER, keep true —
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, server-git / github‑mcp‑server, your test runner's MCP
Vendor-free — context is plain Markdown (AGENTS.md); the memory and
identity formats are swappable examples. It reads and writes only its own
three files (AGENTS.md, project.fafm, .well-known/fafa) — no general
file access, no shell, no search.
The card
The screenshot at the top of this page is exactly this — the same three
sources rendered as one self‑contained HTML page: identity, AGENTS.md,
memory, and how a machine fetches it. The view for people: read it, screenshot
it, drop it in a PR, put it on a status page.
AGENTS.md sections are collapsed by default, so the card scans in one screen;
a sticky index jumps to any section, Expand all opens everything. Sections
toggle natively — the one small inline script only adds the bulk button and the
print handler. --expanded / ?expand=all renders it fully open, script-free,
for a screenshot.
npx mcp-context-card card # at a terminal: writes context-card.html and opens it
npx mcp-context-card card --expanded # every section open
npx mcp-context-card card > x.html # piped/redirected: raw HTML to stdout
GET /card # live, on the HTTP transport
GET /card?expand=all&theme=light&accent=%230066cc
Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex.
This repo's own card, live: auto ·
light ·
dark
(all in the AAIF accent shown here — pass any hex to change it).
Add it to your setup
No AGENTS.md yet?
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), 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.)
To author or keep the facts layer true outside a session:
npx agents-md-facts
npx agents-md-facts --check
See the card
One command, no host, no config — from your project directory:
npx mcp-context-card card
At a terminal it writes context-card.html and opens it in your browser. Piped
or redirected (> card.html, a script, CI) it writes raw HTML to stdout instead;
--stdout forces that from a terminal too. --expanded opens every section.
Wire it into a host
Claude Desktop, Cursor, or any stdio host:
{
"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. Requires Node ≥20.
If command: "npx" fails to spawn (spawn npx ENOENT — seen on Cursor, whose
host process doesn't inherit a shell PATH), point command at node and
the installed dist/bin.js instead — see
docs/WIRING.md. Transport choice is
in 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
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:
- Server Card
_meta (SEP‑2127) —
one reverse‑DNS‑namespaced key per concern, readable in‑band as an MCP
resource and at GET /.well-known/mcp/server-card.
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 and
.fafa — one instantiation each,
swap in your own.
The wire‑level detail is in docs/MECHANISMS.md.
| Tool | What it's for |
|---|
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 |
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:
- Context — list the
AGENTS.md sections, then pull just ## Test.
- Memory —
remember() a fact, stop the server process, start a new one,
recall() the same fact. Only the file carries it across.
- Identity —
whoami(), and the Server Card _meta block read back from a
live client.
- Discovery —
list_context_sources(), then the same server over stateless
HTTP with its .well-known routes and GET /card.
104 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
| 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 — 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 + 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 · --help · --version |
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.