BlockHand – Minecraft Education MCP

Gibt der KI in Minecraft Education Edition Hände und Füße: Aktionen (Agent-Bewegung, Graben, Platzieren, Ackerbau, Transport), Augen (Blöcke erfassen, Koordinaten abfragen, Spielereignisse abonnieren), Erschaffen (zehn geometrische Formen und Raster-für-Raster-Blaupausen).

Funktioniert über den offiziell dokumentierten /wsserver-Verbindungsbefehl von Minecraft Education (/connect ist ein Alias), ohne Prozessinjektion, ohne Änderung von Spieldateien, ohne Bildschirmerkennung. Der Verbindungsbefehl ist eine offizielle Schnittstelle; das nachfolgende WebSocket-Nachrichtenprotokoll hat keine öffentliche Stabilitätsgarantie, daher muss nach Spielupdates erneut verifiziert werden.

• 42 Tools, 2 Ressourcen

• 216 Unit- und Integrationstests, 1 stdio-/Prozesslebenszyklus-Smoke-Test ohne Spielstart, 1 Live-Verifikation auf echter Hardware

• Keine Konten, Tokens oder Geheimnisse erforderlich; die MCP-Runtime bindet nur an Loopback, schreibt keine Spieldateien oder Artefakte

1. In drei Schritten startklar

Schritt 1: Auf jedem Rechner installieren und bauen

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

Node muss die im Projekt-.nvmrc angegebene Version 22.23.1 sein, pnpm ist per Corepack auf 11.17.0 fixiert. Windows und Mac müssen Abhängigkeiten lokal installieren; kopiere nicht das node_modules eines anderen Betriebssystems herüber. Minecraft Education benötigt auf dem Mac derzeit mindestens macOS 14.

Schritt 2: MCP einmal auf diesem Rechner registrieren

Unterstützt Codex／Claude Code／Gemini CLI／Grok CLI, auf Windows und macOS gleichermaßen.

Zuerst zwei absolute Pfade ermitteln

Bei der Registrierung müssen absolute Pfade verwendet werden, nicht nur node. Desktop-KI-Tools werden vom Finder／Explorer gestartet und können das nvm, Homebrew oder PATH in deiner Shell nicht lesen; wenn du node schreibst, funktioniert es im Terminal, aber beim Desktop-Start schlägt es fehl, und die Fehlermeldung sagt meist nur „Server antwortet nicht", was schwer zu diagnostizieren ist.

macOS:

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

Windows (PowerShell):

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

Im Folgenden steht <NODE> für den absoluten Node-Pfad und <REPO> für den absoluten Projektpfad. Der Servereinstiegspunkt ist fest <REPO>/dist/index.js (unter Windows <REPO>\dist\index.js). Wenn Pfade Leerzeichen enthalten, muss der gesamte Abschnitt in Anführungszeichen gesetzt werden.

Mit dem Installer (von allen vier unterstützt, empfohlen)

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

Der Installer schreibt nicht nur Befehle in die Konfigurationsdatei, sondern:

• Füllt automatisch den absoluten Node-Pfad dieses Rechners ein, ohne darauf angewiesen zu sein, dass das Desktop-Programm nvm, Homebrew oder das Shell-PATH lesen kann.

• Führt zuerst eine echte MCP-Initialisierung aus (mit den gleich zu schreibenden command／args／env), um zu bestätigen, dass alle 42 Tools vorhanden sind, bevor irgendeine persistente Einstellung geändert wird. Alte dist, falsche Launcher oder nicht ausführbares Node schlagen fehl, bevor etwas geschrieben wird.

• Tut nichts, wenn bereits korrekt registriert, erneutes Ausführen ist sicher.

• Stoppt bei gleichnamigen, aber inkompatiblen Einträgen und listet die Unterschiede auf, ohne automatisch remove/add durchzuführen, um die Timeouts, Tool-Policies oder Einstellungen eines anderen Clones nicht zu überschreiben.

• Schreibt nur über die offiziellen mcp add／mcp remove-Unterbefehle der jeweiligen Anbieter, ohne Konfigurationsdateien manuell zu ändern – das würde die eigene Schema-Validierung und Scope-Auflösung der Anbieter umgehen.

