回報 WebSocket 橋接是否在監聽、Minecraft 是否已連入、遊戲內應輸入的 /connect 指令、已訂閱事件與累計指令數。任何工具失敗時先查這個。無副作用。

阻塞等待遊戲連上橋接，最多等 timeoutSeconds 秒。逾時不算錯誤，只是回報 connected=false。適合在請使用者輸入 /connect 之後呼叫。

送出一條原始 slash 指令，涵蓋本 server 沒有專用工具的功能。只接受單行、不得換行串接，並拒絕 wsserver／connect（那會切斷本橋接）。前導斜線可有可無。

照順序送出多條原始指令，每條都各自通過政策檢查。適合手動編排的巨集；大量方塊請改用 mc_build_shape 或 mc_build_blueprint，它們會自動合併成最少的 fill。

在玩家旁邊生成 Agent。已存在時重複呼叫是安全的。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

讓 Agent 往指定方向走 steps 格，每格一條指令。被方塊擋住時該步會失敗但不會中斷後續。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

讓 Agent 原地左轉或右轉，每次 90 度。times=2 等於轉身。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

把 Agent 叫到玩家旁邊。Agent 走丟、卡住或掉進洞裡時用這個回收。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

對指定方向做動作：attack 攻擊生物、destroy 挖掉方塊並收進背包、till 把泥土翻成耕地。repeat 可連續執行。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

從指定背包槽（1–27）取出方塊放到指定方向。槽位空的時候會失敗。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

撿取 Agent 附近的掉落物。item 留空代表全部撿。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

對 Agent 背包做一件事：count 查槽內數量、space 查剩餘空間、detail 查物品細節、drop 丟出指定數量、dropAll 清空整槽方向、transfer 在槽之間搬移。Agent 是 Education Edition 專屬的機器人，必須先用 mc_agent_create 召喚。方向是相對 Agent 自身面向，不是世界方位。

讀取 Agent 周圍狀態，不改變世界：inspect 看方塊種類、inspectData 看方塊資料值、detect 偵測該方向是否有實體方塊、detectRedstone 偵測紅石訊號。這是 Agent 的「眼睛」，行動前先看。

把一連串 Agent 動作當成一支程式依序執行，這是讓 Agent 真正「做事」的主力工具：邊走邊鋪路、挖一條隧道、耕一整片田都用它。每步結果都會個別回報，可設定失敗即停。

在指定座標放一個方塊。大量方塊請改用 mc_fill 或 mc_build_shape——逐格呼叫這個工具會非常慢。

用同一種方塊填滿 from 到 to 的長方體。Bedrock 單次上限 32768 格；超過請改用 mc_build_shape，它會自動拆批。mode=hollow 只留外殼、outline 只留邊框。

把 begin–end 的區域複製到 destination。cloneMode="move" 會把原地清空。適合把手工蓋好的樣板量產。

不改變世界，只回報該座標是否為指定方塊。建造前確認地形、或驗證剛才蓋的東西時用。

檢查一塊區域是否左右（或前後）對稱，並在不對稱時指出哪幾塊不對稱。批改學生作品用這個：分數是對稱格子的比例，不是憑感覺。原理：testforblocks 只會平移比對不會鏡像，所以先用 structure save／load 的 mirror 參數做出鏡像副本，再跟原區比對。⚠️ 這會暫時寫入 scratch 指定的暫存區：流程一定先備份該區內容，比對完立刻還原；備份失敗就中止且不動世界。scratch 不可與分析區重疊，否則鏡像副本會蓋掉原始建築。區域受 structure 指令上限限制（64×384×64）。

回報該座標實際上放著什麼，不需要你先猜。Education 沒有讀取方塊的指令，這裡是拿空氣當哨兵去 testforblock，猜錯時遊戲的訊息會把實際方塊講出來。注意：回傳的是在地化顯示名稱（例如「泥土」）而不是方塊 ID（dirt），不能直接餵回 mc_set_block；要用 ID 判斷請改用 mc_test_block。訊息格式沒有官方保證，解析不出來時 block 會是 null 並附上原始訊息，不會亂猜。

讀方塊靠的是 testforblock 失敗訊息會洩漏方塊名稱，而那個訊息格式沒有官方穩定性保證。遊戲改版改了文案、或遊戲語言不是繁中／簡中／英文，解析就會失效——而且失效的樣子是安靜的。這支探測會主動驗證解析路徑是否仍然有效，上課前跑一次就知道 mc_read_block 的結果能不能信。它不需要事先知道那格是什麼：若該格是空氣，就拿基岩去問（保證不符）逼出失敗訊息；若該格有東西，第一問就已經給了訊息。最多兩條指令，完全不寫入世界。parseable=false 代表協定已漂移，此時 mc_read_block 的結果一律不可信。

