claude-faf-mcp

Home: faf.one/mcp
Site: claude.faf.one

Persistent Project Context with Memory, looped for you. One-click setup. 30 seconds. 🐘 Nelly Never Forgets.

FAF defines. MD instructs. AI codes.

⭐ Bookmarks it for you, helps other devs find it too.

v0.2-conformant reader of the FAF Context Ingestion Contract.

🐘 tri-sync | .faf → MEMORY.md (faf_tri_sync), alongside .faf → CLAUDE.md (faf_sync).

⚡ The faf prompt — pick it from your host's prompt list (Claude Code shows it as /mcp__<server name>__faf). It scores your project, fills what the repo can, asks you only what only you can answer, verifies, and syncs.

6.0.0 is a major release. It needs Node 22 or later. faf_clear, faf_friday, faf_guide and faf_write are retired, and so are the AGENTS.md / .cursorrules / GEMINI.md / conductor imports into project.faf. The .mcpb now runs the server bundled inside it. The npx config and the SessionStart hook are not pinned to a version, so an install that runs npx -y claude-faf-mcp moves to 6.x on its next start: check your Node before you upgrade. Every change is in the CHANGELOG.

Context for Claude: faf-cli writes this repo's CLAUDE.md from its scored project.faf — faf_sync here, faf sync in faf-cli. See FAF-CLI for Claude Code 👀.

Composes faf-cli (the version is pinned in package.json). Detection, scoring, the renders and every writer are faf-cli's own functions, loaded as a dependency; claude-faf-mcp does not fork them and never runs a faf found on your PATH.

Core 14 MCP tools (30 with FAF_TOOLS=all). IANA-registered formats (application/vnd.faf+yaml · application/vnd.fafm+yaml).

What's New in v6.0.0 — The Earned Badge Edition

Every badge earned, none claimed: claude-faf-mcp 6.0 composes faf-cli, touches only what it wrote, and every tool tells the truth — one score, facts from repo, nothing from your PATH.

• Composes faf-cli 7.13. Detection, scoring, the renders and every writer are faf-cli's own functions. claude-faf-mcp never runs a faf it finds on your PATH.
• Touches only what it wrote.
  • Every write is atomic and goes through faf-cli's safe path, and a file that links out of the project is refused.
  • project.faf edits keep your comments and exact values.
  • Your soul.fafm and Claude's own MEMORY.md notes stay as you left them.
• One score. Every tool shows faf-cli's score, and ✪ appears only at 100%.
• Facts from repo. Every empty slot says what fills it:
  • a fact from repo, which faf_auto writes;
  • no fact in repo, which you answer with faf_go;
  • or yours, for the 6Ws.
• Tools that tell the truth.
  • Every title, hint and schema matches what the tool does, and bad arguments are refused before anything runs.
  • Core 14: faf_setup and faf_tri_sync join the default list.
• Safe with any repo.
  • A cloned repo's symlinks never reach your AI's context.
  • faf_go answers can't pollute objects.
  • The file tools stay inside the active project.
• Ships what it runs. The .mcpb runs the server bundled inside it, and it's started and checked before its sha is recorded. Node 22+, with CI on Node 22 and 24 across Ubuntu, macOS and Windows.
• Retired: faf_clear, faf_friday, faf_guide, faf_write, the interop imports into project.faf, and faf_check protect/unlock. The archive tag archive/cfm-v5-surface keeps them.

The 3Ws — 3 Answers. That's It.

Every great product started with 3 answers to the 3Ws — Who, What, Why:

Same pattern. Every product that works starts here. .faf captures it:

human_context:
  who: "people who need a ride across town"
  what: "tap a button, car arrives in minutes"
  why: "taxis are slow, expensive, and hard to find"

30 seconds. Claude builds your project.faf from this. Every session after, AI starts smart.

The 6Ws — For Optimized AI

3Ws gets you started. For fully optimized AI, complete the set — Where, When, How:

  where: "mobile app, iOS and Android"    # where does it live?
  when: "launch in 3 months"              # when is it shipping?
  how: "GPS matching, real-time pricing"  # how does it work?

3Ws initiates the project with AI. 6Ws optimizes AI to 100%. Same YAML, same file. More examples → faf.one/ideas

Quick Start

Needs Node 22 or later.

Claude Desktop — one click

⬇ Download claude-faf-mcp-6.0.0.mcpb

Open it in Claude Desktop. The extension runs the server bundled inside it (no npx, no network at start) and lists the Core 14 tools.

Claude Desktop — config

Add to claude_desktop_config.json, then restart Claude Desktop:

{
  "mcpServers": {
    "faf": { "command": "npx", "args": ["-y", "claude-faf-mcp"] }
  }
}

After npm install -g claude-faf-mcp you can use the installed bin instead: { "command": "claude-faf-mcp" }. With Bun on Claude Desktop's PATH, { "command": "bunx", "args": ["claude-faf-mcp"] } works too.

Claude Code

claude mcp add faf -- npx -y claude-faf-mcp

Pinning

The npx config and the SessionStart hook faf_setup installs (npx -y claude-faf-mcp --session-refresh) are not pinned: they run the latest release, so fixes arrive without a reinstall, and a new major arrives the same way. To stay on a major, write it in your config yourself: "args": ["-y", "claude-faf-mcp@6"]. The .mcpb runs the version it was built from.

Then

Run the faf prompt — Claude scores your project, fills what the repo can, asks you what only you can answer, verifies and syncs.