Entfernen mit corepack pnpm run uninstall:codex (bzw. uninstall:claude usw.). Ebenso mit Löschschutz: Einträge, die nicht als zu diesem Arbeitsbaum gehörig erkennbar sind, werden abgelehnt.

Schreiborte und Neustartanforderungen der einzelnen Anbieter:

Die Lesestrategien unterscheiden sich: Codex und Grok haben mcp list --json und verwenden direkt die maschinenlesbare Ausgabe. Die list-Befehle von Claude Code und Gemini liefern nur menschenlesbaren Text ohne env und eignen sich nicht zur Kompatibilitätsprüfung, daher werden die Konfigurationsdateien, die ihre offiziellen CLIs gerade geschrieben haben, nur lesend geprüft. Geschrieben wird immer über die CLI.

Manuelle Befehle (wenn der Installer nicht verwendet werden soll)

Die Befehle sind äquivalent, aber die absoluten Pfade müssen selbst eingetragen werden, und es gibt keine vorherige Initialize-Validierung oder Überschreibschutz.

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

Drei häufige Stolperfallen:

• Bei Gemini sind command und args Positionsparameter, die direkt auf den Namen folgen, ohne ---Trennung.

• Der Standard-Scope von Gemini ist project; für globale Verfügbarkeit muss explizit --scope user angegeben werden.

• Der Standard-Scope von Claude ist local (wirkt nur im aktuellen Verzeichnis); --scope project schreibt in die .mcp.json im Projektstamm, die mit dem Repo geteilt werden kann – für die gemeinsame Nutzung in einer ganzen Klasse verwenden.

Konfigurationsdateien manuell bearbeiten (Fallback, wenn der Installer versagt)

Claude Code und Gemini CLI verwenden JSON:

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

Codex und Grok CLI verwenden TOML:

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

Windows-Ergänzungen

• Der absolute Node-Pfad ist normalerweise C:\Program Files\nodejs\node.exe, mit nvm-windows etwa C:\Users\<du>\AppData\Roaming\nvm\v22.23.1\node.exe.

• Backslashes in JSON-Konfigurationsdateien müssen maskiert werden: "C:\\Program Files\\nodejs\\node.exe". TOML kann stattdessen einfache Zeichenkettenliterale verwenden: command = 'C:\Program Files\nodejs\node.exe'.

• Wenn Minecraft Education die UWP-Version aus dem Microsoft Store ist, wird Loopback durch die Windows-App-Isolation blockiert; eine zusätzliche CheckNetIsolation LoopbackExempt-Ausnahme ist erforderlich (siehe Abschnitt 8).

Nach der Registrierung

Das KI-Tool vollständig beenden und neu starten – beim Desktop-Programm wirklich beenden, nicht nur das Fenster schließen. Dann mit doctor bestätigen (fasst Minecraft nicht an, ändert keine Einstellungen):

corepack pnpm run doctor

Es prüft Node-Version, Build-Artefakte, Plattformanforderungen, Registrierungsstatus und führt mit den tatsächlich registrierten command／args／env erneut eine MCP-Initialisierung aus, damit keine Einstellung auf ein ungültiges Node zeigt und fälschlich grün ist. Mit --json erhält man strukturierte Ausgabe. Man kann auch direkt die CLIs der Anbieter fragen:

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

Oder die KI direkt mc_status aufrufen lassen; wenn connectCommand zurückkommt, bedeutet das, dass der Server starten kann.

Jeder Rechner muss einmal separat registriert werden: Windows-Laptop, Mac und ein anderer Computer haben unterschiedliche Node- und Projekt-Absolutpfade, die Einstellungen können nicht gegenseitig kopiert werden. Auf demselben Rechner teilen sich Desktop／CLI／IDE desselben Tools dieselbe Einstellung.

Schritt 3: Im Spiel manuell verbinden

corepack pnpm run connect

Dieser Kompatibilitätseinstieg zeigt nur die Bedienung, startet Minecraft nicht, wechselt nicht das Vordergrundfenster und simuliert keine Tastatur. Die automatische Eingabe über Windows PowerShell wurde entfernt; auch auf dem Mac gibt es keine AppleScript-Automatisierung.

