pm-minecraft

Ein eigenständiger Minecraft-Überlebens-Körper für MCP-Clients.

Er führt Mineflayer, Prismarine Viewer, eine lokale Web-UI und einen Streamable-HTTP-MCP-Server aus.

Er enthält keinen Agenten, kein Modell und keine kognitive Laufzeit. Nur einige minimale Anweisungen, die deinem Agenten deiner Wahl sagen, wie er das MCP nutzen, Screenshots ansehen und benutzerdefinierte TypeScript-Skripte erstellen kann, die über MCP ausgeführt werden können.

Großen Dank an https://github.com/minedojo/voyager und https://github.com/Mega-Gorilla/Discovery :3

Dies ist Teil meiner laufenden Bemühungen, einen unterhaltsamen kognitiven Architektur-KI-Begleiter zu entwickeln, der mit dir Minecraft spielen kann. Funktioniert auch eigenständig ^_^

Einrichtung

Voraussetzungen: Windows PowerShell, Node.js 20+, Python 3.12 über py und ein erreichbarer Minecraft-Java-1.19.x-Server mit dem Charakter im Überlebensmodus.

Set-Location C:\workspace\pm-minecraft-mcp
.\setup.ps1

Die Einrichtung folgt dem gemeinsamen PM-Workflow: Sie verwendet uv, um den Python-3.12-.venv dieses Repositorys zu erstellen, synchronisiert dessen Lockfile und installiert gesperrte Node Pakete. scripts/setup.ps1 bleibt als Kompatibilitäts-Wrapper erhalten.

Wenn es nicht funktioniert, sag deinem Coding-Agenten, er soll es reparieren.

Related MCP server: Godot MCP Runtime

Minecraft

Ich habe das Setup von https://github.com/Mega-Gorilla/Discovery übernommen.

Ich habe Minecraft noch nie manuell modifiziert, was bei mir funktioniert:

• Prism herunterladen

• 1.19.4 installieren

• Fabric Loader 0.19.3 installieren

• Diese Mods über Prism installieren:

  • Fabric API

  • CompleteConfig

  • Mod Menu

  • Multiplayer Server Pause (Forge)

  • item-pickup-range von wenhao (/setPickupRange 5)

• Überlebenswelt erstellen, Cheats aktiviert, friedlich

• Betreten und "Für LAN öffnen" auf Port 12345

Einen Charakter erstellen und starten

.\scripts\init_character.ps1 `
  -Name Floppa `
  -AgentRoot C:/Temp/Floppa `
  -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

.\scripts\start_minecraft_mcp.ps1 `
  -Name Floppa `
  -MinecraftHost 127.0.0.1 `
  -MinecraftPort 12345 `
  -AgentRoot C:/Temp/Floppa `
  -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

Der Initialisierer erstellt den Agenten-Arbeitsbereich, memory/minecraft/, drafts/, skills/, lib/minecraft.ts und .mcp.json. Der Launcher gibt die lokale Web-UI, den Prismarine-Viewer und die MCP-URLs aus. Für mehrere Charaktere verwende eindeutige -WebPort-, -ViewerPort- und -McpPort-Werte.

