Persistent project context for Claude. IANA-registered .faf format.
io.github.Wolfe-Jam/claude-faf-mcp (MCP)
This Model Context Protocol (MCP) server provides persistent project context for Claude using an IANA-registered .faf format. It is implemented as a TypeScript MCP server (package name shown in the excerpt) and exposes 19 tools for context-related interactions.
🛠️ Key Features
Persistent project context for Claude
Uses IANA-registered .faf format
TypeScript + MCP server
Tooling footprint: 19 tools
🚀 Use Cases
Supplying Claude with project context via a canonical project.faf
Context preparation for AI agents in developer workflows
⚡ Developer Benefits
Developer-tool oriented integration aligned with Model Context Protocol
Topics indicate support for developer environments and tooling (e.g., TypeScript/Node/VSC-related stack)
Includes a referenced “12 Core tools (34 total)” in the provided excerpt
⚠️ Limitations
Described capabilities are limited to persistent context for Claude via .faf; no additional behaviors are specified in the available data
Discover tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints. Optionally suggest tags for a specific handle.
Parameters1
handle
string
optional
Optional: suggest tags for this specific namepoint
Raw schema
{
"type": "object",
"properties": {
"handle": {
"type": "string",
"description": "Optional: suggest tags for this specific namepoint"
}
}
}
generate_faf_from_github
Generate a .faf file from any public GitHub repository WITHOUT cloning. Extracts 6 Ws from README, analyzes stack from languages and package.json, and generates Championship-grade AI context. Returns .faf content, quality score, and metadata.
Parameters1
repo
string
required
GitHub repository URL or owner/repo format (e.g., "facebook/react" or "https://github.com/facebook/react")
Raw schema
{
"type": "object",
"properties": {
"repo": {
"type": "string",
"description": "GitHub repository URL or owner/repo format (e.g., \"facebook/react\" or \"https://github.com/facebook/react\")"
}
},
"required": [
"repo"
]
}
faf_score
Score .faf YAML content via the Mk4 Zig-WASM engine. Returns 0-100 (capped). Same engine as xai-faf-rust + xai-faf-zig (parity-tested). Sub-ms at the edge.
Parameters1
content
string
required
Raw .faf YAML content. Souls with a [faf] section have it extracted automatically.
Raw schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Raw .faf YAML content. Souls with a [faf] section have it extracted automatically."
}
},
"required": [
"content"
]
}
faf_validate
Validate .faf YAML content via the Mk4 Zig-WASM engine. Returns true if mission-ready (>= 100).
Re-ground on .faf content — re-score via the Mk4 Zig-WASM Enterprise scorer (33-slot, honors the authored app-type shape), report drift vs an optional baseline score, and return a stamped re-ground. The explicit re-grounding primitive for long sessions: drift → refresh → re-grounded. Built for Grok, by request.
Parameters3
content
string
required
Raw .faf YAML content to re-ground on.
baseline
number
optional
Optional last-known score (0-100). When provided, the drift delta (current - baseline) is reported.
verbatim
boolean
optional
When true, return the full .faf content verbatim with the stamp. Default false (stamped delta + summary).
Raw schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Raw .faf YAML content to re-ground on."
},
"baseline": {
"type": "number",
"description": "Optional last-known score (0-100). When provided, the drift delta (current - baseline) is reported."
},
"verbatim": {
"type": "boolean",
"description": "When true, return the full .faf content verbatim with the stamp. Default false (stamped delta + summary)."
}
},
"required": [
"content"
]
}
faf_orchestrate_recommendation
Takes raw content strings (`.faf`, `.fafm`, and optionally `package.json`/`CHANGELOG.md`/`README.md`) and runs deterministic drift + contradiction signals across the FAF substrate. Returns a structured `Recommendation` (recommend, severity, reason, summary) with `hints` containing the current `effective_policy` and `partial[]` for any stateful signals unavailable on the current surface. Light-lane execution (hosted) is WASM-pure with no filesystem access. Heavy-lane execution (local via bunx/rust-faf-mcp) has full FS + persisted state. Advisory only — never auto-fires.
Parameters5
faf
string
optional
Raw .faf YAML content (project DNA). Required for any meaningful analysis.
fafm
string
optional
Raw .fafm YAML content (memory layer). Enables drift detection.
packageJson
string
optional
Raw package.json content. Enables version cross-stamp checks (.faf vs pkg).
changelog
string
optional
Raw CHANGELOG.md content. Enables changelog cross-stamp checks.
readme
string
optional
Raw README.md content. Enables README arch-tree cross-stamp checks.
Phase III (FRC) — pre-promotion quality gate. Scores .faf content (edge Mk4) + estimates tokens and returns a deterministic promote/hold verdict BEFORE it goes to a Grok Collection. Promote IFF score >= min_score AND tokens <= max_tokens (defaults 85/8000). Edge parity with the local gate; the hold-hint can't list empty slots at the edge.
Phase III (FRC) — returns an EXACT, WHOLE .faf section by dotted path (e.g. "stack", "human_context"), structure preserved — the deterministic complement to blind chunking. Omit "section" to list every path.
Parameters2
content
string
required
Raw .faf YAML content.
section
string
optional
Dotted path to retrieve (e.g. "stack.backend"). Omit to list all paths.
Raw schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Raw .faf YAML content."
},
"section": {
"type": "string",
"description": "Dotted path to retrieve (e.g. \"stack.backend\"). Omit to list all paths."
}
},
"required": [
"content"
]
}
faf_memory
Phase III (FRC) — query the durable .fafm model by type/tag/priority/text. Omit filters for a structured summary. .fafm is NOT scored: this SELECTS facts (provenance preserved), never grades them.
Parameters5
content
string
required
Raw .fafm YAML content.
type
string
optional
Filter by fact type (e.g. "feedback").
tag
string
optional
Filter by a tag.
priority
string
optional
Filter by priority (e.g. "critical").
query
string
optional
Case-insensitive substring match on fact text.
Raw schema
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "Raw .fafm YAML content."
},
"type": {
"type": "string",
"description": "Filter by fact type (e.g. \"feedback\")."
},
"tag": {
"type": "string",
"description": "Filter by a tag."
},
"priority": {
"type": "string",
"description": "Filter by priority (e.g. \"critical\")."
},
"query": {
"type": "string",
"description": "Case-insensitive substring match on fact text."
}
},
"required": [
"content"
]
}
faf_collections_search
Phase III (FRC §7b) — semantic search over a Grok Collection at the edge, KV-cached (1h TTL). Returns matched chunks (content, score, file). Requires the XAI_API_KEY secret; composes with faf_section (structural) for hybrid retrieval. Handled env-aware in the MCP handler (needs the key + KV).
Parameters3
query
string
required
The search query.
collection_id
string
required
The Grok Collection id to search.
limit
number
optional
Max chunks to return (default 5).
Raw schema
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query."
},
"collection_id": {
"type": "string",
"description": "The Grok Collection id to search."
},
"limit": {
"type": "number",
"description": "Max chunks to return (default 5)."
}
},
"required": [
"query",
"collection_id"
]
}
⚡ 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.
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.
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.
One engine, one number: claude-faf-mcp 7 scores all 33 slots 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?
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 →
How It Works
code
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:
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:
code
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
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.
code
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
code
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.
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
@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}
}
