.faf - Universal Project Context

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).

⭐ Bookmarks it for you, helps other devs find it too.

What's New in 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_git has one scorer. It reports faf-cli's score of the file it authored, writes the slots faf-cli scores, and asks before replacing an existing project.faf.
• faf_sync previews each change. The dry run lists every field it would update and names apply: true.
• Imports say when nothing was written, and merge: true with no project.faf fails 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 export and faf sync write. faf_auto runs 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_doctor and faf_claude all report faf-cli's scorer on the bytes on disk — no local heuristics, no frozen birth score, no "0%".
• Nothing shells out. The which faf detector, the exec fallback and the "install faf-cli first" banner are gone; nothing under src/ imports child_process. A machine with an unrelated faf on 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. prebuild clears dist/ so nothing deleted ever ships again.
• Resource URIs are faf://context and faf://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 (v7.12) 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-mcp

Add to your MCP config:

{"mcpServers": {"faf": {"command": "bunx", "args": ["faf-mcp"]}}}

Run It

faf-mcp runs locally over stdio. Point your IDE at one of these commands.

Interop Tools

# 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) · 25 test suites · 7 bundled parsers

Eternal Sync

project.faf is the source. faf-mcp writes every tool's context file from it in milliseconds.

project.faf  ──── 8ms ───→  CLAUDE.md / AGENTS.md / .cursorrules / GEMINI.md
                    Single source of truth

• faf_claude { all: true } writes all four formats at once
• faf_agents, faf_cursor and faf_gemini can also import an existing file: merge: true merges it into project.faf
• Content 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

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 enhance my project

Works on all platforms — stops web search, forces tool usage.

29 MCP Tools

The 15 Core tools, shown by default:

+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 the same roots) · 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 (<5ms scoring)
• faf-wasm-gen — Rust→WASM project.faf authoring 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