BlockHand

BlockHand — Minecraft Education 用 MCP サーバー

英語 | 繁體中文

BlockHand を使うと、AI エージェントが Minecraft Education Edition の世界で手と目を使えるようになります。Claude Code、Codex、Gemini CLI、Grok、その他のあらゆる Model Context Protocol クライアントから、Agent ロボットを操作したり、構造物を作ったり、ブロックを読み取ったり、領域を比較したり、ゲームイベントに反応したりできます。

ゲームとの通信には、Minecraft Education に組み込まれている /connect (/wsserver) WebSocket コマンドのみを使用します。ゲームにインストールするアドオン、ビヘイビアーパック、MOD、Script API はありません。ゲームプロセスへの注入も、画面の読み取りも行いません。学校のコンピューターにインストールする必要があるのは、AI クライアントだけです。

• 44 個のツールと 2 個のリソース：Agent ロボットの操作、ワールドの編集、24 種類の形状の構築、ブループリント、ブロックの読み取り、領域の比較、対称性の確認、イベントの購読に対応します。
• 高速な構築：形状は可能な限り少ない /fill コマンドにまとめられます（半径 8 の中身が詰まった球体では、2,000 個以上のブロックへの配置が 200 未満のコマンドで済みます）。
• デフォルトでローカル：MINECRAFT_EDU_WS_HOST を変更しない限り、ゲームの WebSocket は 127.0.0.1 で待ち受けます。アカウントやオンラインサービスは不要です。
• 固定アドレスは 1 つ：マシン上のすべての AI セッションがバックグラウンドのハブを 1 つ共有するため、ゲームは常に /connect 127.0.0.1:19131 で接続します。
• ソースから実行する場合、Claude Code、Codex、Gemini CLI、Grok CLI 用のインストーラーを利用できます。

/connect コマンドは公式インターフェイスです。その背後で使われる WebSocket メッセージプロトコルには、公開された安定性の保証がありません。そのため、ゲームのアップデート後は動作を再確認してください。

目次

• クイックスタート
• ソースからインストール
• ツール
• 接続と接続の維持
• 構築を高速に保つ方法
• ブロックの読み取り
• 元に戻す（デフォルトでは無効）
• 設定
• 安全性
• トラブルシューティング
• 既知の制限
• 開発
• ライセンスと商標

クイックスタート

要件：

• チートが有効なワールドの Minecraft Education Edition。接続するプレイヤーにはオペレーター権限が必要です。1.26.32（Windows デスクトップおよび macOS 14 以降）で動作確認済みです。
• AI クライアントを実行するマシンに Node.js 22 以降が必要です。

1. AI クライアントにサーバーを登録する

Claude Code：

claude mcp add blockhand --scope user -- npx -y @gjlmotea/blockhand-mcp

Codex：

codex mcp add blockhand -- npx -y @gjlmotea/blockhand-mcp

mcpServers JSON 設定を読み込むクライアント（Claude Desktop、Cursor、Gemini CLI）：

{
  "mcpServers": {
    "blockhand": {
      "command": "npx",
      "args": ["-y", "@gjlmotea/blockhand-mcp"]
    }
  }
}

VS Code では代わりにトップレベルの servers キーを使用し、各サーバーに type を指定します：

{
  "servers": {
    "blockhand": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@gjlmotea/blockhand-mcp"]
    }
  }
}

各クライアントの設定ファイルの場所：

クライアント	設定ファイル
Claude Desktop	macOS：~/Library/Application Support/Claude/claude_desktop_config.json；Windows：%APPDATA%\Claude\claude_desktop_config.json。Settings → Developer → Edit Config を選択すると開きます
Cursor	すべてのプロジェクト用は ~/.cursor/mcp.json、特定のプロジェクト内では .cursor/mcp.json
Gemini CLI	~/.gemini/settings.json（ユーザー）、.gemini/settings.json（プロジェクト）
VS Code	ワークスペース内の .vscode/mcp.json、または MCP: Open User Configuration コマンドで開くユーザー用の mcp.json

