How do I install .FAF Context?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does .FAF Context need an API key?

No required environment variable is listed on this record.

What transport does .FAF Context use?

.FAF Context runs locally over stdio.

When was .FAF Context last checked?

Last checked 2026-11-10. .FAF Context — persistent project context for Cursor, VS Code and every MCP-compatible IDE.

.FAF Context MCP server

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

.FAF Context

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions