{
  "markdown": "# mcp-better — built for 7/28\n\n**NONE | GOOD | [BETTER] | BEST**\n\nTextbook for **AGENTS.md** on that scale — honest modern MCP at the **BETTER** step.  \n*(protocol **2026-07-28** — the modern MCP release)*\n\n```text\nthe book is the app is the book\n```\n\nAAIF-verified modern MCP textbook **that runs**. Rust · `rmcp` **3.0.x** (lock **3.0.1**, Tier 1 assessed) · Discover · stamped list cache.  \n**Book:** [`textbook/`](./textbook/) — what · why · how · [doctrine](./textbook/DOCTRINE-book-is-app.md).  \n**App:** this binary + smokes. Lesson after lesson, version after version — knowledge compounds.\n\n> **BEST** (persistent project DNA for agents — **AGENTS.md** / FAF at scale) lives at **[faf.one/agents](https://faf.one/agents)** — one hop up from this textbook.\n\n## Dual-package (optional)\n\n**We are Cargo.** Install is `cargo install`. `npx` is a try path. We do **not** offer `npm install` as an option.\n\n→ [Why dual-package](./docs/DUAL-PACKAGE-FOR-RUST-MCP.md) — positioning + FAQ  \n→ [Full guide (how)](./docs/DUAL-PACKAGE-RUST-MCP.md) — lockstep, publish order, OIDC, score + wire\n\n## Skills over MCP (optional · textbook)\n\nOne Agent Skill (`mcp-better-lab`) on the same process as tools:\n\n→ [docs/SKILLS-OVER-MCP.md](./docs/SKILLS-OVER-MCP.md) — extension · `skills/list` · `skills/get` · digests\n\n## What is 7/28?\n\n| Name | What it is |\n|------|------------|\n| **7/28** | The **era name** — speakable, brandable. “Built for 7/28.” |\n| **2026-07-28** | The **protocol version** — the date string on the wire / in SDKs. |\n\n**7/28 is a great name. 2026-07-28 is a date.**  \nHumans say **7/28**. Machines negotiate **`2026-07-28`**.\n\n## What to expect\n\n1. **Built for 7/28** — not bolted onto a legacy server (official `rmcp` 3.0.x / Tier-1 assessed cut).\n2. **Honest surface** — transport and capabilities match docs and CI.\n3. **Roadmap expands the era** — versions add road; they do not “become” 7/28 later.\n\n| Version | Lesson (the version *is* the lesson) |\n|---------|--------------------------------------|\n| **v0.1** | **7/28 over stdio** — Discover, stamped `ttlMs` / `cacheScope`, stable order, `health` + `echo` |\n| **v0.2** | Same 7/28 era + **Streamable HTTP** road + routing headers (`Mcp-Method` / `Mcp-Name`) |\n| **v0.3** | Same era + **deeper correctness** — multi-list + restart-order smokes · `mcp-worse` contrast |\n| **v0.4** | Same era + **dual package** — cargo + npm shim · `npx mcp-better` with **no Rust toolchain** |\n| **v0.4.3** | Same era + **`confirm_echo` MRTR** (SEP-2322) + **Agent Skills** (`mcp-better-lab`) — see [`docs/MRTR-CONFIRM-ECHO.md`](./docs/MRTR-CONFIRM-ECHO.md) · [`docs/SKILLS-OVER-MCP.md`](./docs/SKILLS-OVER-MCP.md) |\n| **v0.4.4** | Same era + **book matches 0.4.3 wire** — no new tool · catalogs named `health` → `echo` → `confirm_echo` |\n| **v0.5** | Same era + **matching client completes MRTR** — `mrtr-client` finishes `confirm_echo` |\n\n## What BETTER means\n\n1. **Protocol honesty** — claim 7/28 / `2026-07-28` only for surfaces you implement and test.\n2. **Discover-compatible** — clients should use `ClientLifecycleMode::Discover` (or Auto → 7/28), not only legacy initialize.\n3. **List cache stamps** — `tools/list` returns positive `ttlMs` and `cacheScope` (static catalog → `public`). SDK defaults are unstamped.\n4. **Stable tool order** — same process, same order across N list calls.\n5. **Transports** — **stdio** (default) and **Streamable HTTP** (`--http`) in the **same 7/28 era**.\n\n## Quickstart (≤10 min)\n\n| Path | What it is |\n|------|------------|\n| **`cargo install mcp-better`** | **The install** — we are Cargo. crates.io, native binary on PATH. |\n| **`npx mcp-better`** | **Suggested try** — no Rust, no compile. Not the install. |\n| **npm** | A published **shim** so `npx` / some hosts can start the same binary. We do **not** offer `npm install` / `npm i -g`. |\n\n### Try (suggested) — `npx`\n\n```bash\n# No Rust toolchain. Downloads the native binary from GitHub Releases.\nnpx mcp-better --help\nnpx mcp-better\n```\n\n### From source / crates.io (Rust 1.85+)\n\n```bash\ngit clone https://github.com/Wolfe-Jam/mcp-better.git\ncd mcp-better\ncargo build --bins\ncargo test\ncargo run --example stdio-client\n# louder 0.3 smokes (build --bins first; or: bash scripts/ci.sh)\nMCP_BETTER_BIN=\"$(pwd)/target/debug/mcp-better\" cargo run --example order-restart-smoke\nMCP_BETTER_BIN=\"$(pwd)/target/debug/mcp-better\" \\\n  MCP_WORSE_BIN=\"$(pwd)/target/debug/mcp-worse\" \\\n  cargo run --example contrast-smoke\nMCP_BETTER_BIN=\"$(pwd)/target/debug/mcp-better\" cargo run --example http-smoke\n# 0.5 matching client (completes confirm_echo)\nMCP_BETTER_BIN=\"$(pwd)/target/debug/mcp-better\" cargo run --example mrtr-client\n```\n\n**Install** (crates.io) — stdio default (Cursor / Claude Desktop):\n\n**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.\n\n```bash\ncargo run --release\n# install from crates.io — first hit compiles deps once (see above):\ncargo install mcp-better --version 0.5.0\nmcp-better --help\n# optional lying companion (teaching only — not for hosts):\n# cargo install mcp-better --version 0.5.0 --bin mcp-worse\n```\n\n**Streamable HTTP** (local demo only — see [SECURITY.md](./SECURITY.md)):\n\n```bash\ncargo run --release -- --http\n# http://127.0.0.1:8787/mcp\n# MCP_BETTER_HTTP_ADDR=127.0.0.1:9000 mcp-better --http\n```\n\n**Transport selection** (CLI wins over env):\n\n| How | Value |\n|-----|--------|\n| CLI | `mcp-better` (stdio) · `mcp-better --http` · `mcp-better --stdio` |\n| Bare args | `http` / `stdio` (same meaning as flags) |\n| Env | `MCP_TRANSPORT` or `MCP_BETTER_TRANSPORT` → `stdio` \\| `http` (**`MCP_TRANSPORT` first** if both set) |\n| 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. |\n\n## Tools\n\n| Tool | Purpose |\n|------|---------|\n| `health` | Liveness — status, version, protocol. No side effects. Not a k8s probe contract. |\n| `echo` | Pure demo — returns `message` unchanged. |\n| `confirm_echo` | Textbook **MRTR** (SEP-2322) — echo after mid-call confirm · sealed `requestState`. |\n\n## Protocol claims (v0.5.0 — same 7/28 era · matching client completes MRTR)\n\n| Surface | Status |\n|---------|--------|\n| Era / protocol | **7/28** · negotiated **`2026-07-28`** (Discover preferred) |\n| Transport | **stdio** (default) · **Streamable HTTP** (`--http`) |\n| HTTP mode | Stateless for 7/28 · `json_response` · local **Host** guards |\n| Routing headers | Streamable HTTP POSTs use **`Mcp-Method`** and **`Mcp-Name`** when naming a tool (SEP-2243); `http-smoke` asserts this happy path |\n| Capabilities | **tools** · **resources** (skill docs) · **experimental** skills extension |\n| List cache | **`ttlMs=60000`**, **`cacheScope=public`**, order **`health`→`echo`→`confirm_echo`** (restart-stable) |\n| MRTR (optional) | **`confirm_echo`** — mid-call confirm · sealed `requestState` · matching client **`mrtr-client`** · [`docs/MRTR-CONFIRM-ECHO.md`](./docs/MRTR-CONFIRM-ECHO.md)\n| Skills (optional) | **`mcp-better-lab`** · `skills/list` · digests · [`docs/SKILLS-OVER-MCP.md`](./docs/SKILLS-OVER-MCP.md) |\n| Lying companion | **`mcp-worse`** — unstamped + reversed order (contrast-smoke only) |\n| OAuth / tasks | out of hero |\n\n## Textbook\n\nThe book is the app is the book — [`textbook/`](./textbook/) (Season 1 · [doctrine](./textbook/DOCTRINE-book-is-app.md)).\n\nStart: [textbook/README.md](./textbook/README.md) → lab [Ch 09](./textbook/09-run-the-textbook.md).\n\n## Non-goals (GOOD-era habits we refuse)\n\n- Shipping unstamped list results while claiming 7/28 modernity  \n- Requiring `project.faf` or any BEST tooling on this repo’s main branch  \n- Treating stdio as “not real 7/28” — **stdio is a first-class 7/28 transport**  \n- FAF install tax in the AAIF lede — this repo is protocol textbook, not a FAF product\n\n## Registry identity\n\n- MCP Registry name: `mcp-name: io.github.Wolfe-Jam/mcp-better`\n- **Dual packages** (same version, both **stdio**):\n  - `registryType`: **cargo** · `identifier`: `mcp-better` · crates.io\n  - `registryType`: **npm** · `identifier`: `mcp-better` · registry.npmjs.org  \n    (Node shim downloads the native binary from GitHub Releases — no Rust on the host)\n- **Package transport in `server.json` is stdio only — by design.**  \n  Hosts spawn via `cargo install` / `npx mcp-better` on **stdio**.  \n  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`.\n\nSee [`server.json`](./server.json). **Not** `one.faf/*`.\n\n## Publish\n\nShip process: **`/pubbetter`** (skill) · short form [`docs/PUBBETTER.md`](./docs/PUBBETTER.md) · local ship bar:\n\n```bash\nexport PATH=\"$HOME/.cargo/bin:$PATH\"\nbash scripts/ci.sh\n```\n\n## BEST\n\nFor persistent, versionable AI project context beyond a protocol textbook:\n\n**https://faf.one/agents**\n\n## Docs\n\n- [BETTER.md](./BETTER.md) — ladder + claim surface  \n- [docs/BETTER-BEST.md](./docs/BETTER-BEST.md) — BETTER vs BEST  \n- [GETTING-STARTED.md](./GETTING-STARTED.md)  \n- [docs/SDK-NOTES.md](./docs/SDK-NOTES.md) — `serve` vs Discover honesty  \n- [docs/DUAL-PACKAGE-FOR-RUST-MCP.md](./docs/DUAL-PACKAGE-FOR-RUST-MCP.md) — why dual-package (cargo first · FAQ)  \n- [docs/DUAL-PACKAGE-RUST-MCP.md](./docs/DUAL-PACKAGE-RUST-MCP.md) — how: full dual cargo+npm guide  \n- [docs/MCP-DIST-POST.md](./docs/MCP-DIST-POST.md) — lockstep post-step (does not publish)  \n- [SECURITY.md](./SECURITY.md) · [CONTRIBUTING.md](./CONTRIBUTING.md)\n\n## License\n\nMIT — see [LICENSE](./LICENSE).\n",
  "bytes": 9715,
  "sha": "ea14ae8ca1c1dd264aef7d367b47e86b0b5555a56524d3bbbf55ff6195cb06fd",
  "repo_slug": "wolfe-jam/mcp-better",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_wolfe_jam_mcp_better_4f9f5404/readme"
}