Die Richtung wird leicht verwechselt: Das Spiel ist die Seite, die sich verbindet, der MCP-Server ist die Seite, mit der verbunden wird.

1. Rufe im aktuellen KI-Dialog mc_status auf und kopiere den zurückgegebenen connectCommand.

2. Öffne Minecraft Education und betrete eine Welt (im Hauptmenü zu bleiben bringt nichts).

3. Die Welt muss Cheats aktiviert haben, der Bediener benötigt Admin／OP-Rechte.

4. Gib in der Chat-Zeile manuell ein, zum Beispiel:

/connect 127.0.0.1:19131

Sobald Connection established erscheint, ist es geschafft. Danach kannst du der KI sagen: „Bau mir vorne eine hohle Glaskugel".

Für eine erneute Verbindung muss nicht der ganze Text neu getippt werden: In der Chat-Zeile T drücken, dann ↑ für den vorherigen Befehl, dann Enter.

Frühere Versionen hatten einen Bug mit „Trennung nach ca. 60 Sekunden Leerlauf": Der Heartbeat erkannte nur WebSocket-Pong-Frames, aber der Bedrock／Education-Client antwortet nie mit Pong, wodurch gesunde Verbindungen vom eigenen Heartbeat beendet wurden. Inzwischen behoben (Aktivität wird anhand jedes eingehenden Pakets beurteilt, ergänzt durch Anwendungsebene-Sonden); Leerlauf sollte keine Trennung mehr verursachen. Falls es weiterhin trennt, prüfe zuerst, ob du ein neu gebautes dist/ verwendest.

Nicht 19131 auswendig lernen: Wenn Desktop, CLI, IDE oder mehrere Tasks gleichzeitig starten, kann der später gestartete MCP einen anderen freien Port erhalten. Verwende immer den Befehl, den der aktuell zu bedienende Task meldet.

Related MCP server: Minecraft MCP Bot

2. Verifikation auf echter Hardware

Zuerst die sichere Diagnose ohne Spielstart:

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

Der doctor ändert keine persistenten Einstellungen und startet Minecraft nicht; er erstellt kurzzeitig einen isolierten Loopback-Socket und prüft Launcher, 42 Tools, 2 Ressourcen, stdio-EOF, Freigabe des Lauschports und führt mit den tatsächlich registrierten command／args／env von Codex eine weitere Initialisierung aus, damit keine Einstellung auf ein ungültiges Node zeigt und fälschlich grün ist.

Wenn das Spiel läuft, die Welt geladen ist und Cheats aktiviert sind:

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

Das Skript gibt den einzugebenden /connect-Befehl aus, wartet auf die Verbindung und durchläuft dann einen vollständigen Pfad mit PASS／FAIL-Meldung pro Schritt: Verbindung → Spielerkoordinaten lesen → im Spiel sprechen → Zeit setzen → Agent beschwören → Erfassen → L-förmigen Pfad gehen → Bauvorschau → hohle Glaskugel bauen → rückwirkend prüfen, dass die Blöcke wirklich existieren → Blaupausen zusammenführen → Ereignisse abonnieren und empfangen → Policy-Gate → Demo-Bauten entfernen.

Nach Spielupdates

Das Lesen von Blöcken (mc_read_block) stützt sich auf das Textformat der Fehlermeldung von testforblock; dieses Format hat keinerlei offizielle Stabilitätsgarantie. Wenn Minecraft Education still automatisch aktualisiert und den Wortlaut ändert oder die Spielsprache nicht mehr Traditionelles Chinesisch／Vereinfachtes Chinesisch／Englisch ist, funktioniert dieser Pfad nicht mehr.

Das Versagen ist leise: Das Tool geht nicht kaputt, es beginnt nur zu sagen „kann nicht lesen". Deshalb wird es in diesem Projekt bewusst nicht als Routineprüfung bei jedem Live-Lauf ausgeführt – Routineprüfungen erzeugen die Gewohnheit, sich bei Grün sicher zu fühlen, aber der Zeitpunkt, an dem man wirklich beurteilen muss, ist „wenn das Verhalten verdächtig wird", nicht der wöchentliche feste Lauf.

Stattdessen bei Bedarf aktiv beurteilen:

mc_verify_reading  { position: 任一座標 }

