rust-faf-mcp
AGENTS.md4 starsChanged 20 days agoMITView on GitHub
This repository is the example of BEST on the FAF side of the ladder — not a slogan. NONE → GOOD → BETTER → BEST 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. Rust MCP server for FAF (Foundational AI-context Format) — IANA-registered application/vnd.faf+yaml…
- Installs packages
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- faf-contextSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 1 is distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 11
Do not collapse BETTER into BEST.
- Very specific: line 13
Read project.faf first. Do not edit the BLOCK.
- Very specific: line 51
Always OK: read the tree · run the tests (cargo test) · build the project · cargo clippy -- -D warnings.
- Distinctive: line 61
Ask a clarifying question, propose a short plan, or open a draft PR with notes — do not push large speculative changes to main.
- Very specific: line 67
If build/test scripts or layout change, refresh this file in the same PR (faf export --agents).
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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). Noproject.fafrequired. - BEST print slice (mcp-better
better-best/*/mcp-better-best) is the same software plusproject.faf. Falsifiable diff. That is the definition. - This crate is BEST on main: Trophy
project.fafand thisAGENTS.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.
<!-- faf:start --><!-- faf: rust-faf-mcp | Rust | | Rust MCP server for FAF (Foundational AI-context Format) — IANA-registered application/vnd.faf+yaml --><!-- faf: claim=project.faf | family=FAF -->AGENTS.md — rust-faf-mcp
Rust MCP server for FAF (Foundational AI-context Format) — IANA-registered application/vnd.faf+yaml — Rust · v0.9.0
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 # publishRun the tests
cargo test
cargo clippy -- -D warningsWhere things live
Cargo.tomlsrc/main.rssrc/server.rssrc/tools.rsREADME.mdLICENSE
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
mainand open a PR — never commit tomaindirectly. - 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 (223 tests, WJTTC 5-tier — setup/sweeps)
- Cicd: GitHub Actions
<!-- faf:end -->Working in this tree
0.9.0 — The Your-Files-Stay-Yours Edition. faf_sync keeps your hand-written CLAUDE.md, refuses what it can't write safely, and says so. .faf-dna lineage (0.8): 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.88 (rmcp 3 requires it; CI builds on it). 12 tools. 223 tests. Live pin: crates.io + npm @0.9.0.
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 warningscargo install rust-faf-mcp
brew install Wolfe-Jam/faf/rust-faf-mcpTests spawn the compiled binary and speak JSON-RPC on stdin/stdout.
| File | Role |
tests/mcp_protocol.rs | Handshake, tools/list, resources, schema |
tests/tools_functional.rs | Tools including faf_go |
tests/tier1_security.rs | Path traversal, injection, oversized input |
tests/tier2_engine.rs | Corrupt YAML, pipelines, dual manifests |
tests/tier3_edge_cases.rs | Unicode, score boundaries |
tests/tier4_aero.rs | manifest.json ↔ server.json ↔ Cargo.toml |
tests/wjttc_setup.rs | Setup / Confirm setup (sweeps) — BRAKE · ENGINE · AERO · TYRE · PIT |
src unit | setup · agents · inject · app_type · interview · intent · skills |
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-mcpArchitecture (load-bearing)
- Split:
tools.rsowns behavior;server.rsowns MCP wiring.agents.rsauthors the BLOCK;inject.rswrites it without touching hand text. - rmcp 3.0.1:
#[tool_handler(router = self.tool_router)]must pin the cached router field. - Runtime:
tokiocurrent_thread. Logging → stderr. stdout is JSON-RPC only. - HTTP:
reqwestonly forfaf_git. - SDK:
faf-rust-sdk3.1. Do not reimplement scoring. - Params:
PathParams/GitParams/CompressParams/GoParams.
The twelve tools
| Tool | Purpose |
faf_agents | Author the AGENTS.md BLOCK from project.faf (hand text outside markers) |
faf_auto | Setup if missing, sync CLAUDE.md, score — Confirm setup (sweeps); does not invent 6Ws |
faf_go | Table-of-8 + Confirm setup (sweeps). 6Ws score after ☑. Below 100: add Human Context. After 100: Time to check your Context (30 days, 90 max) |
faf_init | Setup: first write from the tree. Refuses if the file exists. Confirm setup (sweeps). 6Ws stay empty |
faf_git | From a GitHub URL — mechanical facts only |
faf_discover | Walk up for nearest project.faf |
faf_score | Mk4 0–100% |
faf_sync | project.faf → CLAUDE.md (one way) |
faf_read | Display .faf |
faf_compress | minimal / standard / full |
faf_tokens | Token estimates |
faf_dna | .faf-dna journey (reads only). faf_init births it, faf_auto records growth — same file as faf-cli |
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]inserver.rs+manifest.json+ README + tests.
Guardrails
| Always OK | Read the tree · cargo test / fmt / clippy · cargo build · edit src/ + tests/ with tests |
| Ask first | Dependency bumps · deleting public tools · publish / tag / Homebrew · registry identity · Dockerfile base (rust:1.88-slim = the MSRV; CI builds the image) |
| Never | Force-push · secrets · Guaranteed · chatter on stdout · scoring outside faf-rust-sdk |
Security: team@faf.one (see SECURITY.md). Do not open public issues for vulns.
Definition of Done
cargo fmt --checkcargo clippy -- -D warningscargo test— 171 green (or an updated count you intended)- Version surfaces + CHANGELOG if the surface changed
- Conventional commit
Commit & PR
- Branch off
main. Do not tag,cargo publish, or/pubprounless the human says GO. - crates.io: Trusted Publishing OIDC on GitHub Release.
- MCP Registry
one.faf/*: DNS auth — coordinate with the maintainer.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