参照元：Claude Desktop、Cursor、Gemini CLI、VS Code。

Finder やスタートメニューから起動したデスクトップアプリでは、シェルの PATH が認識されないことがよくあります。曖昧な「server not responding」エラーが表示されてサーバーを起動できない場合は、npx を絶対パス（macOS では which npx、Windows では where npx）に置き換えてください。

登録後、AI クライアントを再起動してください。

2. ゲームに接続する

サーバーではなく、ゲームがサーバーに接続します。

1. Minecraft Education でワールドを開きます。メインメニューでは不十分です。

2. チートが有効になっていることを確認します。

3. チャットに次のように入力します：

   /connect 127.0.0.1:19131
   

接続が確立すると、チャットに緑色の「✔ BlockHand connected」というメッセージが、ゲーム内の言語で表示されます。対応言語は英語、繁体字中国語、簡体字中国語で、その他のゲーム言語では英語で表示されます。AI に mc_status を呼び出すよう頼むこともできます。正確な connectCommand が返されます。

3. やりたいことを頼む

目の前に半径 6 の中空のガラス球を作ってください。

エージェントを呼び出し、5 ブロック前に歩かせて、小麦を一列に植えてください。

0 64 0 から 20 80 20 の範囲にある家が鏡面対称か確認し、対称性を崩しているブロックを示してください。

ソースからインストール

BlockHand 自体を開発する場合や、インストーラーと doctor チェックを使う場合は、この方法を利用してください。

git clone https://github.com/gjlmotea/blockhand-mcp.git
cd blockhand-mcp
corepack pnpm install --frozen-lockfile
corepack pnpm run build

次のいずれかのインストーラーを使って登録します。

corepack pnpm run setup:claude    # or setup:codex / setup:gemini / setup:grok
corepack pnpm run doctor          # add --client=claude etc. to check another client

インストーラーは設定項目を書き込むだけではありません。

• このマシンの Node の絶対パスを設定するため、nvm、Homebrew、またはシェルの PATH を読み取れないデスクトップアプリでもサーバーを起動できます。
• 設定を変更する前に、保存するものとまったく同じコマンド、引数、環境変数を使って実際に MCP の initialize を実行し、44 個すべてのツールがそろっていることを確認します。
• サーバーがすでに正しく登録されている場合は何もしないため、再実行しても安全です。
• 同じ名前の項目が存在していて内容が異なる場合は、他のユーザーの設定を上書きせず、処理を停止して差分を表示します。
• 各クライアントの公式な mcp add／mcp remove コマンドだけを使って書き込みます。設定ファイルを直接編集することはありません。

corepack pnpm run uninstall:claude（または uninstall:codex など）で削除します。このチェックアウトに属するものと特定できない項目は削除しません。

クライアント	書き込み先	その後
Codex	~/.codex/config.toml	終了して再起動します。デスクトップアプリ、CLI、IDE で共有されます
Claude Code	~/.claude.json（ユーザースコープ）	セッションを再起動します
Gemini CLI	~/.gemini/settings.json（ユーザースコープ）	CLI を再起動します
Grok CLI	~/.grok/config.toml	CLI を再起動します

手動で登録する場合は、クライアントに <NODE> <REPO>/dist/index.js を指定します。<NODE> は node -p "process.execPath" で取得できる絶対パス、<REPO> はチェックアウトの絶対パスです。Claude Code と Gemini CLI ではコマンドの指定方法が異なります。

claude mcp add blockhand --scope user -- <NODE> <REPO>/dist/index.js
gemini mcp add --scope user blockhand <NODE> <REPO>/dist/index.js

