Persistent project context for xAI Grok. IANA-registered .faf format.
one.faf/grok-faf-mcp (MCP Server)
This MCP server provides persistent project context for xAI Grok using a URL-based approach. It is associated with an IANA-registered .faf format and is described as zero config, intended to “just works” for supplying context to Grok via a URL. Built with TypeScript.
🛠️ Key Features
Persistent project context for xAI Grok
URL-based context delivery
Zero config
IANA-registered .faf format (vnd.faf+yaml)
🚀 Use Cases
Supplying Grok with project context through a URL
Using the .faf format for AI context packaging
⚡ Developer Benefits
Developer-oriented context format: .faf
TypeScript implementation
Package targets MCP server usage and integration with Grok
⚠️ Limitations
Described at a high level as “first MCP server for Grok”; no additional capabilities beyond URL-based persistent context are specified.
faf_sync keeps your hand-written files, writes the context files it names, and tells you what it couldn't write. Managed blocks now go through faf-cli's injector, so a hand-written AGENTS.md or CLAUDE.md is never reclaimed; faf_sync writes the context files it names, one file at a time, and the reply says what it couldn't write and why.
v2.2.3
faf_write can no longer overwrite the birth certificate or your context files..faf-dna is refused in every spelling and route, existing project.faf, CLAUDE.md and AGENTS.md need overwrite: true, and writes stay inside the project folder.
v2.2.2
Cleanup: removes leftover two-way sync wording. Two-way sync was dropped by design long ago: project.faf pushes structured data out, and prose doesn't come back. The last strings that still said two-way now match. faf_bi_sync still works as the old name for faf_sync.
v2.2.1
One rule for project questions: read project.faf first. New line 2 of the server instructions: "For questions about the project (stack, goal, commands), read project.faf first and answer from it." The same rule in faf-mcp moved Grok Build from 0 of 3 to 2 of 3 runs reading project.faf first, on a repo where project.faf and package.json disagree (3-run pilot). 715 characters.
v2.2.0
grok-faf-mcp now tells Grok how its tools fit together, context and memory: server instructions in initialize (615 characters), plus faf-cli 8.5.0, which knows a skills repo when it sees one.
Server instructions. When Grok connects, the server says how its tools fit together: context (project.faf) and memory (.fafm), which tool checks, creates or syncs, the refresh tools, and that rag_query needs an xAI Collection.
faf-cli 8.5.0 inside.faf_init detects a skills repo: SKILL.md folders make it skills (10 slots), and a Claude Code plugin manifest makes it skills-plugin (14).
Advisories cleared in the MCP SDK, proxy-addr and hono.
Earlier: v2.1.0 — The New Era Edition — glass-box tools: every tool says if it reads, writes or rewrites; its own FAF passport at grok.faf.one; a new look.
Earlier: v2.0.0 — The Always33 Edition — one engine, one number: every score is faf-cli 8's always-33 kernel, on npm and on mcpaas.live. ZEPH is opt-in until the Zig engine is always-33.
Restart Grok TUI (or /mcps r) to refresh. The hosted endpoint scores always-33 — the same number as the npm package. Tools: faf_score, faf_validate, faf_get_tier, faf_estimate_tokens, faf_analyze (plus soul/memory ops).
Hosted on Cloudflare Workers — sub-ms cold start, no subprocess, edge-served. Scores and validates with the faf-kernel WASM (always-33, the same engine as the npm package) since mcpaas-cf 1.8.1; a Zig WASM engine handles token estimates and tier. Externally validated by Grok S1 + S2 on 2026-05-27.
Verify the live contract:
bash
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.
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.
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 authors what Grok agents read from real project detection — bunx faf export --agents. faf-cli's src/interop/grok.ts wires this MCP into .grok/config.toml (that file lives in the faf-cli repo, not here). 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.
code
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:
# project.faf — your project, machine-readablefaf_version:"3.3"project:name:my-apigoal:RESTAPIforusermanagementmain_language:TypeScriptstack:backend:Expressdatabase:PostgreSQLtesting:Jestruntime:Node.jshuman_context:who:Backenddeveloperswhat:UserCRUDwithauthwhy:ReplacelegacyPHPservice
Every AI agent reads this once and knows exactly what you're building.
⚡ What You Get
code
URL: https://mcpaas.live/grok/mcp/v1
Format: IANA-registered .faf (application/vnd.faf+yaml)
Tools: 12 core by default (bunx) — re-grounding (refresh_faf/fafm/blend), LAZY-RAG, orchestration substrate, FAF essentials · extended utilities via FAF_TOOLS=all · 19 hosted (WASM-pure, served by mcpaas-cf) on the URL
Engine: faf-cli 8 — faf-scoring-kernel 3.0.0 (Rust → WASM, always-33)
Speed: 0.5ms average (was 19ms — 3,800% faster with Mk4)
Tests: WJTTC parity (heavy local ↔ light hosted) + full suites. Runner: sh scripts/run-tests.sh (bun + flake retry)
Status: FAST⚡️AF
MCP on a URL. Point your Grok integration at the URL. That's it.
Scoring: From Blind to Optimized
Tier
Score
What it means
🏆 TROPHY
100%
Gold Code — AI is optimized
★ GOLD
99%+
Near-perfect context
◆ SILVER
95%+
Excellent
◇ BRONZE
85%+
Strong baseline
● GREEN
70%+
Solid foundation
● YELLOW
55%+
AI flipping coins
○ RED
<55%
AI working blind
♡ WHITE
0%
Start — good luck
At 55%, Grok guesses half the time. At 100%, Grok knows your project.
Two Ways to Deploy
1. Hosted (zero install — recommended)
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).
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
Write the context files from project.faf: the ones that exist (CLAUDE.md, .cursorrules, .windsurfrules, .clinerules), or CLAUDE.md when there are none; target: all writes every one. One way: it never writes project.faf. A file faf can't safely write is left unchanged and named in the reply. (faf_bi_sync, the old name, still works.)
faf_trust
Validate .faf integrity
Read & Write
Tool
Purpose
faf_read
Read any file
faf_write
Write a file inside the project. Never writes .faf-dna; replacing an existing *.faf, CLAUDE.md or AGENTS.md needs overwrite: true
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.
Benchmarked 10x per tool, warmed up, on local stdio execution. Hosted edge adds sub-ms cold start on top.
Orchestrator (faf_orchestrate_recommendation) characteristics: composition call — reads up to 6 files (.faf, .fafm, package.json, CHANGELOG.md, README.md, plus all 3 receipt logs), runs 2 analyzers (detectFafmDrift + checkId), evaluates the decision table, writes 1 receipt. Expected latency: tens of ms on warm cache; higher under cold-disk or very large .fafm corpora. Designed for occasional agent-initiated calls, not per-turn polling.detectFafmDrift is O(n²) in fact count (cross-fact n-gram recurrence) — comfortable up to ~hundreds of facts.
Production deployment: Cloudflare Workers via mcpaas-cf (serving mcpaas.live/grok/mcp/v1). The api/index.ts + vercel.json paths above stay alive as a catch-site for legacy/bookmarked links — they are no longer the production path.
Scoring pipeline: faf-cli's scoreFafYaml → the always-33 kernel (faf-scoring-kernel, Rust → WASM) scores the file as written: 33 slots, slotignored slots drop out of the denominator. No per-type rewriting, no fallback scorer — the same number faf-cli, claude-faf-mcp and faf-mcp give.
Testing
WJTTC parity (heavy local ↔ light hosted) + full suites (green on CI):
v2.2.0 — The Instructions Edition — server instructions in initialize (615 characters) and faf-cli 8.5.0, which detects skills repos. Scoring is unchanged from v2.0.0.
v2.1.0 — The New Era Edition — glass-box tools (every tool labelled read, write or rewrite), its own FAF passport at grok.faf.one, a new look. Scoring is unchanged from v2.0.0.
v2.0.0 — The Always33 Edition — one engine, one number: faf-cli 8's always-33 kernel on npm and on mcpaas.live. ZEPH is opt-in until the Zig engine is always-33. FafCompiler upgraded to the Always33 fafb model — parity across frontier models, Enterprise/Teams ready.
Everything below still applies; operating it honestly means surfacing what's NOT in here alongside what is.
Earlier: v1.10.0 — The No-Fluff Edition — no fluff in a project.faf. faf_enhance is gone. RAG default is grok-4.6. Fill stays on faf_auto / faf_go.
Earlier: v1.9.0 — The ZEPH Default Edition — the proven-fast Zig→WASM scoring path behind refresh_faf is now default-ON (same score, cheaper to compute; parity proven byte-identical — CI gate + 91/91 live). Kill switch USE_ZEPH=0 forces the canonical scorer. FRC tools stay opt-in behind USE_FRC.
Earlier: v1.8.0 — The Closed-Loop Edition — observability writes, token math is honest, FRC contract locked. The drift→refresh→re-ground loop can finally be measured.
Earlier: v1.7.0 — The Grounded Memory Edition — ZEPH + the FRC layer over Grok Collections (faf_gate/faf_section/faf_memory), opt-in via USE_FRC/USE_ZEPH; 12-tool core unchanged.
Earlier: v1.6.0 — The ZEPH Edition — the ZEPH fast path for re-grounding (refresh_faf/refresh_blend via Zig→WASM cascade.wasm, ~12µs, USE_ZEPH=1; faf-cli stays canonical, parity locked in CI).
What is fully supported:
19 tools on the hosted endpoint (https://mcpaas.live/grok/mcp/v1 and client-specific routes) — scoring · validation · refresh_faf · a content-in faf_orchestrate_recommendation · the FRC trio · souls and search. The live list is at …/grok/mcp/v1/info.
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).
faf_orchestrate_recommendation — the heavy orchestrator that composes drift signals, recurrence, receipts, and take-a-hint into an advisory recommendation.
faf_get_orchestration_policy — pure introspection of the effective policy without running the orchestrator (no drift detection, no receipt write — the quietest tool in the substrate).
Full policy visibility (effective_policy) returned on every orchestration call AND surfaced standalone via faf_get_orchestration_policy.
Current limitations:
faf_get_orchestration_policy, refresh_fafm, refresh_blend, faf_init and faf_sync need filesystem access and run only on the local stdio path (bunx grok-faf-mcp / npx grok-faf-mcp). The hosted faf_orchestrate_recommendation takes file contents instead of reading your repo, and has no receipts or recurrence history (it reports those under partial[]).
Receipt storage — cwd-relative JSON, pull-discoverable. Three append-only JSON files live at the repo root with stable schemas:
code
.faf-drift-index.json ← RepeatOffenderTracker — per-slot recurrence counts
.faf-refresh-receipts.json ← RefreshReceiptsLog — every refresh fire
.faf-recommendation-receipts.json ← RecommendationReceiptsLog — every orchestrator call
Pull-discoverable by external tools (TAF, custom indexers, observability dashboards) — read on your own schedule, no callback/push API required. Promotion to a dedicated orphan branch (mirroring the TAF pattern) is documented but deferred per ship discipline; the cwd-relative JSON is the v1 bootstrap.
No multi-process file lock on the receipt logs. Within a process, the JS event loop serializes writes. Multi-agent concurrent writes can race; future task.
Aggressiveness tier hook — .faf:orchestration:tier reads 'conservative' (default — quietest, no noisy first-impression) · 'balanced' · 'aggressive'. active_tier always surfaced in hints.effective_policy for observability, and standalone via faf_get_orchestration_policy. The policy WRITER (faf_set_orchestration_policy) and scheduling (faf_schedule_heavy_re_ground) are not included in v1.5 — edit .faf:orchestration:tier: directly to override.
No ack mechanism yet for recommendation receipts.acknowledged: false by default, never auto-flipped. Take-a-hint's ladder-reset semantics fire only on explicit ack — conservative by intent. Future task: explicit ack tool OR derived-from-subsequent-refresh-receipt timing.
Outcome tracking ("did this recommendation actually help?") — needs a learning layer beyond 1.5 scope.
The honest split is intentional: hosted = fast, auditable, WASM-pure; local = full capability including filesystem. We will expand the hosted surface only where it can be done safely and without compromising the model.
Subordinate-not-daemon throughout. The orchestrator NEVER auto-fires the recommended tool. Agents surface the recommendation; the user (or higher agent) decides whether to act. Even severity: 'block' is advisory.
See the public verifier and curl https://mcpaas.live/grok/mcp/v1/info for the current contract.
Same project.faf. Same scoring. Same result. Different execution layer.
Voice variant — grok-faf-voice (VML)
.fafm 🐘🎙️ — the voice variant of the .faf 🐘 family.
grok-faf-voice is the reference implementation of the Voice Memory Layer (VML) — what your voice agent remembers across sessions, devices, and model switches. Companion to grok-faf-mcp:
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.
Same family. Different surface. Voice swappable; memory permanent.
Open for deeper native integration, .fafm memory layer, or Grok Build CLI collaboration.
Happy to ship PRs, dogfood, or jump on a call. Just say the word.
Citation
If you use grok-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
@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 — Free and open source
Built for Grok. Built for Speed. Built Right.
FAST⚡️AF • First to Ship • Zero Friction
Zero drift. Eternal sync. AI optimized. 🏆
Get the CLI
faf-cli — The original AI-Context CLI. A must-have for every builder.