MCP-rogal

MCP-rogal

An MCP server for building Minecraft mods and datapacks.

Point an AI assistant at your running game and it can write a datapack, reload it, run it, read the error the game actually produced, and fix it — without you relaying anything by hand.

26 tools, Fabric, Minecraft 26.2.

---

The idea

Most of the time lost writing a datapack goes to one thing: something did not work and the game would not say why. A macro missing one $(key) aborts the whole function. /reload reports success while the pack it just tried to load failed. A trigger that was never armed looks exactly like a button that does nothing.

So every command comes back with what really happened:
time set day → success=true result=1000
setblock ~ ~ ~ minecraft:not_a_block → errorType=parse cursor=15
execute if block ~ ~ ~ bedrock run say → success=false error=null
Three different outcomes, told apart: it worked and returned 1000; it never parsed, and here is the character where parsing stopped; it ran fine and did nothing at all.

That last line is the one that matters. It is what a silent failure looks like, and it is now visible instead of indistinguishable from success.

---

What it can do

Commands and timing

• execute_commands — real status, return value, parse errors with a cursor position. run_as: {player, permission_level} runs at a chosen permission level: execute as X rebinds @s but keeps your permissions, so an operator-gated path looks fine until a real player hits it. This tests the path a real player takes.
• advance_ticks, and a wait_ticks argument — state written this tick is not visible to a read until the next one, so a read/write pair issued together silently sees stale values.
• validate_command — parse without running; also returns the completions available at the cursor, which is how you discover what an argument accepts.

Logs

• get_logs — cursor-based. The response carries nextId; pass it back and you get only what arrived since. Reports missed when the buffer overflowed past your cursor, so a gap is visible rather than silent. Covers both the log file and in-game chat, which never reaches it.
• wait_for_log — blocks until a pattern appears. Trigger something, then wait for the line that tells you whether it worked, instead of polling.
• get_crash_reports — for when the game died along with the buffer.

Datapacks

• files — read, write, list, inside an allow-listed set of directories.
• reload_datapacks — runs /reload and returns the log it produced, because /reload succeeds even when a pack fails to load.
• get_world_info — save folder, datapack folder, and the pack formats this build expects. A wrong pack_format gets the pack rejected with nothing but a vague "Error reading pack metadata", while every function inside it quietly does nothing.
• list_ids, describe_block_state — valid ids by registry, and the exact properties a block accepts in [brackets] with their allowed values and defaults. No more guessing whether a door needs half=upper or part=head.

Fake players

fake_players — real ServerPlayers in the player list, for testing rules that only exist with more than one player. @a selects them, scoreboards score them, their UUID is derived from their name so scores survive death, kill respawns them rather than leaving them dead, despawn fires a genuine leave event, and /tp moves them between dimensions.

Nothing in game logic checks "is this one fake, skip it" — a test against special-cased code proves nothing about the real thing.

What they cannot do: press a button in a dialog. That needs a client.

Client control

• press_key, type_text, send_keybind, mouse — input goes through the same entry points real input does, so it behaves identically in the world, in menus and in text fields.
• get_open_screen — every widget with its rendered text and rectangle. Inspect a menu without reading a screenshot; missing translations show up immediately, because an untranslated widget renders its raw key.
• click_widget — click by the button's visible label. An ambiguous match clicks nothing and returns the candidates. Labels like "Delete World" are refused without explicit permission.
• open_screen, options — jump straight to a screen, or change a setting without dragging a slider.
• reload_resources — F3+T, which has no command.
• rejoin_world — dynamic registries (dialog/, enchantment/, worldgen/) are only read when a world loads. /reload leaves the old definitions in place, which looks exactly like your edit having no effect.

---

Setup

Requires: Minecraft 26.2 · Fabric Loader 0.19.3+ · Fabric API · Java 25+

1. Install Fabric Loader for 26.2
2. Put Fabric API in mods/
3. Put this mod's jar there too
4. Start the game