Claude Code ではコマンドの前に -- が必要です。Gemini CLI では名前の直後にコマンドを指定します（gemini mcp add [options] <name> <commandOrUrl> [args...]）。ここで -- を指定すると、コマンドが渡されません。Gemini で -- が必要なのは、サーバーの引数が Gemini 自身のオプションと競合する場合に限り、コマンドの後に指定します。BlockHand は引数を取りません。Gemini のデフォルトスコープはプロジェクトのため、グローバルにするには --scope user を指定します。Claude Code のデフォルトスコープはローカルです。--scope project を指定すると、クラス全体で共有しやすい .mcp.json に書き込まれます。参照先：Claude Code、Gemini CLI。

ツール

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

ツール	用途
mc_status	ブリッジの状態、/connect コマンド、購読中のイベント、コマンドカウンターを確認します。問題が発生したら、まずこれを確認してください
mc_await_connection	ゲームが接続されるまで待機します（1 回の呼び出しにつき最大 120 秒）
mc_run_command	専用ツールがない場合に使う、スラッシュコマンドを 1 つ実行します
mc_run_commands	複数のコマンドを順番に実行します
mc_undo_control	1 段階の取り消しを確認、解除、または設定します（デフォルトではオフ）
mc_undo	競合する変更がないことを確認した後、最後に保護された建築操作を取り消します

エージェントロボット（10）

ツール	用途
mc_agent_create	エージェントを召喚します
mc_agent_move	指定した方向に N ブロック歩きます
mc_agent_turn	左または右に 90 度回転します
mc_agent_teleport	迷子になったエージェントをプレイヤーのもとに戻します
mc_agent_act	攻撃、破壊、または耕作を行います。繰り返し実行することもできます
mc_agent_place	インベントリのスロットからブロックを設置します
mc_agent_collect	ドロップしたアイテムを拾います
mc_agent_inventory	数量、空き容量、アイテムの詳細を確認し、アイテムのドロップ、すべてのアイテムのドロップ、移動を行います
mc_agent_sense	エージェントの目となる、調査、データの調査、検知、レッドストーンの検知を行います
mc_agent_program	アクションのシーケンス全体を 1 回の呼び出しで送り、各ステップの結果を取得します

エージェントの方向は、方角ではなく、エージェントが向いている方向を基準とします。

ワールド（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 を解析します。建築を始める前に、プレイヤーまたはエージェントの位置を特定するために使います。

mc_compare_regions は、単一の testforblocks で 2 つの領域を比較します。masked モードでは、コピー元の空気を無視します。そのため、周囲に何があっても、生徒の建築に必要なものがすべて含まれているかを確認できます。

mc_analyze_symmetry は、領域が鏡面対称かどうかを確認し、対称でない場合は異なるセルを示します。領域を保存し、作業用領域に反転したコピーを読み込んで比較した後、作業用領域を復元します。作業用領域が解析対象の領域と重なることはできません。コマンドを送信する前にチェックされます。作業用領域のバックアップに失敗した場合は、何も配置されません。

mc_structure は、デフォルトでメモリに保存します（ゲームを終了すると消えます）。構造物を残すようユーザーから求められた場合に限り、saveMode: "disk" を使ってください。ワールド内に保存された構造物を一覧表示するコマンドはゲームにないため、mc_status は現在のセッション中に保存された名前を報告します。

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

mc_teleport、mc_give、mc_gamemode、mc_effect、mc_player_action（kill、clear、xp、ability）、mc_message（say、tell、title、subtitle、action bar）、mc_feedback（サウンドとパーティクル）。

建築（4）

ツール	用途
mc_build_preview	計画のみ：ブロック数、バウンディングボックス、/fill のバッチ数
mc_build_shape	24 種類の幾何学形状。ほとんどは中空にも対応
mc_blueprint_preview	ブロックごとの設計図をプレビュー
mc_build_blueprint	「座標 → ブロック」のリストから任意の形状を作成。同じブロックは統合されます

グループ	形状
立体	box、sphere、ellipsoid、cylinder、cone、pyramid、prism
線と面	line、curve（滑らかな曲線）、disk、tube（任意の方向に伸びる円柱）
建築パーツ	wedge（単一の斜面）、roof（切妻または寄棟）、arch、stairs、spiralStairs、polywall（折れ線状の壁）
地形と道	heightfield（起伏のある地面）、ribbon（道路または橋のデッキ）
装飾	torus、helix、cross、star、revolution（回転体）

