grok-faf-mcp

<!-- faf: grok-faf-mcp | TypeScript | mcp-server | First MCP server for Grok — URL-based AI context, FAST⚡️AF -->
<!-- faf: doc=readme | canonical=project.faf | score=100 | family=FAF -->

# grok-faf-mcp — FAST⚡️AF Edition

<div align="center">
  <img src="https://www.faf.one/orange-smiley.svg" alt="FAF" width="80" />

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

  [![IANA: vnd.faf+yaml](https://img.shields.io/badge/IANA-vnd.faf%2Byaml-00D4D4)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)
  [![DOI: Context paper](https://img.shields.io/badge/DOI-Context%20paper-FF6B35)](https://doi.org/10.5281/zenodo.18251362)
</div>

**Home:** [faf.one/grok](https://faf.one/grok)
**Live demo:** [grok.faf.one](https://grok.faf.one)

![grok-faf-mcp hero](https://raw.githubusercontent.com/Wolfe-Jam/grok-faf-mcp/main/assets/grok-faf-mcp-hero.png)

<div align="center">

[![npm version](https://img.shields.io/npm/v/grok-faf-mcp?color=00CCFF)](https://www.npmjs.com/package/grok-faf-mcp)
[![FAF Trophy 100%](https://img.shields.io/badge/FAF-%F0%9F%8F%86%20100%25-000000?labelColor=FF6B35)](https://faf.one)
[![CI](https://github.com/Wolfe-Jam/grok-faf-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Wolfe-Jam/grok-faf-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![project.faf](https://img.shields.io/badge/project.faf-inside-00D4D4)](https://github.com/Wolfe-Jam/faf)
[![Chat to FAFA live](https://img.shields.io/badge/Chat_to_FAFA_live-000000?style=flat&labelColor=000)](https://faf-voice.vercel.app/agent)
</div>

[![Stars](https://img.shields.io/github/stars/Wolfe-Jam/grok-faf-mcp)](https://github.com/Wolfe-Jam/grok-faf-mcp/stargazers) [![Downloads](https://img.shields.io/npm/dt/grok-faf-mcp)](https://www.npmjs.com/package/grok-faf-mcp)

**FAF defines. MD instructs. AI codes.**

---

## 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).

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

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

Sample corpus: [`xai-faf-proof/pilot`](https://github.com/Wolfe-Jam/xai-faf-proof/tree/main/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.

Happy to ship PRs, run private dogfood sessions, or jump on a call. Real software only. Just say the word.

---

## 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
# 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://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 · 14 hosted (WASM-pure) 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`).

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

### 2. Local (bunx — for FS-touching workflows)
Use the local stdio path when you need filesystem access (`faf_init`, `faf_sync`, file-mutating tools):

```bash
bunx grok-faf-mcp
```

**Or via MCP 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 |
| `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 |

*