FAF

.FAF Context

Persistent Project Context for Cursor, IDEs and VS Code. Define once. Sync everywhere. npm: faf-mcp

[![npm](https://img.shields.io/npm/v/faf-mcp?color=008B8B)](https://www.npmjs.com/package/faf-mcp)[![downloads](https://img.shields.io/npm/dm/faf-mcp?color=008B8B&label=downloads)](https://www.npmjs.com/package/faf-mcp) [![FAF Trophy 100%](https://img.shields.io/badge/FAF-%E2%9C%AA%20100%25-000000?labelColor=FF6B35)](https://faf.one) [![IANA: vnd.faf+yaml](https://img.shields.io/badge/IANA-vnd.faf%2Byaml-008B8B)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) [![DOI: Context paper](https://img.shields.io/badge/DOI-Context%20paper-FF6B35)](https://doi.org/10.5281/zenodo.18251362) [![DOI: Agents paper](https://img.shields.io/badge/DOI-Agents%20paper-FF6B35)](https://doi.org/10.5281/zenodo.21951641) **Home:** [wolfe-jam.github.io/faf-mcp](https://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](https://faf.one/downloads)). ⭐ Bookmarks it for you, helps other devs find it too. [![CI](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![project.faf](https://img.shields.io/badge/project.faf-inside-008B8B)](https://github.com/Wolfe-Jam/faf) [![Business card · Get yours →](https://wolfe-jam.github.io/agent-business-card/badge.svg)](https://wolfe-jam.github.io/agent-business-card/?repo=Wolfe-Jam/faf-mcp) --- ## What's New in 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](CHANGELOG.md). ## 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 👀](https://github.com/Wolfe-Jam/faf-cli/blob/main/docs/faf-cli-for-agents.md). ``` project.faf │ ┌────────┬───────┴───────┬────────────┐ ▼ ▼ ▼ ▼ CLAUDE.md AGENTS.md .cursorrules GEMINI.md (Claude) (Codex) (Cursor) (Gemini) ``` ### Quick Start **Cursor — one click:** [![Add .FAF Context to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=faf-mcp&config=eyJjb21tYW5kIjoiYnVueCIsImFyZ3MiOlsiZmFmLW1jcCJdfQ==) **Everywhere else:** ```bash bunx faf-mcp ``` Add to your MCP config: ```json {"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](https://github.com/Wolfe-Jam/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 | ```text # 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](https://www.npmjs.com/package/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](https://npmjs.com/package/claude-faf-mcp)** — Claude Desktop - **[faf-cli](https://npmjs.com/package/faf-cli)** — Terminal CLI - **[faf-wasm](https://www.npmjs.com/package/faf-wasm)** — WASM SDK (<5ms scoring) - **[faf-wasm-gen](https://www.npmjs.com/package/faf-wasm-gen)** — Rust→WASM `project.faf` authoring engine, browser/edge (faf-wasm's authoring sibling) - **[faf-trinity](https://github.com/Wolfe-Jam/faf-trinity)** — reference MCP server exposing all three IANA FAF formats (context/memory/agent) together - **[faf.one](https://faf.one)** — Official website - **[docs/SKILLS-OVER-MCP.md](./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 ```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*