MCP Context Card

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.

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.

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

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

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 it

npx mcp-context-card card --portrait # the tall view npx mcp-context-card card --expanded # both faces flat, 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?layout=portrait&theme=light&accent=%230066cc

In a chat, hosts that support MCP Apps show the card inline when render_context_card runs; the model gets a short summary instead of the page. Everywhere else, 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. The server's instructions tell the model to show that rather than paste the HTML into the chat.

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.md

npx 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: . Your catalog then publishes urn:air:example.com:context: 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 (`l