agentleFS
Wolfe-JamWolfe-Jam/rust-faf-mcp/AGENTS.md

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.

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
  1. Very specific:

    Do not collapse BETTER into BEST.

    line 11
  2. Very specific:

    Read project.faf first. Do not edit the BLOCK.

    line 13
  3. Very specific:

    Always OK: read the tree · run the tests (cargo test) · build the project · cargo clippy -- -D warnings.

    line 51
  4. Distinctive:

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

    line 61
  5. Very specific:

    If build/test scripts or layout change, refresh this file in the same PR (faf export --agents).

    line 67

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.

<!-- 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    # 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 (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 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.

FileRole
tests/mcp_protocol.rsHandshake, tools/list, resources, schema
tests/tools_functional.rsTools including faf_go
tests/tier1_security.rsPath traversal, injection, oversized input
tests/tier2_engine.rsCorrupt YAML, pipelines, dual manifests
tests/tier3_edge_cases.rsUnicode, score boundaries
tests/tier4_aero.rsmanifest.json ↔ server.json ↔ Cargo.toml
tests/wjttc_setup.rsSetup / Confirm setup (sweeps) — BRAKE · ENGINE · AERO · TYRE · PIT
src unitsetup · 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-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

ToolPurpose
faf_agentsAuthor the AGENTS.md BLOCK from project.faf (hand text outside markers)
faf_autoSetup if missing, sync CLAUDE.md, score — Confirm setup (sweeps); does not invent 6Ws
faf_goTable-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_initSetup: first write from the tree. Refuses if the file exists. Confirm setup (sweeps). 6Ws stay empty
faf_gitFrom a GitHub URL — mechanical facts only
faf_discoverWalk up for nearest project.faf
faf_scoreMk4 0–100%
faf_syncproject.faf → CLAUDE.md (one way)
faf_readDisplay .faf
faf_compressminimal / standard / full
faf_tokensToken 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] in server.rs + manifest.json + README + tests.

Guardrails

Always OKRead the tree · cargo test / fmt / clippy · cargo build · edit src/ + tests/ with tests
Ask firstDependency bumps · deleting public tools · publish / tag / Homebrew · registry identity · Dockerfile base (rust:1.88-slim = the MSRV; CI builds the image)
NeverForce-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

  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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.