mcp-better

mcp-better — 为 7/28 而构建

NONE | GOOD | [BETTER] | BEST

关于 AGENTS.md 的教科书，按上述等级划分——诚实、现代的 MCP，处于 BETTER 阶段。
（协议版本 2026-07-28 — 现代 MCP 版本）

the book is the app is the book

经 AAIF 验证、可运行的现代 MCP 教科书。Rust · rmcp 3.0.x（锁定版本 3.0.1，Tier 1 评估）· Discover · 带时间戳的列表缓存。
教科书： textbook/ — 是什么 · 为什么 · 怎么做 · 原则。
应用： 此二进制文件 + 冒烟测试。一课接一课，一个版本接一个版本——知识不断积累。

BEST（BETTER 加上常驻且实际使用的 project.faf：能编写 Agent 文件的持久化项目上下文）位于 faf.one/agents，从这本教科书再向上一层即可到达。

双包（可选）

我们使用 Cargo。 通过 cargo install 安装。npx 是试用方式。我们不提供 npm install 选项。

→ 为何采用双包 — 定位 + 常见问题
→ 完整指南（操作方法） — 锁步发布、发布顺序、OIDC、评分 + 接线

MCP 之上的 Skills（可选 · 教科书）

同一进程上的一个 Agent Skill（mcp-better-lab），与工具并存：

→ docs/SKILLS-OVER-MCP.md — 扩展 · skills/list · skills/get · 摘要

什么是 7/28？

名称	含义
7/28	时代名称——易于口述，便于打造品牌。“为 7/28 而构建。”
2026-07-28	协议版本——传输线上 / SDK 中使用的日期字符串。

7/28 是个好名字。2026-07-28 是一个日期。
人们说 7/28。机器协商 2026-07-28。

预期内容

1. 为 7/28 而构建——而非在旧服务上临时拼装（官方 rmcp 3.0.x / Tier-1 评估版本）。
2. 诚实的功能面——传输方式和能力与文档及 CI 一致。
3. 路线图拓展这个时代——版本会增加道路，而不是日后才“变成”7/28。

版本	课程（版本本身就是课程）
v0.1	通过 stdio 使用 7/28 — Discover、带时间戳的 ttlMs / cacheScope、稳定顺序、health + echo
v0.2	同属 7/28 时代 + Streamable HTTP 道路 + 路由标头（Mcp-Method / Mcp-Name）
v0.3	同属该时代 + 更深入地确保正确性 — 多次列表 + 重启顺序冒烟测试 · mcp-worse 对比
v0.4	同属该时代 + 双包 — cargo + npm shim · 无需 Rust 工具链即可运行 npx mcp-better
v0.4.3	同属该时代 + confirm_echo MRTR（SEP-2322）+ Agent Skills（mcp-better-lab）— 参见 docs/MRTR-CONFIRM-ECHO.md · docs/SKILLS-OVER-MCP.md
v0.4.4	同属该时代 + 教科书与 0.4.3 线路一致 — 无新增工具 · 目录顺序为 health → echo → confirm_echo
v0.5	同属该时代 + 匹配的客户端完成 MRTR — mrtr-client 完成 confirm_echo

BETTER 的含义

1. 协议诚实性 — 只对实际实现并测试过的功能面声明支持 7/28 / 2026-07-28。
2. 兼容 Discover — 客户端应使用 ClientLifecycleMode::Discover（或 Auto → 7/28），而非只使用旧版 initialize。
3. 列表缓存标记 — tools/list 返回正值 ttlMs 和 cacheScope（静态目录 → public）。SDK 默认值没有标记。
4. 稳定的工具顺序 — 同一进程中，多次调用 list 的顺序保持一致。
5. 传输方式 — 同属同一个 7/28 时代的 stdio（默认）和 Streamable HTTP（--http）。

快速开始（≤10 分钟）

路径	说明
cargo install mcp-better	正式安装 — 我们使用 Cargo。发布于 crates.io，原生二进制文件位于 PATH 中。
npx mcp-better	建议试用 — 无需 Rust，无需编译。这不是正式安装。
npm	已发布的 shim，以便 npx / 某些宿主启动同一个二进制文件。我们不提供 npm install / npm i -g。

试用（推荐）— npx

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

从源代码 / 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

安装（crates.io）— 默认使用 stdio（Cursor / Claude Desktop）：

