rust-faf-mcp

rust-faf-mcp

为 Rust MCP 客户端提供持久化项目上下文。原生、高速。通过 cargo install 安装

传承版（v0.8.3） — one.faf/rust-faf-mcp · rmcp 3.0.1（MCP Tier 1 基础）· faf-rust-sdk 3.1.1（与 faf-wasm-sdk 使用的始终为 33 的内核相同）· 为 Rust 开发者打造的可靠 cargo 原生 Rust MCP

v0.8.3 — --version 和 --help 会直接响应，而不是启动服务。请参阅 更新日志。

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

不必再向每个 AI 会话重复解释你的项目。一个 .faf 文件即可保存持久化项目上下文。每个 AI 只需读取一次，就能了解你正在构建什么。

面向 FAF 的 Rust 原生 MCP（Model Context Protocol）服务 — 以 YAML 格式提供结构化 AI 项目上下文（application/vnd.faf+yaml）。单一二进制文件，使用 stdio 传输，剥离后为 4.3 MB。基于 rmcp 和 faf-rust-sdk 构建。

快速开始

# Rust toolchain (install):
cargo install rust-faf-mcp --version 0.8.3

# No Rust (try — downloads GH Release binary for darwin/linux):
npx --yes [email protected]

让 MCP 客户端指向这个固定版本。PATH 中未固定版本的 rust-faf-mcp 可能是旧版 Homebrew 二进制文件。

# Claude Code
claude mcp add faf -- npx --yes [email protected]

// Cursor, Claude Desktop, Windsurf — any client that reads mcpServers
{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["--yes", "[email protected]"]
    }
  }
}

运行 cargo install rust-faf-mcp --version 0.8.3 后，"command": "rust-faf-mcp" 就会指向安装的版本。在确认该二进制文件可用之前，请使用 npx 固定版本。

无需标志、配置文件或网络监听器。纯 stdio JSON-RPC。

也可以通过 Homebrew 安装（macOS，预编译）。如果已经安装，请升级 — 旧版 keg 可能仍会以 rust-faf-mcp 的名称出现在 PATH 中：

brew update
brew install Wolfe-Jam/faf/rust-faf-mcp
# already installed:
brew upgrade Wolfe-Jam/faf/rust-faf-mcp

一条命令，永久就绪

如果缺少 project.faf，faf_auto 会运行设置（通过树结构检测写入机械事实），然后同步 CLAUDE.md。它不会重写已有文件。**确认设置（扫描）**会列出设置时占用的内容 — 请逐项检查；这不是第二道写入关卡。人工填写的空字段会保持空白，直到你提供相应信息。

faf_auto complete
━━━━━━━━━━━━━━━━━
Score: 0% → 42% (+42) ● GREEN
Steps:
  1. Setup — created project.faf
  2. Created CLAUDE.md

Path: /home/user/my-project

Confirm setup (sweeps)
Walk these. Detection is already a fact. Not a second write-gate.
  project.name           my-api
  project.main_language  Rust
  stack.backend          Rust

生成内容：

# project.faf — your project, machine-readable
faf_version: "3.3"
project:
  name: my-api
  goal: REST API for user management
  main_language: Rust
  version: "0.1.0"
  license: MIT
instant_context:
  what_building: REST API for user management
  tech_stack: Rust 2024
  key_files:
    - Cargo.toml
    - src/main.rs
    - README.md
  commands:
    build: cargo build
    test: cargo test
stack:
  backend: Rust
  build: cargo

每个 AI Agent 只需读取一次，就能准确了解你正在构建什么。无需 20 分钟的引导，也不会产生错误假设。

工具

创建与检测

工具	功能
faf_auto	缺少文件时运行设置，同步 CLAUDE.md 并评分 — 确认设置（扫描）；不会编造 6Ws
faf_init	设置：根据目录树首次写入。文件已存在时拒绝操作。确认设置（扫描）。6Ws 保持空白
faf_go	Table-of-8 + 确认设置（扫描）。勾选 ☑ 后对 6Ws 评分。低于 100：补充人工上下文。达到 100 后：每 30 天进行一次礼貌检查（最多 90 次）
faf_git	根据任意 GitHub 仓库 URL 编写 project.faf — 无需克隆。使用公开 GitHub API；返回文本，不写入任何内容
faf_discover	沿目录树向上查找最近的 project.faf

评分与验证

工具	功能
faf_score	对 AI 就绪度进行 0–100% 评分，并提供字段级细分
faf_sync	将 project.faf 同步到 CLAUDE.md（保留现有内容）
faf_agents	根据 project.faf 编写 AGENTS.md（非破坏性操作，保留手写内容）

优化

