mcp-better

io.github.Wolfe-Jam由 GitHub 帳號 Wolfe-Jam 發布v0.7.0更新於 Nov 19, 2026

Rust MCP textbook for 2026-07-28: annotated tools, MCP conformance suite in CI. AAIF contribution.

已驗證STDIO僅桌面知識與記憶開發者工具

概覽

AI 產生的概覽

一個可執行的 Rust MCP 教科書式伺服器,面向 2026-07-28 協定,提供三個附註解的示範工具與技能文件,用於學習與測試 MCP 用戶端。

可以做什麼
  • 用健康檢查工具查看服務存活狀態與協定版本
  • 原樣回傳訊息,作為純示範
  • 執行帶呼叫中確認的回傳,使用密封的請求狀態
  • 透過 Skills 擴充以資源形式讀取技能文件
  • 以 stdio 或可選的本機 Streamable HTTP 模式提供同一套介面
適用情境
適合需要一個精簡、誠實的參考伺服器來測試 MCP 用戶端對 2026-07-28 協定的支援,觀察工具註解、快取提示與 Discover 行為的實際表現,或跟著配套教材學習。它不是生產力或資料處理工具。
執行需求
以本機程序執行。可用 cargo install 安裝(需 Rust 1.88+,首次建置會編譯相依套件),或用 npx 試用,後者會下載原生二進位檔、不需 Rust 工具鏈。可選的 Streamable HTTP 模式預設綁定 127.0.0.1:8787,可用 MCP_BETTER_HTTP_ADDR 修改;傳輸方式可用 MCP_TRANSPORT 或 MCP_BETTER_TRANSPORT 設定。不需帳號或 API 金鑰。
安裝前請注意
HTTP 模式是本機示範且沒有身分驗證;除非接受開放端點,否則不要綁定到 0.0.0.0。工具皆為唯讀、不修改資料,但 npm 套件會在執行時從 GitHub Releases 下載原生二進位檔,專案的 CI 發布門檻也會連網取得官方一致性測試套件。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 mcp-better,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

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)

text
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, and for the textbook binary every scored check except those that need a suite fixture or an undeclared method.
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.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.
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
v0.6Same era + the spec's own tests — the official MCP conformance suite in CI (Conformance) · cache hints on every list and read · declare what you answer · rmcp 3.10
v0.7Same era + tools say what they do — every tool carries all four annotation hints (read-only, not destructive, idempotent, closed world) · confirm_echo asks only clients that declare elicitation (else -32021) · server/discover stamped like the lists · a strict command line (--version, unknown arguments exit 2)

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 — server/discover, 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. Annotated tools — every tool sets readOnlyHint, destructiveHint, idempotentHint and openWorldHint. A tool with no hints gets the spec's defaults: it may write, may destroy, and reaches the outside world.
  6. 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.88+)

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.7.0 --lockedmcp-better --version   # mcp-better 0.7.0mcp-better --help# optional lying companion (teaching only — not for hosts):# cargo install mcp-better --version 0.7.0 --locked --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 · --version / --help win wherever they appear
Bare argshttp / stdio (same meaning as flags)
EnvMCP_TRANSPORT or MCP_BETTER_TRANSPORT → stdio | http (MCP_TRANSPORT first if both set)
Anything elseAn unknown argument or transport value prints the error and exits 2; nothing falls back to stdio silently
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.

All three are annotated readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false: they read only, change nothing and stay in the process.

Protocol claims (v0.7.0 — same 7/28 era · the official conformance suite in CI)

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) · skills extension (SEP-2640, rmcp native) · prompts and completions not declared (prompts/*, completion/complete → method not found)
Cache hintsdiscover, tools, resources and skills: ttlMs=60000, cacheScope=public · tool order health→echo→confirm_echo (restart-stable)
Tool annotationsall four hints on every tool: read-only · not destructive · idempotent · closed world (tests/handlers.rs)
MRTR (optional)confirm_echo — mid-call confirm · sealed requestState · asked only of clients that declare elicitation (else -32021) · 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 — reversed tool order (the lie) + the SDK defaults left in place: no cache hints of its own (the wire shows ttlMs: 0 + private, valid but uninformative), no tool annotations, and prompts/list / completion/complete answered without being declared · stdio only · same --version · contrast-smoke only
OAuth / tasksout 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).

RunBinary2026-07-28 requirementsSkills
Conformance buildconformance/: mcp-better-conformance100%, no baseline: 196 checks pass across the 50 scenarios, none fail or warn; the suite itself skips one scenario (tasks-status-notifications, 0 checks)38 of 38
Textbookmcp-better, what you installthe 37 scored scenarios: 74 checks pass; 33 fail or warn, each listed in conformance-baseline.yml as fixture or not declared38 of 38

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), which declares elicitation, and by a handler test that a client without it gets -32021 (missing required client capability).

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

Publish

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

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

The ship bar needs Node 18+ and network: it fetches the official MCP conformance suite with npx (pinned version) and, if installed, runs rust-mcp-preflight on server.json (it reads crates.io and the MCP Registry).

BEST

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

https://faf.one/agents

Docs

License

MIT — see LICENSE. Except conformance/ (the unpublished conformance build), which is Apache-2.0: see conformance/NOTICE.


[Business card · Get yours →]

來源:README.md,提交 bfa76f0

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

3
  1. v0.7.0最新Nov 19, 2026
  2. v0.6.0Nov 16, 2026
  3. v0.5.0Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分