# AGENTS.md

`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

```bash
npm ci
```

Node 22 or newer. No other system dependencies.

## Build

```bash
npm run build       # tsc -p tsconfig.build.json, then copy the bundled card script → dist/
npm run typecheck   # tsc --noEmit over src/ + test/, then the browser script
```

## Test

```bash
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/browser/card-app.ts` | the card's MCP Apps script (size, inline view), inlined only into the `ui://` resource |
| `scripts/bundle-card-app.mjs` | bundles the script so the sandbox loads nothing from the network |
| `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. `card:check` also fails if a plain card exceeds 64 KB.

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