MCP Context Card

mcp-context-card

[npm] [CI] [license: MIT] [mcp-context-card MCP server] [Business card · Get yours →]

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.

See your own project's business card — run this in its folder. It writes context-card.html and opens it in your browser. The front is the card: name, title, one-liner. Flip it for the back: About, Context, Memory, Discovery.

npx mcp-context-card card

context — the project's AGENTS.md, served whole or one section at a time.

[the back's Context tab — AGENTS.md, section nav, read_agents_md]

memory — facts that persist across sessions, in a file.

[the back's Memory tab — real, tagged, verified facts]

identity — what this server is, from its own .fafa (agent.fafa, else .well-known/fafa).

[the back's About tab — the identity in full]

Discovery goes through two surfaces already in the ecosystem: the Server Card _meta block and ai-catalog.json sibling entries.

Pick one

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.

Ten 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, and agent.fafa or .well-known/fafa), plus the context-card.html it saves on request — no general file access, no shell, no search.

The card

The screenshot at the top of this page is exactly this: the same sources rendered as a business card in one self‑contained HTML page. The view for people: read it, screenshot it, drop it in a PR, put it on a status page.

• Front: the name, a title (what it is and its version: "MCP server", "A2A agent", from where the project's .fafa says it runs) and a one-liner (the start of its description).
• Back (Flip): tabs for About (the identity in full), Skills (when the .fafa lists capabilities), Context (AGENTS.md), Memory and Discovery. Long content scrolls inside the card.
• Landscape or portrait: the ▭ ▯ button switches the view; --portrait / ?layout=portrait sets it.
• Light or dark card: the card's colour is its own, like a printed card. --theme / ?theme= sets it (default: follow your OS), and ◐ switches it. The page around it always follows your OS.

Flip, tabs and the view switch are plain CSS, so they work with scripts off. The one small inline script adds Expand all, opens a #section link on the back, and opens every section for printing. Hosts that support MCP Apps read ui://mcp-context-card/card.html: this same page, plus a hidden inline view and the helper bundled in (scripts/bundle-card-app.mjs), so the host can fit its frame. Nothing is loaded from the network. The saved context-card.html, GET /card, and the CLI are the plain page, without that helper and without the inline view.

In a host, the inline view is a mini card for the panel: monogram, name, kind · version, one line, and a strip of counts (sections · facts · identity), with one action, "Open full card". It shows when the host's display mode is inline (or picture-in-picture). Fullscreen, and any page with no host, is the full card. "Open full card" asks the host for fullscreen; a host that stays smaller points to save_context_card, which writes the full card to context-card.html. --expanded / ?expand=all renders both faces flat, every section open, for a screenshot or print.

npx mcp-context-card card            # at a terminal: writes context-card.html and opens itnpx mcp-context-card card --portrait # the tall viewnpx mcp-context-card card --expanded # both faces flat, every section opennpx mcp-context-card card > x.html   # piped/redirected: raw HTML to stdoutGET /card                            # live, on the HTTP transportGET /card?layout=portrait&theme=light&accent=%230066cc

render_context_card is the one command, with three outcomes. In a chat whose host supports MCP Apps, the host draws the card (the mini card in a panel) and the model gets a short line. Anywhere else, a terminal for one, the reply is the text card: the card as Markdown. Ask for it as text and format: "markdown" gives the text card in any chat. HTML goes only to a browser: save_context_card writes context-card.html into the project, opens it in your browser when the server runs locally, and replies with the card as Markdown (identity, the AGENTS.md sections, memory, discovery), a link to the full card, and its address to copy. The Markdown is a tl;dr by default: five facts, each cut to its first sentence as stored, so it stays small however much a project remembers. detail: "full" lists every fact whole. For a client without MCP Apps, the server's instructions point the model at save_context_card when the user wants to see the card.

Light, dark, or auto. The colour is the owner's: set it in the project's .fafa (metadata.cards.accent: "#0066cc"), or pass any hex with --accent or ?accent. With none, the card is drawn in ink, black or white; no colour is guessed. This repo's own card, live: auto · light · dark (in the AAIF orange its .fafa declares).

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          # author / refresh AGENTS.mdnpx agents-md-facts --check  # fail if missing or stale (CI, pre-commit)

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

goose, Claude Desktop, Cursor, or any stdio host:

{  "mcpServers": {    "context-card": {      "command": "npx",      "args": ["-y", "mcp-context-card"]    }  }}

No path to configure: the server asks the host which project you're in (MCP roots — goose sends its session's working directory), then falls back to the directory it was started in if that has an AGENTS.md. list_context_sources reports which project it picked and how. To pin one project instead, set "env": { "MCP_CONTEXT_CARD_ROOT": "/abs/path/to/your/project" }; that always wins. Identity is optional. Over HTTP instead: PORT=8080 npx mcp-context-card. Requires Node ≥22.

HTTP mode is local by default, as the MCP transports spec asks: it binds 127.0.0.1, refuses foreign browser origins with 403, and refuses DNS names rebound to this machine. HOST=0.0.0.0 exposes it (a container or hosted deploy). There is no authentication or rate limiting, so put an exposed server behind your own. Memory is session data: an exposed server shows only its count on /card, and never serves or lists project.fafm, unless you set MCP_CONTEXT_CARD_PUBLISH_MEMORY=1. Details: docs/TRANSPORT.md.

In a host that shows MCP Apps (goose, for one), the card comes with the official MCP Apps helper, so it reports its size and fits its frame (about 700 KB, loaded by the host, not the model). For the plain card instead (about 30 KB, the host's default frame), set "env": { "MCP_CONTEXT_CARD_APP": "plain" }. Everywhere else the card is plain either way.

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.

Your identifiers

The AI Catalog names each entry urn:air:{domain}:{namespace}:{name}, and the domain is yours. It comes from your project's .fafa: run npx faf-cli card init (or --domain example.com), and it writes agent.id: urn:air:example.com:agent:<short-name>. Your catalog then publishes urn:air:example.com:context:<short-name> and so on, with no code to change. This repo's own .fafa says faf.one; that's our example, and yours says yours.

With no .fafa, no domain is invented: the served catalog uses the host it's served from (localhost when you run it locally), and the static .well-known/ai-catalog.json uses plain <short-name>:<namespace> IDs.

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) — one reverse‑DNS‑namespaced key per concern, readable in‑band as an MCP resource and at GET /mcp/server-card (the 1.x /.well-known/mcp/server-card still answers).
2. ai-catalog.json — the Server Card plus 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.

Tools

Seven tools only read. remember and forget write the memory file, and save_context_card writes context-card.html, so those three are marked destructive and a host can ask before running them. Every tool carries a title and MCP tool annotations.

The demo

npm run demo walks through context, memory, identity and discovery, live, 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.

252 tests on Linux, macOS, and Windows, coverage‑gated in CI. npm run wjttc runs the WJTTC certification suite (seven tiers, from protocol and Server Card conformance to stdio/HTTP parity and the shipped package). 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, and another checks every tool's title and behaviour hints against what it actually does. src/conformance/discovery.ts checks any server's Server Card, AI Catalog and transport security against the specs, one MUST or SHOULD at a time.

Layout

Related

• Server Card SEP‑2127 · ai-catalog · AGENTS.md
• 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.