Jedes deploy/drafts/*.ts-Beispiel wird in das drafts/ des Arbeitsbereichs kopiert und in dessen AGENTS.md aufgelistet. Sie laufen unverändert über minecraft_execute_typescript, sodass der Agent eines direkt ausführen oder dessen Guard-and-Verify-Form in einen neuen Entwurf kopieren kann. Füge ein Beispiel zu deploy/drafts/ hinzu, um es mit jedem neuen Charakter auszuliefern.

Der Agent kann minecraft_list_capabilities aufrufen, bevor er ein neues Verhalten schreibt. Wenn keine Fähigkeit passt, schreibt der Agent einen TypeScript-Entwurf aus generischen Körperaktionen. Der Agent führt den Entwurf mit einer deterministischen Nachbedingung aus. Nach einem erfolgreichen Lauf kopiert minecraft_promote_skill den Entwurf in skills/. Der Förderungsdatensatz enthält den Quell-Hash, die Ausführungs-ID und die Nachbedingung.

Entitätsbeobachtungen enthalten stabile Laufzeit-IDs, solange jede Entität geladen bleibt. Die generische Aktion attack_entity führt einen gewöhnlichen Überlebensangriff gegen eine beobachtete ID aus. Für ein Tötungsziel muss der Agent ein Überlebensergebnis verifizieren, z. B. eine Inventarerhöhung. Eine Fähigkeit kann Beobachtung, Bewegung, Ausrüstung, Angriffe und Verifikation zu Verhaltensweisen wie der Jagd kombinieren.

Stoppe eine Instanz mit:

.\scripts\stop_minecraft_mcp.ps1 -ArtifactRoot C:/Temp/Floppa/artifacts/minecraft

Verwende sie dann aus dem Arbeitsbereich:

Set-Location C:/Temp/Floppa
codex

Codex liest .mcp.json. Fordere es auf, den minecraft-Server zu verwenden; Zustandsprotokolle und Screenshots findest du unter ./artifacts/minecraft.

Wahrnehmung und Viewer-Modi

minecraft_find_block verwendet standardmäßig require_visible: true. Dies ist die normale Überlebenseinstellung: Es werden nur Blöcke zurückgegeben, die einen ungehinderten Strahl vom Kopf des Charakters haben. Ein Agent muss erkunden, sich zu einem besseren Blickpunkt bewegen oder eine andere Beobachtung verwenden, wenn er das Ziel nicht sehen kann. Für die Fernplanung setze require_visible: false; das Ergebnis ist nur ein Ort in der geladenen Welt und muss vor dem Abbauen immer noch erreicht und sichtbar verifiziert werden.

Protokollierung auf der Festplatte

Alles wird unter dem Artefakt-Root des Charakters geschrieben (artifacts/minecraft/):

• states/ — eine rohe vollständige Zustandsdatei pro Schnappschuss (<timestamp>-mcstate-<id>.yaml). Jeder Zustand speichert nur die Chat-Nachrichten, die in diesem Zustand erstmals gesehen wurden, sodass jede Chat-Nachricht genau einmal im gesamten Baum existiert; rekonstruiere das Transkript, indem du die Dateien der Reihe nach durchgehst. Jeder Zustand verlinkt auf seinen Screenshot; er enthält niemals Bildbytes oder duplizierte Screenshot-Metadaten. current_state.yaml ist eine Zeigerdatei, die nur den relativen Pfad des neuesten Zustands enthält.

• screenshots/ — der einzige Ort, an dem Bilder leben (.png plus eine kleine Metadaten- Sidecar-Datei pro Frame). Zustände und Aktionen verlinken nur auf diese.

• actions/ — ein flaches YAML pro MCP-Toolaufruf, benannt <timestamp>_<tool>.yaml, das im laufenden Betrieb geschrieben wird (eine Startdatei mit dem Tool und der Eingabe erscheint in dem Moment, in dem der Aufruf beginnt, Vorher/Nachher-Zustands- und Screenshot- Links werden angehängt, sobald Schnappschüsse entstehen, und die rohe, hübsch formatierte Tool- Ausgabe, die Dauer und etwaige Ausnahmen landen in der endgültigen Neufassung). Felder: tool, tool_input, tool_output (beide hübsch formatierte JSON-Block-Skalare), die vier Links before_state_path / before_screenshot_path / after_state_path / after_screenshot_path (leer, wenn das Tool keinen Zustand erzeugt hat, nur vorher für Tools wie minecraft_observe, die einen erzeugen), plus Nachschlage-Header wie execution_id / skill_path für Fähigkeiten. Erfolg oder Fehlschlag wird direkt aus den Rückgabedaten in tool_output gelesen; Ausnahmen landen in einem error:-Block.

• mcp-server.log — jeder abgefangene Körper-/Netzwerkfehler und jede unbehandelte Ausnahme (mit Traceback) landet hier.

Tool-Ergebnisse geben dieselben Links zurück (beforeStatePath / afterStatePath / beforeScreenshotPath / afterScreenshotPath), anstatt den gesamten Zustand einzubetten, sodass das Modell den Dateien folgt, wenn es Details benötigt.

Screenshots werden für jeden Zustand erfasst und nach artifacts/minecraft/screenshots geschrieben – vor und nach jeder Aktion, bei jedem minecraft_observe-Aufruf – unabhängig von include_image, solange der Server mit aktivierter Bildaufnahme gestartet wird (Standard; deaktivieren mit --no-images). Dies ergibt eine vollständige, nahtlose visuelle Verlaufsaufzeichnung auf der Festplatte für die spätere Analyse, auch für Zustände, die der Agent selbst nie angesehen hat.

include_image steuert nur, ob die Pixelbytes auch an die Antwort dieses bestimmten Toolaufrufs angehängt werden, damit der Agent sie sofort sehen kann; minecraft_observe verwendet standardmäßig include_image=true (alle anderen Tools verwenden standardmäßig include_image=false, um Routineaktionen im Kontext kostengünstig zu halten). Übergib include_image=false an minecraft_observe, um das Bild aus der Antwort wegzulassen, wenn nur der Zustand benötigt wird – der Screenshot wird in beiden Fällen trotzdem erfasst und auf der Festplatte gespeichert. Ein Screenshot, der angefordert, aber nicht erfasst werden konnte (Viewer/Bot nicht bereit, kein unterstützter Browser gefunden), wird als screenshot: {"error": ..., "message": ...} gemeldet, abweichend von screenshot: null (Bildaufnahme ist serverweit über --no-images deaktiviert).

Navigation (nur Gehen)

minecraft_walk_to geht nur. Es kann 1-Block-Stufen erklimmen und 1 Block hinuntersteigen, aber es gräbt nicht, platziert kein Gerüst, baut keinen Turm, macht kein Parkour und öffnet keine Türen. Es zielt auf die horizontale Position (GoalNearXZ, sodass die Geländehöhe automatisch gewählt wird) mit einem statischen Ziel innerhalb einer startzentrierten Region von chunk_limit Chunks (Standard 3, begrenzt durch das konfigurierte Maximum des Servers). Wenn sich das Ziel außerhalb dieser Region befindet, keinen begehbaren Boden in der Nähe hat oder keinen Weg zu Fuß gibt, schlägt der Aufruf schnell fehl, anstatt herumzusitzen.

tolerance beträgt standardmäßig 1.5. Das Such-A*-Budget (walkSearchTimeoutMs, Standard 1000) begrenzt, wie lange die Pfadfindung dauern darf, bevor sie mit einer "bewege dich näher"-Meldung fehlschlägt.

Tunnelbau & Navigation über lange Distanzen

• minecraft_mine_block erfordert normalerweise Sichtlinie auf Kopfhöhe, was für den angrenzenden Block auf Fußhöhe in einem 1-Block-breiten Schacht unmöglich ist. Es überspringt diese Hürde jetzt für Ziele innerhalb von --mine-visibility-ignore-distance Blöcken (Standard 3, übergib -MineVisibilityIgnoreDistance an das Start- Skript), sodass du aus einem 1-Block-Tunnel geradeaus graben kannst.

• minecraft_walk_to akzeptiert ein chunk_limit bis zu --max-chunk-limit (Standard 8). Größere Anfragen werden mit error: requested chunk limit (N) greater than allowed (M) abgelehnt.

• minecraft_pillar_up meldet einen klaren pillar_up_needs_placeable_block- Fehler, wenn das gehaltene Item kein platzierbarer Block ist, und erklärt, dass der Landekopfraum zuerst freigeräumt werden muss; dig_up räumt den Kopfraum pro Sprung frei.

• Mit jedem Charakter ausgelieferte Entwürfe (automatisch nach drafts/ bereitgestellt):

  • dig_staircase(height, distance, stop) — begehbare 2-Blöcke-hohe absteigende Rampe.

  • clear_room(width, depth, height) — erweitert einen 1-Block-Tunnel zu einem Raum.

  • dig_up(targetY) / descend_to_depth(targetY, stopOnOre) — gefahrensicheres Ein-Sprung-Aufsteigen / -Absteigen, das vor dem Graben auf Lava/Wasser prüft.

  • tunnel_forward / tunnel_iron / branch_mine_safe_iron — Tunnelbau & Erzabbau, alle gefahrenabgesichert (sie stoppen, bevor sie in Wasser/Lava graben).

  • place_crafting_table / place_block / climb_pillar / find_village (Patrouille über lange Distanz, die meldet, wenn sie einen Dorfbewohner sieht).

Angehaltene Läufe, Timeouts & der Anti-Stall-Schutz

• minecraft_stop hält den aktiven Mineflayer-Befehl an und beendet jeden laufenden TypeScript-Fähigkeitsprozess (beendet beide). minecraft_kill_command stoppt nur den aktuellen physischen Befehl; minecraft_kill_skill beendet nur den laufenden Fähigkeitsprozess.

• Kooperative Abbrechung: Fähigkeiten prüfen bei jedem API-Aufruf / Schlaf ein Kill-Signal-Marker und brechen sauber aus (SkillCancelledError), wenn sie gestoppt werden, sodass minecraft_stop/kill_skill (und eine Client-Trennung) eine Fähigkeit schnell anhalten und ihr erlauben, ihr Ergebnis zu schreiben – der Runner wird nur hart beendet, wenn er den Marker ignoriert.

• Konfigurierbares Fähigkeits-Timeout: minecraft_set_skill_timeout(seconds) (1..3600) legt die maximale Dauer für minecraft_execute_typescript und minecraft_collect_blocks fest (Standard 90; Startzeit-Standard über -SkillTimeoutSeconds / --skill-timeout-seconds). Lange Fähigkeiten laufen in einem separaten Unterprozess und werden serverseitig bei diesem Timeout beendet.

• Passe dein Client-Fenster an: das requestTimeoutMs in der .mcp.json des Agenten (Charakter-Standard 200000) muss ÜBER dem Server-Fähigkeits-Timeout liegen, sonst werden lange Fähigkeiten clientseitig abgeschnitten, bevor sie fertig sind. Faustregel: setze minecraft_set_skill_timeout auf requestTimeoutMs - 10s.

• Der Wiederholungs-ohne-Gewinn-Schutzschalter ist standardmäßig deaktiviert. Er war ein Relikt älterer, schwächerer Modelle, die eine identische Operation ohne Gewinn in einer Schleife wiederholten; an ein einzelnes "relevantes Item" gekoppelt, blockierte er fälschlicherweise nicht verwandte Fähigkeitsoperationen. Aktiviere ihn explizit, wenn du ihn möchtest, mit dem --enable-anti-stall-guard-MCP-Argument (-EnableAntiStallGuard im Startskript).

Zustandstransparenz

• Jeder Zustand (vollständig und Delta) trägt immer die Spieler-position, health, food und foodSaturation, und jedes Ergebnis meldet immer das aktuelle heldItem, sodass ein Agent seine eigenen Vitalwerte oder das gehaltene Werkzeug nie aus einem Diff ableiten muss.

• minecraft_collect_blocks rüstet im Voraus das billigste Werkzeug aus, das den Zielblock erntet (statt mitten im Lauf mit einer unharvestable-Ablehnung zu sterben), und der Körper tauscht das gehaltene Item nicht mehr, außer wenn collect_blocks ein anderes Werkzeug benötigt.

Tipps aus Live-Tests (Agenten-Ergonomie)

Diese stammen aus echten In-Game-Sitzungen mit einem Coding-Agenten und sind es wert, in die AGENTS.md deines Agenten oder in Fähigkeits-Prompts aufgenommen zu werden:

• Koordinaten sind flach bei den Wrapper-Tools: minecraft_walk_to(x,y,z,…) / minecraft_mine_block(x,y,z,…) nehmen einzelne Zahlen, KEIN position/block-Objekt. Für verschachtelte Aktions-Schemas verwende minecraft_call mit den Formen in minecraft_info (z. B. {"action":"place_block","parameters":{"referenceBlock":{…}}}).

• Erkunde, bevor du gräbst: lies hazards (Wasser/Lava) und inspect die nächste Zelle, bevor du tunnelst. Laufende Entwürfe stoppen bei einer Gefahr; ein rohes mine_block in Wasser/Lava strandet den Bot.

• Abweichung des gehaltenen Werkzeugs: ein kletterartiges mine_block oder pillar_up kann ein platzierbares Block (Erde/Kopfstein) in der Hand hinterlassen statt eines Werkzeugs. Rüste neu aus und verifiziere nach jedem kletterartigen Mine; Werkzeuge brechen auch bei Haltbarkeit, also halte eine Ersatz-Spitzhacke bereit.

• Mine breit, nicht 1-breit: 1-breite Tunnel legen nur die Vorderseite frei und tunneln an Seitenwand-Erz vorbei. Verwende clear_room/branch_mine_safe_iron (3-breit), um Erz freizulegen, und behandle das Sichtlinien-Ergebnis (Anti-X-Ray) von find_block als „geh hin / mine, um es zu enthüllen".

• Lange Überlandreisen funktionieren mit dem dynamischen Chunk-Streaming-Lauf; halte jeden walk_to innerhalb deines Client-Fensters und es deckt viel mehr Boden ab als Ein-Chunk-Sprünge.

• Timeouts: halte minecraft_set_skill_timeout bei requestTimeoutMs - 10s, damit lange Fähigkeiten fertig werden statt abgeschnitten zu werden. minecraft_info meldet den aktuellen Wert; lies ihn erneut, wenn die Doku abweicht.

• Bevorzuge viele kleine umkehrbare Fähigkeiten gegenüber einer großen unumkehrbaren; jede braucht eine deterministische Nachbedingung. minecraft_observe + minecraft_stop lassen dich jede abweichende Ausführung verfolgen und stoppen.

Coole Sachen

Hier ist die WebUI, wo du den Charakter manuell steuern oder sehen kannst, wie der Coding-Agent das MCP verwendet.

Und hier beschreibt Codex den Skin meines Charakters. Prismarine rendert nur Standard-Steve :(

Entwicklung

npm test
npm run build
.\.venv\Scripts\python.exe -m compileall mcp

Programmatische Nutzung (pip install)

pm-minecraft kann direkt in ein anderes Python-Projekt eingebettet werden – zum Beispiel in eine kognitive Architektur, die einen Minecraft-Charakter in Daemon-Threads am Leben hält. Keine ps1-Skripte, kein subprocess.Popen von Launchern und keine abgetrennten Kindprozesse irgendwo: jeder Node-Prozess ist an seinen Python-Elternprozess über eine stdin-Lifecycle-Pipe gebunden. Wenn der Elternprozess stirbt – ordentlich oder hart gekillt – schließt das Betriebssystem die Pipe, Node sieht EOF und fährt sauber herunter. Gleiche Semantik unter Windows und Linux.

Installation

pip install git+https://github.com/flamingrickpat/pm-minecraft.git

Anforderungen an die Zielmaschine:

• Python 3.12 und Node.js 20+ auf PATH (node und npm).

• Beim ersten Start eines Charakters in einer Python-Umgebung installiert das Paket seinen Node-Abhängigkeitsbaum einmal in <venv>/pm-minecraft-runtime/<version>/ (führt npm ci unter einer Dateisperre aus; einmalig, ein paar Minuten). Jeder spätere Start ist sofort. Vorwärmen mit pm_minecraft_mcp.ensure_node_runtime().

• Ein erreichbarer Minecraft-Java-1.19.x-Server mit dem Charakter im Überlebensmodus (wie beim eigenständigen Setup).

Einstiegspunkte

Alles ist ein typisiertes Konfigurationsobjekt plus blockierende Funktionen, die für Daemon-Threads ausgelegt sind:

• pm_minecraft_mcp.ServerConfig(...) – alle Einstellungen: Minecraft-Host/Port, Benutzername, Agent-Heimat, Artefakt-Root, Web/Viewer/MCP-Hosts+Ports, Start- Timeout, Bildaufnahme, Fähigkeitslimits, Sichtweite.

• pm_minecraft_mcp.execute_node_main_loop(config) – führt den Minecraft-Körper (ein Node-Prozess) aus und blockiert, bis er beendet wird.

• pm_minecraft_mcp.execute_python_main_loop(config, manage_body=True) – führt den MCP-Server aus und blockiert, während er bedient. Mit dem Standard- manage_body=True startet und besitzt es auch den Körper selbst (ein Thread reicht); mit manage_body=False erwartet es, dass der Körper von einem begleitenden execute_node_main_loop-Thread verwaltet wird, und wartet, bis er bereit ist.

• pm_minecraft_mcp.init_character(name, agent_root, artifact_root, ...) – Python-Port von scripts/init_character.ps1: erstellt den Agent-Arbeitsbereich (AGENTS.md, .mcp.json, lib/minecraft.ts, drafts/, skills/, memory/minecraft/). Lehnt nicht-leere Agent-Roots ab.

• pm_minecraft_mcp.check_prerequisites(config) – die Fail-Fast-Prüfungen, die auch automatisch vor jedem Start ausgeführt werden: Agent-Heimat initialisiert, Minecraft-Server über TCP erreichbar, lokale Service-Ports frei, node auf PATH. Jeder Fehler wirft sofort mit einer spezifischen Meldung. Nachdem der Körper beigetreten ist, muss die ausgehandelte Version 1.19.x und der Spielmodus Überleben sein, sonst wirft der Einstiegspunkt.

Beispiel

examples/main.py startet einen Charakter in zwei Daemon-Threads und fährt bei Strg-D herunter:

import threading
from pathlib import Path

from pm_minecraft_mcp import (
    ServerConfig,
    execute_node_main_loop,
    execute_python_main_loop,
    init_character,
)

AGENT_ROOT = Path.home() / "characters" / "Floppa"

if not (AGENT_ROOT / "AGENTS.md").exists():
    init_character(
        name="Floppa",
        agent_root=AGENT_ROOT,
        artifact_root=AGENT_ROOT / "artifacts" / "minecraft",
        minecraft_host="127.0.0.1",
        minecraft_port=12345,
        web_port=3000,
        viewer_port=3007,
        mcp_port=8765,
    )

config = ServerConfig(
    minecraft_host="127.0.0.1",
    minecraft_port=12345,
    username="Floppa",
    agent_home=AGENT_ROOT,
    artifact_root=AGENT_ROOT / "artifacts" / "minecraft",
    web_host="127.0.0.1",
    web_port=3000,
    viewer_port=3007,
    mcp_host="127.0.0.1",
    mcp_port=8765,
    startup_timeout_seconds=90,
    capture_images=True,
    max_skill_characters=50000,
    viewer_scale=1,
    viewer_fov=80,
    view_distance=24,
)

threading.Thread(target=execute_node_main_loop, args=(config,), daemon=True).start()
threading.Thread(
    target=execute_python_main_loop, args=(config,), kwargs={"manage_body": False}, daemon=True
).start()

try:
    while True:
        input()  # Ctrl-D (EOF) ends the process; children follow via stdin EOF
except (EOFError, KeyboardInterrupt):
    pass

Die Ein-Thread-Variante funktioniert auch: ein Daemon-Thread auf execute_python_main_loop(config) startet sowohl Körper als auch MCP.

Mehrere Charaktere

Verwende eine Konfiguration (eindeutiger Benutzername + eindeutige Web/Viewer/MCP-Ports) pro Charakter und gib jedem sein eigenes Paar Daemon-Threads. Die Node-Laufzeit wird schreibgeschützt zwischen allen Charakteren in derselben Python-Umgebung geteilt.

Agent-seitiges Verhalten ist unverändert

Aus Sicht des MCP-Clients ändert sich nichts: dieselben Tool-Namen, Schemas, .mcp.json-Layout und der minecraft_execute_typescript-Vertrag. Ein Agent kann weiterhin einen beliebigen TypeScript-Entwurf in seinen Arbeitsbereich schreiben und ihn gegen den Server ausführen; Entwürfe laufen durch die tsx-Laufzeit des Pakets mit lib/minecraft.ts aus dem Charakter-Heimatverzeichnis.

Lifecycle-Garantien

• Der Körper ist ein Node-Prozess (keine npm/tsx-Wrapper-Prozesse); Fähigkeitsläufe sind ebenfalls jeweils ein Prozess. Es gibt keine Prozessbäume, die man verfolgen müsste.

• Kinder bekommen nie CREATE_NEW_PROCESS_GROUP und werden nie taskkilled. Herunterfahren ist zuerst stdin-EOF, einfaches kill() als letzte Möglichkeit.

• Das Töten des einbettenden Prozesses zu jedem Zeitpunkt (einschließlich taskkill /F oder kill -9) kann den Körper nicht verwaist zurücklassen: die Lifecycle-Pipe bricht und Node beendet sich innerhalb von Sekunden.