Grok FAF

grok-faf-mcp v2.1 — 新时代版

主页： faf.one/grok 在线演示： grok.faf.one

FAF 负责定义。AGENTS.md 负责指示。AI 负责编码。

v2.2.0 — 指令版

grok-faf-mcp 现在会告诉 Grok 各工具如何协同工作，以及上下文和记忆如何配合：在 initialize 中提供服务端指令（615 个字符），并内置 faf-cli 8.5.0，它能识别技能仓库。

• 服务端指令。 Grok 连接时，服务端会说明各工具如何协同工作：上下文（project.faf）和记忆（.fafm）、哪个工具负责检查、创建或同步，以及刷新工具；还会说明 rag_query 需要 xAI Collection。
• 内置 faf-cli 8.5.0。 faf_init 会检测技能仓库：含有 SKILL.md 的文件夹会将其识别为 skills（10 个槽位），Claude Code 插件清单则会将其识别为 skills-plugin（14 个槽位）。
• MCP SDK、proxy-addr 和 hono 中的安全公告已清除。

更早版本：v2.1.0 — 新时代版 — 玻璃盒工具：每个工具都会说明自己是读取、写入还是重写；在 grok.faf.one 上拥有专属 FAF 护照；焕然一新的外观。

更早版本：v2.0.0 — Always33 版 — 一个引擎，一个数字：每个分数都是 faf-cli 8 的 always-33 内核，在 npm 和 mcpaas.live 上均可使用。ZEPH 为可选项，直到 Zig 引擎实现 always-33。

☆ 将 grok.faf.one 加入书签，以便日后访问。

FAF Context Ingestion Contract 的首个符合 v0.2 规范的读取器——这是与 @grok 公开共同编写的开源标准。

---

安装 — 一行命令

添加到 ~/.grok/config.toml：

[mcp_servers.grok-faf-mcp]
url = "https://mcpaas.live/grok/mcp/v1"

重启 Grok TUI（或运行 /mcps r）以刷新。托管端点的评分始终为 33，与 npm 包相同。工具包括：faf_score、faf_validate、faf_get_tier、faf_estimate_tokens、faf_analyze（以及 soul/memory 操作）。

Smithery： wolfe-jam/grok-faf-mcp — 网关地址：https://grok-faf-mcp--wolfe-jam.run.tools

Homebrew（本地 stdio）：

brew install wolfe-jam/faf/grok-faf-mcp

托管在 Cloudflare Workers 上 — 冷启动时间低于 1 毫秒，无子进程，由边缘节点提供服务。自 mcpaas-cf 1.8.1 起，使用 faf-kernel WASM 评分和验证（始终为 33，与 npm 包使用相同的引擎）；使用 Zig WASM 引擎估算 Token 数量和层级。已于 2026-05-27 通过 Grok S1 + S2 外部验证。

验证实时契约：

curl https://mcpaas.live/grok/mcp/v1/info

返回端点、协议版本、引擎详情、工具列表，以及架构行：.faf=vROM | AI-in-session=RAM。

示例语料库：xai-faf-proof/pilot — 10 条可供评分的记录。

---

六个 W — 快速参考

每份 README 都应该回答这些问题。以下是我们的答案：

问题	答案
WHO 面向谁？	使用基于 URL 的 MCP 构建项目的 Grok/xAI 开发者和团队
WHAT 是什么？	为 xAI Grok 提供持久的项目上下文 — URL 优先部署、由 IANA 注册的 .faf 格式
WHERE 在哪里可用？	Cloudflare Workers（mcpaas.live/grok/mcp/v1） • 支持原生 url= 配置的任意 MCP 客户端 • 部署到你自己的 CF/Vercel Worker
WHY 为什么需要它？	URL 上零配置 MCP — Grok 提出了需求，我们率先构建
WHEN 何时使用？	Grok 集成、xAI 项目，以及任何基于 URL 的 MCP 客户端
HOW 如何工作？	url = "https://mcpaas.live/grok/mcp/v1" — 通过 MCPaaS 从边缘节点提供上下文工具（冷启动时间低于 1 毫秒，无子进程）

