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

⭐ Star it on GitHub: bookmarks it for you, helps other devs find it too.

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.

Related MCP server: gemini-faf-mcp

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:

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

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