Or tell Claude your 3Ws: "I'm building [what] for [who] because [why]"

faf-cli — any terminal

npx faf-cli auto

Same .faf, every surface — Claude, Gemini, Grok, Cursor. faf-cli on npm →

How It Works

You → 3 answers → project.faf → AI reads it → every session → forever

project.faf  ──→  CLAUDE.md     (faf_sync)
project.faf  ──→  MEMORY.md     (faf_tri_sync 🐘)

Language, framework, package manager, build tools — faf-cli detects them from your existing files. The human context is the part only you can give.

For Claude Code teams

.faf lives in the repo. Your context travels with the code — committed, versioned, done.

Every session starts grounded. Install the native SessionStart hook once (faf_setup — preview first, your settings preserved). After that, every Claude Code session opens with a one-line heartbeat instead of a blank slate:

faf: context ✪ 100% — fresh · +7 intent the code can't carry

That line is the relay: Claude already knows your stack and your score — and the +N is the intent the code can't carry: the goal and 6Ws only you can give or confirm. No re-explaining "what this project is" at the top of every session.

It scales to the team by construction:

commit project.faf  →  every teammate's Claude starts with the same context
git clone           →  a new dev's Claude is grounded before they write a line

• One source of truth. faf_sync writes CLAUDE.md from .faf — only its faf-managed block, so your own notes stay put. Add MEMORY.md for cross-session memory (tri-sync 🐘).
• No drift. The score is deterministic — same .faf, same number, on every machine and in CI. A teammate can't be accidentally less grounded than you.
• Local. No accounts, no telemetry, nothing sent to FAF. The one network use is cloning a repo you name, only when you ask (privacy). The context is yours; it rides in the repo.

Onboarding becomes git clone → grounded. The context a new teammate would normally pick up by asking around is already in the repo, machine-readable, from the first clone.

Scoring: From Blind to Optimized

At 55%, AI guesses half the time. At 100%, AI knows your project. The score is faf-cli's scoreFafYaml — the number faf score prints for the same file.

MCP Tools — Core 14, 30 with FAF_TOOLS=all

By default claude-faf-mcp lists the Core 14 — the lifecycle tools you reach for. Set FAF_TOOLS=all to list the Extended tools too; every tool is callable by name either way. Retired in 6.0.0: faf_clear, faf_friday, faf_guide and faf_write (a call by name returns one line naming what to use instead), the AGENTS.md / .cursorrules / GEMINI.md / conductor imports into project.faf, and faf_check protect/unlock.

Every tool runs on the faf-cli this package depends on. Nothing is run from your PATH.

Core

Extended (FAF_TOOLS=all)

🐘 Nelly Never Forgets

faf_sync writes CLAUDE.md from .faf, so the two stay aligned.

tri-sync adds MEMORY.md — your AI remembers your project across every session.

faf_sync = .faf → CLAUDE.md              ← written from .faf
tri-sync = .faf → MEMORY.md   (faf_sync writes CLAUDE.md)  ← Nelly never forgets 🐘

Pro feature, free for developers. Teams & Enterprise: faf.one/pro (plans)

The .FAF Position

Model        Context          Protocol
─────        ───────          ────────
Claude    →   .faf        →    MCP
Gemini    →   .faf        →    MCP
Codex     →   .faf        →    MCP
Any LLM   →   .faf        →    MCP

IANA-registered (application/vnd.faf+yaml). One file, one format. Define once, use everywhere.

Ecosystem

Same project.faf. Same scoring. Same result. Different execution layer.

Quality

Tests run with bun on ubuntu, macOS and Windows; the built package is packed, installed and started on Node 22 and 24 on all three. CI →

Privacy

claude-faf-mcp runs on your machine. No analytics, no telemetry, no accounts. Its one network use is faf_git, and only when you ask it to read a repo: git clones it from the URL you give. The files it writes are listed in the privacy policy →

If claude-faf-mcp has been useful, consider starring the repo — it helps others find it.

Citation

If you use claude-faf-mcp or the .faf / .fafm / .fafa formats in research or production, please cite the format papers:

Wolfe, J. (2025). Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory. Zenodo. https://doi.org/10.5281/zenodo.20348942

Wolfe, J. (2026). Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era. Zenodo. https://doi.org/10.5281/zenodo.21951641

BibTeX

@article{wolfe2025faf,
  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},
  author    = {Wolfe, James},
  year      = {2025},
  month     = {nov},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.18251362},
  url       = {https://doi.org/10.5281/zenodo.18251362}
}

@article{wolfe2026fafm,
  title     = {Permanent Memory and Instant Recall: The .fafm Standard for Multi-Profile AI Agent Memory},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {may},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.20348942},
  url       = {https://doi.org/10.5281/zenodo.20348942}
}

@article{wolfe2026fafa,
  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},
  author    = {Wolfe, James},
  year      = {2026},
  month     = {aug},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.21951641},
  url       = {https://doi.org/10.5281/zenodo.21951641}
}

License

MIT — Free and open source

FAF Family

format | driven 🏎️⚡️ wolfejam.dev

Get the CLI

faf-cli — The original AI-Context CLI. A must-have for every builder.

npx faf-cli auto

MCP Registry: one.faf/claude-faf-mcp · 2 IANA registrations: vnd.faf+yaml (Context) · vnd.fafm+yaml (Memory) · faf.one · npm

Zero-Config. Context that's just there — every session.