BlockHand（積木の手）— Minecraft Education MCP

AI に Minecraft Education Edition の中で手と足を与える：動作（Agent の移動、掘削、設置、耕作、運搬）、目（ブロックのセンシング、座標の照会、ゲームイベントの購読）、造物（10 種の幾何学形状とマスごとのブループリント）。

Minecraft Education の公式ドキュメントに記載された /wsserver 接続コマンド（/connect はエイリアス）を使用して操作します。プロセスへの注入も、ゲームファイルの改変も、画面認識も行いません。接続コマンドは公式インターフェースです。ただし後続の WebSocket メッセージプロトコルには公開された安定性の保証がないため、ゲームのアップデート後には再検証が必要です。

• 42 個のツール、2 つのリソース

• 216 件のユニットテストと統合テスト、ゲームを起動せずに行う 1 つの stdio／プロセスライフサイクル smoke、1 つの実機ライブ検証

• アカウント、トークン、シークレットは一切不要。MCP runtime は loopback のみにバインドし、ゲームファイルやアーティファクトを書き込まない

1. 3 ステップで始める

ステップ 1: 各マシンでのインストールとビルド

cd /你的路徑/minecraft-edu
corepack pnpm install --frozen-lockfile
corepack pnpm run build

Node はプロジェクトの .nvmrc で指定された 22.23.1 である必要があります。pnpm は Corepack によって 11.17.0 に固定されています。Windows と Mac の両方でローカルに依存関係をインストールしてください。他の OS の node_modules をコピーしてこないでください。Minecraft Education の Mac における現在の最低要件は macOS 14 です。

ステップ 2: そのマシンで MCP を 1 回登録する

Codex／Claude Code／Gemini CLI／Grok CLI に対応しており、Windows と macOS の両方で同じです。

先に 2 つの絶対パスを取得する

登録時は必ず絶対パスを使う必要があり、node だけを書くことはできません。デスクトップ版の AI ツールは Finder／エクスプローラーから起動されるため、シェルの nvm、Homebrew、PATH を読み取れません。node と書くとターミナルではテストに通っても、デスクトップ版にすると起動に失敗します。しかもエラーメッセージは通常「server が応答しない」としか出ず、原因を特定しにくいです。

macOS：

node -p "process.execPath"   # Node 絕對路徑
pwd                          # 專案絕對路徑（在 minecraft-edu 目錄下執行）

Windows（PowerShell）：

node -p "process.execPath"
(Get-Location).Path

以下では <NODE> は Node の絶対パス、<REPO> はプロジェクトの絶対パスを表します。サーバーのエントリーポイントは常に <REPO>/dist/index.js です（Windows では <REPO>\dist\index.js と書きます）。パスに空白が含まれる場合は全体を引用符で囲んでください。

インストーラーを使う（4 つすべて対応、推奨）

corepack pnpm run setup:codex     # 或 setup:claude / setup:gemini / setup:grok
corepack pnpm run doctor          # 加 --client=claude 等可診斷其他家

インストーラーは単に設定ファイルにコマンドを書き込むだけではなく、次のことを行います：

• このマシンの絶対 Node パスを自動で入力するため、デスクトップアプリが nvm、Homebrew、shell PATH を読み取れるかどうかに依存しない。

• 書き込む予定の command／args／env を使って、実際の MCP initialize を先に 1 回実行し、42 個のツールがすべて揃っていることを確認してから永続的な設定に触る。古い dist、誤った launcher、実行不能な Node は、書き込み前に失敗する。

• 正しく登録済みの場合は何もしないので、再実行は安全。

• 同名だが互換性がない場合は停止して差分を列挙する。自動で remove/add はせず、他人の timeout、tool policy、別クローンの設定を上書きしないようにする。

• 各社の公式 mcp add／mcp remove サブコマンド経由でのみ書き込む。設定ファイルを手で編集しない——それでは各社自身のスキーマ検証と scope 解決を迂回してしまう。

削除は corepack pnpm run uninstall:codex（または uninstall:claude など）を使います。こちらにも誤削除防止があります：この作業ツリーのものと識別できない entry は拒否されます。

各クライアントの書き込み先と再起動の要件：

読み取り戦略に違いがあります：Codex と Grok には mcp list --json があり、機械可読な出力を直接使えます。Claude Code と Gemini の list は人間可読なテキストのみで env も含まれず、互換性を判断できないため、公式 CLI が書き込んだばかりの設定ファイルを読み取り専用で確認します。書き込みは常に CLI 経由です。

