Rust FAF

rust-faf-mcp

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

⭐ Star it on GitHub: bookmarks it for you, helps other devs find it too.

The Your-Files-Stay-Yours Edition (v0.9.0) — one.faf/rust-faf-mcp · rmcp 3.0.1 (MCP Tier 1 foundation) · faf-rust-sdk 3.1.1 (the same always-33 kernel faf-wasm-sdk uses) · solid cargo-native Rust MCP for Rust devs

v0.9.0 — faf_sync keeps your hand-written CLAUDE.md, refuses what it can't write safely, and says so. See CHANGELOG.

FAF defines. AGENTS.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

# Rust toolchain (install):

cargo install rust-faf-mcp --version 0.9.0

No Rust (try — downloads GH Release binary for darwin/linux):

npx --yes rust-faf-mcp@0.9.0

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

# Claude Code

claude mcp add faf -- npx --yes rust-faf-mcp@0.9.0

// Cursor, Claude Desktop, Windsurf — any client that reads mcpServers

{ "mcpServers": { "faf": { "command": "npx", "args": ["--yes", "rust-faf-mcp@0.9.0"] } } }

After cargo install rust-faf-mcp --version 0.9.0, "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:

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.

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:

# 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

Score & Validate

Optimize

Lineage

Every tool declares MCP annotations: faf_read, faf_score, faf_compress, faf_discover, faf_tokens, faf_dna and faf_git are read-only; the writers are non-destructive; only faf_git reaches the network.

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

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 always-33 number, validate() for structural checks only)
• Server: `rmcp` 3.0.1 with #[tool_router] / #[tool_handler] — JSON-RPC, JSON Schema from the param types, stdio transport (Tier-1 assessed SDK cut)

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

Testing

223 tests (152 integration + 71 unit):

cargo test    # runs all 223

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

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.

Build from source

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)

Edition: 2024 | LTO: enabled | Strip: symbols

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

Links

• crates.io/crates/rust-faf-mcp
• npmjs.com/package/rust-faf-mcp — npx --yes rust-faf-mcp@0.9.0 (no Rust toolchain; downloads GH Release binary)

• Dual-package publish guide — cargo + npm (this server is the product example)
• docs/DUAL-PACKAGE.md — pointer + OIDC docs for this repo
• docs/SKILLS-OVER-MCP.md — J1 Agent Skill faf-context (skills/list · digests)
• faf-rust-sdk — the parser this depends on
• faf.one — FAF home
• IANA registration — application/vnd.faf+yaml
• MCP Registry name: mcp-name: one.faf/rust-faf-mcp
• CHANGELOG

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