grok-faf-mcp

grok-faf-mcp is the FAF ecosystem's MCP (Model Context Protocol) server implementation for xAI Grok. It exposes .faf project context files to AI clients via HTTP-SSE transport, addressing the lack of persistent project memory across AI coding assistant sessions.

Core Capabilities#

• AI Readiness Scoring: Powered by the Mk4 WASM engine (faf-scoring-kernel), scoring .faf files from 0-100% across seven tiers: Trophy/Gold/Silver/Bronze/Green/Yellow/Red. The scoring pipeline: TypeScript parsing → project type detection → "The Bouncer" injecting slotignored → WASM scoring → Mk3.1 fallback.
• Auto-Detection & Population: faf_auto automatically detects the project tech stack and populates .faf context with a single command.
• RAG Context Retrieval: Built-in rag_query, rag_cache_stats, rag_cache_clear tools with @upstash/redis as the caching backend.
• Bidirectional Sync: faf_bi_sync enables two-way synchronization between .faf and platform context files (e.g., CLAUDE.md).
• High Performance: Average execution time of 0.5ms (up from 19ms in v1.1, a 3,800% improvement), fastest tool response at 3,360ns (self-reported).

Tool System#

The base mode provides 21 core MCP tools. Setting FAF_SHOW_ADVANCED=true unlocks an additional 34 advanced tools, totaling 55. Core tools span creation & detection (faf_init, faf_auto, faf_score, faf_status, faf_enhance), sync & persistence (faf_sync, faf_bi_sync, faf_trust), read/write (faf_read, faf_write, faf_list), and RAG/Grok-specific (rag_query, rag_cache_stats, rag_cache_clear, grok_go_fast_af).

Deployment Options#

• Hosted endpoint (zero-install): Point MCP clients to https://grok-faf-mcp.vercel.app/sse
• Local npx: npx grok-faf-mcp, or add the corresponding entry in MCP config
• Self-deploy on Vercel: One-click deploy using the "Deploy with Vercel" button in the repo
• Project initialization: npx faf-cli auto

Architecture Overview#

Built with TypeScript (87.3%), requiring Node.js ≥ 20. The entry point api/index.ts is a Vercel serverless function (Express + SSE transport), with the core MCP server defined in src/server.ts. Key dependencies: @modelcontextprotocol/sdk ^1.27.1, express ^4.21.0, faf-scoring-kernel ^2.0.3 (WASM), faf-cli ≥3.1.1, yaml ^2.4.1, @upstash/redis ^1.37.0. Current version 1.2.1 with 179 test cases across 7 suites, released under the MIT license.

FAF Ecosystem#

A single project.faf file can be read by multiple FAF ecosystem implementations: claude-faf-mcp (Claude), gemini-faf-mcp (Gemini), rust-faf-mcp (Rust), faf-mcp (universal for Cursor/Windsurf/Cline), and faf-cli (terminal CLI), achieving cross-platform project context consistency.

Unconfirmed Items#

• .faf claims IANA MIME type registration application/vnd.faf+yaml but no registration link provided
• README references "Anthropic MCP #2759" without a specific link
• Performance figures are self-reported; no independent third-party benchmarks found
• No xAI official endorsement or partnership statement found
• Names and functions of the 34 advanced tools require source code inspection
• Scope of rag_query (.faf content only vs. extended to project source code) is unclear