Es sendet höchstens zwei Befehle, schreibt überhaupt nicht in die Welt und gibt parseable zurück:

• true → Der Parsing-Pfad funktioniert, die Ergebnisse von mc_read_block sind vertrauenswürdig.

• false → Das Protokoll ist abgedriftet. In diesem Fall gibt mc_read_block immer einen Fehler statt null zurück (siehe Abschnitt 3), sodass niemand „kann nicht lesen" mit „dort ist es leer" verwechselt. Das zurückgegebene raw ist die ursprüngliche Spielmeldung; vergleiche sie mit den PATTERNS in src/domain/block-report.ts, um zu sehen, welches Muster ergänzt werden muss.

Drei Signale, die dich dazu bringen wollen, es auszuführen:

1. mc_read_block beginnt, Fehler zurückzugeben, aber du siehst im Spiel, dass dort sichtbar etwas ist.

2. Das Spiel wurde gerade aktualisiert und du wirst als Nächstes etwas tun, das vom Lesen abhängt (Korrektur, Symmetrieanalyse).

3. Die Spielsprache wurde gewechselt.

Die Server-Instructions enthalten denselben Hinweis, sodass die KI bei verdächtigem Verhalten selbst dieses Tool findet, ohne dass du es ihr sagen musst.

Standardmäßig werden die Demo-Bauten mit air aufgefüllt, es bleibt kein Müll in der Welt. Zum Ansehen behalten:

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

Verifikation ohne Spielstart (Typen, Tests, Build, stdio-Handshake, Portfreigabe bei STDIN-Schließung und Portbelegungsfehler in einem Durchlauf):

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

3. Tool-Übersicht

Verbindung und Fallback (4)

Agent – Hände und Füße (10)

Die Agent-Richtung ist relativ zu seiner eigenen Blickrichtung, nicht zur Weltausrichtung.

