An MCP server that controls a Minecraft bot via mineflayer, enabling automated mining, combat, following, and inventory management through standardized MCP tools.
This server has 6 tools with schemas and descriptions, but the quality is inconsistent. All tools are defined in src/config/toolsSchema.ts with proper JSON Schema input structures. However, descriptions are in Japanese (not English-first, limiting LLM accessibility), and several critical issues emerge: (1) descriptions lack WHEN/WHY context needed for tool selection; (2) parameter descriptions are sparse and don't clarify prerequisites or constraints; (3) output schemas are completely undocumented, the LLM has no idea what these tools return; (4) conditional parameter requirements (e.g., blockName and quantity required only when mode='on') are documented but not enforced via JSON Schema; (5) no error handling guidance is visible; (6) no tool annotations (readOnlyHint, destructiveHint, idempotentHint) despite clear risk classifications. The naming is reasonable (minecraft_get_status, minecraft_set_mining_mode, etc. follow verb_noun pattern), but descriptions read like Japanese API docs, not LLM prompts. Most tools lack the 50 - 200 character 'how-to' summary that helps LLMs decide when to invoke them.
Descriptions are in Japanese, not English. While this may suit a Japanese-language user, most LLMs are English-first and will perform worse on Japanese descriptions. Descriptions should be in English for maximum LLM clarity.
Conditional parameter requirements (blockName and quantity required only when mode='on') are documented in prose but NOT enforced in JSON Schema. Schema shows these as optional (not in 'required' array) even though they are conditionally mandatory. Use oneOf or discriminated union patterns to express this formally.
Recommendations
Translate all descriptions and parameter docs to English. Use clear, action-oriented language: 'When should the LLM call this?' and 'What happens next?' Examples: minecraft_get_status → 'Fetch the bot's current health, hunger, position, active modes, and task queue. Call this before taking actions to check if the bot is in danger or busy. Returns object: {health: 0-20, hunger: 0-20, position: {x, y, z}, modes: {mining, combat, following}, tasks: []}.' minecraft_set_mining_mode → 'Enable mining a target block type. On success, bot enters auto-mining mode and returns {mode: "mining", target: "oak_log", quantity: 10, progress: 0}. If blockName is invalid, returns error with available blocks list.'
Express conditional parameter requirements in JSON Schema using oneOf or conditional constraints. Example for minecraft_set_mining_mode: Use oneOf with two branches: (1) mode=off with no other params required; (2) mode=on with blockName and quantity both required. This prevents LLM confusion and enables schema validation.
No error handling guidance. Tools provide no indication of what errors might occur, how to recover, or what the LLM should do next. E.g., minecraft_get_status should document 'returns error if bot is not connected; try reconnecting first.' minecraft_set_mining_mode should document 'returns error if blockName is invalid; call minecraft_get_available_blocks first.'
No tool annotations. Several tools modify state (minecraft_stop_behavior is destructive; minecraft_set_mining_mode, minecraft_set_follow_mode, minecraft_set_combat_mode, minecraft_set_home all have WRITE risk), but none declare readOnlyHint, destructiveHint, or idempotentHint. This prevents clients from warning users or adding confirmation steps.
Descriptions are too brief (avg ~150 chars, some <50 chars). They state WHAT but not WHEN or WHY. A description should answer: What does this do? When is it called? What are side effects? E.g., minecraft_get_status should say 'Call this to inspect bot state before every action; returns health, hunger, position, active modes, and pending tasks. If health is low (<5), consider calling minecraft_stop_behavior and taking shelter.'
No parameter validation guidance. Schema defines enums and types, but the description does not explain validation bounds, regex patterns, or ranges. E.g., 'quantity' has no min/max documented. What happens if quantity is 0, negative, or 1000000?
minecraft_set_mining_modeminecraft_set_home
Add tool annotations. For each WRITE tool, add destructiveHint or mark as idempotent. Example: minecraft_set_mining_mode should include {"destructiveHint": false, "idempotentHint": true} (setting the same target twice is idempotent). minecraft_stop_behavior should include {"destructiveHint": true} (interrupting all tasks is irreversible).
Add error handling guidance in descriptions. For each tool, document likely errors and recovery paths. Example: minecraft_set_mining_mode → 'If blockName is invalid, an error message lists available blocks. If bot is currently in combat, mining is delayed until combat mode is off; call minecraft_set_combat_mode("off") first if needed.' minecraft_get_status → 'Returns error if bot is not connected to Minecraft server; ensure the server is running and reachable at the configured host and port.'
Expand minecraft_get_status description to act as a discovery tool. Include sample output or field names so LLMs understand the structure before calling. E.g., 'Returns: {health, hunger, position: {x, y, z}, modes: {mining, combat, following}, taskQueue: [{name, progress}]}. Use this to check state before other actions.'
For minecraft_set_mining_mode and minecraft_set_follow_mode, add bounds to quantity and targetPlayer. E.g., 'quantity: integer, 1 - 1000 items' and 'targetPlayer: string, 1 - 32 characters, must match exact Minecraft username'.
Add a tool discovery mechanism (e.g., minecraft_list_available_blocks or minecraft_list_online_players) so LLMs can validate inputs before calling mining/follow tools.
Create a README or docstring explaining the bot's state machine (waiting → mining → home → waiting, or waiting → following, or waiting → combat) so LLMs understand which mode-setting combinations are valid.