mcp-better

mcp-better — built for 7/28

NONE | GOOD | [BETTER] | BEST

Textbook for AGENTS.md on that scale — honest modern MCP at the BETTER step. *(protocol 2026-07-28 — the modern MCP release)*

the book is the app is the book

Modern MCP textbook that runs, reviewed and approved as an AAIF Ambassador contribution. Rust · rmcp 3.10 · Discover · stamped cache hints · the official MCP conformance suite in CI: 100% for the conformance build, every scored check that needs no suite fixture for the textbook binary. Book: textbook/ — what · why · how · doctrine. App: this binary + smokes. Lesson after lesson, version after version — knowledge compounds.

BEST (BETTER plus project.faf that is resident and used: persistent project context that authors the agent files) lives at [faf.one/agents](https://faf.one/agents), one hop up from this textbook.

Dual-package (optional)

We are Cargo. Install is cargo install. npx is a try path. We do not offer npm install as an option.

→ Why dual-package — positioning + FAQ → Full guide (how) — lockstep, publish order, OIDC, score + wire

Skills over MCP (optional · textbook)

One Agent Skill (mcp-better-lab) on the same process as tools:

→ docs/SKILLS-OVER-MCP.md — extension · skills/list · skills/get · digests

What is 7/28?

7/28 is a great name. 2026-07-28 is a date. Humans say 7/28. Machines negotiate `2026-07-28`.

What to expect

1. Built for 7/28 — not bolted onto a legacy server (official rmcp 3.10).
2. Honest surface — transport and capabilities match docs and CI.
3. Roadmap expands the era — versions add road; they do not “become” 7/28 later.

What BETTER means

1. Protocol honesty — claim 7/28 / 2026-07-28 only for surfaces you implement and test.
2. Discover-compatible — clients should use ClientLifecycleMode::Discover (or Auto → 7/28), not only legacy initialize.
3. Cache hints by choice — tools/list, resources/list, resources/templates/list, resources/read, skills/list and skills/get return a positive ttlMs and cacheScope (static catalog → public). The SDK default is ttlMs: 0 + private: valid, but it tells every client not to cache.
4. Stable tool order — same process, same order across N list calls.
5. Transports — stdio (default) and Streamable HTTP (--http) in the same 7/28 era.

Quickstart (≤10 min)

Try (suggested) — npx

# No Rust toolchain. Downloads the native binary from GitHub Releases.

npx mcp-better --help npx mcp-better

From source / crates.io (Rust 1.88+)

git clone https://github.com/Wolfe-Jam/mcp-better.git

cd mcp-better cargo build --bins cargo test cargo run --example stdio-client

louder 0.3 smokes (build --bins first; or: bash scripts/ci.sh)

MCP_BETTER_BIN="$(pwd)/target/debug/mcp-better" cargo run --example order-restart-smoke MCP_BETTER_BIN="$(pwd)/target/debug/mcp-better" \ MCP_WORSE_BIN="$(pwd)/target/debug/mcp-worse" \ cargo run --example contrast-smoke MCP_BETTER_BIN="$(pwd)/target/debug/mcp-better" cargo run --example http-smoke

0.5 matching client (completes confirm_echo)

MCP_BETTER_BIN="$(pwd)/target/debug/mcp-better" cargo run --example mrtr-client

Install (crates.io) — stdio default (Cursor / Claude Desktop):

First `cargo install` compiles Rust deps once (often 100+ units — rmcp / tokio / …, not 100 tools of ours). One-time; then the binary is instant. To skip that compile, try with npx mcp-better (above) — that is not the install.

cargo run --release

install from crates.io — first hit compiles deps once (see above):

cargo install mcp-better --version 0.5.0 --locked mcp-better --help

optional lying companion (teaching only — not for hosts):

cargo install mcp-better --version 0.5.0 --locked --bin mcp-worse

Streamable HTTP (local demo only — see SECURITY.md):

cargo run --release -- --http

http://127.0.0.1:8787/mcp

MCP_BETTER_HTTP_ADDR=127.0.0.1:9000 mcp-better --http

Transport selection (CLI wins over env):

Tools

Protocol claims (v0.5.0 — same 7/28 era · matching client completes MRTR)

| MRTR (optional) | `confirm_echo` — mid-call confirm · sealed requestState · matching client `mrtr-client` · docs/MRTR-CONFIRM-ECHO.md | Skills (optional) | `mcp-better-lab` · skills/list · digests · docs/SKILLS-OVER-MCP.md | | Lying companion | `mcp-worse` — reversed tool order (the lie) + no cache hints of its own (the wire shows the SDK default ttlMs: 0 + private, valid but uninformative) · contrast-smoke only | | OAuth / tasks | out of hero |

Conformance

CI runs the official MCP conformance suite (@modelcontextprotocol/conformance, pinned) against two binaries. Each run covers --requirements 2026-07-28 (50 scenarios: 37 the suite scores, 13 it runs but does not score) and the two Skills scenarios (sep-2640-skills-enumeration, sep-2640-skills-manifest, an extension outside that set).

What each run measures. Most scenarios call tools, prompts and resources that exist only in the suite's reference server (test_*, test://…), and the 13 unscored ones are the Tasks extension and three pending scenarios. The official SDKs pass those with a separate server that carries the fixtures; mcp-better-conformance is that server for mcp-better. Its fixtures, capabilities and Tasks are adapted from the Rust MCP SDK's conformance server (Apache-2.0, conformance/NOTICE); BetterServer serves mcp-better's three tools, the skill resource and Skills. So the 100% mostly measures the fixtures and the shared transport (mcp_better::http_config). The textbook run and the Skills scenarios measure mcp-better's own code.

Reading the textbook run. caching is 7 of 8: the eighth check calls prompts/list, and mcp-better doesn't declare prompts, so it answers method-not-found (not declared in the baseline). prompts-list and completion-complete fail for the same reason. Every other failure is a missing suite fixture. The suite's MRTR scenarios use its own fixture tools, so confirm_echo is checked by the matching client (examples/mrtr-client) in CI.

bash scripts/conformance.sh                                             # textbook + baseline

(cd conformance && cargo build) && \ MCP_BETTER_BIN="$(pwd)/conformance/target/debug/mcp-better-conformance" \ MCP_CONFORMANCE_BASELINE='' bash scripts/conformance.sh # conformance build, strict

Textbook

The book is the app is the book — textbook/ (Season 1 · doctrine).

Start: textbook/README.md → lab Ch 09.

Non-goals (GOOD-era habits we refuse)

• Shipping unstamped list results while claiming 7/28 modernity
• Requiring project.faf or any BEST tooling on this repo’s main branch
• Treating stdio as “not real 7/28” — stdio is a first-class 7/28 transport
• FAF install tax in the AAIF lede — this repo is protocol textbook, not a FAF product

Registry identity

• MCP Registry name: mcp-name: io.github.Wolfe-Jam/mcp-better
• Dual packages (same version, both stdio):
• registryType: cargo · identifier: mcp-better · crates.io
• registryType: npm · identifier: mcp-better · registry.npmjs.org (Node shim downloads the native binary from GitHub Releases — no Rust on the host)
• Package transport in `server.json` is stdio only — by design. Hosts spawn via cargo install / npx mcp-better on stdio. Streamable HTTP (--http) is an opt-in local demo in the same binary and the same 7/28 era; it is not a Registry remote package. Discover it in this README and --help.

See server.json. Not one.faf/*.

##