Persistent Project Context for xAI Grok

Officialdeprecated19 toolsLive

by Wolfe-Jam · TypeScript

Persistent project context for xAI Grok. IANA-registered .faf format.

io.github.Wolfe-Jam/grok-faf-mcp — MCP Server for URL-based Grok Context

This MCP server provides persistent project context for xAI Grok using an IANA-registered .faf format. It is described as URL-based with “zero config” setup, intended to “just works” for Grok context retrieval.

🛠️ Key Features

Persistent project context for xAI Grok
URL-based AI context delivery
Zero config setup (“Just works”)
Uses IANA-registered .faf format
Written in TypeScript; distributed as an npm package (repo-style topics include typescript, npm, nodejs)

🚀 Use Cases

Supplying Grok with ongoing project context via a URL
Using .faf as a project context format (faf, project-dna, ai-context-format)
Integrating with MCP workflows (model-context-protocol, mcp, mcp-server)

⚡ Developer Benefits

Standardized context format via IANA registration (iana, vnd.faf+yaml)
Developer-oriented tooling ecosystem signals: ai-tools, developer-tools, agents-md
Tool surface indicated by toolCount: 19

⚠️ Limitations

Available context mechanism is explicitly described as URL-based
Context format scope specified as .faf (IANA-registered)

Topics

ai-contextai-toolsfafgrokllmmcpmodel-context-protocoltypescriptvercelxaiagents-mdaiai-readinessdeveloper-toolsianamcp-servernodejsnpmproject-dnaai-context-format

Captured live from the server via tools/list.

get_soul

Fetch a context soul by name. Returns structured AI context.

Parameters1

soul

string

required

Soul identifier (e.g., "spacex", "wolfe", "grok")

Raw schema

{
  "type": "object",
  "properties": {
    "soul": {
      "type": "string",
      "description": "Soul identifier (e.g., \"spacex\", \"wolfe\", \"grok\")"
    }
  },
  "required": [
    "soul"
  ]
}

list_souls

List all available context souls.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

delta_check

Determine if a topic needs FULL, DELTA, or X-DELTA soul.

Parameters1

topic

string

required

Topic to check

Raw schema

{
  "type": "object",
  "properties": {
    "topic": {
      "type": "string",
      "description": "Topic to check"
    }
  },
  "required": [
    "topic"
  ]
}

list_tags

List all unique tags used in a soul, with counts.

Parameters1

soul

string

required

Soul identifier

Raw schema

{
  "type": "object",
  "properties": {
    "soul": {
      "type": "string",
      "description": "Soul identifier"
    }
  },
  "required": [
    "soul"
  ]
}

search_by_tag

Find all entries in a soul with a specific tag.

Parameters2

soul	string	required	Soul identifier
tag	string	required	Tag to search for

Raw schema

{
  "type": "object",
  "properties": {
    "soul": {
      "type": "string",
      "description": "Soul identifier"
    },
    "tag": {
      "type": "string",
      "description": "Tag to search for"
    }
  },
  "required": [
    "soul",
    "tag"
  ]
}

search_context

Full-text search across souls. Returns matching lines only (token-efficient).

Parameters2

query	string	required	Text to search for
soul	string	optional	Specific soul (optional, searches all if omitted)

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Text to search for"
    },
    "soul": {
      "type": "string",
      "description": "Specific soul (optional, searches all if omitted)"
    }
  },
  "required": [
    "query"
  ]
}

tag_intel

Discover tag patterns, co-occurrence, candidates, and merge suggestions across all namepoints. Optionally suggest tags for a specific handle.

Parameters1

handle

string

optional

Optional: suggest tags for this specific namepoint

Raw schema

{
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "description": "Optional: suggest tags for this specific namepoint"
    }
  }
}

generate_faf_from_github

Generate a .faf file from any public GitHub repository WITHOUT cloning. Extracts 6 Ws from README, analyzes stack from languages and package.json, and generates Championship-grade AI context. Returns .faf content, quality score, and metadata.

Parameters1

repo

string

required

GitHub repository URL or owner/repo format (e.g., "facebook/react" or "https://github.com/facebook/react")

Raw schema

{
  "type": "object",
  "properties": {
    "repo": {
      "type": "string",
      "description": "GitHub repository URL or owner/repo format (e.g., \"facebook/react\" or \"https://github.com/facebook/react\")"
    }
  },
  "required": [
    "repo"
  ]
}

faf_score

Score .faf YAML content via the Mk4 Zig-WASM engine. Returns 0-100 (capped). Same engine as xai-faf-rust + xai-faf-zig (parity-tested). Sub-ms at the edge.

Parameters1

content

string

required

Raw .faf YAML content. Souls with a [faf] section have it extracted automatically.

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .faf YAML content. Souls with a [faf] section have it extracted automatically."
    }
  },
  "required": [
    "content"
  ]
}

faf_validate

