Minecraft Console Client (MCC) Documentation

Minecraft Console Client (MCC) is a lightweight, cross-platform, open-source TUI (Text User Interface) client for Minecraft Java Edition. It allows users to connect to servers, send commands, and receive messages without the overhead of the full Minecraft game client.

Key Capabilities

• Communication: Send/receive chat, log history, set keyword alerts, and auto-respond.
• Automation: Includes features like Anti-AFK, Auto-Relog, Script Scheduler, Auto-Fishing, Auto-Eat, Auto-Craft, and more.
• Extensibility: Provides a C# API for creating custom bots and runtime scripts.
• Advanced Handling: Supports inventory, terrain traversing, and entity handling (subject to protocol version).
• Deployment: Supports Docker for containerized usage.

MCC utilizes an A* path-finding algorithm combined with a physics-based movement system.

Supported Movement Capabilities

• Navigation: Terrain navigation using A* and physics-driven movement.
• Collision: Collision-aware movement using real block shapes.
• Obstacles: Automatic jumping for vertical movement, step-up movement for slabs, and climbing (ladders, vines).
• Physics: Movement in water/lava, gravity, friction, and block-specific modifiers (ice, soul sand, soul soil, honey blocks).
• States: Sneaking and sprinting.

Current Limitations

• Complexity: Path-finding is block-based; extremely complex terrain may cause failures.
• Water: Automatic route planning avoids underwater routes by default (not a full swimming path-finder).
• External Forces: Knockback and other external velocity effects are not currently simulated.

When using the MCC MCP toolset, follow a structured operating loop to ensure accuracy and prevent hallucinating game states:

1. Inspect: Always inspect the current situation using direct observation tools before acting.
2. Plan: Create the shortest possible plan that can achieve the goal.
3. Act: Use the smallest set of high-signal tools required to perform the action.
4. Verify: After an action, use fresh tool calls to read the state again and confirm the outcome.
5. Report: Report only what is verified. Clearly label anything that is inferred, conflicting, or unknown.

Key Principles:

• Use the MCC MCP toolset as the sole source of truth. Do not guess based on intent.
• If tool results and fresh observations disagree, trust the freshest direct observation.
• For conversational requests that don't require game state, answer directly without using tools.

All events pushed to authenticated WebSocket clients follow a standard JSON envelope. The data field contains a serialized JSON string representing the event's specific payload, which you must parse to access the details.

Event Envelope Format:

{
  "event": "EventName",
  "data": "{ ... serialized payload ... }"
}

Important Note: Enum values (like entity types or item types) are serialized as their string names (e.g., "Zombie") rather than integer IDs.

Recipes are defined in the [[ChatBot.AutoCraft.Recipes]] section. Each recipe requires a Name, Type (player or table), Result (item name), and Slots (an array of material names).

Slot Mapping:

• 2x2 (Player): 1 | 2 --+-- 3 | 4
• 3x3 (Table): 1 | 2 | 3 --+---+-- 4 | 5 | 6 --+---+-- 7 | 8 | 9

Important: Use the string "Null" to represent empty slots in the Slots array.

# Stone Bricks using the player inventory
[[ChatBot.AutoCraft.Recipes]]
Name = "Recipe-Name-1"
Type = "player"
Result = "StoneBricks"
Slots = [ "Stone", "Stone", "Stone", "Stone" ]

# Stone Bricks using a crafting table
[[ChatBot.AutoCraft.Recipes]]
Name = "Recipe-Name-2"
Type = "table"
Result = "StoneBricks"
Slots = [ "Stone", "Stone", "Null", "Stone", "Stone", "Null", "Null", "Null", "Null" ]

Events emitted by the bot arrive as JSON objects. The payload is contained within a stringified JSON field named data.

Event Format:

{
  "event": "EventName",
  "data": "{ ... serialized payload ... }"
}

To access the event details, you must parse the data field separately as a JSON string.

Internal commands can be executed from the chat prompt, via scripts, or through remote control.

• Chat Prompt: Commands must be prepended with a slash (e.g., /quit).
• Scripts and Remote Control: No slash is required (e.g., quit).

To see a full list of available commands, use /help.

Commands sent to the Minecraft Console Client (MCC) via WebSocket must be JSON objects. Each command produces a response through the OnWsCommandResponse event. A command object requires a command name, a requestId for tracking, and an array of parameters.

{
  "command": "CommandName",
  "requestId": "unique-id",
  "parameters": []
}

The harness allows an AI agent to drive development without a human-interactive terminal. It uses the following components to create a feedback loop:

• Local Minecraft Server: Runs in a tmux session.
• mc-rcon: Used for server-side commands (e.g., /op, /give, /summon).
• MCC Input Injection: MCC is started with MCC_FILE_INPUT=1.
• FileInputBot: Watches the session input file located at ${TMPDIR:-/tmp}/mcc-debug/<session>/mcc_input.txt.
• Log Inspection: The agent inspects logs from both MCC and the local server to validate changes.

The WebSocket Bot serializes all enums (e.g., ItemType, EntityType, Direction, Hand) as string names rather than numeric IDs.

Sending Enum Parameters

When sending commands that require enums, you can provide either the string name or the numeric ID:

Using String Names:

{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, "Interact", "MainHand"] }

Using Numeric IDs:

{ "command": "InteractEntity", "requestId": "abc", "parameters": [42, 0, 0] }

Querying Mappings

To ensure your client uses the correct names or IDs for the current MCC version, use these dedicated commands to retrieve mapping tables:

• GetItemTypeMappings: Returns a mapping of { "Name": ID, ... } for items.
• GetEntityTypeMappings: Returns a mapping of { "Name": ID, ... } for entities.