手動コマンド（インストーラーを使いたくない場合）

コマンドは同等ですが、絶対パスは自分で入力する必要があり、事前の initialize 検証や上書き保護もありません。

codex  mcp add minecraft-edu --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
claude mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js
gemini mcp add minecraft-edu <NODE> <REPO>/dist/index.js --scope user --env MINECRAFT_EDU_WS_PORT=19131
grok   mcp add minecraft-edu --scope user --env MINECRAFT_EDU_WS_PORT=19131 -- <NODE> <REPO>/dist/index.js

つまずきやすい違いが 3 つあります：

• Gemini の command と args は位置引数で、名前の後に続けます。-- による区切りはありません。

• Gemini のデフォルトの scope は project で、グローバルに使うには --scope user と明示する必要があります。

• Claude のデフォルトの scope は local（現在のディレクトリでのみ有効）です。--scope project はプロジェクトルートの .mcp.json に書き込まれ、repo と一緒に共有できます。クラス全体で共有するときはこれを使います。

手動で設定ファイルを編集する（インストーラーが使えない場合の代替）

Claude Code と Gemini CLI は JSON を使います：

{
  "mcpServers": {
    "minecraft-edu": {
      "command": "<NODE>",
      "args": ["<REPO>/dist/index.js"],
      "env": { "MINECRAFT_EDU_WS_PORT": "19131" }
    }
  }
}

Codex と Grok CLI は TOML を使います：

[mcp_servers.minecraft-edu]
command = "<NODE>"
args = ["<REPO>/dist/index.js"]
env = { MINECRAFT_EDU_WS_PORT = "19131" }

Windows の補足

• Node の絶対パスは通常 C:\Program Files\nodejs\node.exe ですが、nvm-windows を使う場合は C:\Users\<你>\AppData\Roaming\nvm\v22.23.1\node.exe のようになります。

• JSON 設定ファイル内のバックスラッシュはエスケープが必要です："C:\\Program Files\\nodejs\\node.exe"。TOML では代わりにシングルクォートのリテラル文字列を使えます：command = 'C:\Program Files\nodejs\node.exe'。

• Minecraft Education が Microsoft Store の UWP 版の場合、loopback が Windows のアプリ分離によってブロックされるため、追加の CheckNetIsolation LoopbackExempt の除外が必要です（第 8 節参照）。

登録後

その AI ツールを完全に終了して再起動します——デスクトップ版はウィンドウを閉じるのではなく、本当にプログラムを終了してください。その後、doctor で確認します（Minecraft には触れず、設定も変更しません）：

corepack pnpm run doctor

Node のバージョン、ビルド成果物、プラットフォーム要件、登録状態をチェックし、実際に登録されている command／args／env でもう一度 MCP initialize を実行します。設定が無効な Node を指しているのに見かけ上は正常となることを防ぎます。--json を付けると構造化された出力が得られます。各 CLI に直接問い合わせることもできます：

codex mcp list
claude mcp list
gemini mcp list
grok mcp list

あるいは AI に mc_status を呼び出させてもよいです。connectCommand が返ってくれば server が起動できることを意味します。

マシンごとにそれぞれ 1 回ずつ登録する必要があります：Windows ノート、Mac、別のコンピュータでは Node とプロジェクトの絶対パスが異なるため、設定を互いにコピーすることはできません。同じマシン上では、同じツールのデスクトップ版／CLI／IDE は同じ設定を共有します。

ステップ 3: ゲーム内で手動で接続する

corepack pnpm run connect

この互換エントリーは操作方法を表示するだけで、Minecraft を開くことはなく、フォアグラウンドウィンドウを切り替えることも、キーボードをシミュレートすることもありません。Windows PowerShell の自動入力機能は削除されました。Mac でも AppleScript による自動化は追加していません。

方向を間違えやすいですが、ゲームが接続しに行く側で、MCP server が接続される側です。

1. 現在の AI の会話で mc_status を呼び出し、返ってきた connectCommand をコピーします。

2. Minecraft Education を開き、ワールドに入ります（メインメニューに止まっているだけではダメです）。

3. ワールドで Cheats が有効になっている必要があり、操作者には Admin／OP 権限が必要です。

4. チャット欄に手動で入力します。例：

/connect 127.0.0.1:19131

