Grok FAF

SSE

by Wolfe-Jam

17 276 downloads Not rated yet MIT

GitHub Website SSE

About

Persistent Project Context for xAI Grok — IANA-registered .faf format · MCP server on a URL

Details

Transport: SSE
License: MIT

Explore

- refresh_faf and refresh_fafm as explicit, callable re-grounding primitives
- refresh_blend as the baked-in two-intensity refresh (Cmd+R / Cmd+Shift+R analog)
- Outcome tracking ("did this recommendation actually help?") — needs a learning layer beyond 1.5 scope
- grok-faf-mcp (this) — .faf Foundational Context Layer for Grok via MCP-on-a-URL
- grok-faf-voice — .fafm Voice Memory Layer (VML) for Grok Voice via LiveKit + xAI realtime

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

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": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

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": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

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": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

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": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

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": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

From the repository

Add to ~/.grok/config.toml:

[mcp_servers.grok-faf-mcp]
url = "https://mcpaas.live/grok/mcp/v1"

Restart Grok TUI (or /mcps r) to refresh. Tools: faf_score, faf_validate, faf_get_tier, faf_estimate_tokens, faf_analyze (plus soul/memory ops).

Smithery: wolfe-jam/grok-faf-mcp — gateway at https://grok-faf-mcp--wolfe-jam.run.tools

Homebrew (local stdio):

brew install wolfe-jam/faf/grok-faf-mcp

Hosted on Cloudflare Workers — sub-ms cold start, no subprocess, edge-served. 4865-byte Zig WASM engine, parity-tested vs the Rust authority (xai-faf-rust). Externally validated by Grok S1 + S2 on 2026-05-27.

Verify the live contract:

curl https://mcpaas.live/grok/mcp/v1/info

Returns endpoint, protocol versions, engine details, tool list, and the architecture line: .faf=vROM | AI-in-session=RAM.

Sample corpus: xai-faf-proof/pilot — 10 records ready to score.

---

Every README should answer these questions. Here's ours:

| Question | Answer |
|----------|--------|
| WHO is this for? | Grok/xAI developers and teams building with URL-based MCP |
| WHAT is it? | Persistent project context for xAI Grok — URL-first deployment, IANA-registered .faf format |
| WHERE does it work? | Cloudflare Workers (mcpaas.live/grok/mcp/v1) • Any MCP client supporting native url= config • Self-deploy to your own CF/Vercel worker |
| WHY do you need it? | Zero-config MCP on a URL — Grok asked for it, we built it first |
| WHEN should you use it? | Grok integration, xAI projects, any url-based MCP client |
| HOW does it work? | url = "https://mcpaas.live/grok/mcp/v1" — context tools served from edge via MCPaaS (sub-ms cold start, no subprocess) |

For AI: Read the detailed sections below for full context.
For humans: Use this pattern in YOUR README. Answer these 6 questions clearly.

Point your MCP client at the production URL — edge-served on Cloudflare Workers, no subprocess, sub-ms cold start. WASM-pure tools only on this path (scoring, validation, refresh_faf).

{
  "mcpServers": {
    "grok-faf": {
      "url": "https://mcpaas.live/grok/mcp/v1"
    }
  }
}

`faf_init`

Create project.faf from your project

`faf_auto`

Auto-detect stack and populate context

`faf_score`

AI-readiness score (0-100%) with breakdown

`faf_status`

Check current AI-readability

`faf_enhance`

Intelligent enhancement

`refresh_faf`

Re-ground on the live `.faf` — re-read + re-score, report drift, return fresh DNA (drift → refresh → re-grounded). **Requested by Grok.**

`refresh_fafm`

Re-ground on the live `.fafm` memory layer for one or more souls. Returns a stamped delta (added/updated facts) by default; `verbatim: true` for full content. Read-only · always stamped. Sister to `refresh_faf` for the RAM/memory layer in the vROM/RAM model. **Built for Grok, by request.**

`refresh_blend`

The baked-in two-intensity refresh (Cmd+R / Cmd+Shift+R analog). `mode: "blend"` (default) fires `refresh_faf` (light) + `refresh_fafm` (delta); `mode: "nuke"` fires both at hard intensity. Blend is **BAKED IN, NOT a dial** — both layers always fire; mode only affects fafm intensity.

