.FAF Context
You can create, score, diagnose, and sync a persistent project.faf context that feeds multiple AI/IDE context files.
Initialize or auto-generate a
project.faffrom a project path, with stack detection and CLAUDE.md generation.Fill missing goal and human-context slots through a guided interview using repo-based suggestions.
Score AI-readiness, validate required fields, rate context quality, and diagnose low scores with fixes.
Reconcile
project.fafwith package.json metadata and dependencies in dry-run or applied mode.Write CLAUDE.md and optionally AGENTS.md, .cursorrules, and GEMINI.md from
project.faf.Import, export, or sync AGENTS.md, .cursorrules, and GEMINI.md while preserving non-faf content.
Author a new
project.faffrom a public GitHub repository URL.Set or view the active project path, and explain the IANA-registered
.fafformat.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@.FAF Context sync .faf to all AI formats"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Home: wolfe-jam.github.io/faf-mcp
.FAF Context is the MCP server for the IDE side of FAF. One project.faf in your repo, and every AI tool's context file is authored from it — AGENTS.md, .cursorrules, GEMINI.md, CLAUDE.md — and scored, so you know exactly where to focus. It runs locally over stdio on the same faf-cli the terminal uses. The FAF ecosystem it belongs to has comfortably passed 100k downloads across npm and PyPI (live count).
⭐ Star it on GitHub: bookmarks it for you, helps other devs find it too.
What's New in 4.2.0 — The Human Slots Edition
AI suggests, you confirm. faf-mcp no longer writes your project's goal or six W's: faf_go shows each suggestion with its source, and only what you confirm is written.
faf_gooffers the suggestions. Each empty goal or W comes with faf-cli's suggestion and where it came from (README.md § Why,package.json description). Your editor's AI asks you; only the answers you confirm are written.faf_initandfaf_autoleave them empty and say how many suggestions are waiting, so a new project.faf scores lower, honestly. Files you already have are not changed.faf_readmesuggests and never writes;faf_syncnever writes the goal.faf_syncstill updates the name and stack from package.json.faf_goanswers are real slots, as text. Any other key refuses the call and nothing is written.faf-cli 8.10.0 inside. Not changed yet:
faf_gitstill writes the goal from the GitHub description; it moves to faf-cli's pipeline in a later release.
Related MCP server: gemini-faf-mcp
4.1.3 — The Instructions Edition
faf-mcp now says what faf-cli's writer did: the note when faf's block goes above older faf text, and each file it could not write. When a context file starts with older faf text, the reply carries faf-cli's note that the old text is left as you had it; faf_claude names any chained file it could not write, with the reason.
4.1.2
faf_write can no longer overwrite the birth certificate or your context files, and faf_dna never issues a second one. .faf-dna is refused in every spelling and route, existing context files need overwrite: true, and faf_dna refuses rather than reissue when git shows a certificate existed.
4.1.1
One rule for project questions: read project.faf first.
Server instructions, line 2. "For questions about the project (stack, goal, commands), read project.faf first and answer from it. faf_score shows what is missing; faf_doctor says why." It replaces "start with
faf_doctororfaf_score", which agents read as a hint. In a 3-run pilot on a repo where project.faf and package.json disagree, Claude Code read project.faf first 3 of 3 and Grok Build 2 of 3 with the new line, against 0 of 3 for both with the old one. 712 characters.
4.1.0 — The Instructions Edition
faf-mcp now tells the model how its tools fit together: server instructions in initialize (642 characters), plus faf-cli 8.5.0, which knows a skills repo when it sees one.
Server instructions. When your editor's AI connects, the server says how its tools fit together: one project at a time, start with
faf_doctororfaf_score, ask the user for the human answers, and project.faf is the source for CLAUDE.md, AGENTS.md, .cursorrules and GEMINI.md.faf-cli 8.5.0 inside.
faf_initandfaf_autodetect a skills repo:SKILL.mdfolders make itskills(10 slots), and a Claude Code plugin manifest makes itskills-plugin(14).hono advisory cleared (serveStatic double-decode).
4.0.1
faf-mcp --version and --help answer and exit. Before, both started the server.
--version(-v) prints the version;--help(-h) prints usage and a client config. Anything else starts the server as before, so your client config doesn't change.
4.0.0 — The Always33 Edition
One engine, one number: faf-mcp 4 scores with faf-cli 8's always-33 kernel — the same score faf-cli, claude-faf-mcp 7 and faf-kernel give.
The always-33 engine. Every tool scores with faf-cli 8.0.0 — all 33 Mk4 slots, one Rust kernel, one copy of it. Checked live: faf-python-sdk 56, mcp-context-card 56, faf-cli ✪ 100.
Your 21 slots, and the 12 enterprise slots in view. The enterprise slots (infra, app, ops) are marked
slotignoredunless your app-type uses them.faf_scorescores against all 33;slotignoredslots drop out of the denominator.Upgrading from 3.x: a
.fafwithout the 12 markers now scores against 33. Runfaf_auto— it writes them and your score returns.
3.0.2 — The Compose Edition
Tools that say what they do: faf_git scores with faf-cli and asks before overwriting, faf_sync previews each change, and imports say when nothing was written.
faf_githas one scorer. It reports faf-cli's score of the file it authored, writes the slots faf-cli scores, and asks before replacing an existingproject.faf.faf_syncpreviews each change. The dry run lists every field it would update and namesapply: true.Imports say when nothing was written, and
merge: truewith noproject.faffails clearly.Descriptions, annotations and errors match the code. No CLI commands or terminal colour codes in tool output.
3.0.1 renamed faf_bi_sync to faf_claude and made faf_init write what faf init writes. The full history is in the CHANGELOG.
The Compose Edition (3.0)
Compose, don't port: faf-mcp 3.0 runs on faf-cli 7.12 in-process — one scorer, one set of renderers, one injector — and every number, file and claim this package makes is true. Local stdio, 29 tools, Node 22+.
Composes faf-cli 7.12. AGENTS.md, GEMINI.md, .cursorrules and CLAUDE.md are written by faf-cli's own renderers, repo enrichment and block injector — the same bytes
faf exportandfaf syncwrite.faf_autoruns faf-cli's own update chain. The hand-ported renderers, the pre-v3 CLAUDE.md template and the local injector are gone.One score function.
faf_auto,faf_go,faf_dna,faf_doctorandfaf_claudeall report faf-cli's scorer on the bytes on disk — no local heuristics, no frozen birth score, no "0%".Nothing shells out. The
which fafdetector, the exec fallback and the "install faf-cli first" banner are gone; nothing undersrc/importschild_process. A machine with an unrelatedfafon PATH is no longer a problem.Every tool contract matches its handler. Descriptions say what the tools do, schemas declare only flags that are read, failures carry their reason.
The Mk3 engine is deleted. 44 unreachable modules, ~15,900 lines; the tarball halves.
prebuildclearsdist/so nothing deleted ever ships again.Resource URIs are
faf://contextandfaf://status;claude-faf://remains readable as an alias for this release.Node 22 or newer. 18 and 20 are end of life; the CI matrix runs 22 and 24 and a guard keeps the floor honest.
Define once. Sync everywhere.
You maintain .cursorrules. Your teammate uses AGENTS.md. Someone on the team just switched to Gemini. Every AI tool wants its own context file — and they all say the same thing in different formats.
faf-mcp is the dedicated MCP server for Cursor, Windsurf, Cline, VS Code, and every non-Claude platform. One .faf file in your repo, synced to every format your team needs.
Context for Cursor & IDE agents: faf-cli authors the files this server syncs — bunx faf export --agents, zero-install and git-native. See FAF-CLI for Cursor & IDE agents 👀.
project.faf
│
┌────────┬───────┴───────┬────────────┐
▼ ▼ ▼ ▼
CLAUDE.md AGENTS.md .cursorrules GEMINI.md
(Claude) (Codex) (Cursor) (Gemini)Quick Start
Cursor — one click:
Everywhere else:
bunx faf-mcpAdd to your MCP config:
{"mcpServers": {"faf": {"command": "bunx", "args": ["faf-mcp"]}}}Platform | Config File |
Cursor |
|
Windsurf |
|
Cline | Cline MCP settings |
VS Code | MCP extension config |
Claude Desktop | Use claude-faf-mcp |
Run It
faf-mcp runs locally over stdio. Point your IDE at one of these commands.
Method | Command |
npm |
|
Bun |
|
Interop Tools
Tool | Platform | Action |
| OpenAI Codex | Import/export/sync AGENTS.md |
| Cursor IDE | Import/export/sync .cursorrules |
| Google Gemini | Import/export/sync GEMINI.md |
| Conductor | Import/export directory structure |
| GitHub | Author .faf from a public GitHub repo URL |
# MCP tool calls — ask your IDE's AI
# Write all four formats from project.faf
faf_claude { all: true }
# Author .faf from any GitHub repo
faf_git { url: "https://github.com/facebook/react" }Core tier: 15 essential tools shown by default; set FAF_TOOLS=all for the full 29 (every tool stays callable by name either way) · 7 bundled parsers
Eternal Sync
project.faf is the source. faf-mcp writes every tool's context file from it.
project.faf ──────────→ CLAUDE.md / AGENTS.md / .cursorrules / GEMINI.md
Single source of truthfaf_claude { all: true }writes all four formats at oncefaf_agents,faf_cursorandfaf_geminican also import an existing file:merge: truemerges it intoproject.fafContent outside the faf-managed block is preserved, byte for byte
Works across teams, branches, sessions
AI assistants forget. They drift. Every new session, AI starts guessing again. One source means context never goes stale.
Tier System: From Blind to Optimized
Tier | Score | Status |
✪ TROPHY | 100% | AI never has to guess |
★ GOLD | 99%+ | 1 slot from Trophy |
◆ SILVER | 95%+ | Close — keep going |
◇ BRONZE | 85%+ | Interim — keep going |
● GREEN | 70%+ | Interim — keep going |
● YELLOW | 55%+ | AI flipping coins |
○ RED | <55% | AI working blind |
♡ WHITE | 0% | No context at all |
At 55%, AI is guessing half the time. At 100%, AI is optimized.
use>faf | Prompt Pattern
Start every prompt with "Use FAF" to invoke MCP tools:
Use FAF to initialize my project
Use FAF to score my AI-readiness
Use FAF to sync my context
Use FAF to ask me for my goalWorks on all platforms — stops web search, forces tool usage.
29 MCP Tools
The 15 Core tools, shown by default:
Tool | Purpose |
| Create a new |
| One-call setup: init or merge, stack detection, CLAUDE.md, score |
| The goal and six W's: each empty one with faf-cli's suggestion and its source, for you to confirm; only what you confirm is written |
| AI-readiness score (0-100%) and tier; |
| Diagnose a low score: missing files, slot counts, config issues, each with a fix |
| Rate each |
| Validate the required fields and |
| Reconcile |
| Set or show the active project path |
| What the IANA-registered |
Interop Tools | |
| Write CLAUDE.md from |
| Import AGENTS.md into |
| Import .cursorrules into |
| Import GEMINI.md into |
| Author a |
+14 more with FAF_TOOLS=all: faf_status · faf_what · faf_guide · faf_debug · faf_clear · faf_list · faf_read (read a file within the allowed roots: cwd, the OS temp dir, or FAF_ALLOWED_ROOTS) · faf_write (write a file within cwd or FAF_ALLOWED_ROOTS; never .faf-dna or .git/; an existing *.faf, CLAUDE.md or AGENTS.md needs overwrite: true) · faf_readme · faf_human_add · faf_quick · faf_formats · faf_dna · faf_conductor
Built on faf-cli. Every tool composes the bundled faf-cli in-process — the same scorer, the same renderers, the same block injector the CLI uses. Nothing shells out to a faf on your PATH.
Ecosystem
claude-faf-mcp — Claude Desktop
faf-cli — Terminal CLI
faf-wasm — WASM SDK
faf-wasm-gen — Rust→WASM
project.fafauthoring engine, browser/edge (faf-wasm's authoring sibling)faf-trinity — reference MCP server exposing all three IANA FAF formats (context/memory/agent) together
faf.one — Official website
docs/SKILLS-OVER-MCP.md — J1 Agent Skill
faf-ide(stdio · skills/list · digests)
If faf-mcp has been useful, consider starring the repo — it helps others find it.
Citation
If you use faf-mcp or the .faf / .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). 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{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 License — Free and open source
Zero drift. Eternal sync. AI optimized. ✪
"It's so logical if it didn't exist, AI would have built it itself" — Claude
Available Tools
15 toolsfaf_aboutARead-only
Explain what the .faf format is — the IANA-registered, portable context file (application/vnd.faf+yaml) that gives any AI instant project understanding. Returns a plain-language overview of the format and its purpose. Use this when you or the user are new to FAF and want the concept before running other tools.
Inputs: no named parameters.
faf_agentsA
Import AGENTS.md (the OpenAI/Codex convention) into project.faf, or write it from project.faf. Returns the merged or written result for the chosen action. Use this to keep a Codex/OpenAI-style AGENTS.md and your .faf in agreement from one source.
Inputs: action (required), path, force, merge.
faf_autoA
Run the setup pipeline in one call — init or merge, stack detection, CLAUDE.md, and score — taking a project from no context to a scored project.faf plus CLAUDE.md; faf_go closes the human slots. Returns the final AI-readiness score and what was created. Use this as the fast path on a fresh project; use the individual tools when you need finer control.
Inputs: path.
faf_checkA
Inspect the human_context fields and rate each empty/generic/good. Returns the ratings; with protect it records the good fields in _protected_fields as an advisory list (other tools do not enforce it), with unlock it clears that list. Use this to gauge context quality.
Inputs: path, unlock, protect.
faf_claudeA
Write CLAUDE.md from project.faf (one direction: .faf → CLAUDE.md) and, with the format flags or all, also AGENTS.md, .cursorrules and GEMINI.md. Content outside the faf-managed block is preserved. Returns the files written. Use this to keep every AI tool's context file current from one source. (Named faf_bi_sync before 3.0.1; that name still works.)
Inputs: all, path, agents, cursor, +1 more.
faf_contextARead-only
Set or show the active project path that later faf_ project tools resolve against (faf_read and faf_write resolve relative paths against the server's working directory instead). Returns the current context path. Call this once at the start of a session so the project tools target the right project.
Inputs: path.
faf_cursorA
Import .cursorrules (the Cursor IDE convention) into project.faf, or write it from project.faf. Returns the merged or written result for the chosen action. Use this to keep Cursor rules and your .faf in agreement from one source.
Inputs: action (required), path, force, merge.
faf_doctorARead-only
Diagnose a project.faf setup — report missing files, the real score with populated/active slot counts, and common configuration issues, each with a fix. Returns a checklist. Use this when your score is low and you need to know why.
Inputs: path.
faf_geminiA
Import GEMINI.md (the Google Gemini CLI convention) into project.faf, or write it from project.faf. Returns the merged or written result for the chosen action. Use this to keep a Gemini context file and your .faf in agreement from one source.
Inputs: action (required), path, force, merge.
faf_gitADestructive
Author a project.faf from any public GitHub repository URL — fetches the repo and extracts its stack and context. Returns the authored .faf. Use this to bootstrap context for a project you have the URL for but not cloned locally.
Inputs: url (required), path, force.
faf_goA
Drive a project.faf to 100% through a guided interview — returns the next questions for the missing human-context and goal fields, each with faf-cli's suggestion from the repo and its source, then applies the answers the user confirmed. Returns the updated score after each round. Use this to close the gap to a complete context when auto-detection cannot fill the human slots.
Inputs: path, answers.
faf_initA
Create a project.faf for a project, making it instantly AI-readable. Returns the new file location and starting score. Accepts a path or bare project name (e.g. ~/Projects/my-app, my-app) and omitting it uses the current directory.
Inputs: path, force.
faf_scoreARead-only
Calculate a project.faf AI-readiness score (0-100%) from the populated context slots. Returns the percentage and tier, and with details a slot-by-slot breakdown with improvement suggestions. Use this to measure how complete the AI context is and what to fill next.
Inputs: path, details.
faf_syncA
Reconcile project.faf with what the repo manifests say now (package.json name, description, framework dependencies). Dry-run by default: reports the fields that would change. Pass apply:true to write them into project.faf. Does not touch CLAUDE.md — use faf_claude for CLAUDE.md, AGENTS.md, .cursorrules and GEMINI.md.
Inputs: path, apply.
faf_trustBRead-only
Validate a project.faf's required fields (faf_version, project.name) and about.* block with faf-cli's validator, and report its real score.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 15 tools
Several clusters overlap: faf_score, faf_doctor, faf_check and faf_trust all report scores/validation and it takes careful reading to pick the right one, while faf_init, faf_auto and faf_go all build or complete a project.faf. The four convention-specific sync tools (faf_agents, faf_cursor, faf_gemini, faf_claude) are distinguishable only by target file, though descriptions do explicitly disambiguate them.
Every tool uses the same faf_ prefix plus a short lowercase token (faf_init, faf_score, faf_sync, faf_doctor), giving a single predictable convention across the whole set. There is no mixing of camelCase, verb-first or noun-first styles.
15 tools is within a reasonable range for a full context-file lifecycle, and each has a stated role. However, the four per-IDE sync tools are near-duplicates that could be one parameterized tool, making the surface slightly heavier than necessary.
Creation, sync, scoring, validation, interview and multi-format export are covered, so the core lifecycle is present. But faf_context's description references faf_read and faf_write tools that are not exposed, and there is no general read/inspect or remove/delete operation, leaving dead ends.
Maintenance
Related MCP Connectors
Persistent project context — Rust-native MCP server. IANA-registered .faf format.
Share one project context across ChatGPT, Claude, Telegram and any MCP client.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Persistent project context for xAI Grok. IANA-registered .faf format.
Related MCP Servers
- AlicenseAqualityBmaintenance.FAF (Foundational AI-context Format) with 50+ tools - Only Persistent project context that integrates seamlessly with Claude Desktop workflows. Officially merged (#2759) Anthropic MCP server.141,548 npm23MIT
- AlicenseAqualityBmaintenancePersistent project context for Google Gemini. 12 MCP tools for .faf Project DNA — auto-detect your stack, validate, score, and sync across CLAUDE.md, GEMINI.md, and AGENTS.md. Python/FastMCP. IANA-registered format (application/vnd.faf+yaml). 183 tests. One file, every AI platform.13617 PyPI2MIT
- AlicenseNot gradedqualityBmaintenancePersistent project context in Rust. 8 MCP tools via rmcp SDK — parse, validate, score, compress, discover, and token analysis. Single binary, zero config. IANA-registered format (application/vnd.faf+yaml). One file, every AI platform.111 npm5MIT
- AlicenseBqualityBmaintenanceGrok asked for MCP on a URL. This is it. First MCP server built for Grok URL-based • Zero config • Just works12334 npm19MIT