{
  "markdown": "<!-- faf: faf-mcp | TypeScript | mcp-server | FAF MCP IDE Edition — persistent project context for Cursor, Windsurf, Cline, VS Code -->\n<!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->\n\n<div style=\"display: flex; align-items: center; gap: 12px;\">\n  <img src=\"https://www.faf.one/orange-smiley.svg\" alt=\"FAF\" width=\"40\" />\n  <div>\n    <h1 style=\"margin: 0; color: #FF8C00;\">.FAF Context</h1>\n    <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>\n  </div>\n</div>\n\n[![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)\n[![FAF Trophy 100%](https://img.shields.io/badge/FAF-%F0%9F%8F%86%20100%25-000000?labelColor=FF6B35)](https://faf.one)\n[![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)\n[![DOI: Context paper](https://img.shields.io/badge/DOI-Context%20paper-FF6B35)](https://doi.org/10.5281/zenodo.18251362)\n[![DOI: Agents paper](https://img.shields.io/badge/DOI-Agents%20paper-FF6B35)](https://doi.org/10.5281/zenodo.21951641)\n\n**Home:** [wolfe-jam.github.io/faf-mcp](https://wolfe-jam.github.io/faf-mcp/) · **Hosted MCP endpoint:** `https://ide.faf.one/mcp/v1` (Streamable HTTP)\n\nThe 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](https://faf.one/downloads)), we bring you faf-mcp to cure your syncing pain and fuel your chosen AI with optimized context, on-demand.\n\n⭐ Bookmarks it for you, helps other devs find it too.\n\n[![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)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![project.faf](https://img.shields.io/badge/project.faf-inside-008B8B)](https://github.com/Wolfe-Jam/faf)\n\n---\n\n## What's New in 2.3.0 — The Curated Edition\n\n**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.\n\n---\n\n## Define once. Sync everywhere.\n\nYou 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.\n\n**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.\n\n**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 👀](https://github.com/Wolfe-Jam/faf-cli/blob/main/docs/faf-cli-for-agents.md).\n\n```\n                      project.faf\n                           │\n          ┌────────┬───────┴───────┬────────────┐\n          ▼        ▼               ▼            ▼\n      CLAUDE.md  AGENTS.md  .cursorrules  GEMINI.md\n      (Claude)   (Codex)      (Cursor)    (Gemini)\n```\n\n### Quick Start\n\n**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==)\n\n**Everywhere else:**\n\n```bash\nbunx faf-mcp\n```\n\nAdd to your MCP config:\n\n```json\n{\"mcpServers\": {\"faf\": {\"command\": \"bunx\", \"args\": [\"faf-mcp\"]}}}\n```\n\n| Platform | Config File |\n|----------|-------------|\n| **Cursor** | `~/.cursor/mcp.json` |\n| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` |\n| **Cline** | Cline MCP settings |\n| **VS Code** | MCP extension config |\n| **Claude Desktop** | Use [claude-faf-mcp](https://github.com/Wolfe-Jam/claude-faf-mcp) |\n\n---\n\n## Three Ways to Deploy\n\n| Door | Method | Best For |\n|------|--------|----------|\n| **Hosted** | [mcpaas.live](https://mcpaas.live) | Zero-install, point any MCP client to the URL |\n| **Self-Deploy** | [Deploy to Vercel](https://vercel.com/new?repository-url=https://github.com/Wolfe-Jam/faf-mcp) | Your own instance, full control |\n| **Local** | `bunx faf-mcp` | IDE integration via stdio transport |\n\n### Hosted (mcpaas.live)\n\nPoint 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.\n\n### Self-Deploy (Vercel)\n\nDeploy your own MCP server on Vercel in one click. Once deployed, your server exposes:\n- `/health` — Health check\n- `/info` — Server metadata + tool list\n- `/mcp/v1` — MCP Streamable HTTP transport\n\n### Local (npm)\n\n```bash\nnpx faf-mcp\n```\n\n---\n\n## Interop Tools\n\n| Tool | Platform | Action |\n|------|----------|--------|\n| `faf_agents` | OpenAI Codex | Import/export/sync AGENTS.md |\n| `faf_cursor` | Cursor IDE | Import/export/sync .cursorrules |\n| `faf_gemini` | Google Gemini | Import/export/sync GEMINI.md |\n| `faf_conductor` | Conductor | Import/export directory structure |\n| `faf_git` | GitHub | Author .faf from any repo URL |\n\n```bash\n# Sync to all formats at once\nfaf bi-sync --all\n\n# Generate .faf from any GitHub repo\nfaf_git { url: \"https://github.com/facebook/react\" }\n```\n\n**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**\n\n---\n\n## Cloud Sync\n\nShare your FAF context globally via [mcpaas.live](https://mcpaas.live):\n\n| Tool | Purpose |\n|------|---------|\n| `faf_cloud_publish` | Upload to cloud, get shareable URL |\n| `faf_cloud_fetch` | Pull context from cloud |\n| `faf_cloud_list` | List available souls |\n| `faf_cloud_search` | Search across souls |\n| `faf_cloud_share` | Generate share links |\n\n**Example Workflow:**\n```bash\n# Upload your project.faf\nfaf_cloud_publish { soul_name: \"my-project\" }\n→ https://mcpaas.live/souls/my-project\n\n# Anyone can fetch it\nfaf_cloud_fetch { soul_name: \"my-project\" }\n→ Context merged into local project.faf\n```\n\n**Zero-install sharing** - Recipients need no MCP setup. Served from 300+ Cloudflare edges with <1ms cold starts via 2.7KB Zig-WASM engine.\n\n---\n\n## Eternal Bi-Sync\n\nYour `.faf` file and your platform context files stay synchronized in milliseconds.\n\n```\nproject.faf  ←── 8ms ──→  .cursorrules / AGENTS.md / CLAUDE.md / GEMINI.md\n                    Single source of truth\n```\n\n- Update either side → both stay aligned\n- `--all` flag syncs to all four formats at once\n- Zero manual maintenance\n- Works across teams, branches, sessions\n\nAI assistants forget. They drift. Every new session, AI starts guessing again. Bi-sync means **context never goes stale**.\n\n---\n\n## Tier System: From Blind to Optimized\n\n| Tier | Score | Status |\n|------|-------|--------|\n| 🏆 **TROPHY** | 100% | AI never has to guess |\n| ★ **GOLD** | 99%+ | 1 slot from Trophy |\n| ◆ **SILVER** | 95%+ | Close — keep going |\n| ◇ **BRONZE** | 85%+ | Interim — keep going |\n| ● **GREEN** | 70%+ | Interim — keep going |\n| ● **YELLOW** | 55%+ | AI flipping coins |\n| ○ **RED** | <55% | AI working blind |\n| ♡ **WHITE** | 0% | No context at all |\n\n**At 55%, AI is guessing half the time.** At 100%, AI is optimized.\n\n---\n\n## use>faf | Prompt Pattern\n\n**Start every prompt with \"Use FAF\"** to invoke MCP tools:\n\n```\nUse FAF to initialize my project\nUse FAF to score my AI-readiness\nUse FAF to sync my context\nUse FAF to enhance my project\n```\n\nWorks on all platforms — stops web search, forces tool usage.\n\n---\n\n## 29 MCP Tools\n\n| Tool | Purpose |\n|------|---------|\n| `faf_init` | Initialize project.faf |\n| `faf_score` | Check AI-readiness (0-100%) |\n| `faf_sync` | Sync context across platforms |\n| `faf_bi_sync` | Bi-directional .faf ↔ CLAUDE.md |\n| `faf_read` | Parse and validate FAF files |\n| `faf_write` | Create/update FAF with validation |\n| **Interop Tools** | |\n| `faf_agents` | Import/export/sync AGENTS.md |\n| `faf_cursor` | Import/export/sync .cursorrules |\n| `faf_gemini` | Import/export/sync GEMINI.md |\n| `faf_conductor` | Import/export directory structure |\n| `faf_git` | Author .faf from GitHub repo URL |\n| **Cloud Tools** | |\n| `faf_cloud_publish` | Upload to mcpaas.live |\n| `faf_cloud_fetch` | Pull from cloud |\n| `faf_cloud_list` | List souls |\n| `faf_cloud_search` | Search souls |\n| `faf_cloud_share` | Generate share links |\n\n**Plus CLI fallback** (via faf-cli):\n- `faf readme` - Extract 6 Ws from README (+25-35% boost)\n- `faf human-add` - Non-interactive YAML merge (6Ws Builder)\n- `faf git` - GitHub repo analysis without cloning\n- And 40+ more commands...\n\n---\n\n## Ecosystem\n\n- **[claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp)** — Claude Desktop (33 tools)\n- **[faf-cli](https://npmjs.com/package/faf-cli)** — Terminal CLI\n- **[faf-wasm](https://www.npmjs.com/package/faf-wasm)** — WASM SDK (<5ms scoring)\n- **[faf-wasm-gen](https://www.npmjs.com/package/faf-wasm-gen)** — Rust→WASM `project.faf` generator, browser/edge (faf-wasm's generate sibling)\n- **[faf-trinity](https://github.com/Wolfe-Jam/faf-trinity)** — reference MCP server exposing all three IANA FAF formats (context/memory/agent) together\n- **[faf.one](https://faf.one)** — Official website\n- **[docs/SKILLS-OVER-MCP.md](./docs/SKILLS-OVER-MCP.md)** — J1 Agent Skill `faf-ide` (stdio · skills/list · digests)\n\n---\n\nIf `faf-mcp` has been useful, consider starring the repo — it helps others find it.\n\n## Citation\n\nIf you use `faf-mcp` or the `.faf` / `.fafa` formats in research or production, please cite the format papers:\n\n> Wolfe, J. (2025). *Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding*. Zenodo. https://doi.org/10.5281/zenodo.18251362\n\n> Wolfe, J. (2026). *Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era*. Zenodo. https://doi.org/10.5281/zenodo.21951641\n\n### BibTeX\n\n```bibtex\n@article{wolfe2025faf,\n  title     = {Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding},\n  author    = {Wolfe, James},\n  year      = {2025},\n  month     = {nov},\n  publisher = {Zenodo},\n  doi       = {10.5281/zenodo.18251362},\n  url       = {https://doi.org/10.5281/zenodo.18251362}\n}\n\n@article{wolfe2026fafa,\n  title     = {Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era},\n  author    = {Wolfe, James},\n  year      = {2026},\n  month     = {aug},\n  publisher = {Zenodo},\n  doi       = {10.5281/zenodo.21951641},\n  url       = {https://doi.org/10.5281/zenodo.21951641}\n}\n```\n\n## License\n\nMIT License — Free and open source\n\n---\n\n**Zero drift. Eternal sync. AI optimized.** 🏆\n\n*\"It's so logical if it didn't exist, AI would have built it itself\" — Claude*\n",
  "bytes": 11198,
  "sha": "be0dcb9933f9ff444db0e480de44fbc19e8cd0251586a7f41983288c027450dd",
  "repo_slug": "wolfe-jam/faf-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wolfe_jam_faf_mcp_e262cc3b/readme"
}