.FAF Context
.FAF Context — persistent project context for Cursor, VS Code and every MCP-compatible IDE.
Open source Open in the app JSON README (API)
About
.FAF Context — persistent project context for Cursor, VS Code and every MCP-compatible IDE.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- one.faf
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 2.3.1
- Stars
- 6
- Forks
- 2
- Open pull requests
- 1
- Last push
- 2026-09-04T03:03:27Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:50
- Updated
- 2026-09-10 22:02:32
- Origin id
one.faf/faf-mcp
README
<!-- faf: faf-mcp | TypeScript | mcp-server | FAF MCP IDE Edition — persistent project context for Cursor, Windsurf, Cline, VS Code -->
<!-- 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>
[](https://www.npmjs.com/package/faf-mcp)[](https://www.npmjs.com/package/faf-mcp)
[](https://faf.one)
[](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
[](https://doi.org/10.5281/zenodo.18251362)
[](https://doi.org/10.5281/zenodo.21951641)
**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)
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](https://faf.one/downloads)), 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.
[](https://github.com/Wolfe-Jam/faf-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](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 👀](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:** [](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) |
---
## Three Ways to Deploy
| Door | Method | Best For |
|------|--------|----------|
| **Hosted** | [mcpaas.live](https://mcpaas.live) | Zero-install, point any MCP client to the URL |
| **Self-Deploy** | [Deploy to Vercel](https://vercel.com/new?repository-url=https://github.com/Wolfe-Jam/faf-mcp) | 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)
```bash
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 |
```bash
# 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](https://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](https://npmjs.com/package/claude-faf-mcp)** — Claude Desktop (33 tools)
- **[faf-cli](https://npmjs.com/package/faf-cli)** — Terminal CLI
- **[faf-wasm](https://www.npmjs.com/package/faf-wasm)** — WASM SDK (<5ms scoring)
- **[faf-wasm-gen](https://www.npmjs.com/package/faf-wasm-gen)** — Rust→WASM `project.faf` generator, browser/edge (faf-wasm's generate sibling)
- **[faf-trinity](https://github.com/Wolfe-Jam/faf-trinity)** — reference MCP server exposing all three IANA FAF formats (context/memory/agent) together
- **[faf.one](https://faf.one)** — Official website
- **[docs/SKILLS-OVER-MCP.md](./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
```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*