.FAF Context

by Wolfe-Jam

5 stars

296 downloads

Not rated

GitHub Website

About

Persistent Project Context for Cursor, IDEs and VS Code — IANA-registered .faf format · 25 tools

Details

Author: Wolfe-Jam
GitHub stars: 5
Downloads: 296
Categories: AI

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name .FAF Context

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

From the repository

The README includes setup instructions such as npx faf-mcp.

`faf_about`

Explain what the .faf format is — the IANA-registered, portable context file (application/vnd.faf+yaml) that gives any AI instant project understanding. Returns a plain-language overview of the format and its purpose. Use this when you or the user are new to FAF and want the concept before running other tools.

`faf_score`

Calculate a project.faf AI-readiness score (0-100%) from the populated context slots. Returns the percentage and tier, and with details a slot-by-slot breakdown with improvement suggestions. Use this to measure how complete the AI context is and what to fill next.

`faf_init`

Create a project.faf for a project, making it instantly AI-readable. Returns the new file location and starting score. Accepts a path or bare project name (e.g. ~/Projects/my-app, my-app) and omitting it uses the current directory.

`faf_trust`

Validate a project.faf for structural integrity and field consistency. Returns trust metrics flagging malformed, missing, or contradictory data. Use this to confirm the context is sound before relying on it or syncing it to other formats.

`faf_sync`

Sync a project.faf with CLAUDE.md so the two stay aligned. Returns what was written. Use this for the single CLAUDE.md target; use faf_bi_sync to fan out to AGENTS.md, .cursorrules, and GEMINI.md as well.

`faf_bi_sync`

Bi-directionally sync a project.faf with CLAUDE.md and, with the format flags or all, also AGENTS.md, .cursorrules, and GEMINI.md. Returns the formats written and any conflicts. Use this to keep every AI tool context file aligned from the single .faf source.

`faf_check`

Inspect the human_context fields and rate each empty/generic/good/excellent. Returns the ratings; with protect it locks good/excellent fields from being overwritten, with unlock it releases them. Use this to gauge context quality and guard your best answers.

`faf_context`

Set or show the active project path that later faf_ calls resolve against. Returns the current context path. Call this once at the start of a session so the other tools target the right project.

`faf_go`

Drive a project.faf to 100% through a guided interview — returns the next questions for the missing human-context and goal fields, then applies the answers passed back. Returns the updated score after each round. Use this to close the gap to a complete context when auto-detection cannot fill the human slots.

`faf_auto`

Run the full setup pipeline in one call — init, stack detection, sync, bi-sync, and score — taking a project from no context to a complete project.faf. Returns the final AI-readiness score and what was created. Use this as the fast path on a fresh project; use the individual tools when you need finer control.

`faf_doctor`

Diagnose a project.faf setup — report missing files, empty or weak slots, and common configuration issues, each with how to fix it. Returns a prioritized checklist. Use this when your score is low and you need to know why.

`faf_agents`

Import, export, or sync context between AGENTS.md (the OpenAI/Codex convention) and project.faf. Returns the merged or written result for the chosen action. Use this to keep a Codex/OpenAI-style AGENTS.md and your .faf in agreement from one source.

`faf_cursor`

Import, export, or sync context between .cursorrules (the Cursor IDE convention) and project.faf. Returns the merged or written result for the chosen action. Use this to keep Cursor rules and your .faf in agreement from one source.

`faf_gemini`

Import, export, or sync context between GEMINI.md (the Google Gemini CLI convention) and project.faf. Returns the merged or written result for the chosen action. Use this to keep a Gemini context file and your .faf in agreement from one source.

`faf_git`

Generate a project.faf from any public GitHub repository URL — fetches the repo and extracts its stack and context. Returns the generated .faf. Use this to bootstrap context for a project you have the URL for but not cloned locally.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        ".faf context": {
            "faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-mcp"
                ]
            }
        }
    }
}

McpServers

{
    "faf-mcp": {
        "command": "npx",
        "args": [
            "faf-mcp"
        ]
    }
}

<div style="display: flex; align-items: center; gap: 12px;">

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

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 100,000+ downloads across the FAF ecosystem, we bring you faf-mcp to cure your syncing pain and fuel your chosen AI with optimized context, on-demand.

---

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) generates 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 | Generate .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 | Generate .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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

faf_about

faf_score

faf_init

faf_trust

faf_sync

faf_bi_sync

faf_check

faf_context

faf_go

faf_auto

faf_doctor

faf_agents

faf_cursor

faf_gemini

faf_git

Claude Desktop / Cursor

McpServers

What's New in 2.3.0 — The Curated Edition

Define once. Sync everywhere.

Quick Start

Three Ways to Deploy

Hosted (mcpaas.live)

Self-Deploy (Vercel)

Local (npm)

Interop Tools

Generate .faf from any GitHub repo

Cloud Sync

Anyone can fetch it

Eternal Bi-Sync

Tier System: From Blind to Optimized

use>faf | Prompt Pattern

29 MCP Tools

Ecosystem

License

Install

More like this

Context 7

1Panel

🔎 GPT Researcher

Serena

FastMCP v2 🚀

MaxKB

`faf_about`

`faf_score`

`faf_init`

`faf_trust`

`faf_sync`

`faf_bi_sync`

`faf_check`

`faf_context`

`faf_go`

`faf_auto`

`faf_doctor`

`faf_agents`

`faf_cursor`

`faf_gemini`

`faf_git`