24 種類もの形状があると、実際のリスクは AI が間違った形状を選ぶことです。間違った形状を選んでも失敗にはならず、もっともらしく見えても意図とは異なるものが作られます。そのため、ツールの説明は作りたいもの別に整理し、特に間違えやすい組み合わせを明示しています。

作りたいもの	使用するもの	使用しないもの
傾いた柱、梁、パイプ	tube	cylinder（軸は座標軸に沿うもののみ）
角が鋭い壁	polywall	curve（角が丸くなる）
棟のある屋根	roof	wedge（斜面は 1 つのみ）
塔を上る螺旋階段	spiralStairs	helix（踏み板なし）または stairs（直線）
先細りの塔や煙突	topRadius を指定した cone / pyramid	box の積み重ね
ドーム、花瓶、冷却塔	プロファイルを指定した revolution	オブジェクトごとに新しい形状を作成
起伏のある地面	heightfield	多数の box

読み違えやすいパラメーターがいくつかあります。prism と pyramid の radius は、中心から角ではなく辺までの距離です。roof の ridgeAxis は、斜面が向く方向ではなく、棟が伸びる方向です。heightfield の角の値は、ブロック単位の厚さです。また、arch はアーチそのものを描画し、中央に開口部（幅 2 × 半径 − 1）ができます。

イベント（4）

mc_events_catalog、mc_events_subscribe、mc_events_unsubscribe、mc_events_poll。

イベントはリングバッファに格納され、カーソルを使って読み取ります。dropped > 0 は、ポーリングが遅すぎて一部のイベントが失われたことを意味します。再接続後、サブスクリプションは自動的に復元されます。既知のイベント名には PlayerMessage、BlockPlaced、BlockBroken、ItemAcquired、ItemCrafted、MobKilled、PlayerTravelled、AgentCommand などがあります（詳しくは mc_events_catalog を参照してください）。イベントは対象の事象が実際に起きたときにのみ発生します。BlockPlaced はプレイヤーが手でブロックを設置したときに送信され、/setblock や /fill による設置では送信されません。

リソース（2）

minecraft-edu://connection（ライブ接続状態）と minecraft-edu://capabilities（ブリッジで可能な操作と不可能な操作）。

接続と接続の維持

1台のマシン上のすべてのAIセッション（デスクトップアプリ、CLI、IDE、並行タスク）は、ポート19131と単一のゲーム接続を管理するバックグラウンドのハブを共有します。各セッションのMCPサーバーは、ハブへのシンプルなプロキシです。ハブを必要とする最初のセッションがハブを起動します。開いている各セッションは1分に1回チェックインするため、いずれかのセッションが開いている間はポート19131でサービスが提供され、ハブが停止した場合はすぐに再起動します。最後のセッションとゲームが終了してから約10分後に、ハブは終了します。

• セッション、モデル、AIツールを切り替えても、ゲーム接続は切断されません。
• 通常の読み込み中であれば、/reload all や別のワールドへの移動でも切断されません。メインメニューでは接続は維持されますが、すべてのコマンドに「Unknown command」と返されます。
• Minecraftを再起動した場合、またはハブ側で接続が閉じられた場合（チャットに「Connection closed」と表示されます）にのみ、再度 /connect を入力する必要があります。
• 接続中に /connect を入力する必要はありません。 入力しても何も表示されず、ハングしたように見えますが、入力やコマンドは通常どおり動作します。
• mc_run_command で reload all を送信できます。開発パック、スクリプト、ビヘイビアパックのJSONはこの方法で再読み込みされます。リソースパックは、プレイヤーがチャットで /reload all と入力したときにのみ再読み込みされます。追加のコマンドを送る前に、ワールドの読み込みが完了するまでお待ちください。読み込みが止まっている間も、ブリッジの30秒間隔のキープアライブプローブは実行されます。プローブに3回連続で応答がない場合、ブリッジは接続を閉じます。
• ハブに対応していない古いBlockHandがすでに19131を使用している場合、新しいセッションはランダムなポートでスタンドアロンモードに切り替わります。mc_status が報告するアドレスを使用してください。スタンドアロンモードが19131を使用することはありません。

