rust-faf-mcp

Persistent Project Context for Rust MCP clients. Native. Fast. cargo install

The Table-of-8 Edition (v0.7.1) — one.faf/rust-faf-mcp · rmcp 3.0.1 (MCP Tier 1 foundation) · faf-rust-sdk 3.1 (the same always-33 kernel faf-wasm-sdk uses) · solid cargo-native Rust MCP for Rust devs

v0.7.1 — Pin the install. PATH rust-faf-mcp is not the pin. See CHANGELOG.

FAF defines. MD instructs. AI codes.

Stop re-explaining your project to every AI session. One .faf file holds your persistent project context. Every AI reads it once and knows what you're building.

Rust-native MCP (Model Context Protocol) server for FAF — structured AI project context in YAML (application/vnd.faf+yaml). Single binary, stdio transport, 4.3 MB stripped. Built on rmcp and faf-rust-sdk.

Quickstart

bash

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

# No Rust (try — downloads GH Release binary for darwin/linux):
npx --yes rust-faf-mcp@0.7.1

Point an MCP client at the pin. A bare rust-faf-mcp on PATH may be an old Homebrew binary.

bash

# Claude Code
claude mcp add faf -- npx --yes rust-faf-mcp@0.7.1

jsonc

// WARP / Cursor / Zed / Claude Desktop — any stdio MCP client
{
  "mcpServers": {
    "faf": {
      "command": "npx",
      "args": ["--yes", "rust-faf-mcp@0.7.1"]
    }
  }
}

After cargo install rust-faf-mcp --version 0.7.1, "command": "rust-faf-mcp" is the install. Until you have proven that binary, use the npx pin.

No flags, no config files, no network listener. Pure stdio JSON-RPC.

Or via Homebrew (macOS, pre-built). If you already have it, upgrade — an old keg can sit on PATH as rust-faf-mcp:

bash

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

One command, done forever

faf_auto runs setup if project.faf is missing (tree detection writes mechanical facts), then syncs CLAUDE.md. It does not rewrite an existing file. Confirm setup (sweeps) lists what setup occupied — walk it; not a second write-gate. Empty human slots stay empty until you state them.

Code

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

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

Every AI agent reads this once and knows exactly what you're building. No 20-minute onboarding. No wrong assumptions.

Tools

Create & Detect

Tool	What it does
`faf_auto`	Setup if missing, sync `CLAUDE.md`, score — Confirm setup (sweeps); does not invent 6Ws
`faf_init`	Setup: first write from the tree. Refuses if the file exists. Confirm setup (sweeps). 6Ws stay empty
`faf_go`	Table-of-8 + Confirm setup (sweeps). 6Ws score after ☑. Below 100: add Human Context. After 100: courtesy check every 30 days (90 max)
`faf_git`	Generate `project.faf` from any GitHub repo URL — no clone needed
`faf_discover`	Walk up the directory tree to find the nearest `project.faf`

Score & Validate

Tool	What it does
`faf_score`	Score AI-readiness 0-100% with field-level breakdown
`faf_sync`	Sync `project.faf` → `CLAUDE.md` (preserves existing content)
`faf_agents`	Generate `AGENTS.md` from `project.faf` (non-destructive, preserves hand-written content)

Optimize

Tool	What it does
`faf_read`	Parse and display `project.faf` contents
`faf_compress`	Compress `.faf` for token-limited contexts (`minimal` / `standard` / `full`)
`faf_tokens`	Estimate token count at each compression level

faf_init will not overwrite an existing file. Setup occupies mechanical facts; Confirm setup (sweeps) is the walk. Empty human slots stay empty until faf_go.

Architecture

Code

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

Runtime: tokio single-threaded (current_thread)
HTTP: reqwest async (only used by faf_git for GitHub API)
SDK: faf-rust-sdk 3.1 (Cargo pin — the facade over faf-kernel/faf-fafb in faf-rust; score() for the real Mk4 number, validate() for structural checks only)
Server: rmcp 3.0.1 with #[tool_router] / #[tool_handler] — JSON-RPC, schema generation, stdio transport (Tier-1 assessed SDK cut)

Tools return serde_json::Value. The server adapts them to Result<String, String> for rmcp's IntoCallToolResult.

Testing

171 tests (136 integration + 35 unit):

bash

cargo test    # runs all 171

# 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

File	Tests	Coverage
`mcp_protocol.rs`	9	Init handshake, tools/list, resources, schema validation, ID preservation
`tools_functional.rs`	31	Tools — happy path, error paths, language detection, faf_go
`tier1_security.rs`	12	Path traversal, null bytes, shell injection, oversized input, malformed JSON
`tier2_engine.rs`	36	Corrupt YAML, sync replacement, pipelines, dual manifests, legacy filenames, direct paths
`tier3_edge_cases.rs`	10	Unicode, CJK, score boundaries, unknown fields, GitHub URL parsing
`tier4_aero.rs`	22	Manifest structure, version sync, server.json, context block, manifest-server cross-validation
`wjttc_setup.rs`	16	Setup / Confirm setup (sweeps) — BRAKE · ENGINE · AERO · TYRE · PIT
`src` unit	35	setup sweep, skills digest, `agents::`, `inject::`, intent, app-type

Tests spawn the compiled binary as a subprocess and communicate via stdin/stdout JSON-RPC — true integration tests against the real server.

FAF Ecosystem

One format, every AI platform.

Package	Platform	Registry
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	Universal	npm

Build from source

bash

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

Edition: 2024 | LTO: enabled | Strip: symbols

If rust-faf-mcp has been useful, consider starring the repo — it helps others find it.

Citation

If you use rust-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

License

MIT

Built by @wolfe_jam | wolfejam.dev

Rust FAF README

rust-faf-mcp

Quickstart

One command, done forever

Tools

Create & Detect

Score & Validate

Optimize

Architecture

Testing

FAF Ecosystem

Build from source

Links

Citation

License