`faf_orchestrate_recommendation`

The heavy orchestrator. Reads current substrate state, composes the full 1.5 library substrate (drift detection · CheckID · repeat-offender · take-a-hint · refresh history), returns a structured `Recommendation` with `recommend`, `severity`, `summary`, `reason`, and a rich `hints` object including `effective_policy` (the tier in force). **Advisory only — never auto-fires** (subordinate-not-daemon). Writes a recommendation receipt on every call (no silent decisions). Spec source: Grok-1 `FAF-DRIF

`faf_get_orchestration_policy`

Pure introspection of the effective policy WITHOUT running the orchestrator. Returns `{ tier, thresholds, source, overrides_applied }` — what aggressiveness tier the next orchestration call would use, and whether it came from defaults or a `.faf:orchestration:` override. No drift detection · no signals · no receipt write — the quietest tool in the 1.5 substrate. Useful for debugging unexpected orchestrator behavior, pre-flight checks before bulk operations, and override-took-effect verification.

`faf_sync`

Sync .faf → CLAUDE.md

`faf_bi_sync`

Bi-directional .faf ↔ platform context

`faf_trust`

Validate .faf integrity

`faf_read`

Read any file

`faf_write`

Write any file

`faf_list`

Discover projects with .faf files

`rag_query`

RAG-powered context retrieval

`rag_cache_stats`

RAG cache statistics

`rag_cache_clear`

Clear RAG cache

`grok_go_fast_af`

Auto-load .faf context for Grok

Create & Detect

| Tool | Purpose |
|------|---------|
| faf_init | Create project.faf from your project |
| faf_auto | Auto-detect stack and populate context |
| faf_score | AI-readiness score (0-100%) with breakdown |
| faf_status | Check current AI-readability |
| faf_enhance | Intelligent enhancement |
| refresh_faf | Re-ground on the live .faf — re-read + re-score, report drift, return fresh DNA (drift → refresh → re-grounded). Requested by Grok. |

Drift & Orchestration (1.5 — the prestige release)

| Tool | Purpose |
|------|---------|
| refresh_fafm | Re-ground on the live .fafm memory layer for one or more souls. Returns a stamped delta (added/updated facts) by default; verbatim: true for full content. Read-only · always stamped. Sister to refresh_faf for the RAM/memory layer in the vROM/RAM model. Built for Grok, by request. |
| refresh_blend | The baked-in two-intensity refresh (Cmd+R / Cmd+Shift+R analog). mode: "blend" (default) fires refresh_faf (light) + refresh_fafm (delta); mode: "nuke" fires both at hard intensity. Blend is BAKED IN, NOT a dial — both layers always fire; mode only affects fafm intensity. |
| faf_orchestrate_recommendation | The heavy orchestrator. Reads current substrate state, composes the full 1.5 library substrate (drift detection · CheckID · repeat-offender · take-a-hint · refresh history), returns a structured Recommendation with recommend, severity, summary, reason, and a rich hints object including effective_policy (the tier in force). Advisory only — never auto-fires (subordinate-not-daemon). Writes a recommendation receipt on every call (no silent decisions). Spec source: Grok-1 FAF-DRIFT-DETECTION-SPEC §9.5 + Appendix C. |
| faf_get_orchestration_policy | Pure introspection of the effective policy WITHOUT running the orchestrator. Returns { tier, thresholds, source, overrides_applied } — what aggressiveness tier the next orchestration call would use, and whether it came from defaults or a .faf:orchestration: override. No drift detection · no signals · no receipt write — the quietest tool in the 1.5 substrate. Useful for debugging unexpected orchestrator behavior, pre-flight checks before bulk operations, and override-took-effect verification. |

Sync & Persist

| Tool | Purpose |
|------|---------|
| faf_sync | Sync .faf → CLAUDE.md |
| faf_bi_sync | Bi-directional .faf ↔ platform context |
| faf_trust | Validate .faf integrity |

Read & Write

| Tool | Purpose |
|------|---------|
| faf_read | Read any file |
| faf_write | Write any file |
| faf_list | Discover projects with .faf files |

RAG & Grok-Exclusive

| Tool | Purpose |
|------|---------|
| rag_query | RAG-powered context retrieval |
| rag_cache_stats | RAG cache statistics |
| rag_cache_clear | Clear RAG cache |
| grok_go_fast_af | Auto-load .faf context for Grok |

Plus 34 advanced tools available with FAF_SHOW_ADVANCED=true.

---

Claude Desktop / Cursor

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

{
    "mcpServers": {
        "grok faf": {
            "grok-faf-mcp": {
                "command": "npx",
                "args": [
                    "faf-cli",
                    "auto"
                ]
            }
        }
    }
}

McpServers

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

<h3>Grok asked for MCP on a URL. This is it.</h3>

<p><strong>Persistent Project Context for xAI Grok.</strong></p>
<p><code>URL-based • Zero config • Just works</code></p>

</div>

Home: faf.one/grok
Live demo: grok.faf.one

grok-faf-mcp hero

</div>

FAF defines. MD instructs. AI codes.

---

Install — one line

Add to ~/.grok/config.toml:

[mcp_servers.grok-faf-mcp]
url = "https://mcpaas.live/grok/mcp/v1"

Restart Grok TUI (or /mcps r) to refresh. Tools: faf_score, faf_validate, faf_get_tier, faf_estimate_tokens, faf_analyze (plus soul/memory ops).

Smithery: wolfe-jam/grok-faf-mcp — gateway at https://grok-faf-mcp--wolfe-jam.run.tools

Homebrew (local stdio):

brew install wolfe-jam/faf/grok-faf-mcp

Verify the live contract:

curl https://mcpaas.live/grok/mcp/v1/info

Returns endpoint, protocol versions, engine details, tool list, and the architecture line: .faf=vROM | AI-in-session=RAM.

Sample corpus: xai-faf-proof/pilot — 10 records ready to score.

---

The 6 Ws - Quick Reference

Every README should answer these questions. Here's ours:

For AI: Read the detailed sections below for full context.
For humans: Use this pattern in YOUR README. Answer these 6 questions clearly.

For the xAI / Grok Build team

Built for Grok and shaped by direct Grok feedback.
Open for native Grok Build integration, .fafm memory layer, refresh_faf primitives, or any other context features the team needs.
Live and dogfooded at https://grok.faf.one and https://mcpaas.live/grok/mcp/v1.

Context for Grok agents: faf-cli generates what Grok agents read from real project detection — bunx faf export --agents. The existing src/interop/grok.ts wires FAF MCP into .grok/config.toml. See FAF-CLI for Grok & xAI agents 👀.

---

The Problem

Every Grok session starts from zero. You re-explain your stack, your goals, your architecture. Every time.

.faf fixes that. One file, your project DNA, persistent across every session.

Without .faf  →  "I'm building a REST API in Rust with Axum and PostgreSQL..."
With .faf     →  Grok already knows. Every session. Forever.

---

One Command, Done Forever

faf_auto detects your project, creates a .faf, and scores it — in one shot:

faf_auto ━━━━━━━━━━━━━━━━━ Score: 0% → 85% (+85) ◇ BRONZE Steps: 1. Created project.faf 2. Detected stack from package.json 3. Synced CLAUDE.md

Path: /home/user/my-project

What it produces:

```yaml

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

Explore

Setting up with Highlight

From the repository

faf_init

faf_auto

faf_score

faf_status

faf_enhance

refresh_faf

refresh_fafm

refresh_blend

faf_orchestrate_recommendation

faf_get_orchestration_policy

faf_sync

faf_bi_sync

faf_trust

faf_read

faf_write

faf_list

rag_query

rag_cache_stats

rag_cache_clear

grok_go_fast_af

Claude Desktop / Cursor

McpServers

Install — one line

The 6 Ws - Quick Reference

For the xAI / Grok Build team

The Problem

One Command, Done Forever

More like this

Context 7

1Panel

🔎 GPT Researcher

Serena

`faf_init`

`faf_auto`

`faf_score`

`faf_status`

`faf_enhance`

`refresh_faf`

`refresh_fafm`

`refresh_blend`

`faf_orchestrate_recommendation`

`faf_get_orchestration_policy`

`faf_sync`

`faf_bi_sync`

`faf_trust`

`faf_read`

`faf_write`

`faf_list`

`rag_query`

`rag_cache_stats`

`rag_cache_clear`

`grok_go_fast_af`