Connection established と表示されたら完了です。あとは AI に「前に中空のガラスの球を建てて」と言うだけです。

再接続するときは全部を打ち直す必要はありません：チャット欄で T を押して開き、↑ で直前のコマンドを呼び出して、Enter を押します。

初期バージョンには「約 60 秒アイドル状態が続くと必ず切断される」というバグがありました：ハートビートが WebSocket pong frame しか認識しないのに、Bedrock／Education のクライアントは pong を返さないため、健全な接続が自分のハートビートによって終了させられていました。現在は修正済みです（受信した任意のパケットで活性を判定し、アプリケーション層のプローブも併用）。アイドル状態で切断されることはもうないはずです。それでも切断される場合は、再ビルドした dist/ を実行しているかどうかを先に確認してください。

19131 を固定で覚えないでください：デスクトップ版、CLI、IDE、または複数の task が同時に起動している場合、後から起動した MCP は別の空きポートを取得することがあります。常に今操作したい task が報告したコマンドを使ってください。

Related MCP server: Minecraft MCP Bot

2. 実機検証

まずはゲームを起動しない安全な診断を行います：

corepack pnpm run doctor
# 機器可讀版本
corepack pnpm blockhand doctor --json

doctor は永続的な設定を変更せず、Minecraft も起動しません。隔離された loopback socket を一時的に作成し、launcher、42 tools、2 resources、stdio EOF、待受ポートの解放を検証し、Codex に実際に登録されている command／args／env でもう一度 initialize を完了させます。設定が無効な Node を指しているのに見かけ上正常となることを防ぎます。

ゲームが起動していて、ワールドが読み込まれ、チートが有効になった後：

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run live

スクリプトは入力すべき /connect を表示し、接続を待ってから、完全なパスを一通り実行して各項目を PASS／FAIL で報告します：接続 → プレイヤー座標の読み取り → ゲーム内での発言 → 時刻の設定 → Agent の召喚 → センシング → L 字経路の移動 → プレビュー建造 → 中空ガラス球の建造 → 戻ってブロックが実際に存在するかを検証 → ブループリントの結合 → イベントの購読と受信 → ポリシーゲート → デモ建築の撤去。

ゲームアップデート後

ブロック読み取り（mc_read_block）は testforblock の失敗メッセージのテキスト形式に依存しています。その形式には公式の安定性保証はありません。Minecraft Education が自動更新で文言を静かに変更したり、ゲーム言語が繁体字中国語／簡体字中国語／英語以外に変わったりすると、この経路は機能しなくなります。

機能しなくなる様子は静かです：ツールが壊れるわけではなく、「読み取れない」と言い始めるだけです。そのため本プロジェクトではこれを毎回の live で実行する定期チェックにはあえてしていません——定期チェックは緑のランプを見て安心する習慣を育ててしまいます。本当に判断が必要なタイミングは「挙動が怪しくなったその場」であり、毎週決まったタイミングで実行するチェックではありません。

必要になったときに能動的に判断する形にしています：

mc_verify_reading  { position: 任一座標 }

これは最大 2 つのコマンドを送るだけで、ワールドに一切書き込みません。parseable を返します：

• true → 解析経路は正常で、mc_read_block の結果は信頼できます。

• false → プロトコルがドリフトしています。この場合、mc_read_block は null ではなく常にエラーを返します（第 3 節参照）。そのため、「読み取れない」を「そこは空である」と誤認する人はいません。返ってくる raw はゲームの生のメッセージなので、src/domain/block-report.ts の PATTERNS と突き合わせれば、どのパターンを追加すべきか分かります。

これを実行したくなるサインが 3 つあります：

1. mc_read_block がエラーを返し始めたが、ゲーム内ではそのマスに明らかにブロックがあるのが見える。

2. ゲームを更新したばかりで、次に読み取りに依存する何か（採点、対称性分析）を行う予定がある。

3. ゲーム言語を変更した。

server の instructions にも同じ手がかりが入れてあるので、AI は挙動が怪しいときに自分でこのツールを見つけられます。あなたが覚えておいて促す必要はありません。

デフォルトではデモ建築を air に戻し、ワールドにゴミを残しません。残して見たい場合：

cd gjlmotea/vibe/mcp/minecraft-edu && node scripts/live-check.mjs --keep

ゲームを開く必要のない検証（型チェック、テスト、build、stdio ハンドシェイク、STDIN クローズによるポート解放とポート占有失敗を一度に実行）：