The server starts on its own and logs:
HTTP MCP Server started on http://localhost:8080/mcp with 26 tools
Works on a client and on a dedicated server. On a dedicated server the tools that need a screen are simply not registered.

Connecting an assistant

Claude Code:
claude mcp add --transport http minecraft http://localhost:8080/mcp
Cursor, Windsurf, VS Code — in your MCP config:
{
"mcpServers": {
"minecraft": {
"url": "http://localhost:8080/mcp"
}
}
}
A world has to be loaded. Without one the tools say so plainly.

---

In practice

The whole datapack loop, without leaving the game:

Write a function that gives every hunter a compass, put it in a datapack, reload it, and tell me whether it loaded.

get_world_info for the folder and pack format → files write → reload_datapacks → read the log. A pack that failed to load is reported, not assumed away.

Testing the non-operator path:

Check that /dialog show is refused for an ordinary player but works through /trigger.

execute_commands with run_as: {permission_level: 0}.

A multiplayer rule:

Spawn two fake players, assign roles, and check each hunter gets their own compass.

Menu navigation:

Open the video settings and tell me what they are set to.

open_screen, then get_open_screen returns the text of every widget.

---

Configuration

config/mcp.json, created on first run:
{
"server": { "port": 8080, "host": "localhost", "requestTimeoutMs": 30000 },
"input": { "enabled": true, "allowDestructiveUi": false,
"preventPauseOnLostFocus": true },
"logs": { "bufferSize": 5000, "maxWaitMs": 60000, "maxBodyLogChars": 2000 },
"files": { "enabled": true, "allowDelete": false,
"allowedRoots": ["saves","config","datapacks","resourcepacks",
"logs","crash-reports"] },
"fakePlayers": { "enabled": true, "maxCount": 8 },
"auth": { "token": null }
}
preventPauseOnLostFocus — singleplayer normally pauses the moment you click into another window, and the pause menu covers the view. Every screenshot and every screen read would then report the pause menu instead of the game. This is off by default here; Escape still pauses.

---

Security

This endpoint runs commands, injects input and writes files. Treat it accordingly.

• auth.token — when set, requires an Authorization: Bearer <token> header.
• The server refuses to start on a non-loopback host without a token.
• Files — confined to the allow list; paths resolving outside it, through .. or a symlink, are refused. Deleting is off by default.
• Destructive buttons — clicking "Delete World" and the like needs both a config flag and an explicit argument.
• Commands still pass a configurable safety validator.

---

Technical notes

• Input goes through the private KeyboardHandler and MouseHandler callbacks via mixin invokers rather than KeyMapping, which is why it works in menus and text fields and not only in the world.
• Commands run on the server thread through CommandSourceStack.withCallback, with parse errors separated from runtime errors. In singleplayer that means the integrated server, so results are real rather than inferred from chat.
• Logs are captured by a Log4j appender attached programmatically, with a reentrancy guard.
• Tools live in a registry — adding one is a single class.
• Everything touching the loader sits behind a Platform interface, so a NeoForge port is the entry point, the tick subscription and the mixin config; the rest is plain Minecraft API.

---

Troubleshooting

It will not connect — look for HTTP MCP Server started in the log. Port 8080 may be taken; change server.port.

"No server is running" — no world is loaded.

A command returns success=false with no error — it ran and did nothing. Usually a condition that did not match, or a function that returned early. Not a tool failure.

/function is always success=false — vanilla behaviour: a function returns 0 unless it ends with /return. Check the world state, or add a /return.

A datapack is not picked up — check pack_format against get_world_info.

An edit does nothing after /reload — if it is under dialog/, enchantment/ or worldgen/, use rejoin_world.

A click did not register — screens that fade out switch a few ticks later. Raise settle_ticks or read get_open_screen again.

---

Credits and license

Built on top of mcp-server-mod by cuspymd, which provided the original HTTP MCP bridge, the command safety validator and the block scanner.

Released under CC0-1.0, the same as the original — public domain, no strings.

Full tool reference: TOOLS.md · Русское описание: DESCRIPTION.ru.md