すばやく再接続するには、ゲーム内で T を押し、↑ で最後に入力したコマンドを呼び出してから、Enterを押します。

建築を高速に保つ方法

ブロックごとに setblock を1回ずつ送信すると、中規模の球体でもWebSocketの往復が数万回発生します。BlockHandのパイプラインは次のとおりです。

shape parameters → inside() test over the bounding box → set of block coordinates
  → merge runs along X → merge rectangles along Z → merge boxes along Y (3-stage greedy)
  → split by the 32,768-block /fill limit
  → send

マージ処理は決定的であり、マージ後のバッチが元のブロック集合と過不足なく一致することをテストで固定しています。中空形状はすべて、同じ「内部判定とシェル隣接判定」から生成されるため、新しい形状に必要なのは inside() 関数だけです。tests/domain/fill-efficiency.test.ts では、すべての形状について、ブロックあたりのfillコマンド数の上限を定めています。

非常に大規模な地形を作成する場合は、座標を自分で計算して mc_run_commands で /fill コマンドをまとめて送信する（1回につき200件）か、.mcfunction ファイルを作成して /function で実行してください。関連する制限については、agents/docs/large-builds.md を参照してください。

ブロックの読み取り

Minecraft Educationには、位置を指定してブロックを直接返すコマンドがないため、読み取りには次のような制限があります。

• mc_test_blockは「はい」か「いいえ」で答える質問です。ブロックIDを推測する必要があります。
• mc_read_blockでは推測は不要です。対象のブロックが空気かどうかを確認し、空気でない場合は、ゲームのエラーメッセージに実際のブロック名が表示されます。結果はローカライズされた表示名（「Dirt」）であり、ブロックID（dirt）ではありません。
• メッセージを解析できない場合、mc_read_blockはエラーを返します。block: nullを含む成功応答を返すことはありません。利用するのはAIです。成功応答でnullを見たAIは、その場所を空いていると確信してしまい、生徒の作品の上に建築するおそれがあります。
• mc_verify_readingは、読み取り専用コマンドを最大2回実行して、解析が引き続き機能することを確認します。ゲームのアップデート後、ゲームの言語を変更した後（対応言語：繁体字中国語、簡体字中国語、英語）、またはmc_read_blockが目に見えるブロックの読み取りに失敗し始めたときに実行してください。変更テストでは、解析ルールが壊れた場合にプローブとパーサーがエラーになることを確認します。

領域全体のブロックを1つずつ読み取るには、ビヘイビアーパックとScript APIが必要ですが、BlockHandはこれを意図的に避けているため、学校のコンピューターに追加インストールは不要です。

元に戻す（既定では無効）

自動で元に戻す機能は既定では無効です。Minecraft Education 1.26.32（macOS）では、小規模な建築の前に元に戻す処理が送信するネイティブの領域チェック（body.version=25）に応答がありませんでした。その後、プレイヤーがチャットに入力した内容も含め、接続上のすべてのコマンドがタイムアウトし、Minecraftを再起動するまで復旧しませんでした。この現象は3回再現しました。このリスクを受け入れられる場合に限り、MINECRAFT_EDU_UNDO_ENABLED=1またはmc_undo_controlのconfigure enabled=trueで有効にしてください。設計メモ：agents/docs/undo/region-undo.md。

有効にすると、元に戻す機能は最大4,096ブロックの操作を1件保持し、ゲームのメモリ内にstructure save ... memoryでスナップショットを保存します（ディスクには書き込みません）。やり直し機能はありません。対象はオーバーワールド、絶対座標の整数値、および基本的な静的建築ブロックです。対応していない建築は、変更を加える前に拒否されます。