cd gjlmotea/vibe/mcp/minecraft-edu && corepack pnpm run verify

3. ツール面

接続とフォールバック（4）

Agent — 手と足（10）

Agent の方向は自分自身の向きに対する相対であり、世界の方角ではありません。

ワールド（13）

mc_set_block、mc_fill、mc_clone、mc_test_block、mc_read_block、mc_verify_reading、mc_compare_regions、mc_analyze_symmetry、mc_query_target、mc_summon、mc_world_settings（時間／天気／ゲームルール／難易度）、mc_structure（ストラクチャーの保存・読み込み）、mc_ticking_area。

mc_query_target は querytarget が返す JSON 文字列をパースします。これはプレイヤーまたは Agent の座標を取得する正規の方法です——建造する前にまずこれを呼びます。

読み取りには構造上の制限があります。ないものとして装うより、はっきり説明するほうがよいのです。 Education には「任意のブロックを読み取る」コマンドがないため、次のようになります：

• mc_test_block は○×問題です：先にブロック ID を推測する必要があります。

• mc_read_block は推測不要です——空気をセンチネルとして問い合わせ、推測が外れるとゲームのメッセージが実際のブロックを教えてくれます。ただし返ってくるのはローカライズされた表示名（「土」）であり、ブロック ID（dirt）ではありません。mc_set_block にそのまま渡すことはできません。パースできない場合、このツールは null の成功応答ではなくエラーを返します——理由は後述。

• mc_verify_reading は上記のパース経路がまだ有効かどうかを能動的に検証します。授業の前に一度実行すれば mc_read_block の結果を信頼できるかどうか分かります。

• mc_compare_regions は 1 つの testforblocks で領域全体を比較します。マスごとの比較は数百マスを超えるとホスト側のタイムアウトに当たりますが、これは当たりません。masked モードは元の空気を無視するので、「あるべきものがそこにあるか」を周囲に何が増えたかにかかわらず確認するのに適しています——生徒の作品を採点するのがまさにこの形です。

なぜパース失敗時にエラーを返し、null を返さないのか

このツールの利用者は AI であり、AI はシステムが壊れていると疑わないからです。

「成功」の応答に block: null が付いていると、「読み取れた、そこは空だ」と読まれやすくなります。すると AI はこの誤った認識に基づいて非常に自信を持って作業を続けます——例えば、生徒が 1 時間かけて建てた作品を空き地として上書きしてしまい、しかもあとでエラーの記録が何も残りません。人間は null を見ると変だと感じて立ち止まりデバッグしますが、AI はそうしません。

エラーはデータとして使い続けることができません。そこが重要なのです。

mc_verify_reading はもう半分を担います：そのマスが何かを事前に知る必要はありません——そのマスが空気なら基岩を問い合わせて（空気が基岩であるはずはなく、必ず不一致になる）失敗メッセージを引き出します。そのマスに何かあれば、最初の問い合わせで既にメッセージが得られます。どちらの経路でもメッセージが必ず得られ、最大 2 コマンドで、ワールドに一切書き込みません。

この防衛線はミューテーションテストで守られています：意図的にパース規則を壊すと、プローブとパーサーを合わせた 7 つのテストが必ず赤になります。

マスごとに領域全体を読み取りたい場合はビヘイビアパックと Script API を使ってください。本プロジェクトはあえてその道を選びません。学校のコンピュータにインストール手順が 1 つ増えてしまうからです。

同じ建物を繰り返し変更する

mc_structure の saveMode はまさにこのために設計されています：

バージョン管理は名前を付けることです：castle_v1、castle_v2。同名はそのまま上書きされるので、バージョンを変える前に名前を変えてください。

ゲームには**「保存済みストラクチャーを一覧表示する」コマンドがありません**。そのため、何を保存したかは名前で覚えるしかありません。ブリッジは今回の接続で保存した名前のリストを覚えており、mc_status に問い合わせると見られます——ただし、これはこのプロセスの間に限られ、再起動すると消えます（disk モードのファイルは残りますが、名前は自分で覚える必要があります）。

対称性分析——作品の採点

mc_analyze_symmetry は領域が鏡像対称かどうかをチェックし、非対称の場合にどのブロックが非対称かを指摘します。「いいえ」とだけ返すのではありません。