Welt (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 (Zeit／Wetter／Spielregeln／Schwierigkeit), mc_structure (Strukturen speichern/laden), mc_ticking_area.

mc_query_target parst die von querytarget zurückgegebene JSON-Zeichenkette; das ist der reguläre Weg, um Spieler- oder Agent-Koordinaten zu erhalten – vor dem Bauen zuerst fragen.

Dieser Lesebereich hat inhärente Einschränkungen; es ist besser, sie klar zu benennen, als so zu tun, als gäbe es sie nicht. Education hat keinen Befehl zum „Lesen beliebiger Blöcke", daher:

• mc_test_block ist eine Ja/Nein-Frage: Du musst zuerst eine Block-ID raten.

• mc_read_block muss nicht raten – es verwendet Luft als Sentinel und fragt; bei falscher Vermutung nennt die Spielmeldung den tatsächlichen Block. Aber zurückgegeben wird der lokalisierte Anzeigename („Erde") statt der Block-ID (dirt), der nicht in mc_set_block zurückgefüttert werden kann. Wenn das Parsen fehlschlägt, gibt dieses Tool einen Fehler zurück, nicht eine erfolgreiche Antwort mit null – der Grund folgt unten.

• mc_verify_reading prüft aktiv, ob der obige Parsing-Pfad noch funktioniert. Einmal vor dem Unterricht ausführen, dann weiß man, ob die Ergebnisse von mc_read_block vertrauenswürdig sind.

• mc_compare_regions vergleicht eine ganze Region mit einem einzigen testforblocks. Block-für-Block-Vergleiche stoßen bei mehreren hundert Blöcken an den Host-Timeout; dieser nicht. Der masked-Modus ignoriert Luft in der Quelle und eignet sich zum Prüfen, ob „das, was da sein soll, da ist", unabhängig davon, was drumherum zusätzlich ist – die Korrektur von Schülerarbeiten hat genau diese Form.

Warum ein Fehler statt null bei Parsing-Fehlern

Weil der Nutzer dieses Tools eine KI ist und eine KI nicht vermutet, dass das System kaputt ist.

Eine „erfolgreiche" Antwort mit block: null wird leicht als „gelesen, dort ist es leer" interpretiert. Danach arbeitet die KI sehr selbstbewusst auf dieser falschen Grundlage weiter – zum Beispiel überschreibt sie eine Schülerarbeit, die eine ganze Unterrichtsstunde gebaut wurde, als wäre sie leeres Land, und hinterher gibt es keine Fehleraufzeichnung, die man prüfen könnte. Ein Mensch sieht null, findet es seltsam und stoppt zum Debuggen; eine KI tut das nicht.

Ein Fehler kann nicht als Daten weiterverwendet werden – genau das ist der Punkt.

mc_verify_reading ist die andere Hälfte: Es muss nicht vorher wissen, was in der Zelle ist – wenn die Zelle Luft ist, fragt es mit Bedrock (Luft kann nicht Bedrock sein, garantiert ungleich), um eine Fehlermeldung zu erzwingen; wenn dort etwas ist, liefert schon die erste Frage die Meldung. Beide Wege garantieren eine Meldung, mit höchstens zwei Befehlen, ohne die Welt zu beschreiben.

Diese Verteidigungslinie wird durch Mutationstests abgesichert: Wenn die Parsing-Regeln absichtlich kaputt gemacht werden, müssen die insgesamt 7 Tests für Sonde und Parser rot werden.

Für das blockweise Lesen einer ganzen Region bitte das Verhaltenspaket und die Script API verwenden; dieses Projekt geht diesen Weg bewusst nicht, weil das einen zusätzlichen Installationsschritt auf den Schulrechnern bedeuten würde.

Wiederholtes Ändern desselben Gebäudes

saveMode von mc_structure ist genau dafür entworfen:

Versionsverwaltung ist Namensgebung: castle_v1, castle_v2. Gleiche Namen überschreiben direkt; vor einer neuen Version den Namen ändern.

Das Spiel hat keinen Befehl zum „Auflisten gespeicherter Strukturen", daher kann man nur über Namen wissen, was gespeichert wurde. Die Brücke merkt sich die in dieser Verbindung gespeicherten Namen; mc_status zeigt sie – aber das deckt nur diese Prozessinstanz ab und ist nach einem Neustart weg (die Dateien im disk-Modus bleiben, die Namen musst du dir selbst merken).

Symmetrieanalyse – Korrektur von Arbeiten

mc_analyze_symmetry prüft, ob eine Region spiegelsymmetrisch ist, und nennt bei Asymmetrie, welche Blöcke nicht symmetrisch sind, statt nur ein „Nein" zu liefern.

Prinzip: testforblocks macht nur Translationsvergleiche, keine Spiegelung. Daher wird die Region zuerst mit structure save gespeichert, dann mit dem mirror-Parameter von structure load als Spiegelbild in einen Scratch-Bereich gelegt und anschließend verglichen. Wenn das Ganze besteht, gibt es direkt volle Punktzahl; nur bei Nichtbestehen wird in n³-Zellen einzeln verglichen, die Punktzahl ist der Anteil übereinstimmender Zellen.

Dieses Tool schreibt vorübergehend in die Welt, der Ablauf ist wie folgt, und bei jedem fehlgeschlagenen Schritt bleibt kein Chaos zurück:

1. Analysebereich speichern – bei Fehler abbrechen (meist Chunk nicht geladen).

2. Zuerst den Scratch-Bereich sichern – bei Sicherungsfehler abbrechen, und niemals die Spiegelkopie platzieren, die Welt bleibt unversehrt.

3. Spiegelkopie platzieren, vergleichen.

4. Unabhängig vom Ergebnis den Scratch-Bereich wiederherstellen und die temporäre Struktur löschen; das Wiederherstellungsergebnis wird ehrlich in scratchRestored gemeldet, Fehler werden nicht beschönigt.

Der Scratch-Bereich darf sich nicht mit dem Analysebereich überlappen, sonst überschreibt die Spiegelkopie das Originalgebäude – diese Prüfung erfolgt, bevor irgendein Befehl gesendet wird.

Spieler und Feedback (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 (Sound／Partikel).

Bauen (4)

Ereignisse – Wahrnehmung (4)

mc_events_catalog, mc_events_subscribe, mc_events_unsubscribe, mc_events_poll.

Ereignisse gehen in einen Ringpuffer und werden mit einem Cursor fortlaufend gelesen; dropped > 0 bedeutet, dass das Polling zu langsam war und Ereignisse für immer verloren sind. Nach einer erneuten Verbindung wird automatisch neu abonniert.

4. Warum Bauen nicht einfriert

Der naive Ansatz sendet für jeden Block ein setblock. Eine Vollkugel mit Radius 20 hat über 33.000 Zellen, also über 30.000 WebSocket-Roundtrips – praktisch ein Absturz.

Die Pipeline von BlockHand ist:

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

Eine Vollkugel mit Radius 8 wird von über 2.000 Blöcken auf weniger als 200 Befehle komprimiert, und das Zusammenführungsergebnis ist deterministisch – dieselbe Eingabe ergibt immer dieselben Batches. Daher gibt es Tests, die festnageln, dass „die nach der Zusammenführung abgedeckte Blockmenge exakt der ursprünglichen Punktmenge entsprechen muss" – weder mehr noch weniger.

Hohle Formen werden immer über „Innentest + Hüllen-Nachbartest" implementiert, nicht mit einer eigenen Hohlraum-Mathematik pro Form. Für eine neue Form muss nur inside() geschrieben werden, das Hohlraumverhalten ist automatisch konsistent.

5. Sicherheitsgrenzen

Was nicht getan wird

• Keine Verbindung nach außen: WebSocket lauscht nur auf 127.0.0.1.

• Die MCP-Runtime schreibt keine Host-Dateien: Es gibt keinen Artefakt-Ausgabepfad. Nur wenn der Nutzer ausdrücklich setup:<client>／uninstall:<client> ausführt, aktualisiert die offizielle CLI des jeweiligen Anbieters die lokale MCP-Konfiguration.

• Eine Ausnahme muss klar benannt werden: saveMode="disk" von mc_structure schreibt über das Spiel eine Struktur als Datei in den Weltordner von Minecraft. Das ist nicht die MCP-Runtime, die Dateien schreibt, aber es hinterlässt tatsächlich etwas auf der Festplatte des Nutzers. Daher ist der Standard memory (temporär, verschwindet beim Schließen des Spiels); disk sollte nur verwendet werden, wenn der Nutzer ausdrücklich sagt, dass etwas behalten werden soll, und die Tool-Antwort nennt immer, wohin es geschrieben wurde – kein stilles Hinterlassen von Dateien.

• Keine Geheimnisse: Das gesamte Projekt hat keine Tokens, Konten oder Zertifikate.

• Keine aktive Verbindung: Wenn das Spiel nicht per /connect hereinkommt, geben alle Tools umsetzbare Fehlermeldungen zurück, kein stilles Scheitern.

Das Gate von mc_run_command

Architekturprinzip 4 in mcp/README.md verlangt, beliebige Ausführungseinstiegspunkte abzulehnen. Die Beurteilung hier: Slash-Befehle wirken ausschließlich innerhalb der lokalen Spielwelt, berühren weder das Host-Dateisystem, Prozesse noch das Netzwerk, daher sind sie keine beliebige Codeausführung. Was wirklich blockiert werden muss, sind Operationen, die die Brücke unwirksam machen. Daher ist die Policy strukturell und keine Schlüsselwort-Blacklist, die Absichten errät:

1. Nur eine Zeile erlaubt – Zeilenumbrüche und NUL werden direkt abgelehnt, \n kann nicht verwendet werden, um eine Anfrage in zwei Befehle zu zerlegen.

2. wsserver und connect werden abgelehnt – das würde das Spiel auf einen anderen Endpunkt richten und danach wären alle Tools wirkungslos.

3. Übrige Befehle werden mit den Risikostufen read-only／world-write／wide-effect markiert; der MCP-Host entscheidet anhand der Annotationen, ob eine manuelle Bestätigung nötig ist.

Alle Block-IDs, Selektoren und Zustandszeichenketten, die in Befehlszeilen eingefügt werden, durchlaufen zuerst einen Whitelist-Regulärausdruck, um das Zusammensetzen zusätzlicher Parameter mit Leerzeichen zu verhindern.

Klassenzimmer-Schutz (standardmäßig aktiv)

Punkt 3 oben überlässt die Entscheidung dem Host – das gilt für Einzelentwicklung, aber der Einsatzort dieses Projekts ist das Klassenzimmer:

• Der Host kann auf automatische Genehmigung gestellt sein – Lehrer tun das leicht, damit der Unterricht flüssig läuft.

• Ein Schüler, der mit der KI sprechen kann, kann damit auch Befehle erteilen. Er muss die Brücke nicht knacken, er muss nur das Modell überzeugen.

• Missbrauch braucht nicht einmal raw-Befehle: mc_player_action akzeptiert ohnehin @a und kill ist eine der Optionen. Nur raw-Befehle zu blockieren ist Theater; beide Wege müssen blockiert werden.

Die Regel ist so geformt, dass sie einem Lehrer in einem Satz beigebracht werden kann: Aktionen, die auf „Personen" wirken, müssen namentlich benannt werden.

„Alle in der Klasse töten" wird damit von einem Satz zu einer namentlichen Aufzählung, während legitime Klassenraumverwaltung (den Rucksack eines Schülers leeren) völlig unbeeinflusst bleibt.

Zum Deaktivieren MINECRAFT_EDU_CLASSROOM_GUARD=0 setzen – die Fehlermeldung selbst weist darauf hin, sodass niemand denkt, das Tool sei kaputt.

Markenzeichen

Gemäß den Minecraft Usage Guidelines dürfen Drittanbieter-Tools nicht wie offizielle Produkte aussehen. Der Produktname BlockHand enthält bewusst keine Minecraft-Marken; minecraft-edu ist nur ein beschreibender Ordnername in diesem privaten Arbeitsbereich. Falls später eine Veröffentlichung nach außen erfolgt, müssen Paketname und jede öffentliche Darstellung erneut überprüft werden.

6. Einstellungen

Alle haben Standardwerte, .env ist nicht erforderlich.

7. Modulübersicht

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 入口

Die Domänenschicht weiß nichts von WebSocket, daher kann die gesamte MCP-Tool-Pipeline mit reinen In-Memory-Fakes bis zum Ende getestet werden – die 16 Tests in tests/integration/mcp-client.test.ts benötigen kein laufendes Spiel.

8. Bekannte Einschränkungen

• Die Welt muss Cheats aktiviert haben, sonst lehnt das Spiel jeden Befehl ab. Das ist eine Regel von Minecraft, kein Fehler.

• macOS wurde mit echter Hardware live verifiziert (Claude-Code-Pfad): Am 2026-08-25 wurden unter macOS über Claude Code /connect, umfangreiche Lese-/Schreibvorgänge (über 45.000 Blöcke in einer einzigen Sitzung, einschließlich fill/setblock/testforblock/teleport) sowie der gesamte Ablauf von Trennen und Wiederverbinden durchgeführt. Noch nicht verifiziert ist der Startpfad „Codex Desktop aus dem Finder starten“ – der GUI-Start erbt PATH und Umgebungsvariablen anders und muss jeweils separat getestet werden.

• Der Agent ist exklusiv für die Education Edition, die normale Bedrock-Version hat diese Funktion nicht.

• Ereignisnamen und agent-Unterbefehle sind von Mojang nicht offiziell dokumentiert, sie stammen aus öffentlichen Beobachtungen; Spielupdates können das Verhalten ändern. mc_events_subscribe erlaubt Namen außerhalb der Liste, markiert sie jedoch als unverifiziert.

• Die Parameterreihenfolge von agent setitem ist nicht bestätigt, es gibt derzeit kein spezielles Werkzeug dafür; bei Bedarf verwenden Sie mc_run_command.

• @s wird unter WebSocket-Befehlen möglicherweise nicht aufgelöst: Befehle, die über die Brücke eingespeist werden, haben keine Entitätsidentität; in Tests liefert querytarget @s überhaupt keine Antwort. mc_query_target verwendet daher standardmäßig @p (nächster Spieler), und live versucht nacheinander @p → @a → @e[type=player] und meldet jedes Ergebnis.

• Große Bauvorhaben können die Anforderungs-Timeout des MCP-Hosts überschreiten: Das Bauwerkzeug sendet jede fill-Anweisung einzeln und wartet auf die Spielantwort; in Tests dauert eine hohle Kugel mit Radius 6 (126 Anweisungen) etwa 13 Sekunden, bei ausgelastetem Spiel jedoch länger. Die Standard-Timeout der MCP-Clients beträgt meist 60 Sekunden; wird sie überschritten, wird die Verbindung auf Host-Seite abgebrochen (das Werkzeug läuft weiter). Prüfen Sie zuerst mit mc_build_preview die fillBatches und bauen Sie bei großen Mengen in Chargen.

• Jeder BlockHand-Prozess hält weiterhin einen eigenen Lauschport: Nach dem Schließen des STDIO-Clients schließt der Server synchron die Minecraft-WebSocket-Verbindung und gibt den Port frei. Wenn die Desktop-Version des KI-Tools mehrere Aufgaben gleichzeitig lädt oder Desktop/CLI/IDE parallel laufen, erhält die erste den bevorzugten Port, die übrigen erhalten automatisch freie Ports; verwenden Sie immer den mc_status.connectCommand der aktuellen Aufgabe, damit das Spiel mit der tatsächlich zu bedienenden Instanz verbunden wird. Falls ein fester Port benötigt wird, können Sie für jeden Client einen anderen MINECRAFT_EDU_WS_PORT konfigurieren oder MINECRAFT_EDU_WS_PORT_FALLBACK auf 0 setzen.

• Der erste Befehl nach dem Handshake führte früher zwangsläufig zu einer Zeitüberschreitung, wurde aber inzwischen behoben: Vier unabhängige Läufe auf echter Hardware reproduzierten das Problem – das Spiel sendet einen verschlüsselten Frame, bevor der Server den Entschlüsseler installiert hat, wodurch die Stream-Ausrichtung verschoben wird und die Antwort auf die nächste Anfrage nicht gelesen werden kann. AES-CFB8 synchronisiert sich selbst, daher ist nur der erste Befehl betroffen. Der Adapter sendet jetzt nach Abschluss des Handshakes automatisch einen schreibgeschützten time query daytime-Befehl, um diesen Verlust zu absorbieren und das Ergebnis zu verwerfen; die erste Aktion des Aufrufers funktioniert dann normal. Auf stderr wird primed post-handshake stream protokolliert.

• Ereignisse werden nur ausgelöst, wenn sie tatsächlich eintreten: BlockPlaced wird nur gesendet, wenn ein Spieler einen Block von Hand platziert; /setblock und /fill zählen nicht. Um Ereignisse zu empfangen, müssen Sie zuerst abonnieren und dann das Ereignis tatsächlich auslösen.

• Bei einigen Antworten stimmt die requestId nicht mit der Anfrage überein (es wurde beobachtet, dass eine komplett aus Nullen bestehende ID zurückgegeben wird). Der Adapter ordnet die Antwort der einzigen ausstehenden Anfrage zu, wenn nur noch eine vorhanden ist, und protokolliert auf stderr, dass dies eine Schlussfolgerung ist; andernfalls laufen diese Anfragen still in eine Zeitüberschreitung, und der Aufrufer sieht nur „keine Reaktion“ statt der eigentlichen Fehlerursache.

• Es wird nur eine Spielverbindung gleichzeitig aufrechterhalten; eine neue Verbindung ersetzt die alte.

• Bereits auf echter Hardware verifizierte Umgebung: Minecraft Education 1.26.32.0 (Win32-Desktopversion). Bei Verwendung der UWP-Version aus dem Microsoft Store wird Loopback durch die Windows-App-Isolation blockiert; eine zusätzliche CheckNetIsolation LoopbackExempt-Ausnahme ist erforderlich. Die Abnahmematrix für macOS 14+ finden Sie in agents/docs/macos-support.md.

9. Lizenz

Dieses Projekt ist unter der MIT-Lizenz veröffentlicht. Sie können es frei verwenden, modifizieren, verbreiten und weiterlizenzieren, einschließlich kommerzieller Nutzung, unter der einzigen Bedingung, den ursprünglichen Urheberrechtshinweis und die Lizenzbedingungen beizubehalten.

Die Software wird „wie besehen“ bereitgestellt, ohne ausdrückliche oder stillschweigende Gewährleistung.

Minecraft und Minecraft Education sind Marken von Mojang Studios und Microsoft; dieses Projekt steht in keiner Verbindung zu ihnen und wird von ihnen nicht unterstützt.