# claude-faf-mcp [](https://www.npmjs.com/package/claude-faf-mcp) [](https://smithery.ai/servers/wolfe-jam/claude-faf-mcp) [](https://faf.one) [](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)[](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml) [](https://doi.org/10.5281/zenodo.18251362)[](https://doi.org/10.5281/zenodo.20348942) **Home:** [faf.one/mcp](https://faf.one/mcp) **Site:** [claude.faf.one](https://claude.faf.one) **Persistent Project Context with Memory, looped for you.** One-click setup. 30 seconds. 🐘 Nelly Never Forgets. [](https://registry.modelcontextprotocol.io/v0.1/servers?search=one.faf%2Fclaude-faf-mcp) [](https://github.com/Wolfe-Jam/claude-faf-mcp/actions/workflows/ci.yml) [](https://www.npmjs.com/package/claude-faf-mcp) [](https://opensource.org/licenses/MIT) [](https://faf-voice.vercel.app/agent) [](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/claude-faf-mcp) **FAF defines. MD instructs. AI codes.** ⭐ [Star it on GitHub](https://github.com/Wolfe-Jam/claude-faf-mcp): bookmarks it for you, helps other devs find it too. **v0.2-conformant reader** of the [FAF Context Ingestion Contract](https://github.com/Wolfe-Jam/faf/blob/main/CONTEXT-INGESTION.md). > 🐘 **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____faf`). It scores your project, fills what the repo can, asks you only what only you can answer, verifies, and syncs. > **7.0.0 is a major release — scores can move.** claude-faf-mcp now scores with faf-cli 8's always-33 engine. A `.faf` without the 12 enterprise `slotignored` markers counts them as empty (21 filled = 64%): run `faf_auto` and it writes the markers. 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 7.x on its next start. Every change is in the [CHANGELOG](./CHANGELOG.md). **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 👀](https://github.com/Wolfe-Jam/faf-cli/blob/main/docs/faf-cli-for-claude.md). **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 v7.1.0 — The Instructions Edition **claude-faf-mcp now tells Claude how its tools fit together: server instructions in initialize (637 characters), plus faf-cli 8.5.0, which knows a skills repo when it sees one.** - **Server instructions.** When Claude connects, the server says how its tools fit together, in five short lines: one project at a time, read project.faf first, ask the user for the human answers, project.faf is the source, remember only when asked. - **faf-cli 8.5.0 inside.** `faf_init` and `faf_auto` detect a skills repo: `SKILL.md` folders make it `skills` (10 slots), and a Claude Code plugin manifest makes it `skills-plugin` (14). - **`--version` and `--help`** print and exit, instead of starting the server. - **Three advisories cleared:** the MCP SDK, zod and hono. ## The Always33 Edition (7.0) **One engine, one number: claude-faf-mcp 7 scores with faf-cli 8's always-33 kernel — the same score faf-cli and faf-kernel give.** - **The always-33 engine.** Every tool scores with faf-cli 8.0.0 — all 33 Mk4 slots, one Rust kernel. Checked live: faf-python-sdk 56, mcp-context-card 56, faf-cli ✪ 100, the same numbers faf-cli and the reference scorer give. - **Your 21 slots, and the 12 enterprise slots in view.** The enterprise slots (infra, app, ops) are marked `slotignored` unless your app-type uses them. `faf_score` scores against all 33; `slotignored` slots drop out of the denominator. - **Upgrading:** a `.faf` without the 12 markers now scores against 33. **Run `faf_auto`** — it writes them and your score returns (56% → ✪ 100% on a real v7-era file). --- ## 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:** | | WHO is it for? | WHAT does it do? | WHY build it? | |---|-----|------|-----| | **Uber** | People who need a ride | Tap a button, car arrives | Taxis were broken | | **Airbnb** | Travelers who can't afford hotels | Stay in someone's spare room | Millions of empty rooms exist | | **Slack** | Teams drowning in email | Organized group messaging | Decisions buried in threads | | **Venmo** | Friends splitting bills | Send money instantly | Someone always forgets to pay back | Same pattern. Every product that works starts here. `.faf` captures it: ```yaml 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:** ```yaml 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](https://faf.one/ideas)** --- ## Quick Start Needs Node 22 or later. ### Claude Desktop — one click [**⬇ Download `claude-faf-mcp-7.1.0.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/download/v7.1.0/claude-faf-mcp-7.1.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: ```json { "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 ```bash 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 ```bash npx faf-cli auto ``` Same `.faf`, every surface — Claude, Gemini, Grok, Cursor. **[faf-cli on npm →](https://www.npmjs.com/package/faf-cli)** --- ## 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](./PRIVACY.md)). 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 | Tier | Score | What it means | |------|-------|---------------| | ✪ **TROPHY** | 100% | Gold Code — AI is optimized | | ★ **GOLD** | 99%+ | Near-perfect context | | ◆ **SILVER** | 95%+ | Excellent | | ◇ **BRONZE** | 85%+ | Production ready | | ● **GREEN** | 70%+ | Solid foundation | | ● **YELLOW** | 55%+ | AI flipping coins | | ○ **RED** | <55% | AI working blind | | ♡ **WHITE** | 0% | No context at all | At 55%, AI guesses half the time. At 100%, AI knows your project. The score is faf-cli's `scoreFafYaml` — the always-33 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** | Tool | Purpose | |------|---------| | `faf_init` | Create project.faf for a folder (faf-cli detects the stack) | | `faf_auto` | Fill project.faf from the repo's own files, then CLAUDE.md | | `faf_go` | The goal and the 6Ws, by question and answer | | `faf_score` | AI-readiness score (0-100%), from faf-cli | | `faf_bench` | Benchmark AI grounding — cold vs with the .faf, graded mechanically, with a receipt | | `faf_doctor` | Diagnose project.faf: each finding with the tool that fixes it | | `faf_trust` | Validate project.faf and return a trust receipt for its score | | `faf_sync` | Write CLAUDE.md from project.faf — `agents`/`cursor`/`gemini`/`copilot`/`all` also write AGENTS.md / .cursorrules / GEMINI.md / copilot-instructions.md | | `faf_tri_sync` | Write faf's block into the MEMORY.md Claude Code loads for this project 🐘 | | `faf_setup` | Install the SessionStart hook in the project settings (preview first) | | `faf_context` | Show or set the active project; `detail` returns the .faf text | | `faf_etch` | Remember a decision across sessions (the project soul, soul.fafm) | | `faf_recall` | Recall memories from the project soul | | `faf_about` | What the .faf format is | **Extended** (`FAF_TOOLS=all`) | Tool | Purpose | |------|---------| | `faf` | Start here: the project, its score and the steps to 100% (reads only) | | `faf_quick` | Create project.faf from one line: name, goal, language, framework, hosting | | `faf_readme` | Read the 6Ws from README.md; `apply` fills only empty slots | | `faf_human_add` | Set one 6W slot in project.faf | | `faf_formats` | The formats faf-cli finds in the folder, and what faf_auto would write (dry run) | | `faf_git` | Author a project.faf from a repo URL (clones it with git — uses the network) | | `faf_check` | faf-cli's validateFaf and the state of every slot | | `faf_dna` | The project's .faf-dna lineage (reads only) | | `faf_status` | Whether the project has a .faf, with its first lines | | `faf_agents` | Write AGENTS.md (OpenAI Codex and other agents) | | `faf_cursor` | Write .cursorrules (Cursor IDE) | | `faf_gemini` | Write GEMINI.md (Google Gemini CLI) | | `faf_conductor` | Write Google Conductor's conductor/ files | | `faf_read` | Read a file inside the active project | | `faf_list` | List a folder inside the active project | | `faf_debug` | The active project, write access and the bundled faf-cli version | --- ## 🐘 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](https://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 | Package | Platform | Registry | |---------|----------|----------| | **[claude-faf-mcp](https://www.npmjs.com/package/claude-faf-mcp)** (this) | Claude | npm | | **[faf-cli](https://www.npmjs.com/package/faf-cli)** | CLI | npm + Homebrew | | **[gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/)** | Google Gemini | PyPI | | **[grok-faf-mcp](https://www.npmjs.com/package/grok-faf-mcp)** | xAI Grok | npm | | **[rust-faf-mcp](https://crates.io/crates/rust-faf-mcp)** | Rust | crates.io | | **[faf-wasm](https://www.npmjs.com/package/faf-wasm)** | Browser/Edge | npm | | **[Chrome Extension](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm)** | Browser | Chrome Web Store | 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 →](https://github.com/Wolfe-Jam/claude-faf-mcp/actions/workflows/ci.yml)** --- ## 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 →](./PRIVACY.md)** --- 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 ```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 | | | |---|---| | **[faf-cli](https://www.npmjs.com/package/faf-cli)** | `npx faf-cli init` — create .faf for any project | | **[claude-faf-mcp](https://www.npmjs.com/package/claude-faf-mcp)** | MCP server for Claude Desktop | | **[gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/)** | MCP server for Gemini CLI | | **[grok-faf-mcp](https://www.npmjs.com/package/grok-faf-mcp)** | MCP server for Grok | | **[faf-mcp](https://www.npmjs.com/package/faf-mcp)** | MCP server for Cursor, Windsurf, Cline, VS Code | | **[rust-faf-mcp](https://crates.io/crates/rust-faf-mcp)** | MCP server in Rust | | **[faf-skills](https://github.com/Wolfe-Jam/faf-skills)** | Claude Code skills for .faf | | **[faf.one](https://faf.one)** | Blog, downloads, docs | | **[IANA: vnd.faf+yaml](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)** | Context format (2025-10-30) | | **[IANA: vnd.fafm+yaml](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml)** | Memory format (2026-05-13) | *format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev)* --- ### Get the CLI > **faf-cli** — The original AI-Context CLI. A must-have for every builder. ```bash npx faf-cli auto ``` **MCP Registry:** `one.faf/claude-faf-mcp` · **2 IANA registrations:** `vnd.faf+yaml` (Context) · `vnd.fafm+yaml` (Memory) · [faf.one](https://faf.one) · [npm](https://www.npmjs.com/package/faf-cli) --- **Zero-Config. Context that's just there — every session.**