面向 AI： 阅读下方详细章节，了解完整背景。 面向开发者： 在你自己的 README 中使用此模式。清晰回答这 6 个问题。

致 xAI / Grok Build 团队

专为 Grok 构建，并根据 Grok 的直接反馈打磨。
欢迎原生集成到 Grok Build、.fafm 记忆层、refresh_faf 原语，或团队需要的任何其他上下文功能。
已在 https://grok.faf.one 和 https://mcpaas.live/grok/mcp/v1 上线并用于实际场景。

Grok Agent 上下文： faf-cli 根据真实项目检测结果生成 Grok Agent 读取的内容 — bunx faf export --agents。faf-cli 的 src/interop/grok.ts 会将此 MCP 接入 .grok/config.toml（该文件位于 faf-cli 仓库中，不在此处）。参见 面向 Grok 和 xAI Agent 的 FAF-CLI。

---

问题

每次 Grok 会话都从零开始。你得一次又一次地解释自己的技术栈、目标和架构。

.faf 可以解决这个问题。一个文件，记录项目 DNA，并在每次会话中持续保留。

Without .faf  →  "I'm building a REST API in Rust with Axum and PostgreSQL..."
With .faf     →  Grok already knows. Every session. Forever.

---

一条命令，永久搞定

faf_auto 会检测你的项目、创建 .faf 并评分，一步完成：

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

生成内容：

# 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

每个 AI Agent 只需读取一次，就能准确了解你在构建什么。

---

⚡ 你将获得

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

URL 上的 MCP。 将你的 Grok 集成指向该 URL 即可。

---

评分：从盲目到优化

层级	分数	含义
🏆 TROPHY	100%	Gold Code — AI 已优化
★ GOLD	99%+	上下文近乎完美
◆ SILVER	95%+	表现出色
◇ BRONZE	85%+	扎实的基线
● GREEN	70%+	坚实的基础
● YELLOW	55%+	AI 靠抛硬币猜测
○ RED	<55%	AI 在盲目工作
♡ WHITE	0%	从这里开始 — 祝你好运

55% 时，Grok 有一半时间靠猜测。100% 时，Grok 了解你的项目。

---

两种部署方式

1. 托管（零安装 — 推荐）

将 MCP 客户端指向生产 URL — 由 Cloudflare Workers 在边缘提供服务，无需子进程，冷启动时间不到 1 毫秒。此路径仅提供 WASM 纯工具（评分、验证、refresh_faf）。

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

2. 本地（stdio — 适用于需要访问文件系统的工作流）

需要访问文件系统时（faf_init、faf_sync、会修改文件的工具），请使用本地 stdio 路径：

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

或者通过 MCP 配置：

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

---

MCP 工具

创建与检测

工具	用途
faf_init	根据你的项目创建 project.faf
faf_auto	自动检测技术栈并填充上下文
faf_score	AI 就绪度评分（0-100%）及详细分解
faf_status	检查当前 AI 可读性
refresh_faf	根据实时 .faf 重新建立上下文 — 重新读取并评分、报告偏差、返回最新 DNA（偏差 → 刷新 → 重新建立上下文）。由 Grok 提出请求。

偏差与编排（1.5 — 重磅版本）

工具	用途
refresh_fafm	根据一个或多个 soul 的实时 .fafm 记忆层重新建立上下文。默认返回带时间戳的增量（新增／更新的事实）；设置 verbatim: true 可返回完整内容。只读 · 始终带时间戳。它是 vROM/RAM 模型中 RAM／记忆层对应 refresh_faf 的姊妹工具。应 Grok 请求打造。
refresh_blend	内置的双强度刷新（类似 Cmd+R / Cmd+Shift+R）。mode: "blend"（默认）会触发 refresh_faf（轻量）和 refresh_fafm（增量）；mode: "nuke" 会以高强度触发两者。Blend 是内置功能，不是调节旋钮 — 两层始终都会触发；模式只影响 fafm 的强度。
faf_orchestrate_recommendation	重型编排器。读取当前基底状态，组合完整的 1.5 库基底（偏差检测 · CheckID · 重复违规者 · 举一反三 · 刷新历史），返回结构化的 Recommendation，包含 recommend、severity、summary、reason，以及丰富的 hints 对象，其中包括 effective_policy（当前生效的层级）。仅提供建议 — 绝不会自动触发（从属而非守护进程）。每次调用都会写入建议回执（不会做出无声决策）。规范来源：Grok-1 FAF-DRIFT-DETECTION-SPEC §9.5 + Appendix C。
faf_get_orchestration_policy	纯粹检查有效策略，不会运行编排器。返回 { tier, thresholds, source, overrides_applied } — 显示下一次编排调用将采用的激进程度层级，以及它来自默认设置还是 .faf:orchestration: 覆盖项。不进行偏差检测 · 不发出信号 · 不写入回执 — 1.5 基底中最安静的工具。适用于调试意外的编排器行为、批量操作前的预检，以及验证覆盖项是否生效。

