.FAF Context

npmdownloads FAF Trophy 100% IANA: vnd.faf+yaml DOI: Context paper DOI: Agents paper

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.

CI License: MIT project.faf Business card · Get yours →

---

What's New in 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_doctor or faf_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_doctor or faf_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_init and faf_auto detect a skills repo: SKILL.md folders make it skills (10 slots), and a Claude Code plugin manifest makes it skills-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 slotignored unless your app-type uses them. faf_score scores against all 33; slotignored slots drop out of the denominator.
• Upgrading from 3.x: a .faf without the 12 markers now scores against 33. Run faf_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_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: Add .FAF Context to Cursor

Everywhere else:

bunx faf-mcp

Add to your MCP config:

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

Platform	Config File
Cursor	~/.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
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	npx faf-mcp
Bun	bunx faf-mcp

---

Interop Tools

Tool	Platform	Action
faf_agents	OpenAI Codex	Import/export/sync AGENTS.md
faf_cursor	Cursor IDE	Import/export/sync .cursorrules
faf_gemini	Google Gemini	Import/export/sync GEMINI.md
faf_conductor	Conductor	Import/export directory structure
faf_git	GitHub	Author .faf from any 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) · 26 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

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

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

---

29 MCP Tools

The 15 Core tools, shown by default:

Tool	Purpose
faf_init	Create a new project.faf (use faf_auto to enhance an existing one)
faf_auto	One-call setup: init or merge, stack detection, CLAUDE.md, score
faf_go	Guided interview that fills the missing human-context and goal fields toward 100%
faf_score	AI-readiness score (0-100%) and tier; details:true adds a slot-by-slot breakdown
faf_doctor	Diagnose a low score: missing files, slot counts, config issues, each with a fix
faf_check	Rate each human_context field empty / generic / good
faf_trust	Validate the required fields and about.* block with faf-cli's validator
faf_sync	Reconcile project.faf with package.json (dry-run; apply:true writes)
faf_context	Set or show the active project path
faf_about	What the IANA-registered .faf format is, in plain language
Interop Tools
faf_claude	Write CLAUDE.md from project.faf (all:true also writes AGENTS.md, .cursorrules, GEMINI.md)
faf_agents	Import AGENTS.md into project.faf, or write it from project.faf
faf_cursor	Import .cursorrules into project.faf, or write it from project.faf
faf_gemini	Import GEMINI.md into project.faf, or write it from project.faf
faf_git	Author a project.faf from a public GitHub repo URL

+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 (<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