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

In your AI client, once the server is added (Add it to your setup), say show context card. The AI picks where it appears: drawn in the chat by hosts that support MCP Apps, as Markdown elsewhere. Name a place to choose: *show context card as markdown*, *show context card in the browser*. Clients that list MCP prompts also offer it as the prompt show; in Claude Code type /contextcard:show.

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, one prompt (show), 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

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 (an MCP Apps host still draws the card too). 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. The server's instructions send *show context card* to render_context_card, and use save_context_card only when the user asks for the browser or a file.

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": { "contextcard": { "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, the Cursor editor its open folder), 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.

In goose, the first start downloads the package, and goose can stop waiting before it's ready ("process quit before initialization"). Restart goose once it has downloaded, or install it once (npm i -g mcp-context-card) and set the command to mcp-context-card.

If command: "npx" fails to spawn (spawn npx ENOENT — seen on Cursor, whose host pr