同步与持久化

工具	用途
faf_sync	将 .faf 同步到 CLAUDE.md
faf_bi_sync	在 .faf 与平台上下文之间双向同步
faf_trust	验证 .faf 完整性

读取与写入

工具	用途
faf_read	读取任意文件
faf_write	写入任意文件
faf_list	查找包含 .faf 文件的项目

RAG 与 Grok 专属

工具	用途
rag_query	由 RAG 驱动的上下文检索
rag_cache_stats	RAG 缓存统计信息
rag_cache_clear	清除 RAG 缓存
grok_go_fast_af	为 Grok 自动加载 .faf 上下文

此外，设置 FAF_SHOW_ADVANCED=true 后，还可使用 34 个高级工具。

---

性能

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)

在本地 stdio 执行环境中，每个工具预热后测试 10 次。托管边缘环境的冷启动时间额外增加不到 1 毫秒。

**Orchestrator（faf_orchestrate_recommendation）特性：**组合调用 — 最多读取 6 个文件（.faf、.fafm、package.json、CHANGELOG.md、README.md，以及全部 3 个回执日志），运行 2 个分析器（detectFafmDrift + checkId），评估决策表，并写入 1 条回执。预期延迟：缓存命中时为几十毫秒；冷磁盘或 .fafm 语料非常大时会更高。专为 Agent 偶尔发起的调用而设计，不适用于每轮轮询。 detectFafmDrift 的复杂度为 O(n²)，与事实数量相关（跨事实 n 元语法重复检测）——处理数百条事实时仍然游刃有余。

---

架构

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

**生产部署：**通过 mcpaas-cf 部署到 Cloudflare Workers（服务于 mcpaas.live/grok/mcp/v1）。上文的 api/index.ts + vercel.json 路径仍作为旧版／已收藏链接的接收站运行——它们已不再用于生产。

**评分流水线：**faf-cli 的 scoreFafYaml → 始终采用 33 个槽位的内核（faf-scoring-kernel，Rust → WASM），按文件原样评分：33 个槽位，slotignored 槽位不计入分母。不按类型重写，没有备用评分器——faf-cli、claude-faf-mcp 和 faf-mcp 给出的数字一致。

---

测试

WJTTC 一致性（本地重测 ↔ 托管轻测）+ 全套测试（CI 全部通过）：

sh scripts/run-tests.sh

套件	覆盖范围
desktop-native-validation	核心原生函数、安全性、性能
mcp-conformance	MCP 协议一致性 — 工具、传输、错误
wjttc-mcp	WJTTC MCP 认证
wjttc-bun	WJTTC bun 迁移 + 完整性
rag-system	RAG 查询、缓存、上下文检索
security	输入校验 + 安全防护
visibility	工具可见性（核心／高级筛选）

---

状态与已知限制（v2.2）

v2.2.0 — Instructions 版 — 在 initialize 中加入服务器指令（615 个字符），并采用可检测技能仓库的 faf-cli 8.5.0。评分与 v2.0.0 保持不变。

v2.1.0 — 新时代版 — 玻璃盒工具（每个工具都标记为读取、写入或重写），拥有自己的 FAF 护照 grok.faf.one，以及全新外观。评分与 v2.0.0 保持不变。

