rust-faf-mcp

Imported from Wolfe-Jam/rust-faf-mcp (AGENTS.md). Install upstream with npx skills add Wolfe-Jam/rust-faf-mcp. Copyright stays with the author.

AGENTS.md — rust-faf-mcp

This repository is the example of BEST on the FAF side of the ladder — not a slogan.

NONE → GOOD → BETTER → BEST

• BETTER is protocol honesty (mcp-better main / mcp-better-better). No project.faf required.
• BEST print slice (mcp-better better-best/* / mcp-better-best) is the same software plus project.faf. Falsifiable diff. That is the definition.
• This crate is BEST on main: Trophy project.faf and this AGENTS.md. FAF defines. This file instructs. Sealed BLOCK from the DNA; working brief outside the markers. It is also a FAF MCP server, in Rust, one.faf/rust-faf-mcp — a crate people actually watch.

Do not collapse BETTER into BEST. Do not treat this markdown as the score. The score is project.faf (Mk4 100% ✪).

Read project.faf first. Do not edit the BLOCK. Refresh it with faf_agents. Everything below the BLOCK is how we work in this tree.

AGENTS.md — rust-faf-mcp

Rust MCP server for FAF (Foundational AI-context Format) — IANA-registered application/vnd.faf+yaml — Rust · v0.8.1

Authored by faf — do not edit the managed block; refresh with faf export --agents. Hand content outside <!-- faf:start --> … <!-- faf:end --> is preserved.

Setup & build

cargo build    # build
cargo fmt --check    # fmt
cargo publish    # publish

Run the tests

cargo test
cargo clippy -- -D warnings

Where things live

• Cargo.toml
• src/main.rs
• src/server.rs
• src/tools.rs
• README.md
• LICENSE

Guardrails

• Always OK: read the tree · run the tests (cargo test) · build the project · cargo clippy -- -D warnings.
• Ask first: dependency installs, deletions, migrations, schema changes, publish/release.
• Never: force-push · push straight to main (branch and open a PR) · commit secrets.

Definition of Done

Done when: cargo clippy -- -D warnings exits 0 · cargo test passes · changes committed with a conventional message.

When stuck

Ask a clarifying question, propose a short plan, or open a draft PR with notes — do not push large speculative changes to main.

Commit & PR

• Conventional Commits preferred (feat:, fix:, chore:, …).
• Branch off main and open a PR — never commit to main directly.
• If build/test scripts or layout change, refresh this file in the same PR (faf export --agents).

Stack

• Backend: Rust
• Build Tool: cargo
• Testing: cargo test (190 tests, WJTTC 5-tier — setup/sweeps)
• Cicd: GitHub Actions

Working in this tree

0.8.1 — The Lineage Edition. .faf-dna lineage, the same file as faf-cli and fafb: faf_init births it, faf_auto grows it, faf_dna shows the journey. Pin the install: PATH rust-faf-mcp is not the pin. Edition 2024 · MSRV 1.85. 12 tools. 190 tests. Live pin: crates.io + npm @0.8.1.

Setup (what we actually run)

cargo build
cargo build --release        # LTO + strip → target/release/rust-faf-mcp
cargo test
cargo fmt --check
cargo clippy -- -D warnings

cargo install rust-faf-mcp
brew install Wolfe-Jam/faf/rust-faf-mcp

Tests spawn the compiled binary and speak JSON-RPC on stdin/stdout.

Where things live

src/main.rs      # tokio current_thread, rmcp stdio, tracing → stderr
src/server.rs    # FafServer: #[tool_router], ServerHandler, faf://scoring/weights
src/tools.rs     # Business logic
src/app_type.rs  # App-type → assigned slotignored (never 6Ws)
src/interview.rs # Table-of-8 / faf-interview/1 (cart; CLI authors)
src/intent.rs    # Courtesy Context Call (30|90)
src/agents.rs    # AGENTS.md BLOCK from project.faf
src/inject.rs    # Marker write — faf:start / faf:end as their own lines
src/skills.rs    # MCP skills extension (faf-context)
project.faf      # DNA — keep version in sync with Cargo.toml
server.json      # MCP Registry · name one.faf/rust-faf-mcp
manifest.json    # MCPB tool list
README.md        # Humans + crates.io — visible mcp-name: one.faf/rust-faf-mcp

Architecture (load-bearing)

• Split: tools.rs owns behavior; server.rs owns MCP wiring. agents.rs authors the BLOCK; inject.rs writes it without touching hand text.
• rmcp 3.0.1: #[tool_handler(router = self.tool_router)] must pin the cached router field.
• Runtime: tokio current_thread. Logging → stderr. stdout is JSON-RPC only.
• HTTP: reqwest only for faf_git.
• SDK: faf-rust-sdk 3.1. Do not reimplement scoring.
• Params: PathParams / GitParams / CompressParams / GoParams.

The twelve tools

Resource: faf://scoring/weights.

Conventions

• Version lockstep: Cargo.toml · server.json · manifest.json · project.faf · README · CHANGELOG.
• Registry: one.faf/rust-faf-mcp. stdio only unless an explicit product decision says otherwise.
• Release profile: opt-level = 3, lto = true, codegen-units = 1, strip = true.
• New tools: tools.rs + #[tool] in server.rs + manifest.json + README + tests.

Guardrails

Security: team@faf.one (see SECURITY.md). Do not open public issues for vulns.

Definition of Done

1. cargo fmt --check
2. cargo clippy -- -D warnings
3. cargo test — 171 green (or an updated count you intended)
4. Version surfaces + CHANGELOG if the surface changed
5. Conventional commit

Commit & PR

• Branch off main. Do not tag, cargo publish, or /pubpro unless the human says GO.
• crates.io: Trusted Publishing OIDC on GitHub Release.
• MCP Registry one.faf/*: DNS auth — coordinate with the maintainer.