.FAF Context

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.

⭐ Bookmarks it for you, helps other devs find it too.

---

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:

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:

# 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-wasm-gen — Rust→WASM project.faf generator, browser/edge (faf-wasm's generate 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