v2.0.0 — Always33 版 — 一个引擎，一个数字：faf-cli 8 在 npm 和 mcpaas.live 上采用始终为 33 的内核。ZEPH 为可选功能，直到 Zig 引擎也采用始终为 33 的评分方式。FafCompiler 已升级为 Always33 fafb 模型——在前沿模型间保持一致，并支持 Enterprise／Teams。

以下内容仍然适用；如实说明其运行情况，就意味着既要呈现这里已有的内容，也要指出这里没有的内容。

早期版本：v1.10.0 — 去繁就简版 — project.faf 中不再有冗余内容。faf_enhance 已移除。RAG 默认模型为 grok-4.6。填充功能仍由 faf_auto / faf_go 提供。

早期版本：v1.9.0 — ZEPH 默认版 — refresh_faf 背后经过验证且快速的 Zig→WASM 评分路径现已默认启用（分数相同，计算成本更低；已证明逐字节一致——CI 门禁 + 91/91 实测）。使用熔断开关 USE_ZEPH=0 可强制使用规范评分器。FRC 工具仍需通过 USE_FRC 显式启用。

早期版本：v1.8.0 — 闭环版 — 可观测性写入、令牌计算真实准确、FRC 合约已锁定。现在终于可以测量漂移→刷新→重新落地的循环。 早期版本：v1.7.0 — 落地记忆版 — 在 Grok Collections 上加入 ZEPH + FRC 层（faf_gate/faf_section/faf_memory），通过 USE_FRC/USE_ZEPH 选择启用；12 个核心工具保持不变。 早期版本：v1.6.0 — ZEPH 版 — 用于重新落地的 ZEPH 快速路径（通过 Zig→WASM cascade.wasm 实现 refresh_faf/refresh_blend，约 12µs，使用 USE_ZEPH=1；faf-cli 仍为规范实现，CI 中的一致性已锁定）。 已全面支持的功能：

• 托管端点（https://mcpaas.live/grok/mcp/v1 和客户端专属路由）上的 19 个工具——评分 · 验证 · refresh_faf · 支持传入内容的 faf_orchestrate_recommendation · FRC 三件套 · souls 和搜索。实时列表见 …/grok/mcp/v1/info。
• refresh_faf 和 refresh_fafm 是显式、可调用的重新校准原语。
• refresh_blend 是内置的两档刷新（类似 Cmd+R / Cmd+Shift+R）。
• faf_orchestrate_recommendation——强大的编排器，将漂移信号、重复发生情况、回执和提示建议组合为一项建议。
• faf_get_orchestration_policy——纯粹查看生效策略，不运行编排器（不检测漂移、不写入回执——这是底层系统中最安静的工具）。
• 完整策略可见性（effective_policy）会在每次编排调用中返回，也可通过 faf_get_orchestration_policy 单独查看。

当前限制：

• faf_get_orchestration_policy、refresh_fafm、refresh_blend、faf_init 和 faf_sync 需要文件系统访问权限，且仅在本地 stdio 路径（bunx grok-faf-mcp / npx grok-faf-mcp）运行。托管版 faf_orchestrate_recommendation 接收文件内容，而非读取你的仓库；它没有回执或重复发生历史（相关信息会列在 partial[] 下）。
• 回执存储——相对于 cwd 的 JSON，可供拉取发现。 仓库根目录中有三个仅追加的 JSON 文件，采用稳定的架构：

  .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
  

  外部工具可通过拉取发现（TAF、自定义索引器、可观测性仪表板）——按你自己的计划读取，无需回调／推送 API。将其迁移到专用孤立分支（仿照 TAF 模式）的方案已有文档说明，但根据发布规范暂缓；相对于 cwd 的 JSON 是 v1 的引导方案。