設定

すべてにデフォルト値が設定されているため、.env ファイルは不要です。

変数	デフォルト	意味
MINECRAFT_EDU_WS_HOST	127.0.0.1	ゲームの WebSocket の待ち受けアドレスです。デフォルトではループバックのみです（安全性を参照）。ハブの制御ポートは常に 127.0.0.1 で待ち受けます
MINECRAFT_EDU_WS_PORT	19131	ゲームの接続先ポートです。デフォルトでは共有ハブを使用し、それ以外の値（0 など）を指定すると、分離されたスタンドアロンブリッジが実行されます
MINECRAFT_EDU_HUB	auto	0 はハブを無効にします（セッションごとにブリッジを1つ実行）。1 はカスタムポートでハブを強制的に起動します
MINECRAFT_EDU_HUB_PORT	19132	セッションがハブに接続するために使用するローカル制御ポートです。どのプロセスがハブになるかを決めるロックとしても機能します
MINECRAFT_EDU_HUB_DIR	~/.blockhand	ハブの状態ファイル hub.json（ハブのアクセストークンを保持）とログ hub.log を保存するフォルダーです。安全性を参照してください
MINECRAFT_EDU_HUB_IDLE_MS	600000	セッションからのチェックインもゲーム接続もない状態がこの時間続くと、ハブは終了します
MINECRAFT_EDU_HUB_ATTACH_MS	8000	セッションが、起動したばかりのハブからの応答を待つ時間です（500～60,000 ms）。時間内にハブから応答がない場合、セッションはランダムなポートでスタンドアロンブリッジを実行します
MINECRAFT_EDU_CONNECT_NOTICE	on	チャットに緑色の「✔ BlockHand connected」という行を、ゲームの言語で表示します（最初に読み取り専用の time query daytime を1回実行して言語を検出します）。0 にすると無効になります
MINECRAFT_EDU_WS_PORT_FALLBACK	1	優先ポートが使用中の場合、空いているポートを選びます。0 にすると、代わりに失敗します
MINECRAFT_EDU_ENCRYPTION	on	ゲームの接続時に、WebSocket の暗号化ハンドシェイクを試みます。ネゴシエーションが成立しない場合、接続は平文で続行されます。0 にするとハンドシェイクをスキップします
MINECRAFT_EDU_COMMAND_TIMEOUT_MS	10000	ゲームからコマンドの応答が返るまで待つ時間です
MINECRAFT_EDU_KEEPALIVE_INTERVAL_MS	30000	アイドル状態のキープアライブプローブ（time query daytime）の間隔です。応答のない状態が3回連続すると、接続を閉じます
MINECRAFT_EDU_EVENT_BUFFER	500	イベントリングバッファのサイズです
MINECRAFT_EDU_MAX_BUILD_BLOCKS	40000000	1回のビルドで配置できるブロックの最大数です。非ソリッド形状は、スキャン範囲も最大8,000,000ブロックに制限されます
MINECRAFT_EDU_UNDO_ENABLED	0	1 にすると、1段階の自動取り消しが有効になります（上記の警告を参照）
MINECRAFT_EDU_UNDO_MAX_BLOCKS	4096	取り消しの上限です。最大64個の領域で、1～32,768ブロックまで設定できます
MINECRAFT_EDU_STEP_DELAY_MS	100	エージェントのプログラムステップ間のデフォルトの遅延時間です
MINECRAFT_EDU_DEBUG_FRAMES	unset	1 にすると、ゲームから受信したすべての生フレームを stderr に出力します

安全性