原理：testforblocks は平行移動の比較しかできず鏡像はできないため、まず structure save で領域を保存し、structure load の mirror パラメータで鏡像を一時領域に配置してから、2 つの領域を比較します。全体が通ればそのまま満点。通らない場合のみ n³ マスに細分してマスごとに比較し、スコアは一致したマスの割合です。

このツールは一時的にワールドへ書き込みます。流れは以下のとおりで、どのステップで失敗しても後始末のつかない状態は残しません：

1. 分析領域を保存する——失敗したら中止（通常はチャンクが未読み込み）。

2. 先に一時領域をバックアップする——バックアップに失敗したら中止し、決して鏡像コピーを配置しない。ワールドは無傷のまま。

3. 鏡像コピーを配置して比較する。

4. 成功・失敗にかかわらず一時領域を復元し、一時ストラクチャーを削除します。復元結果は scratchRestored に正直に報告し、失敗を隠しません。

一時領域は分析領域と重なってはいけません。重なると鏡像コピーが元の建物を上書きしてしまうからです。このチェックはどのコマンドを送信する前に行われます。

プレイヤーとフィードバック（7）

mc_teleport、mc_give、mc_gamemode、mc_effect、mc_player_action（kill／clear／xp／ability）、mc_message（say／tell／title／subtitle／actionbar）、mc_feedback（効果音／パーティクル）。

建造（4）

イベント — 感知（4）

mc_events_catalog、mc_events_subscribe、mc_events_unsubscribe、mc_events_poll。

イベントはリングバッファに入り、カーソルで連続して読み取ります。dropped > 0 はポーリングが遅すぎて、一部のイベントが永久に読み取れなかったことを意味します。再接続後は自動的に再購読されます。

4. なぜ建造がフリーズしないのか

素朴なやり方では、ブロックごとに 1 回 setblock を送ります。半径 20 の球体は 33,000 マス以上あり、3 万回以上の WebSocket 往復になります——現実的にはハングアップと同じです。

BlockHand のパイプラインは次のとおりです：

形狀參數 → inside() 判定掃描 → 方塊座標集合
        → X 連段合併 → Z 矩形合併 → Y 立方合併（三階段 greedy）
        → 依 Bedrock 單次 /fill 上限 32768 拆批
        → 送出

半径 8 の球体は 2,000 個余りのブロックが 200 本未満のコマンドに圧縮されます。また、結合結果は決定的です——同じ入力は常に同じバッチの集合になり、「結合後に覆われるブロックの集合は元の点の集合と完全に一致しなければならない」ことをテストで固定しています。多くも少なくもなりません。

中空形状は、形状ごとに中空用の数学を個別に書くのではなく、すべて「内部判定＋外＋外殻の隣接テスト」で実装されています。新しい形状を追加するときは inside() を書くだけで、中空の挙動は自動的に一貫します。

5. 安全境界

やらないこと

• 外部ネットワークには接続しない：127.0.0.1 でのみ WebSocket をリッスンします。

• MCP runtime はホストのファイルを書き込まない：artifact の出力パスは一切ありません。ユーザーが明示的に setup:<client>／uninstall:<client> を実行したときだけ、そのクライアントの公式 CLI がローカルの MCP 設定を更新します。

• 例外を 1 つ明確にしておきます：mc_structure の saveMode="disk" は、ゲームを通じてストラクチャーをファイルとして書き出し、Minecraft のワールドフォルダに保存します。これは MCP runtime がファイルを書くのではありませんが、実際にユーザーのハードディスクに何かを残します。そのためデフォルトは memory（一時保存、ゲームを閉じると消える）であり、ユーザーが明確に残したいと言ったときだけ disk を使うべきです。また、ツールの応答は必ずどこに書き込んだかを伝えます——静かにファイルを残したりはしません。

• シークレットには触れない：プロジェクト全体に token、アカウント、認証情報はありません。

• 能動的に接続しない：ゲームが /connect で入ってこない限り、すべてのツールは「こうすればよい」と分かるエラーメッセージを返し、静かに失敗することはありません。

mc_run_command のゲート

mcp/README.md のアーキテクチャ原則 4 は、任意実行の入口を拒否することを要求しています。ここでの判断は：slash コマンドのスコープは完全にローカルのゲームワールド内にあり、ホストのファイルシステム、プロセス、ネットワークには触れません。そのため、任意のコード実行と同義ではありません。本当にブロックすべきなのはブリッジを無効化する操作です。したがって、ポリシーは意図を推測するキーワードブラックリストではなく、構造的です：