• 回执日志没有多进程文件锁。 在单个进程内，JS 事件循环会对写入进行串行处理。多个 Agent 并发写入可能发生竞争；后续任务。
• 激进程度分级钩子——.faf:orchestration:tier 读取 'conservative'（默认——最安静，避免初次印象嘈杂） · 'balanced' · 'aggressive'。active_tier 始终会在 hints.effective_policy 中显示，以便观察，也可通过 faf_get_orchestration_policy 单独查看。v1.5 不包含策略写入器（faf_set_orchestration_policy）和调度功能（faf_schedule_heavy_re_ground）——可直接编辑 .faf:orchestration:tier: 进行覆盖。
• 推荐回执目前尚无确认机制。 默认值为 acknowledged: false，且不会自动切换。提示建议的阶梯重置语义仅在显式确认后触发——这是有意采取的保守设计。后续任务：添加显式 ack 工具，或根据后续刷新回执的时间推导确认状态。
• 结果追踪（“这条建议实际上有帮助吗？”）——需要超出 1.5 范围的学习层。

**有意采取这种明确区分：**托管版 = 快速、可审计、纯 WASM；本地版 = 完整功能，包括文件系统访问。我们只会在安全且不损害模型的前提下扩展托管版功能。

始终从属于用户，而非自主运行。 编排器绝不会自动调用建议的工具。Agent 会展示建议；由用户（或更高层级的 Agent）决定是否采取行动。即使 severity: 'block' 也仅供参考。

请参阅公开验证器和 curl https://mcpaas.live/grok/mcp/v1/info，了解当前契约。

---

生态系统

一种格式，适用于每个 AI 平台。

软件包	平台	注册表
grok-faf-mcp（本项目）	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、VS Code	npm
faf-cli	终端 CLI	bunx、npm + Homebrew

相同的 project.faf。相同的评分。相同的结果。不同的执行层。

---

语音变体 — grok-faf-voice（VML）

.fafm 🐘🎙️ — .faf 🐘 家族的语音变体。

grok-faf-voice 是 语音记忆层（VML） 的参考实现，决定语音 Agent 会在会话、设备和模型切换之间记住什么。它是 grok-faf-mcp 的配套项目：

• grok-faf-mcp（本项目）— 通过 MCP-on-a-URL 为 Grok 提供 .faf 基础上下文层。
• grok-faf-voice — 通过 LiveKit + xAI realtime 为 Grok Voice 提供 .fafm 语音记忆层（VML）。

同一家族。不同的接口。语音可替换；记忆永久保留。

PyPI · GitHub · 入门指南

---

致 xAI / Grok Build 团队

这个 MCP 服务是专为 Grok 打造的，并持续根据 Grok 本身的直接反馈进行完善。

欢迎开展更深入的合作，包括：

• 原生 Grok Build 集成
• .fafm 记忆层
• 在 Grok TUI / CLI 中加入 refresh_faf 原语
• 团队需要的任何其他上下文或编排功能

我快速交付、严格测试，并在 https://grok.faf.one 和 https://mcpaas.live/grok/mcp/v1 上实时试用所有功能。

我很乐意：

• 提交 PR
• 开展私下试用会
• 参加电话会议
• 或者直接交付任何能带来实际成效的功能

只做真正的软件。有需要尽管说。

---

贡献

PR 规范、代码风格、CI 准则、MCP 工具贡献流程、 npm 发布规范、架构决策：CONTRIBUTING.md。

欢迎 xAI / Grok 开发者——顶部有精简版入门说明。

---

致 xAI / Grok Build 团队

欢迎就更深入的原生集成、.fafm 记忆层或 Grok Build CLI 开展合作。
我很乐意提交 PR、试用功能或参加电话会议。尽管开口。

---

引用

如果你在研究或生产中使用 grok-faf-mcp 或 .faf / .fafa 格式，请引用格式论文：

Wolfe, J. (2025). 格式驱动的 AI 上下文架构：用于持久项目理解的 .faf 标准. Zenodo. https://doi.org/10.5281/zenodo.18251362

Wolfe, J. (2026). 为什么 Agent 需要护照：.fafa——Agent 时代的可移植身份. Zenodo. https://doi.org/10.5281/zenodo.21951641

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

许可证

MIT — 免费且开源

---

---

获取 CLI

faf-cli — 最初的 AI 上下文 CLI。每位构建者的必备工具。

npx faf-cli auto

Anthropic MCP #2759 · IANA 已注册： application/vnd.faf+yaml · faf.one · npm · 与我的 Agent 对话 →