<!-- faf: claude-faf-mcp | TypeScript | mcp-server | FAF MCP server for Claude — persistent project context, 33 tools -->
<!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->

# claude-faf-mcp

**Persistent Project Context for Claude. 30 seconds. 🐘 It never forgets.**

[![FAF](https://mcpaas.live/badge/Wolfe-Jam/claude-faf-mcp.svg)](https://builder.faf.one)
[![Anthropic MCP](https://img.shields.io/badge/Anthropic_MCP-merged_%232759-blueviolet)](https://github.com/modelcontextprotocol/servers/pull/2759)
[![CI](https://github.com/Wolfe-Jam/claude-faf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/claude-faf-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/claude-faf-mcp?color=00CCFF)](https://www.npmjs.com/package/claude-faf-mcp)
[![NPM Downloads](https://img.shields.io/npm/dt/claude-faf-mcp?label=downloads&color=00CCFF)](https://www.npmjs.com/package/claude-faf-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Chat to FAFA live](https://img.shields.io/badge/Chat_to_FAFA_live-00D4D4?style=flat&labelColor=000)](https://faf-voice.vercel.app/agent)

**FAF defines. MD instructs. AI codes.**

> 🐘 **tri-sync now free for all builders** — `.faf` ↔ `CLAUDE.md` ↔ `MEMORY.md` in one command. Pro feature. Now free.

> ⚡ **New: `/faf` prompt** — type `/faf` in Claude Desktop. It checks your project, scores it, drives it to 100%, and syncs. Relentlessly. One command.

33 MCP tools. IANA-registered formats (`application/vnd.faf+yaml` · `application/vnd.fafm+yaml`). 2,346 test executions per push.

---

## The 3Ws — 3 Answers. That's It.

Every great product started with 3 answers to the 3Ws — **Who, What, Why:**

| | WHO is it for? | WHAT does it do? | WHY build it? |
|---|-----|------|-----|
| **Uber** | People who need a ride | Tap a button, car arrives | Taxis were broken |
| **Airbnb** | Travelers who can't afford hotels | Stay in someone's spare room | Millions of empty rooms exist |
| **Slack** | Teams drowning in email | Organized group messaging | Decisions buried in threads |
| **Venmo** | Friends splitting bills | Send money instantly | Someone always forgets to pay back |

Same pattern. Every product that works starts here. `.faf` captures it:

```yaml
human_context:
  who: "people who need a ride across town"
  what: "tap a button, car arrives in minutes"
  why: "taxis are slow, expensive, and hard to find"
```

30 seconds. Claude builds your `project.faf` from this. Every session after, AI starts smart.

### The 6Ws — For Optimized AI

3Ws gets you started. For fully optimized AI, complete the set — **Where, When, How:**

```yaml
  where: "mobile app, iOS and Android"    # where does it live?
  when: "launch in 3 months"              # when is it shipping?
  how: "GPS matching, real-time pricing"  # how does it work?
```

3Ws initiates the project with AI. 6Ws optimizes AI to 100%. Same YAML, same file. **[More examples → faf.one/ideas](https://faf.one/ideas)**

---

## Quick Start

### Web — best of all scenarios

```bash
claude mcp add --transport http claude-faf-mcp https://claude-faf-mcp.vercel.app/sse
```

URL-based. Zero install. Always current. Works in Claude Code today.

### faf-cli — universal (any AI)

```bash
npx faf-cli auto
```

Same `.faf`, every surface — Claude, Gemini, Grok, Cursor. **[faf-cli on npm →](https://www.npmjs.com/package/faf-cli)**

### Claude Desktop — click, copy, paste, install

**Click** — one-click `.mcpb`

[**⬇ Download `claude-faf-mcp-5.5.2.mcpb`**](https://github.com/Wolfe-Jam/claude-faf-mcp/releases/latest/download/claude-faf-mcp-5.5.2.mcpb)

Double-click. **No terminal. No JSON config. 33 tools live in 10 seconds.**

**Copy** — paste-prompt to Claude

> Install the FAF MCP server: `npm install -g claude-faf-mcp`, then add this to my claude_desktop_config.json: `{"mcpServers": {"faf": {"command": "npx", "args": ["-y", "claude-faf-mcp"]}}}` and restart Claude Desktop.

**Paste** — `claude_desktop_config.json`

```json
{
  "mcpServers": {
    "faf": { "command": "npx", "args": ["-y", "claude-faf-mcp"] }
  }
}
```

**Install** — manual npm

```bash
npm install -g claude-faf-mcp
```

Restart Claude Desktop.

### Then

Type `/faf` — Claude checks your project, scores it, drives it to 100%, and syncs. Done.

Or tell Claude your 3Ws: *"I'm building [what] for [who] because [why]"*

---

## How It Works

```
You → 3 answers → project.faf → AI reads it → every session → forever

project.faf  ←── 8ms ──→  CLAUDE.md     (bi-sync, free)
project.faf  ←── 8ms ──→  MEMORY.md     (tri-sync, Pro 🐘)
```

Claude does the rest. Zero-effort, right first time, fast, accurate, done. Language, framework, package manager, build tools — all auto-detected from your existing files. The human context is the part only you can give.

---

## Scoring: From Blind to Optimized

| Tier | Score | What it means |
|------|-------|---------------|
| 🏆 **TROPHY** | 100% | Gold Code — AI is optimized |
| ★ **GOLD** | 99%+ | Near-perfect context |
| ◆ **SILVER** | 95%+ | Excellent |
| ◇ **BRONZE** | 85%+ | Production ready |
| ● **GREEN** | 70%+ | Solid foundation |
| ● **YELLOW** | 55%+ | AI flipping coins |
| ○ **RED** | <55% | AI working blind |
| ♡ **WHITE** | 0% | No context at all |

At 55%, AI guesses half the time. At 100%, AI knows your project. Same compiler as faf-cli — same score everywhere.

---

## 33 MCP Tools

All tools run standalone — zero CLI dependencies, 19ms average execution.

**Create & Detect**
| Tool | Purpose |
|------|---------|
| `faf_init` | Initialize project DNA |
| `faf_auto` | Auto-detect stack and populate context |
| `faf_quick` | Lightning-fast creation (3ms) |
| `faf_readme` | Extract context from README (+25-35% boost) |
| `faf_formats` | Discover all formats in your project |
| `faf_git` | Extract context from any GitHub repo URL |
| `faf_human_add` | Add human context (the 6Ws) |

**Validate & Score**
| Tool | Purpose |
|------|---------|
| `faf_score` | AI-readiness score (0-100%) with breakdown |
| `faf_check` | Validate .faf structure |
| `faf_doctor` | Diagnose and fix common issues |
| `faf_go` | Guided interview to Gold Code |

**Sync & Persist**
| Tool | Purpose |
|------|---------|
| `faf_sync` | Sync .faf → CLAUDE.md |
| `faf_bi_sync` | Bi-directional .faf ↔ CLAUDE.md |
| `faf_tri_sync` | Tri-sync .faf ↔ CLAUDE.md ↔ MEMORY.md — Pro feature, free for developers 🐘 |
| `faf_enhance` | Intelligent enhancement |

**Export & Interop**
| Tool | Purpose |
|------|---------|
| `faf_agents` | Import/export AGENTS.md (OpenAI Codex) |
| `faf_cursor` | Import/export .cursorrules (Cursor IDE) |
| `faf_gemini` | Import/export GEMINI.md (Google Gemini) |
| `faf_conductor` | Import/export Conductor directory |

**Read & Write**
| Tool | Purpose |
|------|---------|
| `faf_read` | Read any file |
| `faf_write` | Write any file |
| `faf_status` | Project status overview |
| `faf_debug` | Environment inspection |
| `faf_about` | What is .faf? |

**[Full tool reference →](https://github.com/Wolfe-Jam/claude-faf-mcp/blob/main/docs/mcp-tools.md)**

---

## 🐘 Nelly Never Forgets

bi-sync keeps `.faf` ↔ `CLAUDE.md` aligned.

tri-sync adds MEMORY.md — your AI remembers your project across every session.

```
bi-sync  = .faf ↔ CLAUDE.md              ← always in sync
tri-sync = .faf ↔ CLAUDE.md ↔ MEMORY.md  ← Nelly never forgets 🐘
```

Pro feature, free for developers. Teams & Enterprise: **[faf.one/pro](https://faf.one/pro)** (plans)

---

## The .FAF Position

```
Model        Context          Protocol
─────        ───────          ────────
Claude    →   .faf        →    MCP
Gemini    →   .faf        →    MCP
Codex     →   .faf        →    MCP
Any LLM   →   .faf        →    MCP
```

IANA-registered (`application/vnd.faf+yaml`). Works with any AI. Define once, use everywhere.

---

## Ecosystem

| Package | Platform | Registry |
|---------|----------|----------|
| **[claude-faf-mcp](https://www.npmjs.com/package/claude-faf-mcp)** (this) | Claude | npm |
| **[faf-cli](https://www.npmjs.com/package/faf-cli)** | Universal CLI | npm + Homebrew |
| **[gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/)** | Google Gemini | PyPI |
| **[grok-faf-mcp](https://www.npmjs.com/package/grok-faf-mcp)** | xAI Grok | npm |
| **[rust-faf-mcp](https://crates.io/crates/rust-faf-mcp)** | Rust | crates.io |
| **[faf-wasm](https://www.npmjs.com/package/faf-wasm)** | Browser/Edge | npm |
| **[Chrome Extension](https://chromewebstore.google.com/detail/lnecebepmpjpilldfmndnaofbfjkjlkm)** | Browser | Chrome Web Store |

Same `project.faf`. Same scoring. Same result. Different execution layer.

---

## Quality

391 tests · 12 suites · 6 platforms (ubuntu/macos/windows × Node 18/20)

**[CI Dashboard →](https://github.com/Wolfe-Jam/claude-faf-mcp/actions/workflows/ci.yml)**

---

## Privacy

Everything runs locally. No data leaves your machine. No analytics, no telemetry, no tracking, no accounts. **[Privacy policy →](./PRIVACY.md)**

---

If `claude-faf-mcp` has been useful, consider starring the repo — it helps others find it.

---

## License

MIT — Free and open source

---

## FAF Family

| | |
|---|---|
| **[faf-cli](https://www.npmjs.com/package/faf-cli)** | `npx faf-cli init` — create .faf for any project |
| **[claude-faf-mcp](https://www.npmjs.com/package/claude-faf-mcp)** | MCP server for Claude Desktop |
| **[gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/)** | MCP server for Gemini CLI |
| **[grok-faf-mcp](https://www.npmjs.com/package/grok-faf-mcp)** | MCP server for Grok |
| **[faf-mcp](https://www.npmjs.com/package/faf-mcp)** | MCP server for Cursor, Windsurf, Cline, VS Code |
| **[rust-faf-mcp](https://crates.io/crates/rust-faf-mcp)** | MCP server in Rust |
| **[faf-skills](https://github.com/Wolfe-Jam/faf-skills)** | 17 Claude Code skills |
| **[faf.one](https://faf.one)** | Blog, downloads, docs |
| **[IANA: vnd.faf+yaml](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)** | Context format (2025-10-30) |
| **[IANA: vnd.fafm+yaml](https://www.iana.org/assignments/media-types/application/vnd.fafm+yaml)** | Memory format (2026-05-13) |

*format | driven 🏎️⚡️ [wolfejam.dev](https://wolfejam.dev)*

---

### Get the CLI

> **faf-cli** — The original AI-Context CLI. A must-have for every builder.

```bash
npx faf-cli auto
```

**Anthropic MCP [#2759](https://github.com/modelcontextprotocol/servers/pull/2759)** · **2 IANA registrations:** `vnd.faf+yaml` (Context) · `vnd.fafm+yaml` (Memory) · [faf.one](https://faf.one) · [npm](https://www.npmjs.com/package/faf-cli)