用一條指令比對整片區域，適合檢查學生蓋的東西跟參考範例是否相同。逐格比對在幾百格以上就會撞到 MCP host 逾時，這個不會。masked=true 會忽略來源區域裡的空氣，只檢查「該有的東西在不在」，不管周圍多了什麼；masked=false 則要求完全一致。兩個區域大小必須相同，destination 是目標區域的最小角。

用選擇器查詢實體的座標、朝向與唯一 ID，回傳已解析的 JSON。這是取得玩家或 Agent 目前位置的正規做法——建造前先問這個，才知道要蓋在哪裡。預設用 @p（最近的玩家）而非 @s：WebSocket 送進來的指令沒有實體身分，@s 在部分情況下無法解析。

在指定座標生成一個實體，可加名牌。position 留空則生在指令發起者位置。

一次改一項世界設定：time 設定時間（day/night/noon/midnight 或 tick 數）、weather 天氣、gamerule 遊戲規則、difficulty 難度。

把一塊區域存成具名結構，或把已存的結構放回世界。這是把 AI 蓋好的東西保存、量產、帶到別的世界的官方途徑。

saveMode 要照使用者的意圖選，不要一律用同一個：

• memory（預設）＝這次連線內的暫存。AI 反覆修改同一棟建築時用這個：想留退路就存一版，改壞了 load 回來。關掉遊戲就消失，不會在硬碟累積檔案。

• disk ＝使用者明確表示要保留時才用（「幫我記住這棟」「存起來下次還要用」）。它會寫成檔案存進遊戲的世界資料夾，關掉遊戲也還在——但那是真的在使用者硬碟上留東西，不要在他沒說要保留時擅自寫入。

版本管理就是取名字：castle_v1、castle_v2。同名會直接覆蓋，改版本前先換名字。遊戲沒有「列出已存結構」的指令，所以存過什麼只能靠名字記——本次連線存過的名單可以問 mc_status。

把一塊區域設為常載，讓玩家離開後那裡的機制仍會運作。Agent 要在遠處自動工作時需要這個。

把選擇器指定的對象傳送到座標。target 預設 @s 是執行指令的玩家。

給對象指定數量的物品。要讓 Agent 有東西可放，先 give 給玩家再交給 Agent。

把對象切成 survival、creative、adventure 或 spectator。

action="apply" 施加藥水效果，"clear" 清除全部效果。

kill 殺死對象、clear 清空背包（可指定單一物品）、xp 給經驗、ability 開關 worldbuilder／mayfly／mute 權限。

say 全體聊天、tell 私訊、title／subtitle／actionbar 在畫面上顯示大字。教學或回報進度時用這個跟玩家說話。

播一個音效或在座標生成粒子效果，用來給玩家即時的感官回饋。

只計算不動工：回報這個形狀會用掉幾個方塊、邊界盒在哪、會拆成幾條 fill 指令。座標一律是絕對世界座標；不知道玩家在哪就先用 mc_query_target。建造會直接改變世界，動手前建議先用對應的 preview 工具看方塊數與邊界盒。

直接在世界蓋出形狀：line 線、box 方體、sphere 球、ellipsoid 橢球、cylinder 圓柱、cone 圓錐、pyramid 金字塔、disk 圓盤／圓環、torus 甜甜圈、helix 螺旋。多數形狀有 hollow 可只蓋外殼。方塊座標會自動合併成最少的 fill 指令，所以蓋一顆半徑 20 的球只要幾百條指令而不是三萬條。座標一律是絕對世界座標；不知道玩家在哪就先用 mc_query_target。建造會直接改變世界，動手前建議先用對應的 preview 工具看方塊數與邊界盒。

只計算不動工：把一份逐格藍圖依方塊種類分組，回報總方塊數與合併後的 fill 批次數。

蓋出任意形狀：直接給一份「座標 → 方塊」清單，相同方塊會自動合併成最少的 fill。幾何形狀請優先用 mc_build_shape；這個工具是給像素畫、文字、不規則造型或從外部資料轉來的模型用的。

回傳已知可用的事件名稱。Mojang 沒有正式文件化這份清單，所以訂閱清單外的名稱是允許的，只會被標記為未驗證。無副作用。

開始接收某類遊戲事件（例如 PlayerMessage 聊天、BlockPlaced 放置方塊、PlayerTravelled 移動）。事件會存進環形緩衝，之後用 mc_events_poll 取出。這是讓 AI「感知」玩家在做什麼的方式。重新連線後會自動重新訂閱。

停止接收某類事件。已經收進緩衝的事件不會被清除。

取出游標之後的事件。第一次用 afterCursor=0，之後帶回上次回傳的 nextCursor 就能連續讀。dropped 大於 0 代表緩衝環繞、有事件永遠讀不到了，該提高輪詢頻率。無副作用。