Validate .faf YAML content via the Mk4 Zig-WASM engine. Returns true if mission-ready (>= 100).

Parameters1

content

string

required

Raw .faf YAML content to validate.

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .faf YAML content to validate."
    }
  },
  "required": [
    "content"
  ]
}

faf_get_tier

Resolve the FAF tier for a given numeric score. Returns the tier symbol (Trophy/Gold/Silver/Bronze/etc.) per the canonical tier-table.

Parameters1

score

number

required

Numeric score 0-100.

Raw schema

{
  "type": "object",
  "properties": {
    "score": {
      "type": "number",
      "description": "Numeric score 0-100."
    }
  },
  "required": [
    "score"
  ]
}

faf_estimate_tokens

Estimate token count for arbitrary content via the Zig WASM engine. Sub-millisecond, zero allocations. Useful for context-budget planning.

Parameters1

content

string

required

Content to estimate tokens for.

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Content to estimate tokens for."
    }
  },
  "required": [
    "content"
  ]
}

faf_analyze

One-call composite — returns score, tier-ready, valid, and engine identifier. Two WASM calls, sub-millisecond total.

Parameters1

content

string

required

Raw .faf YAML content to analyze.

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .faf YAML content to analyze."
    }
  },
  "required": [
    "content"
  ]
}

refresh_faf

Re-ground on .faf content — re-score via the Mk4 Zig-WASM Enterprise scorer (33-slot, honors the authored app-type shape), report drift vs an optional baseline score, and return a stamped re-ground. The explicit re-grounding primitive for long sessions: drift → refresh → re-grounded. Built for Grok, by request.

Parameters3

content	string	required	Raw .faf YAML content to re-ground on.
baseline	number	optional	Optional last-known score (0-100). When provided, the drift delta (current - baseline) is reported.
verbatim	boolean	optional	When true, return the full .faf content verbatim with the stamp. Default false (stamped delta + summary).

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .faf YAML content to re-ground on."
    },
    "baseline": {
      "type": "number",
      "description": "Optional last-known score (0-100). When provided, the drift delta (current - baseline) is reported."
    },
    "verbatim": {
      "type": "boolean",
      "description": "When true, return the full .faf content verbatim with the stamp. Default false (stamped delta + summary)."
    }
  },
  "required": [
    "content"
  ]
}

faf_orchestrate_recommendation

Takes raw content strings (`.faf`, `.fafm`, and optionally `package.json`/`CHANGELOG.md`/`README.md`) and runs deterministic drift + contradiction signals across the FAF substrate. Returns a structured `Recommendation` (recommend, severity, reason, summary) with `hints` containing the current `effective_policy` and `partial[]` for any stateful signals unavailable on the current surface. Light-lane execution (hosted) is WASM-pure with no filesystem access. Heavy-lane execution (local via bunx/rust-faf-mcp) has full FS + persisted state. Advisory only — never auto-fires.

Parameters5

faf	string	optional	Raw .faf YAML content (project DNA). Required for any meaningful analysis.
fafm	string	optional	Raw .fafm YAML content (memory layer). Enables drift detection.
packageJson	string	optional	Raw package.json content. Enables version cross-stamp checks (.faf vs pkg).
changelog	string	optional	Raw CHANGELOG.md content. Enables changelog cross-stamp checks.
readme	string	optional	Raw README.md content. Enables README arch-tree cross-stamp checks.

Raw schema

{
  "type": "object",
  "properties": {
    "faf": {
      "type": "string",
      "description": "Raw .faf YAML content (project DNA). Required for any meaningful analysis."
    },
    "fafm": {
      "type": "string",
      "description": "Raw .fafm YAML content (memory layer). Enables drift detection."
    },
    "packageJson": {
      "type": "string",
      "description": "Raw package.json content. Enables version cross-stamp checks (.faf vs pkg)."
    },
    "changelog": {
      "type": "string",
      "description": "Raw CHANGELOG.md content. Enables changelog cross-stamp checks."
    },
    "readme": {
      "type": "string",
      "description": "Raw README.md content. Enables README arch-tree cross-stamp checks."
    }
  }
}

faf_gate

Phase III (FRC) — pre-promotion quality gate. Scores .faf content (edge Mk4) + estimates tokens and returns a deterministic promote/hold verdict BEFORE it goes to a Grok Collection. Promote IFF score >= min_score AND tokens <= max_tokens (defaults 85/8000). Edge parity with the local gate; the hold-hint can't list empty slots at the edge.

Parameters3

content	string	required	Raw .faf YAML content to gate.
min_score	number	optional	Minimum score to promote (default 85).
max_tokens	number	optional	Maximum tokens to promote (default 8000).

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .faf YAML content to gate."
    },
    "min_score": {
      "type": "number",
      "description": "Minimum score to promote (default 85)."
    },
    "max_tokens": {
      "type": "number",
      "description": "Maximum tokens to promote (default 8000)."
    }
  },
  "required": [
    "content"
  ]
}