首次运行 cargo install 会编译一次 Rust 依赖项（通常超过 100 个单元 — rmcp / tokio / …，并非我们的 100 个工具）。只需一次；之后二进制文件即可立即运行。若想跳过编译，可使用 npx mcp-better 试用（见上文）— 这不是正式安装。

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（仅限本地演示 — 参见 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

传输方式选择（CLI 优先于环境变量）：

方式	值
CLI	mcp-better（stdio） · mcp-better --http · mcp-better --stdio
裸参数	http / stdio（含义与标志相同）
环境变量	MCP_TRANSPORT 或 MCP_BETTER_TRANSPORT → stdio | http（若两者均已设置，则优先使用 MCP_TRANSPORT）
HTTP 绑定地址	MCP_BETTER_HTTP_ADDR — 默认值为 127.0.0.1:8787。除非你接受未认证的开放端点，否则不要使用 0.0.0.0。

工具

工具	用途
health	存活状态 — 状态、版本、协议。无副作用。不是 k8s 探针契约。
echo	纯演示 — 原样返回 message。
confirm_echo	教科书式 MRTR（SEP-2322）— 在调用中途确认后回显 · 密封的 requestState。

协议声明（v0.5.0 — 同属 7/28 时代 · 匹配的客户端可完成 MRTR）

范围	状态
时代 / 协议	7/28 · 协商为 2026-07-28（Discover 优先）
传输	stdio（默认） · Streamable HTTP（--http）
HTTP 模式	对 7/28 无状态 · json_response · 本地 Host 防护
路由标头	Streamable HTTP POST 在指定工具名称时使用 Mcp-Method 和 Mcp-Name（SEP-2243）；http-smoke 会验证这一正常路径
能力	tools · resources（技能文档） · experimental 技能扩展
列表缓存	ttlMs=60000、cacheScope=public、顺序为 health→echo→confirm_echo（重启后稳定）
MRTR（可选）	confirm_echo — 调用中途确认 · 密封的 requestState · 匹配的客户端 mrtr-client · docs/MRTR-CONFIRM-ECHO.md
Skills（可选）	mcp-better-lab · skills/list · 摘要 · docs/SKILLS-OVER-MCP.md
说谎的配套服务	mcp-worse — 未加时间戳 + 顺序颠倒（仅用于对比测试）
OAuth / tasks	不在核心介绍范围内

教科书

本书即应用，应用即本书 — textbook/（第 1 季 · 原则）。

开始阅读：textbook/README.md → 实验 第 09 章。

非目标（我们拒绝遵循的 GOOD 时代习惯）

• 声称符合 7/28 现代规范，却发布未加时间戳的列表结果
• 要求此仓库的主分支包含 project.faf 或任何 BEST 工具
• 将 stdio 视为“并非真正的 7/28” — stdio 是 7/28 的一等传输方式
• 在 AAIF 导语中加入 FAF 安装成本 — 此仓库是协议教科书，不是 FAF 产品

注册表身份

• MCP 注册表名称：mcp-name: io.github.Wolfe-Jam/mcp-better
• 双包（版本相同，均使用 stdio）：
  • registryType：cargo · identifier：mcp-better · crates.io
  • registryType：npm · identifier：mcp-better · registry.npmjs.org
    （Node 垫片会从 GitHub Releases 下载原生二进制文件——主机上无需安装 Rust）
• server.json 中的包传输方式仅为 stdio——这是有意设计的。
  主机通过 stdio 使用 cargo install / npx mcp-better 启动。
  Streamable HTTP（--http）是同一二进制文件中可选启用的本地演示功能，属于同一个 7/28 时期；它不是注册表远程包。请在本 README 和 --help 中查找相关信息。

请参阅 server.json。不是 one.faf/*。

发布

发布流程：/pubbetter（技能）· 简版 docs/PUBBETTER.md · 本地发布门槛：

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

BEST

获取超越协议教科书、持久且可版本化的 AI 项目上下文：

https://faf.one/agents

文档

• BETTER.md — 阶梯 + 声明范围
• docs/BETTER-BEST.md — BETTER 与 BEST 的对比
• GETTING-STARTED.md
• docs/SDK-NOTES.md — serve 与 Discover 说明
• docs/DUAL-PACKAGE-FOR-RUST-MCP.md — 为什么采用双包（优先 cargo · 常见问题）
• docs/DUAL-PACKAGE-RUST-MCP.md — 操作指南：完整的 cargo+npm 双包指南
• docs/MCP-DIST-POST.md — 锁步后续步骤（不会发布）
• SECURITY.md · CONTRIBUTING.md

许可证

MIT — 请参阅 LICENSE。