faf-mcp

<!-- faf: faf-mcp | TypeScript | mcp | The Interop MCP for Context — the Cursor / IDE Edition. Persistent context for Cursor, VS Code, and every MCP-compatible IDE. IANA-registered application/vnd.faf+yaml. Start with "Use FAF". -->
<!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->

<div style="display: flex; align-items: center; gap: 12px;">
  <img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="40" />
  <div>
    <h1 style="margin: 0; color: #FF8C00;">.FAF Context</h1>
    <p style="margin: 4px 0 0 0;"><strong>Persistent Project Context for Cursor, IDEs and VS Code. Define once. Sync everywhere.</strong> <sub>npm: <code>faf-mcp</code></sub></p>
  </div>
</div>

[![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)

---

## 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](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) · **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

| 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, .c