1. 単一行のみ許可——改行と NUL は直接拒否し、\n で 1 つのリクエストを 2 つのコマンドに分割することはできません。

2. wsserver と connect は拒否——それらはゲームを別のエンドポイントに向けてしまい、以後すべてのツールが機能しなくなります。

3. その他のコマンドは read-only／world-write／wide-effect のリスクレベルを付け、MCP Host が annotation に基づいて人間の確認が必要かどうかを判断します。

コマンドラインに挿入される可能性のあるすべてのブロック ID、セレクター、状態文字列は、まずホワイトリストの正規表現を通し、空白を使って余計なパラメータを組み立てることを防ぎます。

教室向けガード（デフォルト有効）

上記の第 3 点は決定権を Host に委ねますが、それは単独開発の状況では成り立ちます。しかし、このプロジェクトの使用現場は教室です：

• Host が自動承認に設定されている可能性があります——教師が授業を円滑に進めるために簡単にそうします。

• 生徒はその AI に話しかけられるだけで、コマンドを実行できるのと同じです。ブリッジを突破する必要はなく、モデルを説得するだけでいいのです。

• 誤用は raw コマンドすら必要ありません：mc_player_action は元々 @a を受け付け、kill は選択肢の 1 つです。そのため、raw コマンドだけをブロックするのは形だけの対策で、両方の経路をブロックする必要があります。

ルールは、教師に一言で教えられる形にしています：「人」に作用する動作は、必ず名前を名指ししなければならない。

「クラス全員を殺す」は、これによって 1 つの言葉から、一人ひとりを名指ししなければならないものに変わります。一方、合法的な教室管理（特定の生徒のインベントリを消すなど）にはまったく影響しません。

無効にするには MINECRAFT_EDU_CLASSROOM_GUARD=0 を設定します——エラーメッセージ自体がこのことを教えてくれるので、ツールが壊れたと誤解されることはありません。

商標

Minecraft Usage Guidelines に従い、第三者のツールは公式製品のように見えてはなりません。製品名 BlockHand は意図的に Minecraft の商標を含んでいません。minecraft-edu はこのプライベートワークスペース内の説明的なフォルダ名にすぎません。将来外部に公開する場合は、パッケージ名と公開される露出はすべて再検討する必要があります。

6. 設定

すべてにデフォルト値があり、.env は必須ではありません。

7. モジュールマップ

src/
  domain/                     純資料與純邏輯，不依賴 MCP、ws 或 Node
    contracts.ts              型別、已知事件名、Bedrock fill 上限
    coordinates.ts            絕對／相對／局部座標格式化與邊界檢查
    commands.ts               所有 slash 指令建構器 + 注入白名單
    command-policy.ts         raw 指令的結構性閘門
    build/shapes.ts           十種形狀；inside() + 外殼鄰居測試
    build/fill-planner.ts     三階段 greedy 合併 + 依上限拆批
  ports/minecraft-connection.ts   連線抽象；測試靠它塞假件
  adapters/ws-minecraft-connection.ts  WebSocket 監聽、requestId 對應、事件緩衝、重連重訂閱
  application/
    blockhand-service.ts      Agent 程式展開、querytarget 解析、事件
    build-service.ts          規劃與執行分離（先讀後寫）
  server/
    create-server.ts          server 實例與給 Host 的操作指引
    schemas.ts                共用 zod 片段
    tool-kit.ts               回應塑形與錯誤包裝
    tools/                    session／agent／world／player／build／event
  composition.ts              組裝；可注入假連線
  index.ts                    stdio 入口

ドメイン層は WebSocket の存在をまったく知らないため、MCP ツールパイプライン全体を純粋なメモリ内フェイクでテストできます。tests/integration/mcp-client.test.ts の 16 のテストはゲームを起動する必要がありません。

8. 既知の制限

• ワールドでチートを有効にする必要があります。そうしないと、ゲームはすべてのコマンドを拒否します。これは Minecraft のルールであり、バグではありません。

• macOS で実機ライブ検証済み（Claude Code パス）：2026-08-25 に macOS 上で Claude Code を介して /connect、大量の読み書き（単一セッションで 45,000 ブロック以上、fill／setblock／testforblock／teleport を含む）、および切断・再接続の全フローを完了しました。まだ検証されていないのは「Finder から Codex Desktop を起動する」という起動パスです。GUI 起動は PATH と環境変数の継承方法が異なるため、それぞれ個別に実測する必要があります。

