grok-faf-mcp — FAST⚡️AF Edition

Grok asked for MCP on a URL. This is it.

Persistent Project Context for xAI Grok.

URL-based • Zero config • Just works

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

grok-faf-mcp hero

FAF defines. MD instructs. AI codes.

v1.10.0 — The No-Fluff Edition

No fluff in a project.faf. faf_enhance is gone. RAG default is grok-4.6.

A .faf is facts. Two writers only: the repo (faf_auto) and the human (faf_go). Empty is honest. There is no enhance.

⭐ Bookmarks it for you, helps other devs find it too.

First v0.2-conformant reader of the FAF Context Ingestion Contract — the open standard co-authored in public with @grok.

Install — one line

Add to ~/.grok/config.toml:

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

bash

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:

Terminal

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:

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:

Code

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

# project.faf — your project, machine-readable
faf_version: "3.3"
project:
  name: my-api
  goal: REST API for user management
  main_language: TypeScript
stack:
  backend: Express
  database: PostgreSQL
  testing: Jest
  runtime: Node.js
human_context:
  who: Backend developers
  what: User CRUD with auth
  why: Replace legacy PHP service

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:  Mk4 WASM scoring (faf-scoring-kernel)
Speed:   0.5ms average (was 19ms — 3,800% faster with Mk4)
Tests: 27 .ts files (~518 test declarations) — 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).

config.json

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

2. Local (stdio — for FS-touching workflows)

Use the local stdio path when you need filesystem access (faf_init, faf_sync, file-mutating tools):

bash

brew install wolfe-jam/faf/grok-faf-mcp   # macOS tap
# or
bunx grok-faf-mcp

Or via MCP config:

config.json

{
  "mcpServers": {
    "grok-faf": {
      "command": "bunx",
      "args": ["grok-faf-mcp"]
    }
  }
}

MCP Tools

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

Performance

Code

Execution:    0.5ms average (97% faster than v1.1)
Fastest:      3,360ns (version — nanosecond territory)
Slowest:      1.3ms (score — Mk4 WASM)
Improvement:  19ms → 0.5ms (3,800% faster)
Engine:       Mk4 WASM via faf-scoring-kernel
Memory:       Zero leaks
Transport:    stdio (local, bunx) · Streamable HTTP (hosted, Cloudflare Workers)

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.

Architecture

Code

grok-faf-mcp
├── src/
│   ├── server.ts             → MCP server (GrokFafMcpServer)
│   ├── handlers/
│   │   ├── championship-tools.ts  → 55+ tool definitions
│   │   ├── tool-registry.ts       → Visibility filtering (core/advanced)
│   │   └── engine-adapter.ts      → FAF engine bridge
│   ├── faf-core/compiler/faf-compiler.ts → Mk4 WASM scoring + Mk3.1 fallback
│   ├── types/                     → Canonical type substrate (1.5)
│   │   ├── drift-signals.ts       → DriftSignal · Contradiction · RepeatOffender
│   │   ├── refresh.ts             → RefreshMode
│   │   ├── escalation.ts          → EscalationLevel
│   │   ├── recommendation.ts      → RecommendationAction
│   │   └── receipts.ts            → ReceiptMetadata
│   ├── detection/fafm-drift.ts    → detectFafmDrift() — repetition-rate gauge
│   ├── integrity/check-id.ts      → checkId() — cross-stamp contradiction check
│   ├── orchestrator/
│   │   ├── repeat-offender.ts     → RepeatOffenderTracker
│   │   ├── take-a-hint.ts         → evaluateTakeAHint() — escalation ladder
│   │   ├── refresh-blend.ts       → runRefreshBlend()
│   │   └── recommendation.ts      → analyzeAndRecommend() + orchestrate()
│   └── telemetry/
│       ├── refresh-receipts.ts        → RefreshReceiptsLog
│       └── recommendation-receipts.ts → RecommendationReceiptsLog
├── smithery.yaml             → Smithery listing config
├── api/index.ts              → Vercel catch-site (legacy showcase surface; kept alive)
└── vercel.json               → Vercel routing for the catch-site

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: TypeScript compiler parses .faf → detects project type → The Bouncer injects slotignored for inapplicable slots → faf-scoring-kernel (WASM) scores → falls back to Mk3.1 if kernel unavailable.