• デフォルトでは、ゲームの WebSocket は 127.0.0.1 のみで待ち受けます。MINECRAFT_EDU_WS_HOST でアドレスを変更できます。ゲームのポートでは接続を認証せず、新しい接続が現在の接続に置き換わるため、別のアドレスに設定すると、そこに到達できるすべてのマシンがゲームに代わって接続できてしまいます。ハブの制御ポート（デフォルトでは MINECRAFT_EDU_HUB_PORT の 19132）は常に 127.0.0.1 で待ち受けます。BlockHand 自体はインターネットに接続しません。
• 共有ハブは ~/.blockhand（または MINECRAFT_EDU_HUB_DIR）に 2 つのファイルを保持します。ハブがオフの場合（MINECRAFT_EDU_HUB=0、または MINECRAFT_EDU_HUB=1 を指定せずにカスタムの MINECRAFT_EDU_WS_PORT を指定した場合）、どちらのファイルも書き込まれません。
  • hub.json には、ハブのプロセス ID、ポート、ビルド ID、起動時刻、ランダムなアクセストークンが保存されます。ハブは起動するたびに新しいトークンを作成し、終了時にファイルを削除します。制御ポートへのすべてのリクエストにはベアラートークンが必要です。セッションはこのファイルからトークンを読み取り、ハブに接続します。フォルダーはモード 0700、ファイルはモード 0600 で作成されます。Node.js は Windows では所有者／グループ／その他の権限を設定できないため、これらのモードが適用されるのは macOS と Linux のみです。
  • hub.log はハブのタイムスタンプ付きログです。新しいハブが起動し、ログのサイズが 1 MiB を超えている場合、hub.log.1 に名前が変更されます。MINECRAFT_EDU_DEBUG_FRAMES=1 を指定すると、ゲームからのすべての生フレームもここに記録されます。
• これらのファイルを除き、サーバーはホストに何も書き込みません。saveMode: "disk" を指定した mc_structure は、ゲームにワールドフォルダー内の構造物を書き込ませます。書き込み先はツールの応答に表示されます。
• オンラインサービスのアカウントや認証情報は使用しません。ハブトークンはローカルの制御ポートを保護するためだけのものです。
• mc_run_command はスラッシュコマンドを受け付けます。これらのコマンドが作用するのはローカルのゲームワールド内のみです。その制限はキーワードのブロックリストではなく、コマンドの構造に基づいています。
  1. 1 行のみです。改行と NUL は拒否されるため、1 つのリクエストが 2 つのコマンドになることはありません。
  2. ブリッジを切断またはリダイレクトするコマンド（wsserver、connect、closewebsocket）は、execute でラップされている場合も含めて拒否されます。
  3. それ以外のコマンドには read-only、world-write、wide-effect のいずれかのタグが付けられるため、MCP ホストはツールの注釈に基づいて確認を求められます。
• コマンドラインに渡すブロック ID、セレクター、状態文字列は、まず許可リストのパターンに照らして検証されるため、スペースを使って引数を追加することはできません。
• 共有ハブでは、一度にワールドを変更できる AI セッションは 1 つだけです。2 つ目のセッションによる書き込みツールの使用は、明確なメッセージとともにただちに拒否されます。読み取り専用ツールには影響しません。

トラブルシューティング

プレイヤーからチャットが応答しなくなったと言われた場合。 まずゲームを再起動しないでください。次の順に確認します。

1. ゲーム画面に何が表示されているか（ワールド内、メインメニュー、または読み込み画面）。
2. mc_status：commandState: "timed-out" は、ブリッジ独自のコマンドにも応答がないことを意味します。
3. PlayerMessage をサブスクライブし、プレイヤーに 1 行入力してもらいます。プレイヤーのチャットは type: "chat" イベントを生成します。ゲームがサブスクリプションを確認しないため、イベントを受信できないことだけでは問題の証明になりません。画面表示と照らし合わせてください。
4. ~/.blockhand/hub.log の最後の数行（すべての行にタイムスタンプが付き、拒否されたハンドシェイクも記録されます）。

time などの組み込みコマンドが「Unknown command」と応答した場合、ツールはヒントを表示します。ゲームがワールド内にない可能性が高いです。

