mcp-better

io.github.Wolfe-JamPublished by GitHub account Wolfe-Jamv0.5.0Updated Oct 24, 2026

AAIF-verified modern MCP setup optimised to the 2026-07-28 model (BETTER textbook).

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

A Rust reference MCP server that demonstrates the 2026-07-28 protocol era with three demo tools (health, echo, confirm_echo) and a textbook.

What you can do
  • Check server liveness and negotiated protocol version
  • Return a message unchanged as a pure echo demo
  • Run a mid-call confirmation echo with sealed request state
  • Expose skill documentation as resources and an experimental skills extension
  • Serve over stdio by default, or opt-in Streamable HTTP on a local address
When to use it
Useful if you want a working example of a modern MCP server to test a host, client or Discover-based lifecycle against, or to study the accompanying textbook. It is a teaching and reference artifact, not a tool for real work.
Requirements
Runs locally over stdio. Install with cargo install (Rust 1.85+ and a one-time dependency compile) or try via npx, which downloads a native binary from GitHub Releases without a Rust toolchain. Optional HTTP mode binds to 127.0.0.1:8787 by default, configurable via MCP_BETTER_HTTP_ADDR and MCP_TRANSPORT.
Before you install
The tools are demos only: health, echo and confirm_echo do not touch real data. HTTP mode is described as a local demo and is unauthenticated; the README warns against binding to 0.0.0.0 unless you accept an open endpoint. The npm package is a shim that downloads a binary from GitHub Releases.

Installation

In SourceWeft

  1. Open mcp-better in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

mcp-better — built for 7/28

[Business card · Get yours →]

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)

text
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 (BETTER plus project.faf that is resident and used: persistent project context that authors the agent files) 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?

NameWhat it is
7/28The era name — speakable, brandable. “Built for 7/28.”
2026-07-28The 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

  1. Built for 7/28 — not bolted onto a legacy server (official rmcp 3.0.x / Tier-1 assessed cut).
  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.
VersionLesson (the version is the lesson)
v0.17/28 over stdio — Discover, stamped ttlMs / cacheScope, stable order, health + echo
v0.2Same 7/28 era + Streamable HTTP road + routing headers (Mcp-Method / Mcp-Name)
v0.3Same era + deeper correctness — multi-list + restart-order smokes · mcp-worse contrast
v0.4Same era + dual package — cargo + npm shim · npx mcp-better with no Rust toolchain
v0.4.3Same era + confirm_echo MRTR (SEP-2322) + Agent Skills (mcp-better-lab) — see docs/MRTR-CONFIRM-ECHO.md · docs/SKILLS-OVER-MCP.md
v0.4.4Same era + book matches 0.4.3 wire — no new tool · catalogs named health → echo → confirm_echo
v0.5Same era + matching client completes MRTR — mrtr-client finishes confirm_echo

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. List cache stamps — tools/list returns positive ttlMs and cacheScope (static catalog → public). SDK defaults are unstamped.
  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)

PathWhat it is
cargo install mcp-betterThe install — we are Cargo. crates.io, native binary on PATH.
npx mcp-betterSuggested try — no Rust, no compile. Not the install.
npmA published shim so npx / some hosts can start the same binary. We do not offer npm install / npm i -g.

Try (suggested) — npx

bash
# No Rust toolchain. Downloads the native binary from GitHub Releases.npx mcp-better --helpnpx mcp-better

From source / crates.io (Rust 1.85+)

bash
git clone https://github.com/Wolfe-Jam/mcp-better.gitcd mcp-bettercargo build --binscargo testcargo 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-smokeMCP_BETTER_BIN="$(pwd)/target/debug/mcp-better" \  MCP_WORSE_BIN="$(pwd)/target/debug/mcp-worse" \  cargo run --example contrast-smokeMCP_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.

bash
cargo run --release# install from crates.io — first hit compiles deps once (see above):cargo install mcp-better --version 0.5.0mcp-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):

bash
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):

HowValue
CLImcp-better (stdio) · mcp-better --http · mcp-better --stdio
Bare argshttp / stdio (same meaning as flags)
EnvMCP_TRANSPORT or MCP_BETTER_TRANSPORT → stdio | http (MCP_TRANSPORT first if both set)
HTTP bindMCP_BETTER_HTTP_ADDR — default 127.0.0.1:8787. Do not use 0.0.0.0 unless you accept an unauthenticated open endpoint.

Tools

ToolPurpose
healthLiveness — status, version, protocol. No side effects. Not a k8s probe contract.
echoPure demo — returns message unchanged.
confirm_echoTextbook MRTR (SEP-2322) — echo after mid-call confirm · sealed requestState.

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

SurfaceStatus
Era / protocol7/28 · negotiated 2026-07-28 (Discover preferred)
Transportstdio (default) · Streamable HTTP (--http)
HTTP modeStateless for 7/28 · json_response · local Host guards
Routing headersStreamable HTTP POSTs use Mcp-Method and Mcp-Name when naming a tool (SEP-2243); http-smoke asserts this happy path
Capabilitiestools · resources (skill docs) · experimental skills extension
List cachettlMs=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 companionmcp-worse — unstamped + reversed order (contrast-smoke only)
OAuth / tasksout 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:

bash
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

License

MIT — see LICENSE.

Source: README.md at commit 52d5b52

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.5.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts