# rust-faf-mcp **Persistent Project Context for Rust MCP clients. Native. Fast. cargo install** **The Lineage Edition (v0.8.0)** — `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.8.0** — `.faf-dna` lineage, the same file as faf-cli and fafb: `faf_init` births it, `faf_auto` grows it, `faf_dna` shows the journey. fafb scores all 33 slots for monorepos and teams. See [CHANGELOG](./CHANGELOG.md#080---2026-09-13--the-lineage-edition). **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. [](https://crates.io/crates/rust-faf-mcp) [](https://faf.one) [](https://github.com/Wolfe-Jam/rust-faf-mcp) [](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) [](LICENSE) Rust-native [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for [FAF](https://faf.one) — structured AI project context in YAML (`application/vnd.faf+yaml`). Single binary, stdio transport, 4.3 MB stripped. Built on [`rmcp`](https://crates.io/crates/rmcp) and [`faf-rust-sdk`](https://crates.io/crates/faf-rust-sdk). ## Quickstart ```bash # Rust toolchain (install): cargo install rust-faf-mcp --version 0.8.0 # No Rust (try — downloads GH Release binary for darwin/linux): npx --yes rust-faf-mcp@0.8.0 ``` 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.8.0 ``` ```jsonc // WARP / Cursor / Zed / Claude Desktop — any stdio MCP client { "mcpServers": { "faf": { "command": "npx", "args": ["--yes", "rust-faf-mcp@0.8.0"] } } } ``` After `cargo install rust-faf-mcp --version 0.8.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`: ```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. ``` 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` | Author `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` | Author `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 | ### Lineage | Tool | What it does | |------|-------------| | `faf_dna` | Your FAF DNA journey from `.faf-dna`: Birth DNA to now, with history. `faf_init` births it, `faf_auto` records growth — the same file as faf-cli | `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](https://github.com/Wolfe-Jam/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, 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 190 tests (143 integration + 47 unit): ```bash cargo test # runs all 190 # 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 | | `wjttc_faf_dna.rs` | 7 | `.faf-dna` lineage — `faf_init` birth, `faf_auto` growth, `faf_dna`, faf-cli's lines | | `src` unit | 47 | setup sweep, skills digest, `agents::`, `inject::`, intent, app-type, `dna::` lineage + faf-cli fixtures | 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](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 | | [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/) | Google | PyPI | | [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm | | [faf-cli](https://npmjs.com/package/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. ## Links - [crates.io/crates/rust-faf-mcp](https://crates.io/crates/rust-faf-mcp) - [npmjs.com/package/rust-faf-mcp](https://www.npmjs.com/package/rust-faf-mcp) — `npx --yes rust-faf-mcp@0.8.0` (no Rust toolchain; downloads GH Release binary) - [Dual-package publish guide](https://github.com/Wolfe-Jam/mcp-better/blob/main/docs/DUAL-PACKAGE-RUST-MCP.md) — cargo + npm (this server is the product example) - [docs/DUAL-PACKAGE.md](./docs/DUAL-PACKAGE.md) — pointer + OIDC docs for this repo - [docs/SKILLS-OVER-MCP.md](./docs/SKILLS-OVER-MCP.md) — J1 Agent Skill `faf-context` (skills/list · digests) - [faf-rust-sdk](https://crates.io/crates/faf-rust-sdk) — the parser this depends on - [faf.one](https://faf.one) — FAF home - [IANA registration](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) — `application/vnd.faf+yaml` - MCP Registry name: `mcp-name: one.faf/rust-faf-mcp` - [CHANGELOG](CHANGELOG.md) ## 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](https://x.com/wolfe_jam) | [wolfejam.dev](https://wolfejam.dev)