{
  "markdown": "<!-- faf: rust-faf-mcp | Rust | mcp-server | RMCP — the Rust-native MCP server for FAF (Foundational AI-context Format). Single binary, stdio transport, 4.3 MB stripped. cargo install rust-faf-mcp. Built on the rmcp Rust MCP SDK + faf-rust-sdk. -->\n<!-- mcp-name: one.faf/rust-faf-mcp -->\n\n\n# rust-faf-mcp\n\n**Persistent Project Context for Rust MCP clients. Native. Fast. cargo install**\n\n**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\n\n**v0.7.1** — Pin the install. PATH `rust-faf-mcp` is not the pin. See [CHANGELOG](./CHANGELOG.md#071---2026-09-02--the-table-of-8-edition).\n\n**FAF defines. MD instructs. AI codes.**\n\n> 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.\n\n[![Crates.io](https://img.shields.io/crates/v/rust-faf-mcp?style=flat-square)](https://crates.io/crates/rust-faf-mcp)\n[![FAF Trophy 100%](https://img.shields.io/badge/FAF-%E2%9C%AA%20100%25-000000?labelColor=FF6B35)](https://faf.one)\n[![Tests](https://img.shields.io/badge/tests-171%20passing-brightgreen?style=flat-square)](https://github.com/Wolfe-Jam/rust-faf-mcp)\n[![IANA](https://img.shields.io/badge/IANA-registered-informational?style=flat-square)](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml)\n[![License](https://img.shields.io/crates/l/rust-faf-mcp?style=flat-square)](LICENSE)\n\nRust-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).\n\n## Quickstart\n\n```bash\n# Rust toolchain (install):\ncargo install rust-faf-mcp --version 0.7.1\n\n# No Rust (try — downloads GH Release binary for darwin/linux):\nnpx --yes rust-faf-mcp@0.7.1\n```\n\nPoint an MCP client at the **pin**. A bare `rust-faf-mcp` on PATH may be an old Homebrew binary.\n\n```bash\n# Claude Code\nclaude mcp add faf -- npx --yes rust-faf-mcp@0.7.1\n```\n\n```jsonc\n// WARP / Cursor / Zed / Claude Desktop — any stdio MCP client\n{\n  \"mcpServers\": {\n    \"faf\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"rust-faf-mcp@0.7.1\"]\n    }\n  }\n}\n```\n\nAfter `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.\n\nNo flags, no config files, no network listener. Pure stdio JSON-RPC.\n\nOr via Homebrew (macOS, pre-built). If you already have it, upgrade — an old keg can sit on PATH as `rust-faf-mcp`:\n\n```bash\nbrew update\nbrew install Wolfe-Jam/faf/rust-faf-mcp\n# already installed:\nbrew upgrade Wolfe-Jam/faf/rust-faf-mcp\n```\n\n## One command, done forever\n\n`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.\n\n```\nfaf_auto complete\n━━━━━━━━━━━━━━━━━\nScore: 0% → 42% (+42) ● GREEN\nSteps:\n  1. Setup — created project.faf\n  2. Created CLAUDE.md\n\nPath: /home/user/my-project\n\nConfirm setup (sweeps)\nWalk these. Detection is already a fact. Not a second write-gate.\n  project.name           my-api\n  project.main_language  Rust\n  stack.backend          Rust\n```\n\nWhat it produces:\n\n```yaml\n# project.faf — your project, machine-readable\nfaf_version: \"3.3\"\nproject:\n  name: my-api\n  goal: REST API for user management\n  main_language: Rust\n  version: \"0.1.0\"\n  license: MIT\ninstant_context:\n  what_building: REST API for user management\n  tech_stack: Rust 2024\n  key_files:\n    - Cargo.toml\n    - src/main.rs\n    - README.md\n  commands:\n    build: cargo build\n    test: cargo test\nstack:\n  backend: Rust\n  build: cargo\n```\n\nEvery AI agent reads this once and knows exactly what you're building. No 20-minute onboarding. No wrong assumptions.\n\n## Tools\n\n### Create & Detect\n\n| Tool | What it does |\n|------|-------------|\n| `faf_auto` | Setup if missing, sync `CLAUDE.md`, score — Confirm setup (sweeps); does not invent 6Ws |\n| `faf_init` | Setup: first write from the tree. Refuses if the file exists. Confirm setup (sweeps). 6Ws stay empty |\n| `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) |\n| `faf_git` | Generate `project.faf` from any GitHub repo URL — no clone needed |\n| `faf_discover` | Walk up the directory tree to find the nearest `project.faf` |\n\n### Score & Validate\n\n| Tool | What it does |\n|------|-------------|\n| `faf_score` | Score AI-readiness 0-100% with field-level breakdown |\n| `faf_sync` | Sync `project.faf` → `CLAUDE.md` (preserves existing content) |\n| `faf_agents` | Generate `AGENTS.md` from `project.faf` (non-destructive, preserves hand-written content) |\n\n### Optimize\n\n| Tool | What it does |\n|------|-------------|\n| `faf_read` | Parse and display `project.faf` contents |\n| `faf_compress` | Compress `.faf` for token-limited contexts (`minimal` / `standard` / `full`) |\n| `faf_tokens` | Estimate token count at each compression level |\n\n`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`.\n\n## Architecture\n\n```\nsrc/\n├── main.rs      # ~20 lines — tokio entry, rmcp stdio transport\n├── server.rs    # FafServer: #[tool_router], ServerHandler, resources\n└── tools.rs     # Business logic — tools as pure functions returning Value\n```\n\n- **Runtime**: `tokio` single-threaded (`current_thread`)\n- **HTTP**: `reqwest` async (only used by `faf_git` for GitHub API)\n- **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)\n- **Server**: **`rmcp` 3.0.1** with `#[tool_router]` / `#[tool_handler]` — JSON-RPC, schema generation, stdio transport (Tier-1 assessed SDK cut)\n\nTools return `serde_json::Value`. The server adapts them to `Result<String, String>` for rmcp's `IntoCallToolResult`.\n\n## Testing\n\n171 tests (136 integration + 35 unit):\n\n```bash\ncargo test    # runs all 171\n\n# Full ship bar (same gates as GitHub CI — run before push)\nbash scripts/ci.sh\n# Optional: block push on red CI twin\nbash scripts/install-hooks.sh\n```\n\n| File | Tests | Coverage |\n|------|-------|----------|\n| `mcp_protocol.rs` | 9 | Init handshake, tools/list, resources, schema validation, ID preservation |\n| `tools_functional.rs` | 31 | Tools — happy path, error paths, language detection, faf_go |\n| `tier1_security.rs` | 12 | Path traversal, null bytes, shell injection, oversized input, malformed JSON |\n| `tier2_engine.rs` | 36 | Corrupt YAML, sync replacement, pipelines, dual manifests, legacy filenames, direct paths |\n| `tier3_edge_cases.rs` | 10 | Unicode, CJK, score boundaries, unknown fields, GitHub URL parsing |\n| `tier4_aero.rs` | 22 | Manifest structure, version sync, server.json, context block, manifest-server cross-validation |\n| `wjttc_setup.rs` | 16 | Setup / Confirm setup (sweeps) — BRAKE · ENGINE · AERO · TYRE · PIT |\n| `src` unit | 35 | setup sweep, skills digest, `agents::`, `inject::`, intent, app-type |\n\nTests spawn the compiled binary as a subprocess and communicate via stdin/stdout JSON-RPC — true integration tests against the real server.\n\n## FAF Ecosystem\n\nOne format, every AI platform.\n\n| Package | Platform | Registry |\n|---------|----------|----------|\n| **rust-faf-mcp** | **Rust** | **crates.io** |\n| [claude-faf-mcp](https://npmjs.com/package/claude-faf-mcp) | Anthropic | npm + MCP #2759 |\n| [gemini-faf-mcp](https://pypi.org/project/gemini-faf-mcp/) | Google | PyPI |\n| [grok-faf-mcp](https://npmjs.com/package/grok-faf-mcp) | xAI | npm |\n| [faf-cli](https://npmjs.com/package/faf-cli) | Universal | npm |\n\n## Build from source\n\n```bash\ngit clone https://github.com/Wolfe-Jam/rust-faf-mcp\ncd rust-faf-mcp\ncargo build --release\n# Binary at target/release/rust-faf-mcp (4.3 MB)\n```\n\n**Edition**: 2024 | **LTO**: enabled | **Strip**: symbols\n\nIf `rust-faf-mcp` has been useful, consider starring the repo — it helps others find it.\n\n## Links\n\n- [crates.io/crates/rust-faf-mcp](https://crates.io/crates/rust-faf-mcp)\n- [npmjs.com/package/rust-faf-mcp](https://www.npmjs.com/package/rust-faf-mcp) — `npx --yes rust-faf-mcp@0.7.1` (no Rust toolchain; downloads GH Release binary)\n\n- [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)\n- [docs/DUAL-PACKAGE.md](./docs/DUAL-PACKAGE.md) — pointer + OIDC docs for this repo\n- [docs/SKILLS-OVER-MCP.md](./docs/SKILLS-OVER-MCP.md) — J1 Agent Skill `faf-context` (skills/list · digests)\n- [faf-rust-sdk](https://crates.io/crates/faf-rust-sdk) — the parser this depends on\n- [faf.one](https://faf.one) — FAF home\n- [IANA registration](https://www.iana.org/assignments/media-types/application/vnd.faf+yaml) — `application/vnd.faf+yaml`\n- MCP Registry name: `mcp-name: one.faf/rust-faf-mcp`\n- [CHANGELOG](CHANGELOG.md)\n\n## Citation\n\nIf you use `rust-faf-mcp` or the `.faf` / `.fafa` formats in research or production, please cite the format papers:\n\n> Wolfe, J. (2025). *Format-Driven AI Context Architecture: The .faf Standard for Persistent Project Understanding*. Zenodo. https://doi.org/10.5281/zenodo.18251362\n\n> Wolfe, J. (2026). *Why Agents Need a Passport: .fafa — Portable Identity for the Agentic Era*. Zenodo. https://doi.org/10.5281/zenodo.21951641\n\n## License\n\nMIT\n\n---\n\nBuilt by [@wolfe_jam](https://x.com/wolfe_jam) | [wolfejam.dev](https://wolfejam.dev)\n",
  "bytes": 9988,
  "sha": "dc4410f716170679a755855a3cfa6a1c625b599d366a9f12600a31c562e1399c",
  "repo_slug": "wolfe-jam/rust-faf-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_one_faf_rust_faf_mcp_329b7590/readme"
}