FAST⚡️AF Context

FAF defines. MD instructs. AI codes.

---

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?	Vercel (production) • Local dev • Any MCP client supporting HTTP-SSE
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 testing, xAI projects, URL-based MCP deployments
HOW does it work?	Point to https://grok-faf-mcp.vercel.app/sse — context tools served via MCP SSE

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

---

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:

# 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

URL:     https://grok-faf-mcp.vercel.app/
Format:  IANA-registered .faf (application/vnd.faf+yaml)
Tools:   21 core MCP tools (55 total with advanced)
Engine:  Mk4 WASM scoring (faf-scoring-kernel)
Speed:   0.5ms average (was 19ms — 3,800% faster with Mk4)
Tests:   169 passed · 0 failed · 169 total (7 suites)
Status:  FAST⚡️AF

MCP over HTTP-SSE. 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%+	Production ready
● GREEN	70%+	Solid foundation
● YELLOW	55%+	AI flipping coins
○ RED	<55%	AI working blind
♡ WHITE	0%	Empty — good luck

At 55%, Grok guesses half the time. At 100%, Grok knows your project.

---

Three Ways to Deploy

1. Hosted (Instant)

https://grok-faf-mcp.vercel.app/sse

Point your MCP client to this endpoint. All 21 tools available instantly.

2. Self-Deploy (Your Own Vercel)

Click the Deploy with Vercel button above. Zero config — get your own instance in 30 seconds.

3. Local (npx)

npx grok-faf-mcp

Or add to your MCP config:

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

---

MCP Tools (21 Core)

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

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

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:    HTTP-SSE (Vercel Edge)

Benchmarked 10x per tool, warmed up, on local execution.

---

Architecture

grok-faf-mcp v1.2.1
├── api/index.ts              → Vercel serverless (Express + SSE transport)
├── src/
│   ├── server.ts             → MCP server (ClaudeFafMcpServer)
│   ├── 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
├── smithery.yaml             → Smithery listing config
└── vercel.json               → Vercel routing

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

179 tests across 7 suites:

npm test    # runs all 179

Suite	Tests	Coverage
Desktop-native validation	10	Core native functions, security, performance
MCP protocol	28	Tool registration, transport, error handling
Compiler scoring	22	Mk4 engine, type detection, slot counting
RAG system	19	Query, caching, context retrieval
Engine adapter	35	CLI detection, fallback behavior
Integration	40	End-to-end tool execution
WJTTC certification	25	Championship-grade compliance

---

Endpoints

Endpoint	URL
Root	https://grok-faf-mcp.vercel.app/
SSE	https://grok-faf-mcp.vercel.app/sse
Health	https://grok-faf-mcp.vercel.app/health
Info	https://grok-faf-mcp.vercel.app/info

---

Ecosystem

One format, every AI platform.

Package	Platform	Registry
grok-faf-mcp (this)	xAI Grok	npm
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

---

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.

---

If grok-faf-mcp has been useful, consider starring the repo ⭐️ it helps others find it.

---

License

MIT — Free and open source

---

---

Get the CLI

faf-cli — The original AI-Context CLI. A must-have for every builder.

npx faf-cli auto

Anthropic MCP #2759 · IANA Registered: application/vnd.faf+yaml · faf.one · npm