<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://www.npmjs.com/package/faf-mcp)![downloads](https://www.npmjs.com/package/faf-mcp) ![FAF Trophy 100%](https://faf.one) ![IANA: vnd.faf+yaml](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) ![DOI: Context paper](https://doi.org/10.5281/zenodo.18251362)

Home: wolfe-jam.github.io/faf-mcp · Hosted MCP endpoint: https://ide.faf.one/mcp/v1 (Streamable HTTP)

The MCP you didn't realise you needed, or wanted but didn't know who to ask, is here. Building on over 100k ecosystem downloads (latest stats), we bring you faf-mcp to cure your syncing pain and fuel your chosen AI with optimized context, on-demand.

⭐ A star helps other devs discover faf-mcp — despite the downloads, ~3 of 4 devs check stars first.

![CI](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml) ![License: MIT](https://opensource.org/licenses/MIT) ![project.faf](https://github.com/Wolfe-Jam/faf)

---

What's New in 2.3.0 — The Curated Edition

The tools you actually need, up front. faf-mcp now leads with 15 essential tools by default — a clean, focused surface instead of a wall of options. Need everything? Set FAF_TOOLS=all for the full 29 (every tool stays callable by name either way). And every Core tool's description was rewritten so your AI picks the right one, first time.

---

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.1) 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](cursor://anysphere.cursor-deeplink/mcp/install?name=faf-mcp&config=eyJjb21tYW5kIjoiYnVueCIsImFyZ3MiOlsiZmFmLW1jcCJdfQ==)

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 |

---

Three Ways to Deploy

| Door | Method | Best For | |------|--------|----------| | Hosted | mcpaas.live | Zero-install, point any MCP client to the URL | | Self-Deploy | Deploy to Vercel | Your own instance, full control | | Local | bunx faf-mcp | IDE integration via stdio transport |

Hosted (mcpaas.live)

Point your MCP client to https://ide.faf.one/mcp/v1 — no install, no config, no maintenance. Served from 300+ Cloudflare edges with sub-ms cold starts via 2.7KB Zig-WASM engine.

Self-Deploy (Vercel)

Deploy your own MCP server on Vercel in one click. Once deployed, your server exposes:

/health — Health check
/info — Server metadata + tool list
/mcp/v1 — MCP Streamable HTTP transport

Local (npm)

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

# Sync to all formats at once
faf bi-sync --all

# Generate .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) · with CLI fallback · 9 test suites · 7 bundled parsers

---

Cloud Sync

Share your FAF context globally via mcpaas.live:

| Tool | Purpose | |------|---------| | faf_cloud_publish | Upload to cloud, get shareable URL | | faf_cloud_fetch | Pull context from cloud | | faf_cloud_list | List available souls | | faf_cloud_search | Search across souls | | faf_cloud_share | Generate share links |

Example Workflow: ```bash

Upload your project.faf

faf_cloud_publish { soul_name: "my-project" } → https://mcpaas.live/souls/my-project

Anyone can fetch it

faf_cloud_fetch { soul_name: "my-project" } → Context merged into local project.faf ```

Zero-install sharing - Recipients need no MCP setup. Served from 300+ Cloudflare edges with <1ms cold starts via 2.7KB Zig-WASM engine.

---

Eternal Bi-Sync

Your .faf file and your platform context files stay synchronized in milliseconds.

project.faf  ←── 8ms ──→  .cursorrules / AGENTS.md / CLAUDE.md / GEMINI.md
                    Single source of truth

Update either side → both stay aligned
--all flag syncs to all four formats at once
Zero manual maintenance
Works across teams, branches, sessions

AI assistants forget. They drift. Every new session, AI starts guessing again. Bi-sync 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

| Tool | Purpose | |------|---------| | faf_init | Initialize project.faf | | faf_score | Check AI-readiness (0-100%) | | faf_sync | Sync context across platforms | | faf_bi_sync | Bi-directional .faf ↔ CLAUDE.md | | faf_read | Parse and validate FAF files | | faf_write | Create/update FAF with validation | | Interop Tools | | | faf_agents | Import/export/sync AGENTS.md | | faf_cursor | Import/export/sync .cursorrules | | faf_gemini | Import/export/sync GEMINI.md | | faf_conductor | Import/export directory structure | | faf_git | Author .faf from GitHub repo URL | | Cloud Tools | | | faf_cloud_publish | Upload to mcpaas.live | | faf_cloud_fetch | Pull from cloud | | faf_cloud_list | List souls | | faf_cloud_search | Search souls | | faf_cloud_share | Generate share links |

Plus CLI fallback (via faf-cli):

faf readme - Extract 6 Ws from README (+25-35% boost)
faf human-add - Non-interactive YAML merge (6Ws Builder)
faf git - GitHub repo analysis without cloning
And 40+ more commands...

---

Ecosystem

claude-faf-mcp — Claude Desktop (33 tools)
faf-cli — Terminal CLI
faf-wasm — WASM SDK (<5ms scoring)
faf.one — Official website

---

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

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