Business Cards for Agents

This is the public card of an AI agent or MCP server: who it is, what it does, where to reach it. Flip it for the detail.

People read it here. Machines read the same facts from its MCP Server Card and AI Catalog, before they ever connect.

Made with mcp-context-card

mcp-context-card

MCP server · v1.7.1

The essential MCP components for a project's context (AGENTS.md), cross-session memory, and identity

faf.one

io.github.Wolfe-JampublishedMIT

Business Cards for Agents

This is the public card of an AI agent or MCP server: who it is, what it does, where to reach it. Flip it for the detail.

People read it here. Machines read the same facts from its MCP Server Card and AI Catalog, before they ever connect.

Made with mcp-context-card

AboutContextMemoryDiscovery

About

The essential MCP components for a project's context (AGENTS.md), cross-session memory, and identity — a base MCP on its own, or a drop-in extension for any existing MCP server, discoverable through the Server Card _meta block and a self-published ai-catalog.json.

Agent ID	`urn:air:faf.one:agent:mcp-context-card`
Publisher	io.github.Wolfe-Jam
Version	v1.7.1
Status	published
License	MIT
Package (npm)	`mcp-context-card`

Context — AGENTS.md

Setup
Build
Test
Layout
Conventions
The invariant
Safety
Definition of done
Authoring this file

mcp-context-card is the essential MCP server for a project's context (this file), memory, and identity — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card _meta block and ai-catalog.json sibling entries.

read_agents_md serves this file, section by section, over the same MCP connection.

Setup

npm ci

Node 22 or newer. No other system dependencies.

Build

npm run build       # tsc -p tsconfig.build.json  →  dist/
npm run typecheck   # tsc --noEmit over src/ + test/

Test

npm test              # node:test — every test/*.test.ts
npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
npm run demo          # end to end: all tools over stdio, then over stateless HTTP
npm run version:check # every version-bearing spot agrees with package.json
npm run faf:check     # project.faf / project.fafm / .well-known/fafa still describe the project

CI runs version:check → faf:check → typecheck → build → test:coverage → demo on Linux, macOS, and Windows for every push and PR to main (.github/workflows/ci.yml), plus catalog:check / card:check, faf-cli check project.faf --strict (the repo dogfoods a project.faf — this keeps it Trophy), and faf:nudge (PR-only, non-blocking — warns if the code's shape moved without project.faf) on Linux.

Layout

Path	What
`src/server.ts`	the MCP server — the ten tools + the Server Card and card resources
`src/agents-md.ts`	reads and section-splits this file
`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 + this file + memory + discovery, as one HTML page
`src/memory.ts` → `src/faf/parse-fafm.ts`	file-backed `remember` / `recall` / `forget`
`src/identity.ts`	`whoami` (`.fafa` → `package.json` fallback) + the `_meta` context block
`src/catalog-gen.ts`	writes `.well-known/ai-catalog.json` from the same three sources
`src/transport/http.ts`	the stateless Streamable HTTP app (Hono)
`src/bin.ts`	the entry point (`resolveLaunch`) — `stdio` · `--http` · `card` · `--help` · `--version`
`src/faf/parse-fafm.ts` · `parse-fafa.ts`	the `.fafm` / `.fafa` parsers

Conventions

TypeScript strict, ESM only ("type": "module", .js import specifiers).
Tests use node:test + node:assert/strict — no test framework.
Every source file opens with a comment stating what it is and why.
Conventional Commit messages (feat:, fix:, chore:, test:, docs:).

The invariant

src/identity.ts, src/catalog-gen.ts, and src/render-card.ts all describe the same three sources: this file, project.fafm, .well-known/fafa. Change what one exposes and you must change the others. npm run catalog:check and npm run card:check enforce it in CI — each regenerates its surface and fails on any diff.

Safety

Branch off main; CI must be green before merge.
npm run demo writes a fact to project.fafm and restores the file on exit — don't kill it mid-run.
No secrets live in this repo; never add any.

Definition of done

npm run typecheck && npm run build && npm test && npm run demo all green, plus npm run catalog:check and npm run card:check clean if you touched AGENTS.md, project.fafm, or .well-known/fafa, and npm run faf:check green if you changed the layout, a dependency, or the identity. On a version bump, npm run version:check green (it lists every spot that must move together) and project.faf still Trophy (faf-cli check project.faf --strict). If CI's faf:nudge warns on your PR, reconcile project.faf (and re-check project.fafm facts if AGENTS.md moved) or say why it's fine.

Authoring this file

AGENTS.md here is maintained by hand. The author_agents_md tool (or faf export --agents) would draft a BEST version straight from this repo's own project.faf plus its detected facts — the server doesn't care how the file was authored, only that it's valid Markdown.

Memory — 4 facts

The context concern points at AGENTS.md — the de-facto standard for agent instructions. read_agents_md serves it whole or one section at a time, so a client pulls '## Test' without spending its context window on the whole file. Memory and identity have no de-facto standard, so this server uses .fafm and .fafa as one instantiation each.

scopeagents-md

Both exposure mechanisms — the Server Card _meta block and a self-published ai-catalog.json — already exist in the MCP ecosystem. This server wires all three concerns through them, from one set of source files, with a CI check (catalog:check) that fails if the two surfaces drift apart.

mcpserver-cardai-catalog

Distribution: a published npm package (bin mcp-context-card, dual transport). The three source files (AGENTS.md, project.fafm, .well-known/fafa) ship with the package so it is a working discovery target on install. MCP_CONTEXT_CARD_ROOT points it at a real project.

distributionmitnpm

author_agents_md authors the best AGENTS.md the project has the material for, not a fixed floor. BETTER is the facts-only draft (via agents-md-facts: build/test commands, entry points, conventions — nothing invented). BEST is that plus a '## Project' section ahead of it, read straight from project.faf when one exists — goal, who it's for, why, and a start-here file list. The rule is concrete: project.faf present means BEST, absent means BETTER.

agents-mdauthor_agents_mdfaf

Discovery

concern	source	media type
context	`AGENTS.md`	`text/markdown`
memory	`project.fafm`	`application/vnd.fafm+yaml`
identity	`.well-known/fafa`	`application/vnd.fafa+yaml`

A machine reads this over MCP from the mcp-context-card://server-card resource; over HTTP also from GET /mcp/server-card and GET /.well-known/ai-catalog.json.