Testing

27 test files (~518 test declarations) — WJTTC parity (heavy local ↔ light hosted) + full suites (recent runs green on CI):

bash

sh scripts/run-tests.sh

Suite	Coverage
`desktop-native-validation`	Core native functions, security, performance
`mcp-conformance`	MCP protocol conformance — tools, transport, errors
`wjttc-mcp`	WJTTC MCP certification
`wjttc-bun`	WJTTC bun-migration + integrity
`wjttc-compiler-scoring`	Compiler scoring — engine, type detection, slots
`rag-system`	RAG query, caching, context retrieval
`security`	Input validation + security guards
`visibility`	Tool visibility (core/advanced filtering)

Status & known limitations (v1.10)

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. Everything below still applies; operating it honestly means surfacing what's NOT in here alongside what is.

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:

WASM-pure tools on the hosted endpoint (https://mcpaas.live/grok/mcp/v1 and client-specific routes) — scoring · validation · refresh_faf.
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_orchestrate_recommendation, faf_get_orchestration_policy, refresh_fafm, and refresh_blend require filesystem access and are only available via the local stdio path (bunx grok-faf-mcp / npx grok-faf-mcp). They are not exposed on the hosted WASM-pure endpoint. The hosted path serves the existing WASM-pure subset only (refresh_faf + scoring + validation).
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.

Ecosystem

One format, every AI platform.

Package	Platform	Registry
grok-faf-mcp (this)	xAI Grok	npm + Homebrew
claude-faf-mcp	Anthropic	npm + MCP #2759
gemini-faf-mcp	Google	PyPI
rust-faf-mcp	Rust	crates.io
faf-mcp	Cursor, IDE's, VS Code	npm
faf-cli	Terminal CLI	bunx, npm + Homebrew

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.

PyPI · GitHub · Onboarding

For the xAI / Grok Build team

This MCP server was built for Grok and continues to be shaped by direct feedback from Grok itself.

Open for deeper collaboration on:

Native Grok Build integration
.fafm memory layer
refresh_faf primitives inside the Grok TUI / CLI
Any other context or orchestration features the team needs

I ship fast, test rigorously, and dogfood everything live on https://grok.faf.one and https://mcpaas.live/grok/mcp/v1.

Happy to:

Open PRs
Run private dogfood sessions
Jump on a call
Or just ship whatever moves the needle

Real software only. Just say the word.

Contributing

PR conventions, code style, CI doctrine, MCP-tool contribution path, npm publish discipline, architecture decisions: CONTRIBUTING.md.

xAI / Grok devs welcome — TL;DR setup at the top, F1-inspired tone throughout.

For xAI / Grok Build team

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

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

Terminal

npx faf-cli auto

Anthropic MCP #2759 · IANA Registered: application/vnd.faf+yaml · faf.one · npm · Talk to my Agent →

grok-faf-mcp — FAST⚡️AF Edition

Grok asked for MCP on a URL. This is it.

v1.10.0 — The No-Fluff Edition

Install — one line

The 6 Ws - Quick Reference

For the xAI / Grok Build team

The Problem

One Command, Done Forever

⚡ What You Get

Scoring: From Blind to Optimized

Two Ways to Deploy

1. Hosted (zero install — recommended)

2. Local (stdio — for FS-touching workflows)

MCP Tools

Performance

Architecture

Testing

Status & known limitations (v1.10)

Ecosystem

Voice variant — grok-faf-voice (VML)

For the xAI / Grok Build team

Contributing

For xAI / Grok Build team

Citation

BibTeX

License

Get the CLI

Voice variant — `grok-faf-voice` (VML)