• Agent は Education Edition 専用で、通常の Bedrock 版にはこの機能はありません。

• イベント名と agent サブコマンドは Mojang によって正式に文書化されていません。公開された観察に基づいています。ゲームのアップデートで動作が変わる可能性があります。mc_events_subscribe はリスト外の名前を許可しますが、未検証としてマークされます。

• agent setitem のパラメータ順序は未確認です。現在専用ツールは作成されておらず、必要な場合は mc_run_command を使用してください。

• @s は WebSocket コマンドでは常に解決できるとは限りません。ブリッジから送信されたコマンドにはエンティティ ID がないため、実際に querytarget @s を試すとまったく応答がありません。そのため mc_query_target はデフォルトで @p（最も近いプレイヤー）を使用し、live も @p → @a → @e[type=player] の順に試して、各結果を報告します。

• 大規模な建造は MCP ホストのリクエストタイムアウトに達する可能性があります。建造ツールは fill を1つずつ送信してゲームの応答を待ちます。実測では半径6の中空球（126個）で約13秒かかりますが、ゲームがビジーな場合はさらに長くなります。MCP クライアントのデフォルトタイムアウトは通常60秒で、それを超えるとホスト側で切断されます（ツール自体はまだ実行中です）。まず mc_build_preview で fillBatches を確認し、数が多い場合はバッチに分けて建造してください。

• 各 BlockHand プロセスは依然として独自のリッスンポートを保持します。STDIO クライアントが閉じると、サーバーは Minecraft WebSocket を同期して閉じ、ポートを解放します。AI ツールのデスクトップ版が複数のタスクを同時に読み込む場合、またはデスクトップ版／CLI／IDE が並行して実行される場合、最初のものが優先ポートを取得し、残りは自動的に空きポートを取得します。常に現在のタスクの mc_status.connectCommand を使用して、ゲームを実際に操作するインスタンスに接続してください。固定ポートが必要な場合は、各クライアントに異なる MINECRAFT_EDU_WS_PORT を設定するか、MINECRAFT_EDU_WS_PORT_FALLBACK を 0 に設定します。

• ハンドシェイク後の最初のコマンドはかつて必ずタイムアウトしていましたが、現在は修正されています。4回の独立した実機実行で再現しました。ゲームがサーバーに復号化器がセットアップされる前に暗号化フレームを送信し、ストリームのずれにより次のリクエストの応答が読み取れなくなりました。AES-CFB8 は自己同期するため、最初のコマンドのみに影響します。アダプタは現在、ハンドシェイク完了後に読み取り専用の time query daytime を自動的に送信してその損失を吸収し、結果を破棄するため、呼び出し側の最初のアクションは正常に動作します。stderr には primed post-handshake stream が記録されます。

• イベントは実際に発生したときのみトリガーされます。BlockPlaced はプレイヤーが手動でブロックを置いたときのみ発行され、/setblock と /fill は対象外です。イベントを受け取るには、まずサブスクライブし、その後イベントを実際に発生させる必要があります。

• 一部の応答の requestId がリクエストと一致しません（すべてゼロの ID が返されることが観察されています）。アダプタは「保留中のリクエストが1つだけ」の場合、その応答をそのリクエストに割り当て、stderr に推測によるものであると記録します。それ以外の場合、それらのリクエストは静かにタイムアウトし、呼び出し側は実際の失敗理由ではなく「応答なし」だけを見ることになります。

• 一度に維持するゲーム接続は1つのみ。新しい接続は古いものを置き換えます。

• 実機検証済みの環境：Minecraft Education 1.26.32.0（Win32 デスクトップ版）。Microsoft Store の UWP 版に切り替える場合、ループバックが Windows アプリの分離によってブロックされるため、追加の CheckNetIsolation LoopbackExempt 免除が必要です。macOS 14+ の受け入れマトリックスは agents/docs/macos-support.md を参照してください。

9. ライセンス

このプロジェクトは MIT License の下で公開されています。商用利用を含め、自由に使用、変更、配布、再ライセンスできます。唯一の条件は、元の著作権表示とライセンス条項を保持することです。

ソフトウェアは「現状のまま」提供され、明示的または黙示的な保証は一切ありません。

Minecraft、Minecraft Education は Mojang Studios と Microsoft の商標です。このプロジェクトは両者とは提携関係になく、承認も受けていません。