faf_section

Phase III (FRC) — returns an EXACT, WHOLE .faf section by dotted path (e.g. "stack", "human_context"), structure preserved — the deterministic complement to blind chunking. Omit "section" to list every path.

Parameters2

content	string	required	Raw .faf YAML content.
section	string	optional	Dotted path to retrieve (e.g. "stack.backend"). Omit to list all paths.

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .faf YAML content."
    },
    "section": {
      "type": "string",
      "description": "Dotted path to retrieve (e.g. \"stack.backend\"). Omit to list all paths."
    }
  },
  "required": [
    "content"
  ]
}

faf_memory

Phase III (FRC) — query the durable .fafm model by type/tag/priority/text. Omit filters for a structured summary. .fafm is NOT scored: this SELECTS facts (provenance preserved), never grades them.

Parameters5

content	string	required	Raw .fafm YAML content.
type	string	optional	Filter by fact type (e.g. "feedback").
tag	string	optional	Filter by a tag.
priority	string	optional	Filter by priority (e.g. "critical").
query	string	optional	Case-insensitive substring match on fact text.

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Raw .fafm YAML content."
    },
    "type": {
      "type": "string",
      "description": "Filter by fact type (e.g. \"feedback\")."
    },
    "tag": {
      "type": "string",
      "description": "Filter by a tag."
    },
    "priority": {
      "type": "string",
      "description": "Filter by priority (e.g. \"critical\")."
    },
    "query": {
      "type": "string",
      "description": "Case-insensitive substring match on fact text."
    }
  },
  "required": [
    "content"
  ]
}

faf_collections_search

Phase III (FRC §7b) — semantic search over a Grok Collection at the edge, KV-cached (1h TTL). Returns matched chunks (content, score, file). Requires the XAI_API_KEY secret; composes with faf_section (structural) for hybrid retrieval. Handled env-aware in the MCP handler (needs the key + KV).

Parameters3

query	string	required	The search query.
collection_id	string	required	The Grok Collection id to search.
limit	number	optional	Max chunks to return (default 5).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "The search query."
    },
    "collection_id": {
      "type": "string",
      "description": "The Grok Collection id to search."
    },
    "limit": {
      "type": "number",
      "description": "Max chunks to return (default 5)."
    }
  },
  "required": [
    "query",
    "collection_id"
  ]
}

README.md26 KBView on GitHub

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

Downloads

FAF defines. MD instructs. AI codes.

v2.0.0 — The Always33 Edition

One engine, one number: grok-faf-mcp 2 scores all 33 slots with faf-cli 8's always-33 kernel — the same score faf-cli, claude-faf-mcp 7 and faf-mcp 4 give, on npm and on mcpaas.live.

Always-33, everywhere you install it. Every score — faf_score, refresh_faf, faf_trust, the resources — is faf-cli 8's scoreFafYaml: all 33 slots, one Rust kernel. The hosted endpoint below scores with the same kernel.
Your 21 slots, and the 12 enterprise slots in view. faf-cli fills the 21 base slots; the 12 enterprise slots (infra, app, ops) are marked slotignored unless your app-type uses them. Scored against all 33; slotignored slots drop out of the denominator.
ZEPH is opt-in (USE_ZEPH=1, or FAF_ZEPH=1 / ZEPH=1) until the Zig engine gives the always-33 number on every file — fast never means a different score.
Scoring never uses a faf from your PATH — faf_trust and the resources run faf-cli in-process. faf_init writes a real project.faf and reports its real score.
Upgrading from 1.x: a .faf without the 12 markers now scores against 33. faf auto writes the markers and re-scores.

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

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

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

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

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:       faf-cli 8 (faf-scoring-kernel 3.0.0, always-33)
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/commands/score.ts → faf-cli scoreFafYaml (always-33)
│   ├── 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: 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):

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
`rag-system`	RAG query, caching, context retrieval
`security`	Input validation + security guards
`visibility`	Tool visibility (core/advanced filtering)

Status & known limitations (v2.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.

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.

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.

bash

npx faf-cli auto

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

Install

Tools (19)

get_soullist_soulsdelta_checklist_tagssearch_by_tagsearch_contexttag_intelgenerate_faf_from_github

Add to VS Code Add to Cursor

claude_desktop_config.json

json

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

io.github.Wolfe-Jam/grok-faf-mcp — MCP Server for URL-based Grok Context

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

get_soul

list_souls

delta_check

list_tags

search_by_tag

search_context

tag_intel

generate_faf_from_github

faf_score

faf_validate

faf_get_tier

faf_estimate_tokens

faf_analyze

refresh_faf

faf_orchestrate_recommendation

faf_gate

faf_section

faf_memory

faf_collections_search

grok-faf-mcp — FAST⚡️AF Edition

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

v2.0.0 — The Always33 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 (v2.0)

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

Install

Related servers

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