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

AAIF-verified modern MCP textbook that runs. Rust · rmcp 3.0.x (lock 3.0.1, Tier 1 assessed) · Discover · stamped list cache.
Book: textbook/ — what · why · how · doctrine.
App: this binary + smokes. Lesson after lesson, version after version — knowledge compounds.

BEST (persistent project DNA for agents — AGENTS.md / FAF at scale) lives at 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?

Name	What it is
7/28	The era name — speakable, brandable. “Built for 7/28.”
2026-07-28	The protocol version — the date string on the wire / in SDKs.

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

What to expect

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

Version	Lesson (the version is the lesson)
v0.1	7/28 over stdio — Discover, stamped `ttlMs` / `cacheScope`, stable order, `health` + `echo`
v0.2	Same 7/28 era + Streamable HTTP road + routing headers (`Mcp-Method` / `Mcp-Name`)
v0.3	Same era + deeper correctness — multi-list + restart-order smokes · `mcp-worse` contrast
v0.4	Same era + dual package — cargo + npm shim · `npx mcp-better` with no Rust toolchain
v0.4.3	Same era + `confirm_echo` MRTR (SEP-2322) + Agent Skills (`mcp-better-lab`) — see `docs/MRTR-CONFIRM-ECHO.md` · `docs/SKILLS-OVER-MCP.md`
v0.4.4	Same era + book matches 0.4.3 wire — no new tool · catalogs named `health` → `echo` → `confirm_echo`
v0.5	Same era + matching client completes MRTR — `mrtr-client` finishes `confirm_echo`

What BETTER means

Protocol honesty — claim 7/28 / 2026-07-28 only for surfaces you implement and test.
Discover-compatible — clients should use ClientLifecycleMode::Discover (or Auto → 7/28), not only legacy initialize.
List cache stamps — tools/list returns positive ttlMs and cacheScope (static catalog → public). SDK defaults are unstamped.
Stable tool order — same process, same order across N list calls.
Transports — stdio (default) and Streamable HTTP (--http) in the same 7/28 era.

Quickstart (≤10 min)

Path	What it is
`cargo install mcp-better`	The install — we are Cargo. crates.io, native binary on PATH.
`npx mcp-better`	Suggested try — no Rust, no compile. Not the install.
npm	A published shim so `npx` / some hosts can start the same binary. We do not offer `npm install` / `npm i -g`.

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.85+)

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
mcp-better --help
# optional lying companion (teaching only — not for hosts):
# cargo install mcp-better --version 0.5.0 --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):

How	Value
CLI	`mcp-better` (stdio) · `mcp-better --http` · `mcp-better --stdio`
Bare args	`http` / `stdio` (same meaning as flags)
Env	`MCP_TRANSPORT` or `MCP_BETTER_TRANSPORT` → `stdio` \| `http` (`MCP_TRANSPORT` first if both set)
HTTP bind	`MCP_BETTER_HTTP_ADDR` — default `127.0.0.1:8787`. Do not use `0.0.0.0` unless you accept an unauthenticated open endpoint.

Tools

Tool	Purpose
`health`	Liveness — status, version, protocol. No side effects. Not a k8s probe contract.
`echo`	Pure demo — returns `message` unchanged.
`confirm_echo`	Textbook MRTR (SEP-2322) — echo after mid-call confirm · sealed `requestState`.

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

Surface	Status
Era / protocol	7/28 · negotiated `2026-07-28` (Discover preferred)
Transport	stdio (default) · Streamable HTTP (`--http`)
HTTP mode	Stateless for 7/28 · `json_response` · local Host guards
Routing headers	Streamable HTTP POSTs use `Mcp-Method` and `Mcp-Name` when naming a tool (SEP-2243); `http-smoke` asserts this happy path
Capabilities	tools · resources (skill docs) · experimental skills extension
List cache	`ttlMs=60000`, `cacheScope=public`, order `health`→`echo`→`confirm_echo` (restart-stable)
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` — unstamped + reversed order (contrast-smoke only)
OAuth / tasks	out of hero

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/*.

Publish

Ship process: /pubbetter (skill) · short form docs/PUBBETTER.md · local ship bar:

export PATH="$HOME/.cargo/bin:$PATH"
bash scripts/ci.sh

BEST

For persistent, versionable AI project context beyond a protocol textbook:

https://faf.one/agents

Docs

BETTER.md — ladder + claim surface
docs/BETTER-BEST.md — BETTER vs BEST
GETTING-STARTED.md
docs/SDK-NOTES.md — serve vs Discover honesty
docs/DUAL-PACKAGE-FOR-RUST-MCP.md — why dual-package (cargo first · FAQ)
docs/DUAL-PACKAGE-RUST-MCP.md — how: full dual cargo+npm guide
docs/MCP-DIST-POST.md — lockstep post-step (does not publish)
SECURITY.md · CONTRIBUTING.md

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
bin		bin
docs		docs
examples		examples
lib		lib
scripts		scripts
skills/mcp-better-lab		skills/mcp-better-lab
src		src
tests		tests
textbook		textbook
.gitignore		.gitignore
BETTER.md		BETTER.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
GETTING-STARTED.md		GETTING-STARTED.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
dist-workspace.toml		dist-workspace.toml
package.json		package.json
rust-toolchain.toml		rust-toolchain.toml
server.json		server.json

Navigation Menu

Repository files navigation

mcp-better — built for 7/28

Dual-package (optional)

Skills over MCP (optional · textbook)

What is 7/28?

What to expect

What BETTER means

Quickstart (≤10 min)

Try (suggested) — `npx`

From source / crates.io (Rust 1.85+)

Tools

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

Textbook

Non-goals (GOOD-era habits we refuse)

Registry identity

Publish

BEST

Docs

License

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

mcp-better — built for 7/28

Dual-package (optional)

Skills over MCP (optional · textbook)

What is 7/28?

What to expect

What BETTER means

Quickstart (≤10 min)

Try (suggested) — npx

From source / crates.io (Rust 1.85+)

Tools

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

Textbook

Non-goals (GOOD-era habits we refuse)

Registry identity

Publish

BEST

Docs

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

Try (suggested) — `npx`