Purpose
faf-mcp is the IDE-facing MCP server in the FAF ecosystem, with the goal of providing persistent, unified project context for AI coding tools such as Cursor, Windsurf, Cline, VS Code, and other non-Claude platforms. The problem it solves is: every AI tool needs its own context file (.cursorrules, AGENTS.md, GEMINI.md, CLAUDE.md, etc.), with the same content but different formats, maintained in a scattered way and prone to becoming stale. faf-mcp's approach is to maintain a single project.faf in the repository, from which it uniformly generates and syncs to each format.
Main capabilities
- Context sync: with project.faf as the single source of truth, write out the context files required by each AI tool in milliseconds.
- Batch write-out: faf_claude { all: true } can write out four formats at once.
- Reverse import: faf_agents, faf_cursor, and faf_gemini can import existing files, and with merge: true, merge them into project.faf.
- Preserve existing content: content outside the faf-managed block is preserved byte-for-byte.
- AI readiness scoring: all tools use the always-33 kernel scoring from faf-cli 8.0.0; among the 33 Mk4 slots, unused (slotignored) enterprise slots (infra, app, ops) are removed from the denominator.
- Toolset tiering: by default, 15 core tools are shown; setting FAF_TOOLS=all enables all 29; whether shown or not, all tools can be invoked by name.
- Resource URIs: faf://context and faf://status; in this version, claude-faf:// can still be read as an alias.
How to use
- Run locally over stdio. Add one of the following to the MCP configuration: npx faf-mcp or bunx faf-mcp
- Prompt mode: use "Use FAF" at the beginning of each prompt to invoke the MCP tools.
- 15 default core tools: faf_init, faf_auto, faf_go, faf_git, faf_sync, faf_score, faf_doctor, faf_agents, faf_cursor, faf_gemini, faf_claude, etc. (the official list gives 15 in total; these are not guessed one by one here).
- After FAF_TOOLS=all, an additional 14 are opened up: faf_status, faf_what, faf_guide, faf_debug, faf_clear, faf_list, faf_read (read files within allowed roots: cwd, the system temp directory, or FAF_ALLOWED_ROOTS), faf_write (write files within the same roots), faf_readme, faf_human_add, faf_quick, faf_formats, faf_dna, faf_conductor.
4.0.0 release highlights (Always33)
faf-mcp 4 and faf-cli 8 share the always-33 kernel scoring, and give the same score as claude-faf-mcp 7 and faf-kernel. When upgrading from 3.x, a .faf missing 12 markers will be scored against 33 slots; running faf_auto can write the markers and restore scoring.
3.0 series capabilities
- faf_git uses a unified scorer, reports the faf-cli score of the files it generates, and asks before overwriting an existing project.faf.
- faf_sync previews each change; a dry run lists the fields that will be updated and prompts apply: true.
- When importing without a write, it says so explicitly; with merge: true but no project.faf, it fails explicitly.
- It does not call an external shell: the source does not import child_process, and tool output contains no CLI commands or terminal color codes.
- Files are generated by the renderer, repository enrichment, and block injector from faf-cli 7.12, byte-identical to what faf export and faf sync write out.
Applicable scenarios
- Teams use multiple AI coding tools (Cursor, Windsurf, Cline, VS Code, Gemini, etc.) and need unified context.
- Keep project context consistent across branches, sessions, and members, avoiding AI having to guess anew each time.
- Want to quantify context completeness (score grades range from 55% "guess" to 100% "optimization"), and complete accordingly.
Limitations and Prerequisites
- Requires Node.js 22 or newer (18 and 20 are end-of-life; the CI matrix covers 22 and 24).
- Runs locally via stdio.
- faf_read and faf_write can only operate within allowed root directories (cwd, the system temporary directory, or FAF_ALLOWED_ROOTS).
- The remaining specific platform support scope, fees, and pricing information are not yet provided.