工具	功能
faf_read	解析并显示 project.faf 内容
faf_compress	压缩 .faf，以适应令牌受限的上下文（minimal / standard / full）
faf_tokens	估算各压缩级别的令牌数量

血统

工具	功能
faf_dna	根据 .faf-dna 展示你的 FAF DNA 旅程：从诞生 DNA 到现在，并包含历史记录。faf_init 负责创建，faf_auto 记录成长——与 faf-cli 使用同一个文件

每个工具都会声明 MCP 注释：faf_read、faf_score、faf_compress、faf_discover、faf_tokens、faf_dna 和 faf_git 均为只读；写入工具不会造成破坏；只有 faf_git 会访问网络。

faf_init 不会覆盖现有文件。Setup 用于记录机械事实；Confirm setup（sweeps）则是实际操作。人类填写的空字段会一直留空，直到运行 faf_go。

架构

src/
├── main.rs      # ~20 lines — tokio entry, rmcp stdio transport
├── server.rs    # FafServer: #[tool_router], ServerHandler, resources
└── tools.rs     # Business logic — tools as pure functions returning Value

• 运行时：tokio 单线程（current_thread）
• HTTP：异步 reqwest（仅供 faf_git 调用 GitHub API）
• SDK：faf-rust-sdk 3.1（Cargo 固定版本——faf-rust 中 faf-kernel/faf-fafb 的外观层；score() 用于始终为 33 的分数，validate() 仅用于结构检查）
• 服务：rmcp 3.0.1，使用 #[tool_router] / #[tool_handler]——JSON-RPC、根据参数类型生成 JSON Schema、stdio 传输（经 Tier-1 评估的 SDK 版本）

工具返回 serde_json::Value。服务会将其适配为 Result<String, String>，以供 rmcp 的 IntoCallToolResult 使用。

测试

193 项测试（146 项集成测试 + 47 项单元测试）：

cargo test    # runs all 193

# Full ship bar (same gates as GitHub CI — run before push)
bash scripts/ci.sh
# Optional: block push on red CI twin
bash scripts/install-hooks.sh

文件	测试数	覆盖范围
mcp_protocol.rs	10	初始化握手、tools/list、工具注释、资源、架构验证、ID 保留
tools_functional.rs	31	工具——正常路径、错误路径、语言检测、faf_go
tier1_security.rs	12	路径遍历、空字节、命令注入、超大输入、格式错误的 JSON
tier2_engine.rs	36	损坏的 YAML、同步替换、流水线、双清单、旧版文件名、直接路径
tier3_edge_cases.rs	10	Unicode、CJK、分数边界、未知字段、GitHub URL 解析
tier4_aero.rs	22	清单结构、版本同步、server.json、上下文块、清单与服务交叉验证
wjttc_setup.rs	16	Setup / Confirm setup（sweeps）——BRAKE · ENGINE · AERO · TYRE · PIT
wjttc_faf_dna.rs	7	.faf-dna 血统——faf_init 诞生、faf_auto 成长、faf_dna、faf-cli 的对应行
src 单元测试	47	setup sweep、技能摘要、agents::、inject::、意图、应用类型、dna:: 血统 + faf-cli 测试夹具

测试会将编译后的二进制作为子进程启动，并通过 stdin/stdout JSON-RPC 通信——这是针对真实服务的集成测试。

FAF 生态系统

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

软件包	平台	注册表
rust-faf-mcp	Rust	crates.io
claude-faf-mcp	Anthropic	npm + MCP #2759
gemini-faf-mcp	Google	PyPI
grok-faf-mcp	xAI	npm
faf-cli	通用	npm

从源代码构建

git clone https://github.com/Wolfe-Jam/rust-faf-mcp
cd rust-faf-mcp
cargo build --release
# Binary at target/release/rust-faf-mcp (about 5 MB)

版本：2024 | LTO：已启用 | 剥离：符号

如果 rust-faf-mcp 对你有所帮助，不妨为仓库点个星——这能让更多人发现它。

链接

• crates.io/crates/rust-faf-mcp

• npmjs.com/package/rust-faf-mcp — npx --yes [email protected]（无需 Rust 工具链；会下载 GH Release 二进制文件）

• 双包发布指南 — cargo + npm（此服务是产品示例）

• docs/DUAL-PACKAGE.md — 本仓库的指引 + OIDC 文档

• docs/SKILLS-OVER-MCP.md — J1 Agent Skill faf-context（skills/list · 摘要）

• faf-rust-sdk — 此项目依赖的解析器

• faf.one — FAF 主页

• IANA 注册 — application/vnd.faf+yaml

• MCP Registry 名称：mcp-name: one.faf/rust-faf-mcp

• 更新日志

引用

如果你在研究或生产环境中使用 rust-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

许可证

MIT

---

由 @wolfe_jam 构建 | wolfejam.dev