Claude FAF
About
Persistent Project Context for Claude — IANA-registered .faf format · 32 tools + 1 prompt · MCP Registry #2759
Details
- Author
- Wolfe-Jam
- GitHub stars
- 19
- Downloads
- 386
- Categories
- Developer Tools, Other, AI
Jump to
- 13 Core MCP tools (35 total with FAF_TOOLS=all)
- Persistent context via .faf ↔ CLAUDE.md ↔ MEMORY.md tri-sync
- Deterministic scoring from 0% to 100%
- SessionStart hook for Claude Code for grounded sessions
- One-click setup, local and private (no accounts, no telemetry)
- IANA-registered YAML formats (application/vnd.faf+yaml)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Claude FAFCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install via one-click .mcpb download, npm global install, or by adding the MCP server to claude_desktop_config.json. After installation, type /faf in Claude Desktop to check and score your project. Alternatively, tell Claude your 3Ws (Who, What, Why) to generate project.faf.
faf_about
Explain what the FAF format is — project DNA for AI — with its IANA registration, version, and connected platforms. Returns format metadata and the available MCP bridges. Use this when someone asks what FAF is or how it connects to other AI tools.
faf_score
Score a project.faf and return its 0–100% AI-readability, tier, and per-slot breakdown, via the deterministic Mk4 engine. Use this for a quick status check; use faf_doctor when you need to diagnose and fix what's missing.
faf_init
Create a new project.faf with a name, goal, and language. Returns the file path and starting score. Won't overwrite an existing file — use faf_auto to fill the stack from your manifests, or faf_go for the human 6Ws.
faf_trust
Attest a project.faf's integrity: its validity, score, and a deterministic parity hash any conformant engine reproduces. Returns the ✪ receipt. Use this to prove a score is genuine and untampered.
faf_sync
Sync project.faf into CLAUDE.md as a faf-managed block, and optionally into AGENTS.md (agents), .cursorrules (cursor), GEMINI.md (gemini), and .github/copilot-instructions.md (copilot) — or all of them (all). Updates each block in place — it never overwrites your file. Use this after editing project.faf so every AI tool sees the latest context.
faf_context
Set or show the active project path that subsequent faf_ calls resolve against. Returns the current context path. Call this once at the start of a session so the other tools target the right project.
faf_go
The friendly front door — "let's go, tell me about your idea." Asks the human the 6Ws (goal, why, who, what, where, when) that can't be auto-detected, then applies them to project.faf. If no project.faf exists yet, faf_go bootstraps it first (creates it, sources the stack) so you go from nothing to the 6Ws in one step. Returns the Table-of-8 to confirm/answer, or applies the answers you pass back. Use faf_auto for the technical stack on its own.
faf_auto
Scan your manifests (package.json, Cargo.toml, pyproject.toml, go.mod…) and fill the project.faf stack slots from real dependencies — no hardcoded defaults. Returns what was detected and the updated score. Use this for the technical context; use faf_go for the human 6Ws it can't detect,
faf_bench
Prove the .faf earns its place — measure how much the context is worth, on THIS repo, falsifiably. Questions derive from the project.faf's own populated slots (the .faf is the answer key), so grading is mechanical — no judge, no rubric. action=questions returns the answer-key-safe question set; action=grade takes your answers WITHOUT the .faf (cold) and WITH it (faf), grades both, and returns the cold→with-faf lift with a ✪ receipt. The delta is the product; the cold number belongs to the absence of context, never to FAF.
faf_doctor
Diagnose a project.faf: report empty or weak slots, common issues, and how to fix each. Returns a prioritized checklist. Use this when faf_score is below target and you need to know why.
faf_etch
Remember a decision, gotcha, or win across sessions by writing it to the project soul (.fafm). Returns the stored memory's id. Use this to persist something an AI should recall later; use faf_recall to read them back.
faf_recall
Recall memories from the project soul (.fafm), ranked by priority then recency, filtered by query/tags/type. Returns the matching entries. Use this to surface past decisions; use faf_etch to add new ones.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"claude faf": {
"claude-faf-mcp": {
"command": "npx",
"args": [
"-y",
"claude-faf-mcp"
]
}
}
}
}McpServers
{
"claude-faf-mcp": {
"command": "npx",
"args": [
"-y",
"claude-faf-mcp"
]
}
}claude-faf-mcp — The GitHub Registry Edition
Home: faf.one/mcp
Live demo: 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.
> 🐘 tri-sync | .faf ↔ CLAUDE.md ↔ MEMORY.md in one command.
> ⚡ New: /faf prompt — type /faf in Claude Desktop. It checks your project, scores it, drives it to 100%, and syncs. Relentlessly. One command.
> v5.20.0 — The GitHub Registry Edition. claude-faf-mcp joins GitHub's MCP Registry — discoverable in VS Code — as Claude FAF, its display title now emitted from project.faf, single-sourced and idempotent. The registry derives a display name from the server-card title; CFM now provides it through the emitter (name + _meta + title, all composed from project.faf, never hand-authored — the BRAKE B1 test enforces emitted == live).
> v5.15.0 — The Instructions Edition. CFM writes the file Copilot reads — done right. .github/copilot-instructions.md is now genuine, distinct Copilot instructions: a prose overview, a ## Build & run command section, and "every request" framing — not the AGENTS.md content reused. The file Copilot actually reads, done to GitHub's spec.
> v5.14.1 — The Copilot Edition. FAF now writes the file GitHub Copilot reads — from inside Claude. The Core faf_sync gains a copilot flag (all includes it), syncing .github/copilot-instructions.md — Copilot's widest-surface instruction file, read by default across web chat, code review, VS Code, JetBrains, the CLI, and the coding agent — straight from your scored .faf. faf_sync now emits every format (agents/cursor/gemini/copilot/all) from the default surface; the redundant faf_bi_sync is retired. Non-destructive, idempotent.
> 🧡 v5.13.0 — The Heartbeat Edition. Persistent Project Context with Memory, looped for you. Every Claude Code session now opens with a one-line heartbeat that carries the intent the code can't: faf: context ✪ 100% — fresh · +7 intent the code can't carry. The +N is the goal and 6Ws only you can give or confirm — so Claude starts each session grounded in what your project means, not just what it contains.
> 🏆 v5.12.0 — The Proof Edition. faf_bench proves FAF's grounding lift in-session — it asks Claude about your repo cold (no context) and with the .faf, grades mechanically (no judge), and emits a ✪ receipt showing the delta. Promoted to lead the Core tier (13 tools, 36 total). faf_go now bootstraps a cold repo (init → auto → 6Ws), and you can still just type faf to start. Proof, not pitch.
> 🏆 v5.11.0 — The Distilled Edition. claude-faf-mcp, distilled — a curated Core of 12 self-documenting tools, with the interview, README extractor, and server-card all composed from faf-cli's single source (no forks), and faf_go's new Table-of-8 where your goal seeds the 6Ws. Fewer tools, nothing forked, nothing guessed.
Context for Claude: faf-cli keeps this MCP's CLAUDE.md / AGENTS.md in sync from one scored source — bunx faf sync. See FAF-CLI for Claude Code 👀.
> 🏆 v5.10.0 — The Dart Edition. claude-faf-mcp now reads Dart & Flutter — it knows a Flutter app from a pure-Dart CLI. Detection by composition: because CFM composes faf-cli's Turbo-Cat (The Sourced Edition), faf-cli 6.13.0's content-aware, pubspec-driven Dart classifier arrives by construction — no forked parser, no drift. 35 tools, npm audit clean.
> 🏆 v5.9.0 — The Sourced Edition. Every answer comes from one source. faf_go and Turbo-Cat detection now compose faf-cli's single-source engines instead of carrying their own copies — fills come from real evidence or stay honestly empty, nothing guessed. The legacy guessing extractor is gone; the /faf prompt drives to a verified 100% (faf_trust + ✪ parity receipt) and keeps it fresh. FAF don't lie, by construction.
> 🏆 v5.8.0 — The Trust Edition. Claude Code-native context that just works. A native SessionStart hook opens every session with fresh context and a one-line ✪ heartbeat (faf: context ✪ 100% — fresh); tool output is quiet (no emoji, parseable) and typed (structuredContent everywhere); every score carries a deterministic parity hash any engine reproduces, sealed in a self-verifying ✪ receipt. Installed explicitly via faf_setup — preview first, your settings preserved. Built on the Canonical foundation: path-confined file access, edge-direct remote, 35 tools.
13 Core MCP tools (35 with FAF_TOOLS=all). IANA-registered formats (application/vnd.faf+yaml · application/vnd.fafm+yaml). 1,716 test executions per push.
---
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:
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
faf-cli — universal (any AI)
npx faf-cli auto
Same .faf, every surface — Claude, Gemini, Grok, Cursor. faf-cli on npm →
Claude Desktop — click, copy, paste, install
Click — one-click .mcpb
⬇ Download claude-faf-mcp-5.13.0.mcpb
Double-click. Zero-Config — no terminal, no JSON config. 13 Core tools live in 10 seconds.
Copy — paste-prompt to Claude
> Install the FAF MCP server: npm install -g claude-faf-mcp, then add this to my claude_desktop_config.json: {"mcpServers": {"faf": {"command": "bunx", "args": ["claude-faf-mcp"]}}} and restart Claude Desktop.
Paste — claude_desktop_config.json
{
"mcpServers": {
"faf": { "command": "bunx", "args": ["claude-faf-mcp"] }
}
}
Install — manual npm
npm install -g claude-faf-mcp
Smithery: wolfe-jam/claude-faf-mcp — hosted at https://mcpaas.live/claude/mcp/v1
Restart Claude Desktop.
Then
Type /faf — Claude checks your project, scores it, drives it to 100%, and syncs. Done.
Or tell Claude your 3Ws: "I'm building [what] for [who] because [why]"
---
How It Works
You → 3 answers → project.faf → AI reads it → every session → forever
project.faf ←── 8ms ──→ CLAUDE.md (bi-sync, free)
project.faf ←── 8ms ──→ MEMORY.md (tri-sync, Pro 🐘)
Claude does the rest. Zero-effort, right first time, fast, accurate, done. Language, framework, package manager, build tools — all auto-detected 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 ↔ CLAUDE.md stay in sync (bi-sync'd). 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 and private. Nothing leaves the machine — no accounts, no telemetry. The context is yours; it just 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. Same compiler as faf-cli — same score everywhere.
---
MCP Tools — 13 Core, 35 with FAF_TOOLS=all
By default claude-faf-mcp advertises a distilled Core of 13 — the lifecycle tools you reach for, each self-documenting. Set FAF_TOOLS=all to expose all 35 (Extended tools stay callable by name regardless). Core 13: faf_init · faf_auto · faf_go · faf_bench · faf_enhance · faf_score · faf_doctor · faf_sync · faf_context · faf_trust · faf_about · faf_etch · faf_recall.
All tools run standalone — zero CLI dependencies, 19ms average execution.
Create & Detect
| Tool | Purpose |
|------|---------|
| faf_init | Initialize project DNA |
| faf_auto | Auto-detect stack and populate context |
| faf_quick | Lightning-fast creation (3ms) |
| faf_readme | Extract context from README (+25-35% boost) |
| faf_formats | Discover all formats in your project |
| faf_git | Extract context from any GitHub repo URL |
| faf_human_add | Add human context (the 6Ws) |
Validate & Score
| Tool | Purpose |
|------|---------|
| faf_score | AI-readiness score (0-100%) with breakdown |
| faf_bench | Benchmark AI grounding — cold vs .faf, with a ✪ receipt |
| faf_check | Validate .faf structure |
| faf_doctor | Diagnose and fix common issues |
| faf_go | Guided interview to Gold Code |
Sync & Persist
| Tool | Purpose |
|------|---------|
| faf_sync | Sync .faf → CLAUDE.md — agents/cursor/gemini/copilot/all also emit AGENTS.md / .cursorrules / GEMINI.md / copilot-instructions.md |
| faf_tri_sync | Tri-sync .faf ↔ CLAUDE.md ↔ MEMORY.md — Pro feature, free for developers 🐘 |
| faf_enhance | Intelligent enhancement |
Export & Interop
| Tool | Purpose |
|------|---------|
| faf_agents | Import/export AGENTS.md (OpenAI Codex) |
| faf_cursor | Import/export .cursorrules (Cursor IDE) |
| faf_gemini | Import/export GEMINI.md (Google Gemini) |
| faf_conductor | Import/export Conductor directory |
Read & Write
| Tool | Purpose |
|------|---------|
| faf_read | Read any file |
| faf_write | Write any file |
| faf_status | Project status overview |
| faf_debug | Environment inspection |
| faf_about | What is .faf? |
---
🐘 Nelly Never Forgets
bi-sync keeps .faf ↔ CLAUDE.md aligned.
tri-sync adds MEMORY.md — your AI remembers your project across every session.
bi-sync = .faf ↔ CLAUDE.md ← always in sync
tri-sync = .faf ↔ CLAUDE.md ↔ MEMORY.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). Works with any AI. Define once, use everywhere.
---
Ecosystem
| Package | Platform | Registry |
|---------|----------|----------|
| claude-faf-mcp (this) | Claude | npm |
| faf-cli | Universal CLI | npm + Homebrew |
| gemini-faf-mcp | Google Gemini | PyPI |
| grok-faf-mcp | xAI Grok | npm |
| rust-faf-mcp | Rust | crates.io |
| faf-wasm | Browser/Edge | npm |
| Chrome Extension | Browser | Chrome Web Store |
Same project.faf. Same scoring. Same result. Different execution layer.
---
Quality
572 tests · 28 suites · 3 platforms (bun on ubuntu/macos/windows)
---
Privacy
Everything runs locally. No data leaves your machine. No analytics, no telemetry, no tracking, no accounts. 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 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
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}
}
License
MIT — Free and open source
---
FAF Family
| | |
|---|---|
| faf-cli | npx faf-cli init — create .faf for any project |
| claude-faf-mcp | MCP server for Claude Desktop |
| gemini-faf-mcp | MCP server for Gemini CLI |
| grok-faf-mcp | MCP server for Grok |
| faf-mcp | MCP server for Cursor, Windsurf, Cline, VS Code |
| rust-faf-mcp | MCP server in Rust |
| faf-skills | 17 Claude Code skills |
| faf.one | Blog, downloads, docs |
| IANA: vnd.faf+yaml | Context format (2025-10-30) |
| IANA: vnd.fafm+yaml | Memory format (2026-05-13) |
format | driven 🏎️⚡️ wolfejam.dev
---
Get the CLI
> faf-cli — The original AI-Context CLI. A must-have for every builder.
npx faf-cli auto
Anthropic MCP #2759 · 2 IANA registrations: vnd.faf+yaml (Context) · vnd.fafm+yaml (Memory) · faf.one · npm
---
Zero-Config. Context that's just there — every session.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
