mcp-better

mcp-better — 7/28 向けに構築

NONE | GOOD | [BETTER] | BEST

この尺度での AGENTS.md の教科書です — BETTER の段階にある、誠実でモダンな MCP です。
(プロトコル 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：エージェントファイルを作成する、永続的なプロジェクトコンテキスト）は、この教科書から一段上の faf.one/agents にあります。

デュアルパッケージ（任意）

私たちは Cargo です。 インストールには cargo install を使います。npx はお試し用です。npm install は選択肢として提供しません。

→ デュアルパッケージを採用する理由 — 位置づけと FAQ
→ 完全ガイド（方法） — 同期、公開順序、OIDC、スコアとワイヤ

MCP よりスキル（任意 · 教科書）

ツールと同じプロセス上で動作する 1 つのエージェントスキル（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）+ エージェントスキル（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 互換 — クライアントはレガシーな initialize のみではなく、ClientLifecycleMode::Discover（または Auto → 7/28）を使用する必要があります。
3. リストキャッシュのスタンプ — tools/list は正の ttlMs と cacheScope（静的カタログ → public）を返します。SDK のデフォルトにはスタンプがありません。
4. 安定したツール順序 — 同一プロセス内の N 回のリスト要求で順序が変わりません。
5. トランスポート — stdio（デフォルト）と Streamable HTTP（--http）を同じ 7/28 時代に提供します。

クイックスタート（10分以内）

パス	内容
cargo install mcp-better	インストール方法 — Cargo を使います。crates.io から PATH 上にネイティブバイナリをインストールします。
npx mcp-better	お試しにおすすめ — Rust もコンパイルも不要です。インストールではありません。
npm	npx や一部のホストから同じバイナリを起動できるように公開している shim です。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 の依存関係を一度コンパイルします（多くの場合、rmcp / tokio / … など100以上のユニットです。こちらのツールが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 skills 拡張
リストキャッシュ	ttlMs=60000、cacheScope=public、順序は health→echo→confirm_echo（再起動後も安定）
MRTR（任意）	confirm_echo — 呼び出し途中で確認 · 封印された requestState · 対応クライアント mrtr-client · docs/MRTR-CONFIRM-ECHO.md
スキル（任意）	mcp-better-lab · skills/list · ダイジェスト · docs/SKILLS-OVER-MCP.md
虚偽を述べるコンパニオン	mcp-worse — スタンプなし＋順序を逆転（contrast-smoke 専用）
OAuth / タスク	主な対象外

教科書

本はアプリであり、アプリは本です — textbook/（シーズン1 · 原則）。

開始： textbook/README.md → ラボ 第09章。

非目標（私たちが拒否する GOOD 時代の慣習）

• 7/28 のモダンさをうたいながら、スタンプのないリスト結果を配信すること
• このリポジトリのメインブランチで project.faf や BEST のツールを必須とすること
• stdio を「本当の7/28ではない」と扱うこと — stdio は第一級の7/28トランスポートです
• AAIF のリード文に FAF のインストール負担を持ち込むこと — このリポジトリはプロトコルの教科書であり、FAF 製品ではありません

レジストリ ID

• MCP Registry 名：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 時代のもの）であり、Registry のリモートパッケージではありません。この 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 を優先 · FAQ）
• docs/DUAL-PACKAGE-RUST-MCP.md — 方法：cargo+npm デュアルパッケージの完全ガイド
• docs/MCP-DIST-POST.md — 同期を保つ後続ステップ（公開はしません）
• SECURITY.md · CONTRIBUTING.md

ライセンス

MIT — LICENSE を参照してください。