mcp-context-card

An MCP server that makes a project's context, memory, and identity discoverable to any MCP client — and renders them as one card you can read.

• 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 agent card

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

What it is / what it is not

It is — an MCP server for a project's AGENTS.md, memory, and identity: nine tools, two discovery surfaces (Server Card _meta, ai-catalog.json), and a rendered card. Small, MIT — read it, npx it, or fork it.

It is not

• a framework or a platform — three concerns, nothing more

• a file, shell, or search tool — it never touches your files or runs commands

• tied to FAF — context is plain Markdown (AGENTS.md); the memory and identity formats are swappable examples

It composes:

• serve · discover · render — this server

• author · keep true — agents-md-facts (the author_agents_md tool wraps it)

• files · shell · git — server-filesystem, server-git / github‑mcp‑server, your test runner's MCP

A piece, not the toolbox.

Related MCP server: research-memory-mcp

The card

The same three sources render as one self‑contained HTML page — identity, AGENTS.md, memory, and how a machine fetches it. The view for people: screenshot it, drop it in a PR, put it on a status page.

GET /card                      # live, on the HTTP transport
GET /card?theme=light&accent=%230066cc
npx mcp-context-card card       # or:  npm run card  →  docs/card.html

Light, dark, or auto; the accent defaults to the AAIF palette and takes any hex. docs/card.html is this repo's, rendered.

Who it's for

Add it to your setup

No AGENTS.md yet?

The author_agents_md tool authors one from your repo's facts — real build/test commands, entry points, toolchain conventions — and hands the agent the draft. It's a thin wrapper over agents-md-facts; to author or keep one 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)

A project.faf is the next rung — a structured source that refreshes the file. Short model: agents-md-facts/docs/BETTER-BEST.md.

See the card

One command, no host, no config:

npx mcp-context-card card > card.html

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. Full wiring is in docs/WIRING.md; transport choice in docs/TRANSPORT.md.

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 /.well-known/mcp/server-card.

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

Tools

The demo

npm run demo runs every tool 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.

88 tests on Linux, macOS, and Windows, coverage‑gated in CI. One spawns a real child process and checks a remembered fact survives the restart; another checks the stdio and HTTP tool surfaces match.

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.