minecraft-mcp

Local Bedrock map planner for family worlds, with Ollama as the default LLM path and free hosted API options for smaller devices.

This repo now ships with:

• Ollama as the default OpenCode profile (local)
• a scripted API profile (OpenRouter/Groq) for constrained devices or as a fallback when local models are unavailable
• free hosted model support through OpenRouter and optional Groq
• a local stdio MCP server with MCP tools, resources, and prompts
• a planner API for defining named areas, landmarks, and Bedrock-safe command plans
• reusable world blueprints for creating multi-area family or creator layouts in one step
• a Bedrock WebSocket bridge for live command execution and player queries
• OpenStreetMap geocoding so you can turn real-world places into Minecraft landmarks and build areas

Newcomer Path

If you are new to the repo, use this flow first:

1. Start the local server with npm install and npm run start:safe (recommended) or npm run start.
2. Create a landmark or area through the HTTP API (http://127.0.0.1:3093).
3. Install and refresh the Bedrock behavior pack with npm run install:bedrock.
4. Enable eoinedge godmode agentic builder in your Bedrock world.
5. Run:
   • /function agentic_builder/info
   • /function agentic_builder/teleport
   • /function agentic_builder/preview
   • /function agentic_builder/clear
   • /function agentic_builder/build

That path works without relying on the optional live WebSocket bridge.

Choose A Workflow

• Stable Bedrock client: use the behavior-pack workflow. This is the recommended path for most users.
• Preview or WebSocket-capable Bedrock client: you can also use the optional live bridge for send_command and list_players.
• Switch play: build on PC first, then upload the finished Bedrock world to a Realm.

Architecture

This repo is intentionally split into two parts:

1. minecraft-mcp server
   • stores planner state for named landmarks and areas
   • geocodes real places through OpenStreetMap
   • converts real-world locations into Minecraft coordinates
   • generates Bedrock-safe command plans
   • optionally talks to Bedrock live through the WebSocket bridge
   • exports and installs the Bedrock behavior pack
2. eoinedge godmode agentic builder behavior pack
   • runs the exported build logic inside the world
   • gives you stable /function agentic_builder/... commands
   • works on stable Bedrock clients without requiring /connect

The short version is:

• the server is the planning and generation layer
• the behavior pack is the in-world execution layer

That split is the point of the project. Bedrock client support for live automation is inconsistent, so the behavior pack gives you a reliable execution path even when the live bridge is unavailable.

Agentic Workflow

The agentic workflow is:

1. you or an LLM decide what to build
2. the server creates or updates a landmark or area
3. the server chooses the best delivery path
4. Minecraft executes the result

There are two delivery paths:

1. Live bridge path
   • Bedrock is connected with /connect
   • the server can push raw commands directly into the world
   • best for quick shell builds and iterative testing
2. Behavior-pack path
   • no live Bedrock bridge required
   • the server exports and installs the pack automatically
   • the player runs /function agentic_builder/... in-game
   • best for stable Bedrock, repeatable builds, and sharing with other players

The repo now includes a single wrapper for that choice:

npm run build:place -- "Colosseum" none mesh

That command will:

• create or reuse the landmark
• try live placement if that path is valid
• otherwise install the behavior pack and tell you which in-game function to run

OpenCode And Agent Use

This repo is designed to work well with OpenCode.

An OpenCode agent can:

• call the local API to create landmarks and areas
• geocode real places from OpenStreetMap
• choose styles such as mesh, rooms, funhouse, civic, or launchsite
• export and install the pack automatically
• guide the player to run the matching in-game functions

Practical OpenCode flow:

1. run npm run start:safe (avoids port-in-use errors if it's already running)
2. run npm run opencode:local
   • OpenCode reads .env.opencode (created from .env.opencode.example).
   • If OPENROUTER_API_KEY or GROQ_API_KEY is set, the launcher will auto-fallback to the api profile if the local profile fails to start.
   • Prefer the repo launcher scripts; running opencode run ... directly may bypass the repo profiles/MCP setup.
3. ask OpenCode for a place, for example:
   • build me the Colosseum
   • import Galway Cathedral and make it funhouse inside
   • make a NASA launch site 900 blocks away from the Colosseum
4. let the agent call the local server and install the latest pack
5. in Minecraft, run the generated agentic_builder functions

The most useful one-command entrypoint for agents is:

npm run build:place -- -Landmark "NASA Launch Site 39A Rocket" -InteriorMode launchsite

Clawdbot, WhatsApp, And Telegram

This repo can also be driven through Clawdbot channel integrations.

• WhatsApp: your local Clawdbot already supports it and can use the repo-local Minecraft skills.
• Telegram: Clawdbot supports it too, but you need a Telegram bot token in channels.telegram.botToken or TELEGRAM_BOT_TOKEN.

Current local bridge rule:

• minecraft-mcp and OpenCode run on this machine.
• Clawdbot is the message-channel bridge for WhatsApp and Telegram.
• If clawdbot channels status --probe shows WhatsApp 401 Unauthorized, the saved WhatsApp session is stale and must be re-linked with clawdbot channels login.
• Telegram is not active until a bot token is configured.

Repo-local Clawdbot assets now live here:

• .clawdbot/skills/minecraft-mcp/SKILL.md
• .clawdbot/skills/bedrock-pack-troubleshooting/SKILL.md
• clawdbot.plugin.json

Useful commands:

npm run verify:chat-bridge
npm run start:chat-bridge
clawdbot channels login

Practical flow through Clawdbot:

1. Clawdbot receives the user message from WhatsApp or Telegram.
2. It loads the minecraft-mcp skill from this repo.
3. It uses the local server and MCP adapter in this repo.
4. It refreshes the Bedrock pack or uses the live bridge when appropriate.

Telegram note:

• Clawdbot has Telegram support locally, but Telegram is not active until you configure a bot token and start the gateway.

Why This Project Exists

Most Minecraft automation tools force you into one of two weak choices:

• bot-first automation that depends on a live client connection
• static packs or maps that are hard to regenerate from real-world data

This repo combines both:

• a local planning server that is scriptable, agent-friendly, and publishable
• a Bedrock behavior-pack layer that is reliable in actual worlds
• OpenStreetMap imports so places can come from real geography, not only hand-made coordinates

That makes it useful as:

• a family world planner
• a Bedrock place importer
• an agentic world-building tool for OpenCode
• a companion server for a shareable Bedrock pack

Real-World Places

The repo now supports an OpenStreetMap-first workflow for bringing real locations into Minecraft.

You can:

• set a world origin that ties one real lat/lon point to one Minecraft coordinate
• geocode a place name through OpenStreetMap Nominatim
• convert geographic coordinates to Minecraft coordinates
• create landmarks directly from geographic coordinates
• create areas directly from a geographic center and explicit size
• create landmarks from real places
• create build areas from OpenStreetMap bounding boxes

Google Maps is not the default integration here. OpenStreetMap is the shipped default because it is the cleanest no-key path to publish and test locally.

Building Playbook

For reusable structure guidance across scripted builds, use BUILDING_PLAYBOOK.md.

It compiles practical instructions for:

• modern buildings
• medieval buildings
• factory buildings

The playbook is distilled from:

• https://buildguides.net/
• https://mcbuild.org/schematics/
• https://minecraft.wiki/w/Tutorial:Construction

Use it when deciding palettes, facade depth, roofs, massing, site planning, and district layout before you script or place a new build.

Install

From npm:

npm install -g eoinedge-minecraft-mcp

Then run:

minecraft-mcp --help
minecraft-mcp --host 127.0.0.1 --port 3093

Without a global install:

npx eoinedge-minecraft-mcp --help

From the repo:

npm install
npm run start:safe

The planner HTTP server binds to 127.0.0.1:3093 by default.

The repo launchers and MCP adapter follow the same configuration inputs:

• HOST or MINECRAFT_MCP_HOST
• PORT or MINECRAFT_MCP_PORT
• DATA_DIR or MINECRAFT_MCP_DATA_DIR
• MINECRAFT_MCP_SERVER_URL when you want the wrappers to target a specific planner URL

Reproducible Test World

The current example seed for the tracked godmode test world is:

-3520022256761164229

Use that seed if you want the repo's scripted demo placements and saved occupancy map to line up with the same test world layout that the repo was exercised against most recently.

If you start a different Bedrock world or switch to a different seed, keep one of these boundaries clear:

• reuse the same repo data/planner-state.json and MAP.md only when you intend to keep building in that same tracked world
• use a separate DATA_DIR or MINECRAFT_MCP_DATA_DIR for a different world so its saved landmarks and district reservations do not get mixed with the existing map
• if you intentionally want a clean slate, reset planner state for that new world and run npm run map:refresh

First health checks:

curl -s http://127.0.0.1:3093/health
curl -s http://127.0.0.1:3093/actions

LLM Profiles

This repo supports two OpenCode profiles:

• local: default, uses local Ollama models
• api: lightweight, uses free hosted API models for devices that cannot run Ollama comfortably

The root opencode.json only defines the allowed providers and shared provider settings. The active model profile is selected by the launcher script.

The repo also now ships project-local OpenCode instructions and skills:

• .opencode/INSTRUCTIONS.md
• .opencode/skills/minecraft-builder/SKILL.md
• .opencode/skills/bedrock-pack-troubleshooting/SKILL.md

Those are discovered by OpenCode from the repo itself and are intended to steer it toward the stable workflows in this project.

Default Path: Ollama

The default repo setup is:

• OpenCode
• Ollama
• Qwen2.5-Coder 7B as the main local coding model
• Qwen2.5-Coder 1.5B as the local small-model fallback

This keeps the normal contributor path fully local and zero spend.

Lightweight Path: Free API Models

For smaller or constrained devices, you can switch to the api profile.

Current free hosted options wired into this repo:

• OpenRouter Free Router
• Groq, if you add a free Groq API key and pick a supported Groq model

The default API profile uses:

• openrouter/openrouter/free

That gives contributors a no-local-GPU path while still avoiding paid providers.

Fast Setup

Full Local Setup

Windows:

npm run setup:free:windows

Linux:

npm run setup:free:unix

macOS:

Install Ollama first from https://ollama.com/download/mac, then run:

npm run setup:free:unix

API-Only Setup

Windows:

npm run setup:free:api:windows

Linux or macOS:

npm run setup:free:api:unix

After setup:

npm install
npm run start

Run OpenCode with the local profile:

npm run opencode:local

Run OpenCode with the API profile:

npm run opencode:api

CLI

The published binary is minecraft-mcp.

Supported flags:

• --help
• --version
• --port <number>
• --data-dir <path>
• --log-requests
• --quiet

.env.opencode

Setup scripts create .env.opencode from .env.opencode.example.

Typical local/default use:

OPENCODE_PROFILE=local

Typical constrained-device use:

OPENCODE_PROFILE=api
OPENROUTER_API_KEY=your-key
OPENCODE_MODEL=openrouter/openrouter/free
OPENCODE_SMALL_MODEL=openrouter/openrouter/free

Optional Groq use:

OPENCODE_PROFILE=api
GROQ_API_KEY=your-key
OPENCODE_MODEL=groq/your-groq-model
OPENCODE_SMALL_MODEL=groq/your-groq-model

To see current Groq models in OpenCode after you add a key:

opencode models groq

What The Setup Scripts Do

Local/full setup:

• installs OpenCode globally if needed
• installs Ollama where the script can do so
• pulls local free coding models
• scaffolds .env.opencode

API-only setup:

• installs OpenCode globally if needed
• scaffolds .env.opencode
• switches the repo to the api profile
• leaves you to add OPENROUTER_API_KEY or GROQ_API_KEY

Where It Fits

This repo now ships both:

• the original local HTTP/WebSocket planning server
• a local stdio MCP adapter for tools, resources, and prompts

The planning layer gives you:

• defining named build areas
• defining landmarks inside those areas
• creating higher-level world blueprints that lay out multiple areas and landmarks at once
• generating Bedrock-safe command sets to mark those places in-world
• executing commands live against a connected Bedrock client
• querying players from a connected Bedrock client
• persisting your plan to disk so you can keep iterating

The MCP adapter gives agentic clients a standards-shaped surface with:

• MCP tools for status, one-shot place building, world blueprints, pack install, pack verification, and live commands
• MCP resources for planner state, blueprints, areas, landmarks, and individual area/landmark records
• MCP prompts for place-building, world-blueprint, and Bedrock-pack recovery workflows

Compared with current Minecraft MCP tooling:

• rgbkrk/rcon-mcp is stronger if you want live Java server administration and direct RCON control
• Mineflayer-style projects are stronger if you want a bot that walks around, gathers blocks, and builds in Java worlds
• Bedrock server utilities are stronger if you want to host or automate a dedicated Bedrock server
• this repo is strongest when you want agent-friendly Bedrock world design: real-world place import, one-shot family-world blueprints, behavior-pack delivery, and a workflow that can be driven by OpenCode or chat bridges and then delivered to Nintendo Switch through Realms

What this repo is now unusually strong at:

• geospatial Bedrock builds from OpenStreetMap or raw coordinates, not just hand-authored command snippets
• reusable world blueprints that lay out multiple areas and landmarks in one call
• a dual delivery path: live websocket command execution when Bedrock supports it, plus behavior-pack export/install when it does not
• an MCP surface that exposes tools, resources, and prompts for planning and building instead of just raw server administration
• Bedrock-first packaging, pack verification, and Realm/Switch-friendly world-prep workflows for family play

MCP Server

OpenCode is now configured to launch a local MCP server from this repo:

"mcp": {
  "minecraft": {
    "type": "local",
    "enabled": true,
    "command": ["node", "scripts/mcp-server.js"]
  }
}

You can also run it directly:

npm run mcp:stdio

The MCP server uses the existing local planning server behind the scenes and will start it if needed.

Exposed MCP surface:

• tools:
  • status
  • list_blueprints
  • create_blueprint_world
  • build_place
  • install_bedrock_pack
  • verify_bedrock_pack
  • create_landmark_from_geocode
  • create_landmark_from_geo
  • generate_landmark_commands
  • send_command
  • list_players
• resources:
  • minecraft://status
  • minecraft://planner/state
  • minecraft://blueprints
  • minecraft://landmarks
  • minecraft://areas
  • minecraft://landmarks/{slug}
  • minecraft://areas/{slug}
• prompts:
  • build-place-workflow
  • world-blueprint-workflow
  • bedrock-pack-recovery

Switch Reality

For Nintendo Switch, the practical workflow is:

1. Build and test the world on PC Bedrock Edition.
2. Upload that world to a Bedrock Realm.
3. Have the kids join the Realm from their Switches.

Direct file-style world importing is awkward on Switch. Realms is the clean path.

Minecraft reference:

• Replace a Realm world: https://www.minecraft.net/en-us/realms/change-realm-world
• Bedrock Realms overview: https://www.minecraft.net/en-us/realms/bedrock

Actions

• status
• send_command
• list_players
• list_templates
• list_blueprints
• set_geo_reference
• get_geo_reference
• geocode_place
• geo_to_minecraft
• minecraft_to_geo
• create_landmark_from_geo
• create_area_from_geo
• create_landmark_from_geocode
• create_area_from_geocode
• create_area
• list_areas
• get_area
• delete_area
• create_landmark
• list_landmarks
• get_landmark
• delete_landmark
• create_blueprint_world
• generate_area_commands
• generate_landmark_commands
• generate_map_plan

Live Bedrock Bridge

This path is optional.

Use it only if your Bedrock client actually supports /connect. Many stable Bedrock clients do not expose that command, so the behavior-pack workflow above is the safer default for newcomers.

The server now exposes a live Bedrock WebSocket bridge on the same port as the HTTP API.

Start the server:

npm run start

Then in Minecraft Bedrock, connect the client to the local bridge:

/connect 127.0.0.1:3093

After that, send_command and list_players work against the connected client.

Send one command:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"send_command\",\"params\":{\"command\":\"/time set day\"}}"

Run a whole generated landmark plan live:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"send_command\",\"params\":{\"landmark\":\"Your Landmark Name\"}}"

List players from the connected Bedrock client:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"list_players\",\"params\":{}}"

If no Bedrock client is connected, the transport actions return a connection error with the /connect hint.

API Quickstart

curl -s http://127.0.0.1:3093/health
curl -s http://127.0.0.1:3093/actions
curl -s -X POST http://127.0.0.1:3093/run -H "Content-Type: application/json" -d "{\"action\":\"status\",\"params\":{}}"

Recommended Local World Flow

This is the clearest first run for most people:

1. Start the server:

npm run start

2. Import or create a landmark:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_landmark_from_geocode\",\"params\":{\"query\":\"Your Place Name\",\"name\":\"Your Landmark Name\",\"style\":\"mesh\",\"height\":18}}"

3. Export a behavior pack for that landmark:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-bedrock-pack.ps1 `
  -Landmark "Your Landmark Name"

4. In Minecraft Bedrock:

   • open your world settings
   • go to Behavior Packs > My Packs
   • enable eoinedge godmode agentic builder
   • enter the world

5. Run these in chat:

/function agentic_builder/info
/function agentic_builder/teleport
/function agentic_builder/preview
/function agentic_builder/clear
/function agentic_builder/build
/function agentic_builder/build_connected

Use build_connected when you want the landmark shell plus cleared connector roads to nearby saved landmarks.

World Map Tracking

Planner state is the real source of truth, but the repo also keeps a generated MAP.md so people and agents can see which districts, landmarks, and reserved spaces already exist before placing something new.

Refresh it after any new build plan or import:

npm run map:refresh

Use MAP.md before creating another district-sized build so you do not drop a mall, pagoda district, launch site, or landmark on top of occupied space.

Most scripted builders already update planner state and refresh MAP.md on success. Run a manual refresh if you edited planner state outside the scripted commands.

Planner state is world-specific in practice. If you move to a new Bedrock world or seed, either point the server at a separate DATA_DIR or clear and rebuild the saved planner map for that world before you trust the existing reservations.

Scripted Demo Districts And Scenes

The repo now includes a larger set of higher-detail scripted builders. Use these when you want a repeatable, map-aware district or scene instead of a one-off shell export.

City, district, and architecture scenes:

• npm run build:japan
  • rebuilds Mini Tokyo District
  • anchor: x=230 y=100 z=360
  • includes a layered pagoda, walls, garden pond, cherry trees, shop blocks, and a more usable interior
• npm run build:mall
  • rebuilds Eoin Edge Mall
  • anchor: x=120 y=100 z=492
  • includes a modern facade, fountain plaza, parking, lamps, and branded Starbucks, Penneys, and Tesco wings
• npm run build:medieval
  • rebuilds Stonekeep Market District
  • anchor: x=347 y=100 z=360
  • includes a keep, gatehouse, towers, smithy, and market stalls
• npm run build:factory
  • rebuilds Ironworks Factory District
  • anchor: x=327 y=100 z=490
  • includes an assembly hall, truck court, tanks, office block, and industrial yard
• npm run build:egypt
  • rebuilds the Egypt district with sphinx, pyramids, interior maze logic, and catacomb-style underground routes
• npm run build:empire
  • rebuilds the local Empire State Building scene at the tracked world anchor
• npm run build:themepark
  • rebuilds the park-style scripted attraction district

Pirate, ocean, and underwater scenes:

• npm run build:pirate
  • rebuilds the main pirate island and ship area
• npm run build:pirate:expansion
  • rebuilds the skull island expansion, cliff-facing pirate route, and hidden ferry corridor
• npm run build:cliff-village
  • rebuilds Bonejaw Cliff Village
  • currently rotated to face the skull-island side
• npm run build:pearlharbor
  • rebuilds Pearl Harbor Battle Waters
  • includes ships, docks, attack aircraft, smoke, and shoreline action below the cloud layer
• npm run build:atlantis
  • rebuilds the Atlantis district under the Pearl Harbor water
  • includes the central dome, outer towers, and lit seafloor layout
• npm run build:oceanfloor
  • rebuilds the current-player seafloor outpost at the live ocean-floor anchor
  • includes a large dry dome, a dry vertical access tube, and a survival-safe ladder path

Space, launch, and sci-fi scenes:

• npm run build:nasa
  • rebuilds the upgraded Launch Complex 39A scene
  • includes the VAB silhouette, crawlerway, pad, tower, tank farm, roads, and support campus
• npm run build:spacex
  • builds the SpaceX, Tesla, and Starlink tech scene
• npm run build:deathstar
  • rebuilds the large Death Star battle sector
• npm run build:deathstar:planets
  • adds the planet set around the Death Star sky sector
• npm run build:solarsystem
  • builds a walkable solar-system orrery scene
• npm run build:milkyway
  • builds the Milky Way sky-gallery scene near the tracked space district

Landmark and showcase scenes:

• npm run build:landmarks
  • rebuilds the world landmarks validation park
  • includes Eiffel Tower, Statue of Liberty, Big Ben, Arc de Triomphe, Leaning Tower of Pisa, and Christ the Redeemer replicas
• npm run build:titanic
  • rebuilds the RMS Titanic memorial scene with the surrounding water layout

Refresh the map manually any time you want to mirror planner changes back into MAP.md:

npm run map:refresh

Use the scripted builders first when a matching district already exists. They are usually more detailed than generic shell generation and they preserve the tracked map layout more reliably.

World Blueprint Quickstart

If you want a stronger high-level planning flow than single landmarks, use a world blueprint.

List the built-in blueprints:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"list_blueprints\",\"params\":{}}"

Preview a multi-area layout without saving it:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_blueprint_world\",\"params\":{\"blueprint\":\"family-adventure-park\",\"x\":0,\"y\":70,\"z\":0,\"dryRun\":true}}"

Create and save a layout:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_blueprint_world\",\"params\":{\"blueprint\":\"switch-realm-starter\",\"x\":0,\"y\":70,\"z\":0,\"namePrefix\":\"Kid World\"}}"

Available built-in blueprints:

• family-adventure-park: safe hub, village green, race quarter, lookout ridge, and secret cave marker
• switch-realm-starter: compact Realm-friendly starter layout with hub, build yard, farm commons, and quest woods
• creator-campus: showcase square, launch campus, and test yard for demo-heavy or agent-driven worlds

Geospatial Quickstart

1. Set a real-world origin for your Minecraft map.
2. Search a place through OpenStreetMap.
3. Import it as a landmark or area.

Set a real-world origin:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"set_geo_reference\",\"params\":{\"name\":\"Home Origin\",\"origin\":{\"lat\":53.3498,\"lon\":-6.2603},\"world\":{\"x\":0,\"y\":70,\"z\":0},\"scale\":2}}"

Geocode a place:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"geocode_place\",\"params\":{\"query\":\"Your Place Name\",\"limit\":1}}"

Suggested place names to try:

• Eiffel Tower
• Empire State Building
• Galway Cathedral
• Colosseum
• Sydney Opera House

Copy-paste geocode examples:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"geocode_place\",\"params\":{\"query\":\"Eiffel Tower\",\"limit\":1}}"

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"geocode_place\",\"params\":{\"query\":\"Empire State Building\",\"limit\":1}}"

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"geocode_place\",\"params\":{\"query\":\"Galway Cathedral\",\"limit\":1}}"

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"geocode_place\",\"params\":{\"query\":\"Colosseum\",\"limit\":1}}"

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"geocode_place\",\"params\":{\"query\":\"Sydney Opera House\",\"limit\":1}}"

Create a Minecraft landmark from that geocoded place:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_landmark_from_geocode\",\"params\":{\"query\":\"Your Place Name\",\"name\":\"Your Landmark Name\",\"style\":\"mesh\",\"height\":18}}"

Create a landmark directly from coordinates:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_landmark_from_geo\",\"params\":{\"name\":\"Custom Landmark\",\"lat\":53.3498,\"lon\":-6.2603,\"style\":\"pillar\"}}"

Create a Minecraft build area from the place bounding box:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_area_from_geocode\",\"params\":{\"query\":\"Your Place Name\",\"name\":\"Your Build Area\",\"padding\":8,\"yMin\":70,\"yMax\":95}}"

Create a build area directly from coordinates and size:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_area_from_geo\",\"params\":{\"name\":\"Custom Area\",\"lat\":53.3498,\"lon\":-6.2603,\"widthBlocks\":40,\"depthBlocks\":28,\"height\":12}}"

Generate the mesh shell commands:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"generate_landmark_commands\",\"params\":{\"landmark\":\"Your Landmark Name\"}}"

Example: Place To Bedrock End To End

This is the generic place-import workflow.

Set the map origin:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"set_geo_reference\",\"params\":{\"name\":\"Home Origin\",\"origin\":{\"lat\":53.3498,\"lon\":-6.2603},\"world\":{\"x\":0,\"y\":70,\"z\":0},\"scale\":2}}"

Import a place as a mesh landmark:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_landmark_from_geocode\",\"params\":{\"query\":\"Your Place Name\",\"name\":\"Your Landmark Name\",\"style\":\"mesh\",\"wallBlock\":\"stone_bricks\",\"roofBlock\":\"deepslate_tiles\",\"floorBlock\":\"polished_andesite\",\"height\":18}}"

Create a build area around the imported place:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_area_from_geocode\",\"params\":{\"query\":\"Your Place Name\",\"name\":\"Your Build Area\",\"padding\":8,\"yMin\":70,\"yMax\":95}}"

Generate the shell commands:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"generate_landmark_commands\",\"params\":{\"landmark\":\"Your Landmark Name\"}}"

Then install the Bedrock behavior pack directly into your local Bedrock development packs:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-bedrock-pack.ps1 `
  -Landmark "Your Landmark Name"

The exported pack uses a generic namespace by default:

/function agentic_builder/info
/function agentic_builder/teleport
/function agentic_builder/preview
/function agentic_builder/clear
/function agentic_builder/build

The installer now reports the resolved namespace plus preview, clear, and the default build entrypoint. If you set an interior mode such as civic or launchsite, the one-step build function becomes /function <namespace>/build_full.

The generated landmark is a footprint extrusion shell. It gives you a solid real-world outline fast, but you will still want to add doors, windows, roof details, and interior structure by hand if you want a closer recreation.

Generic Bedrock Export

The behavior-pack exporter is generic. It can package any saved landmark as a Bedrock behavior pack.

If you do not pass -Landmark, it uses the first saved landmark from planner state. For predictable results, passing -Landmark explicitly is better.

Install the first saved landmark:

npm run install:bedrock

Install a different saved landmark:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-bedrock-pack.ps1 `
  -Landmark "Custom Landmark"

If you export Custom Landmark, the generated functions still use the generic default namespace unless you override it with -FunctionNamespace:

/function agentic_builder/info
/function agentic_builder/teleport
/function agentic_builder/preview
/function agentic_builder/clear
/function agentic_builder/build

You can also shift the installed build without changing saved planner data by using install-time offsets:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-bedrock-pack.ps1 `
  -Landmark "Colosseum" `
  -OffsetX 200 `
  -OffsetZ 150

Useful offset flags:

• -OffsetX <number>
• -OffsetY <number>
• -OffsetZ <number>

You can also choose a default interior mode at install time:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-bedrock-pack.ps1 `
  -Landmark "Colosseum" `
  -InteriorMode civic

Supported interior modes:

• none: shell only
• hollow: clear open internal volume
• rooms: simple room layout
• funhouse: rooms, stairs, basement, and secret room
• civic: wider circulation plus clearer opposing exits, inspired by Irish Part B, Part K, and Part M guidance
• launchsite: clears the site, then adds a stylized rocket, gantry, pad markings, and launch lighting on top of the imported shell footprint

civic is a gameplay heuristic for Minecraft builds. It is not a real-world compliance tool.

After reinstalling with offsets, reload the pack in Minecraft and run:

/function agentic_builder/info
/function agentic_builder/teleport

info will show the shifted anchor and safe teleport coordinates.

In-Game Commands

After the pack is enabled in a world, these are the main in-game commands:

• /function agentic_builder/info
• /function agentic_builder/teleport
• /function agentic_builder/preview
• /function agentic_builder/clear
• /function agentic_builder/build_clear
• /function agentic_builder/build
• /function agentic_builder/rebuild
• /function agentic_builder/roads
• /function agentic_builder/connect
• /function agentic_builder/build_connected
• /function agentic_builder/interior
• /function agentic_builder/build_full
• /function agentic_builder/rebuild_full

Useful prep commands:

• /gamemode creative
• /time set day
• /weather clear

Long-form command equivalents:

• preview = build_preview
• clear = clear_footprint
• tp = teleport
• help = info
• connect = roads
• empty = hollow

Safe recommended order:

1. /function agentic_builder/teleport
2. /function agentic_builder/preview
3. /function agentic_builder/clear
4. /function agentic_builder/build

If you want cleared approach roads as well:

1. /function agentic_builder/teleport
2. /function agentic_builder/build_clear
3. /function agentic_builder/build
4. /function agentic_builder/roads

roads now lays lit connector roads with lamp posts, not just plain road strips.

Or use the one-step shortcut:

/function agentic_builder/build_connected

The in-game function namespace stays stable across pack updates:

/function agentic_builder/info
/function agentic_builder/teleport
/function agentic_builder/build_clear
/function agentic_builder/build
/function agentic_builder/roads
/function agentic_builder/build_connected
/function agentic_builder/launchsite

Fast rebuild:

/function agentic_builder/rebuild

Interior options:

/function agentic_builder/interior
/function agentic_builder/build_full
/function agentic_builder/rebuild_full
/function agentic_builder/hollow
/function agentic_builder/rooms
/function agentic_builder/funhouse
/function agentic_builder/civic
/function agentic_builder/launchsite
/function agentic_builder/stairs
/function agentic_builder/basement
/function agentic_builder/secret

NASA launch-site example:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\install-bedrock-pack.ps1 `
  -Landmark "NASA Launch Site 39A Rocket" `
  -InteriorMode launchsite

One-command local reinstall:

npm run install:bedrock -- "NASA Launch Site 39A Rocket" launchsite

The default installed pack name includes the Bedrock pack version so the newest entry is easy to spot in Bedrock:

eoinedge godmode agentic builder v1.2.0 current

One-command verification:

npm run verify:bedrock

Local Bedrock Screenshots

If you want real screenshots instead of AI renders, use your local Bedrock client after you build the imported shell.

List visible Minecraft windows:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\capture-minecraft-window.ps1 -ListOnly

Capture the first visible Minecraft window after a short countdown:

npm run capture:minecraft

Capture to a specific file with a longer delay so you can position the camera first:

powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\capture-minecraft-window.ps1 `
  -DelaySeconds 10 `
  -OutPath .\output\captures\landmark-exterior.png

Suggested workflow:

1. Run the generated landmark /fill commands in your Bedrock world.
2. Fly to the build and frame the shot you want.
3. Start the capture script.
4. Switch back to Minecraft before the countdown ends.
5. The screenshot is saved under .\output\captures\.

This capture helper works with the local Bedrock window only. It does not move the camera or place blocks for you.

Example: Create An Area

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_area\",\"params\":{\"name\":\"Home Base\",\"theme\":\"starter-town\",\"tags\":[\"safe-zone\",\"spawn\"],\"from\":{\"x\":-20,\"y\":64,\"z\":-20},\"to\":{\"x\":20,\"y\":80,\"z\":20},\"notes\":\"Main family base with beds, storage, and farm plots.\"}}"

Example: Create A Landmark

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"create_landmark\",\"params\":{\"name\":\"North Watchtower\",\"area\":\"Home Base\",\"style\":\"pillar\",\"position\":{\"x\":0,\"y\":64,\"z\":-18},\"description\":\"Tall marker visible from spawn.\"}}"

Example: Generate Commands

Create the area outline:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"generate_area_commands\",\"params\":{\"area\":\"Home Base\",\"outlineBlock\":\"orange_wool\",\"cornerBlock\":\"glowstone\"}}"

Create the landmark:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"generate_landmark_commands\",\"params\":{\"landmark\":\"North Watchtower\",\"baseBlock\":\"stone_bricks\",\"accentBlock\":\"lantern\",\"height\":8}}"

Generate the whole plan:

curl -s -X POST http://127.0.0.1:3093/run \
  -H "Content-Type: application/json" \
  -d "{\"action\":\"generate_map_plan\",\"params\":{}}"

Landmark Styles

• pillar: easiest to spot from far away
• beacon: major hub or castle marker
• camp: scenic stop or quest checkpoint
• gate: district or biome entrance marker
• mesh: imported OpenStreetMap building footprint extruded into a Minecraft shell

Directory Map

Important repo paths:

• assets: branding assets and logos
• assets/eoinedge-godmode-agentic-builder-logo.svg: Doom-inspired repo and pack logo wordmark
• assets/pack_icon.png: Bedrock pack thumbnail copied into exported packs as pack_icon.png
• AGENTS.md: canonical repo-wide agent workflow and troubleshooting guide
• CLAUDE.md: Claude-oriented repo guidance
• llms.txt: concise LLM-readable project summary
• .github/copilot-instructions.md: GitHub Copilot repo instructions
• .claude/skills: Claude-compatible skill mirrors
• .agents/skills: agent-compatible skill mirrors
• server.js: main API server and CLI entrypoint
• scripts/export-bedrock-behavior-pack.ps1: exports and installs the Bedrock behavior pack
• scripts/install-bedrock-pack.ps1: one-command local Bedrock refresh and install
• scripts/verify-bedrock-pack.ps1: one-command Bedrock pack verification
• scripts/capture-minecraft-window.ps1: local screenshot helper for Bedrock windows
• .opencode/INSTRUCTIONS.md: project-local OpenCode instructions
• .opencode/skills: OpenCode project-local skills
• data: local planner state
• data/planner-state.json: saved areas, landmarks, and geo reference
• output/bedrock: generated behavior-pack folders and .mcpack exports
• output/plans: exported raw command plans and build guides
• output/captures: local screenshot output
• test: unit and integration tests
• RELEASE_CHECKLIST.md: release commands and publish checklist
• CHANGELOG.md: release notes history
• .github/workflows/release-bedrock-pack.yml: auto-export the .mcpack on version tags

Important local Bedrock paths on this machine:

• C:\Users\Eoin\AppData\Local\Packages\MICROSOFT.MINECRAFTUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs
• C:\Users\Eoin\AppData\Local\Packages\MICROSOFT.MINECRAFTUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\behavior_packs
• current installed pack: C:\Users\Eoin\AppData\Local\Packages\MICROSOFT.MINECRAFTUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\eoinedge_godmode_agentic_builder
• current imported pack mirror: C:\Users\Eoin\AppData\Local\Packages\MICROSOFT.MINECRAFTUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\behavior_packs\eoinedge_godmode_agentic_builder
• current default world UI name: eoinedge godmode agentic builder v1.2.0 current
• important note: the on-disk source of truth is the development_behavior_packs\eoinedge_godmode_agentic_builder and behavior_packs\eoinedge_godmode_agentic_builder folders. if Bedrock still shows older entries such as 1.0.0, 1.1.0, or 1.1.3, those are stale world/UI cache entries, not extra repo installs.

When troubleshooting, check these locations first:

1. output/bedrock/.../functions/agentic_builder
2. development_behavior_packs/.../functions/agentic_builder
3. world Behavior Packs > Active

Branding

The repo ships with a reusable logo asset:

• eoinedge-godmode-agentic-builder-logo.svg

Intended use:

• GitHub social preview or README image
• npm package branding in docs
• future pack thumbnail or marketplace art base

Testing

npm test

You can also run:

• npm run test:unit
• npm run test:integration

Release-readiness check:

npm run release:check

Publish

Before publishing:

npm run release:check
npm publish --dry-run
npm audit --omit=dev
npm whoami
npm publish --access public

If this folder is not a git repo yet:

git init
git add .
git commit -m "Release 0.1.0"

Then connect GitHub and publish the repo:

gh auth login
git remote add origin https://github.com/<your-user>/minecraft-mcp.git
git branch -M main
git push -u origin main
git tag v0.1.0
git push origin v0.1.0

Share these links after release:

• GitHub repo
• GitHub release page
• npm package page for eoinedge-minecraft-mcp
• one Bedrock screenshot or GIF

Release Troubleshooting

If publish or release setup fails, use this order:

1. Run npm run release:smoke
2. Run npm whoami
3. Run gh auth status
4. Check whether this folder is a git repo

Common issues:

• npm whoami returns 401 Unauthorized Fix: run npm login
• gh auth status says you are not logged in Fix: run gh auth login
• npm publish --dry-run passes but real publish is blocked Fix: confirm npm auth, package name, and version
• package name check Run npm view eoinedge-minecraft-mcp version
• no git history exists yet Run git init, git add ., and create the first release commit

Bedrock-specific troubleshooting:

• If Bedrock shows stale command options, fully close Minecraft, reopen it, remove the active pack from the world, and re-enable it from Behavior Packs > My Packs.
• Autocomplete may not show every function name even when the file exists. Try the full command directly.
• Development packs live under C:\Users\<you>\AppData\Local\Packages\MICROSOFT.MINECRAFTUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\.
• Use npm run install:bedrock for local refreshes. It cleans old eoinedge_godmode_agentic_builder* development-pack folders, reinstalls the current pack, and keeps the stable agentic_builder function namespace.
• When in doubt, trust the files at development_behavior_packs\eoinedge_godmode_agentic_builder\manifest.json and behavior_packs\eoinedge_godmode_agentic_builder\manifest.json first. The world UI can lag behind and keep showing older entries until you remove and re-add the pack in that world.

Release Automation

Tag-based releases now build the Bedrock pack automatically.

When you push a tag like v0.1.0, GitHub Actions will:

1. install dependencies
2. start the local planner server in CI
3. export the .mcpack with the stable agentic_builder namespace
4. upload the .mcpack as a workflow artifact
5. attach the .mcpack to the GitHub release

By default the workflow exports the first saved landmark in planner state. If you want a specific landmark for release assets, set a GitHub repository variable named BEDROCK_RELEASE_LANDMARK.

The Bedrock pack version is tracked separately from the npm package version in package.json under bedrockPackVersion. That keeps the in-game pack version readable even when the npm package is still on an early 0.x release.

Bedrock pack troubleshooting:

• the world still shows old commands Fix: fully close Minecraft, reopen it, deactivate the old pack, then activate the latest one again
• Bedrock caches an older pack revision Fix: run npm run install:bedrock, then fully close Minecraft and re-enable the pack in the world
• in-game autocomplete only shows a few functions Fix: run /function agentic_builder/info or type a more specific prefix like /function agentic_builder/re
• commands exist on disk but say not found in world Fix: the world is attached to a stale pack revision, not the current installed folder

Quick file checks:

Get-ChildItem .\output\bedrock\eoinedge_godmode_agentic_builder\functions\agentic_builder
Get-ChildItem "$env:LOCALAPPDATA\Packages\MICROSOFT.MINECRAFTUWP_8wekyb3d8bbwe\LocalState\games\com.mojang\development_behavior_packs\eoinedge_godmode_agentic_builder\functions\agentic_builder"

Or use:

npm run verify:bedrock

Build A Place Now

Use one command when you want the repo to do the right thing automatically:

• if the Bedrock live bridge is connected, it sends the landmark shell straight into the world
• if the live bridge is not connected, it exports and installs the behavior pack automatically

Quick place-name example:

npm run build:place -- "Colosseum" none mesh

Launch-site example:

npm run build:place -- "NASA Launch Site 39A Rocket" launchsite mesh

Existing saved landmark example:

npm run build:place -- -Landmark "NASA Launch Site 39A Rocket" -InteriorMode launchsite

Move the exported pack build away from another landmark:

npm run build:place -- -Landmark "NASA Launch Site 39A Rocket" -InteriorMode launchsite -OffsetX 900 -OffsetZ 900

Create from coordinates instead of a place name:

npm run build:place -- -Lat 28.6065245 -Lon -80.6041176 -Name "NASA Launch Site 39A Rocket" -InteriorMode launchsite

Notes:

• InteriorMode none is the only mode that can use the live bridge directly.
• launchsite, rooms, funhouse, civic, and other exporter-only modes fall back to behavior-pack install.
• If you do not want the .mcpack file opened automatically, add -NoOpenMcpack.

Docker

copy .env.example .env
docker compose up --build

Planner data is stored in ./data/planner-state.json and mounted into the container.