claude-faf-mcp is an MCP (Model Context Protocol) server for Claude that provides persistent, versionable AI context for projects. It is based on the IANA-registered .faf (Foundational AI-context Format, application type application/vnd.faf+yaml) and .fafm (application type application/vnd.fafm+yaml) formats, defining project information in a single file for AI to read across sessions. The official slogan is "FAF defines. MD instructs. AI codes." — FAF defines, MD instructs, AI codes.
The core purpose is to solve the problem of having to repeatedly explain "what this project is" to the AI in every session. The .faf file is committed to the repository along with the code, so Claude can obtain the project's tech stack, goals, and related context at the start of every session. It can also generate the project's CLAUDE.md from .faf via faf_sync (only maintaining the blocks managed by faf, without touching the user's own notes), and sync to MEMORY.md via faf_tri_sync, achieving three-way synchronization of .faf → CLAUDE.md → MEMORY.md, so the AI remembers the project across sessions.
Main capabilities and toolset: By default it lists the Core 14 MCP tools, covering the project context lifecycle; after setting the environment variable FAF_TOOLS=all, the Extended tools are shown, 30 in total. Regardless of whether that variable is set, all tools can be called by name. Of the 2 included prompts, the faf prompt can be selected from the host's prompt list (for example, in Claude Code it appears as /mcp__<server name>__faf); it scores the project, fills in using facts available in the repository, asks the user only for what only the user can answer, then validates and syncs. Regarding scoring, claude-faf-mcp 7 uses the always-33 kernel of faf-cli 8, giving the same score as faf-cli and faf-kernel; all 33 Mk4 slots are handled by a Rust kernel. The 12 enterprise slots are not included (infra,app, ops, etc.). A .faf marked as slotignored will be scored according to 33 slots (for example, 21 filled = 64%); running faf_auto will write these markers, and the score can return to 100% (the official example shows 56% → 100%).
Usage: Node 22 or higher is required. Claude Desktop users can download the .mcpb extension file (claude-faf-mcp-7.0.1.mcpb) for one-click installation; the extension has the server built in, does not depend on npx or the network at startup, and lists the Core 14 tools; alternatively, you can configure npx in claude_desktop_config.json, or install globally and use the installed bin ({ "command": "claude-faf-mcp" }); if Bun is in Claude Desktop's PATH, you can also use { "command": "bunx", "args": ["claude-faf-mcp"] }. The npx configuration and the SessionStart hook installed by faf_setup (npx -y claude-faf-mcp --session-refresh) do not lock the version and will run the latest version; to pin to a major version, you must write "args": ["-y", "claude-faf-mcp@6"] in the configuration yourself. .mcpb, on the other hand, runs the version at build time. faf-cli can be used in any terminal, and the same .faf file works on different platforms such as Claude, Gemini, Grok, Cursor, and others.
Workflow example: After installation, run faf prompt; Claude will score the project, fill in as much as possible using repository facts, ask only questions that only the user can answer (for example, the 3Ws: Who, What, Why; the 6Ws add Where, When, How), validate, and then sync. The 3Ws are used to start a project, and the 6Ws are used to optimize the AI to 100%. Users can also directly tell Claude: "I'm building [what] for [who] because [why]".
Applicable scenarios: Aimed at individual developers and teams working in Claude Code. In team scenarios, .faf is committed along with the code, and eachSessions all have a base context; after installing the native SessionStart hook (faf_setup, preview first, preserves user settings), every Claude Code session begins with a one-line heartbeat message containing the project tech stack and score, as well as intent that code cannot convey (+N, i.e., goals and the 6Ws). Scoring is deterministic; the same .faf produces consistent results on any machine and in CI. The tool itself runs entirely locally, with no account, no telemetry, and no data sent to FAF; the only network use is faf_git, and only when the user asks to read a repository does it git clone using the URL they provide. The privacy policy lists the files it writes. New members only need to git clone to get the context.
Important version changes: 7.0.0 is a major version, and scoring may change; 7.0.1 (Always33 Edition) bundles faf-cli 8.0.1, supports pnpm installation, and removes two moderate-severity advisories related to fast-uri. Starting with v6.0.0 (Earned Badge Edition), it combines faf-cli, only touches what it writes itself, all writes are atomic and go through faf-cli's safe path, refuses to link to files outside the project, project.faf edits preserve comments and exact values, and soul.fafm and Claude's own MEMORY.md notes remain unchanged. 6.0.0 has retired faf_clear, faf_friday, faf_guide, faf_write, the AGENTS.md / .cursorrules / GEMINI.md / conductor imports for project.faf, and faf_check protect/unlock; calling a retired tool by name returns a one-line note suggesting which tool to use instead. Information such as paper citations for related tools and formats, the MIT open source license, and the MCP Registry number (#2759, one.faf/claude-faf-mcp) is provided in the repository. Enterprise/team plans are listed at faf.one/pro (free for developers).