mc_status に 19131 以外のポートが表示される場合。 別のプロセスが 19131 を使用しています。lsof -nP -iTCP:19131 -sTCP:LISTEN（macOS）でプロセスを調べ、ls ~/.blockhand でハブが実行中かどうか確認してください。

Windows の Microsoft Store（UWP）版の場合。 Windows アプリの分離機能により、ループバック接続がブロックされます。CheckNetIsolation LoopbackExempt で例外を許可してください。

大規模なビルドが途中で切れる場合。 MCP クライアントは通常、約 60 秒でリクエストをタイムアウトしますが、ツールはフィルの送信を続けます。まず mc_build_preview で fillBatches を確認し、大規模なビルドは分割してください。

既知の制限事項

• ゲーム内のテキストはゲームの言語のままです。 ツールの説明、サーバーの指示、エラーメッセージは英語ですが、ゲーム自体が返す内容（statusMessage と mc_read_block のブロック名）はゲーム内の言語で返されます。
• ワールドでチートを有効にする必要があります。有効でない場合、ゲームはすべてのコマンドを拒否します。
• エージェントが利用できるのは Education Edition のみです。
• イベント名と agent のサブコマンドは Mojang によって正式に文書化されていません。公開情報から確認されたものであり、ゲームのアップデートによって変更される可能性があります。mc_events_subscribe は既知のリストにない名前も受け付けますが、未検証として扱います。
• WebSocket 経由で送信されたコマンドでは @s が常に解決されるとは限らないため、mc_query_target はデフォルトで @p を使用します。
• どのリクエストにも一致しないリクエスト ID が付いた応答が届くことがあります。保留中のリクエストが1つだけで、接続上でタイムアウトが発生していない場合、ブリッジは推定によって応答を関連付け、ログに記録することがあります。タイムアウトが一度でも発生した後は、完全に一致するものだけを受け付けます。変更を伴うコマンドが自動的に再送されることはありません。
• コマンドは最大64件のキューに1件ずつ送信されます。上限を超えるコマンドは command-queue-full として拒否され、タイムアウト内に処理されなかったキュー内のコマンドは破棄され、未送信として報告されます。
• 再ビルド後も、実行中のハブは再起動するまで古いバージョンを使い続けます。ハブを再起動すると、ゲームとの接続が切断されます。

開発

corepack pnpm run verify   # typecheck, tests, build, stdio smoke, shared-hub smoke
corepack pnpm run live     # end-to-end check against a running game (prints the /connect to type)

live は、接続、プレイヤーの位置の読み取り、チャット、時刻の設定、Agent の召喚、感知、L 字型の経路の歩行、中空のガラス球のプレビューと建築、ブロックの確認、設計図の統合、イベントの受信、コマンドゲートのテスト、クリーンアップを順に実行します。デモビルドを保持するには、node scripts/live-check.mjs に --keep を追加します。

src/
  domain/          pure logic, no MCP, ws or Node dependencies
    commands.ts            slash command builders and injection allow-lists
    command-policy.ts      structural gate for raw commands
    build/shapes.ts        the 24 shapes: inside() plus shell-neighbor test
    build/fill-planner.ts  3-stage greedy merge and batch splitting
    build/undo-plan.ts     undo regions, budgets and native region checks
  adapters/ws-minecraft-connection.ts   WebSocket server, request matching, events, reconnects
  application/     services: Agent programs, querytarget parsing, building, undo
  hub/             shared hub, session proxy, cross-session write lock
  server/          MCP server, schemas and the tools
  composition.ts   wiring; accepts a fake connection for tests
  index.ts         stdio entry point

ドメイン層は WebSocket について何も認識しないため、実行中のゲームを使わず、メモリ内のフェイクを使って MCP ツールのパイプライン全体をテストします。

ライセンスと商標

MIT。

これは公式の Minecraft 製品ではありません。Mojang または Microsoft による承認を受けておらず、両社との関係もありません。Minecraft および Minecraft Education は、Mojang Studios と Microsoft の商標です。BlockHand は独立したオープンソースプロジェクトです。