Content
# Maicraft
Built on [mineflayer](https://github.com/PrismarineJS/mineflayer) for Minecraft MCP Server.
Mainly used in conjunction with the [Amaidesu](https://github.com/MaiM-with-u/Amaidesu) project (the maicraft plugin is now an independent repository [MaiM-with-u/Maicraft](https://github.com/MaiM-with-u/Maicraft)), allowing [MaiBot](https://github.com/MaiM-with-u/MaiBot) to play Minecraft games.
Of course, you can also use this project like a normal MCP Server.
The implementation of some advanced actions is based on [mineland](https://github.com/cocacola-lab/MineLand)
## Installation
Please configure the minecraft server in advance, whether it is a minecraft client directly starting a LAN game, or a minecraft server, it is supported, and the version will be automatically detected.
Recommended game version: 1.20.4
1.21.4 is also supported, but mineflayer has some problems in this version, and higher versions may have problems. 1.21.8 is currently not supported.
### Method 1: Use npx to execute npm package for configuration
```json
{
"mcpServers": {
"maicraft": {
"transport": "stdio",
"command": "npx",
"args": [
"-y",
"maicraft@latest",
"--host","127.0.0.1",
"--port","25565",
"--username","Mai",
"--auth", "offline"
]
}
}
}
```
Here @latest means using the latest version, you can also replace it with other versions.
### Method 2: Download globally in advance
You can install maicraft globally in advance, and then configure it according to method 1. This will use your globally downloaded maicraft instead of the npx downloaded one when starting, which can avoid being too slow when calling it (because it needs to be downloaded temporarily). The disadvantage is that you need to upgrade manually.
```bash
npm install maicraft -g
```
### Method 3: Local build
When your network is not very good, you can use local build. First clone the local project
```bash
git clone git@github.com:ChangingSelf/maicraft-mcp-server.git
cd maicraft-mcp-server
pnpm install
pnpm run build
```
Then configure as:
```json
{
"mcpServers": {
"minecraft": {
"command": "node",
"args": [
"/path/to/maicraft-mcp-server/dist/main.js",
"--host",
"localhost",
"--port",
"25565",
"--username",
"EvilMai",
]
}
}
}
```
If you don't want to `pnpm run build` every time, you can also directly specify it as `main.ts`, but you need tsx to execute it
```json
{
"mcpServers": {
"minecraft": {
"command": "npx",
"args": [
"tsx"
"/path/to/maicraft-mcp-server/src/main.ts",
"--host",
"localhost",
"--port",
"25565",
"--username",
"EvilMai",
]
}
}
}
```
## Configuration
Maicraft supports two configuration methods: command line parameters and configuration files.
### Method 1: Command line parameters (recommended)
The easiest way is to use command line parameters directly at startup without creating a configuration file:
```bash
# Basic connection parameters
--host <address> # Minecraft server address (default: 127.0.0.1)
--port <port> # Server port (default: 25565)
--username <username> # Robot username
--auth <authentication method> # offline | microsoft | mojang (default: offline)
# Log configuration
--log-level <level> # DEBUG | INFO | WARN | ERROR (default: INFO)
# Event filtering
--events-disabled <event list> # Events to disable, separated by commas
```
**Quick Start Example:**
```bash
# Connect to local server
npx -y maicraft --host 127.0.0.1 --username MyBot
# Connect to remote server and enable debug logs
npx -y maicraft --host mc.example.com --port 25565 --username Bot --log-level DEBUG
# Disable chat events to reduce noise
npx -y maicraft --host 127.0.0.1 --username Bot --events-disabled chat,playerJoined
```
### Method 2: Configuration file (suitable for complex configurations)
If you need complex configurations, or want to save configurations for reuse, you can use a configuration file:
First get the configuration file template:
#### npx user
```bash
# Copy the configuration file template to the current directory
npx -y maicraft --init-config
```
#### Source code installation user
```bash
# Copy the configuration file template
cp config-template.yaml config.yaml
```
Then edit `config.yaml` to configure your settings:
```yaml
minecraft:
host: 127.0.0.1 # Minecraft server address
port: 25565 # Server port
username: MaiBot # Robot username
auth: offline # Authentication method: offline | microsoft | mojang
# Log configuration
logging:
level: INFO # Log level: DEBUG | INFO | WARN | ERROR
enableFileLog: true # Whether to enable file logging
useStderr: true # It is recommended to enable MCP mode
# Optional: Disable specific events
disabledEvents:
- chat # Chat event
- playerJoined # Player joined
# - death # Other events...
# Other advanced configurations...
# ……
```
**Tip:** You can also mix the two methods, first use the configuration file to set the basic configuration, and then use command line parameters to override specific settings.
## Start
Now you can start Maicraft directly:
#### Method 1: npx user
```bash
# Start directly (combined with the above command line parameters)
npx -y maicraft --host 127.0.0.1 --username MyBot
# Or start with a configuration file
npx -y maicraft /path/to/config.yaml
```
#### Method 2: Source code installation user
```bash
# Development mode (hot reload, suitable for development and debugging)
pnpm dev
# Production mode (need to build first)
pnpm build
pnpm start
```
After successful startup, you will see output similar to the following:
````
[INFO] Maicraft client started, press Ctrl+C to exit
[INFO] Log file location: /path/to/logs/maicraft-2024-01-15T10-30-00.log
[INFO] WebSocket log server started: ws://localhost:20915/ws/mcp-logs
````
## Test
#### Method 1: npx user
```bash
# Need to install mcp-inspector first
npm install -g @modelcontextprotocol/inspector
# List registered tools
mcp-inspector --cli --config mcp-inspector.json --server maicraft --method tools/list
# Call query_state for smoke test
mcp-inspector --cli --config mcp-inspector.json --server maicraft --method tools/call --tool-name query_state
```
#### Method 2: Source code installation user
```bash
# List registered tools
pnpm mcp:tools
# Call query_state for smoke test
pnpm mcp:state
```
## Quick Debugging
### Method 1: Direct debugging
No need to download any source code, just run the following command:
```bash
npx @modelcontextprotocol/inspector@0.16.5 npx -y maicraft@latest --host ChangingSelf.xyz --port 50226 --username MaiBot --auth offline
```
After that, a browser web page will pop up. Click the "connect" button in the lower left corner of this web page. If the "List Tools" button appears on the right, it means the configuration is successful, and you can directly perform debugging operations through the UI interface.
The reason for specifying the 0.16.5 version of inspector is that there will be stderr output in the lower left corner. This mcp server supports the stdio type, so in order to prevent the logs from affecting stdio, all logs are redirected to stderr here.
### Method 2: Source code debugging
If you have cloned the project source code, you can directly use the source code for debugging:
```bash
# Clone the project (if not already)
git clone https://github.com/ChangingSelf/Maicraft.git
cd Maicraft
# Install dependencies
pnpm install
# Start the debugging interface (development mode)
pnpm mcp:ui
```
This will start a debugging interface based on the source code, without packaging, and directly run the TypeScript source code.
If you need more flexible debugging, you can also configure it manually:
Create the mcp-inspector.json configuration file
```json
{
"mcpServers": {
"maicraft": {
"type": "stdio",
"command": "tsx",
"args": ["src/main.ts", "./config.yaml"],
"env": {
"NODE_ENV": "development"
}
}
}
}
```
```bash
# Start the debugging interface
mcp-inspector --config mcp-inspector.json --server maicraft
```
## Log Output
Maicraft provides multiple ways to view logs: console output, file logs, and WebSocket real-time stream.
### Log File
Log files are saved in the `logs/` folder in the project root directory by default. The file name format is:
````
logs/maicraft-YYYY-MM-DDTHH-mm-ss.log
````
### WebSocket Log Stream
The program automatically starts a WebSocket server when it starts, which is used to transmit logs in real time:
- **Endpoint**: `ws://localhost:20915/ws/mcp-logs`
- **Default Port**: 20915
- **Purpose**: Used for real-time viewing of logs by tools such as [maicraft-web-ui](https://github.com/ChangingSelf/maicraft-web-ui)
You can modify the WebSocket server settings through configuration:
```yaml
websocket:
enabled: true # Whether to enable the WebSocket log server
port: 20915 # WebSocket server port
host: "localhost" # WebSocket server listening address
```
## Architecture
```mermaid
graph LR
A[main.ts launcher] -->|read| C[config.yaml]
A --> L[Logger]
A --> MC[MinecraftClient]
A --> AE[ActionExecutor]
A --> MCP[MaicraftMcpServer]
MC -->|use| B[mineflayer Bot]
B -->|event| MC
MC -->|gameEvent| A
MCP -->|action tools| AE
MCP -->|connection/status| MC
AE -->|use Bot to execute action| B
AE -->|auto discover| ACT[src/actions/*.ts]
ACT -->|schema + execute| AE
AE -->|auto generate| MCP_TOOLS[MCP Tools]
```
### Action System Architecture
```mermaid
graph TD
A[Action File] -->|inherit| B[BaseAction]
A -->|define| C[schema: z.ZodTypeAny]
A -->|implement| D[execute: bot, params => Promise<ActionResult>]
B -->|auto provide| E[validateParams]
B -->|auto provide| F[getParamsSchema]
B -->|auto provide| G[getMcpTools]
G -->|generate| H[MCP Tool: action_name_snake_case]
C -->|validate| I[parameter type safety]
C -->|describe| J[automatically generate parameter documentation]
```
### Sequence: Calling Action (mine_block)
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as MaicraftMcpServer
participant AE as ActionExecutor
participant MC as MinecraftClient
participant Bot as mineflayer Bot
Client->>Server: tools/call mine_block
Server->>MC: getBot()
MC-->>Server: Bot
alt Bot ready
Server->>AE: execute('mineBlock', Bot, params)
AE->>Bot: Action execution (pathfinding/collection, etc.)
Bot-->>AE: result
AE-->>Server: { success, data }
Server-->>Client: structuredContent
else Bot not ready
Server-->>Client: { ok:false, error: service_unavailable }
end
```
### Sequence: Event Handling
```mermaid
sequenceDiagram
participant Bot as mineflayer Bot
participant MC as MinecraftClient
participant Main as main.ts
Bot->>MC: Raw game event
MC->>MC: Filter disabledEvents (blacklist)
MC-->>Main: gameEvent
```
## Detailed Configuration
### Command Line Parameters
Maicraft supports multiple command line parameters, which can override the settings in the configuration file:
```bash
# Basic connection parameters
--host <address> # Minecraft server address (default: 127.0.0.1)
--port <port> # Server port (default: 25565)
--username <username> # Robot username
--password <password> # Server password (required for online mode)
--auth <authentication method> # offline | microsoft | mojang (default: offline)
--version <version> # Minecraft version (optional, automatically detected)
# Log configuration
--log-level <level> # DEBUG | INFO | WARN | ERROR (default: INFO)
# Event filtering (blacklist mechanism)
--events-disabled <event list> # Event types to disable, separated by commas
# Example: --events-disabled chat,playerJoined,health
# Supported events: chat, playerJoined, playerLeft, death, spawn, rain, kicked, spawnReset, health, entityHurt, entityDead, playerCollect
# MCP Configuration
--mcp-name <name> # MCP server name
--mcp-version <version> # MCP server version
# Tool filtering
--tools-enabled <tool list> # List of enabled MCP tools (whitelist)
--tools-disabled <tool list> # List of disabled MCP tools (blacklist)
```
#### Event Disable Parameter Example
```bash
# Disable chat and player join events
npx -y maicraft --events-disabled chat,playerJoined
# Disable all health-related events
npx -y maicraft --events-disabled health,entityHurt,entityDead
# Disable weather and player collection events
npx -y maicraft --events-disabled rain,playerCollect
```
### Basic Configuration
Configure the Minecraft server connection in `config.yaml`:
```yaml
minecraft:
host: 127.0.0.1 # Server address
port: 25565 # Port
username: MaiBot # Robot username
auth: offline # Authentication method: offline | microsoft | mojang
version: "1.19.0" # Game version (optional)
# List of disabled event types (blacklist mechanism)
```
# List of game event types to disable. By default, all events are enabled.
disabledEvents:
# - chat # Chat event
# - playerJoined # Player joined
# - playerLeft # Player left
# - death # Player death
# - spawn # Player respawn
# - rain # Weather change
# - kicked # Player kicked
# - spawnReset # Respawn point reset
# - health # Health update
# - entityHurt # Entity hurt
# - entityDead # Entity death
# - playerCollect # Player collect item
# List of blocks that cannot be broken
# The robot will avoid breaking these blocks when pathfinding
blocksCantBreak:
- chest # Chest
- furnace # Furnace
- bed # Bed
- door # Door
- trapdoor # Trapdoor
- sign # Sign
- torch # Torch
- lantern # Lantern
maxMessageHistory: 100 # Number of event history cache
### Pathfinding Configuration
#### List of Blocks That Cannot Be Broken
The `blocksCantBreak` configuration item is used to specify a list of blocks that the robot cannot break when pathfinding. When the robot needs to move to a certain position, it will avoid breaking these important blocks.
```yaml
# List of blocks that cannot be broken
blocksCantBreak:
- chest # Chest
- furnace # Furnace
- bed # Bed
- door # Door
- trapdoor # Trapdoor
- sign # Sign
- torch # Torch
- lantern # Lantern
```
**Configuration Instructions:**
- If this option is not configured, the default list will be used: `['chest', 'furnace']`
- Can be set to an empty array `[]` to allow breaking all blocks
- Block names use Minecraft's English names (such as `chest`, `furnace`, etc.)
- If an unknown block name is configured, a warning message will be displayed in the log
**Common Block Name References:**
- `chest` - Chest
- `furnace` - Furnace
- `crafting_table` - Crafting table
- `bed` - Bed
- `door` - Door
- `trapdoor` - Trapdoor
- `sign` - Sign
- `torch` - Torch
- `lantern` - Lantern
- `anvil` - Anvil
- `enchanting_table` - Enchanting table
- `brewing_stand` - Brewing stand
### MCP Tool Configuration
Maicraft supports multiple tool filtering modes. It is recommended to use the blacklist mode:
```yaml
mcp:
name: "Maicraft MCP"
version: "1.0.0"
tools:
# Method 1: Blacklist mode (recommended) - Block specified tools, all others are available
disabled:
- use_chest
- smelt_item
# Method 2: Whitelist mode - Only expose specified tools
# enabled:
# - mine_block
# - place_block
# - follow_player
# Method 3: Use both - The set allowed by the whitelist minus the blacklist
# enabled:
# - mine_block
# - place_block
# - chat
# disabled:
# - chat
# Method 4: Not configured - Expose all tools by default
# (Delete or comment out the tools section)
```
## Action Development
### Action System Features
- **Automatic Discovery**: Place the action file in the `src/actions/` directory to automatically discover it
- **Parameter Validation**: Automatic parameter validation based on Zod
- **Type Safety**: Full TypeScript type support
- **MCP Integration**: Automatically generate the corresponding MCP tool
### Writing a New Action
#### Method 1: Inherit from the Base Class (Recommended)
```typescript
// src/actions/MyAction.ts
import { BaseAction } from '../minecraft/ActionInterface';
import { z } from 'zod';
interface MyActionParams {
target: string;
count?: number;
}
export class MyAction extends BaseAction<MyActionParams> {
name = 'myAction';
description = 'Execute my custom action';
// Define parameter validation schema
schema = z.object({
target: z.string().describe('Target object'),
count: z.number().int().min(1).optional().describe('Number of executions (optional)'),
});
async execute(bot: Bot, params: MyActionParams) {
try {
// Implement action logic
const count = params.count ?? 1;
// ... Specific implementation
return this.createSuccessResult(`Successfully executed action ${count} times`);
} catch (error) {
return this.createExceptionResult(error, 'Execution failed', 'EXECUTION_ERROR');
}
}
// validateParams, getParamsSchema, getMcpTools are automatically provided by the base class
}
```
#### Method 2: Functional Definition
```typescript
// src/actions/MyAction.ts
import { defineAction } from '../minecraft/ActionInterface';
import { z } from 'zod';
export const MyAction = defineAction({
name: 'myAction',
description: 'Execute my custom action',
schema: z.object({
target: z.string().describe('Target object'),
count: z.number().int().min(1).optional().describe('Number of executions (optional)'),
}),
async execute(bot, params) {
// Implement action logic
const count = params.count ?? 1;
// ... Specific implementation
return { success: true, message: `Successfully executed action ${count} times` };
},
});
```
### Action Automatic Registration
1. Place the action file in the `src/actions/` directory
2. The file will be automatically discovered and registered
3. The corresponding MCP tool will be automatically generated (the tool name is the snake_case form of the action name)
4. For example: `MyAction` → `my_action` tool
### Action Development Best Practices
#### 1. Parameter Design Principles
- Use clear parameter names, avoid abbreviations
- Provide reasonable default values for optional parameters
- Use Zod schema for strict parameter validation
- Provide examples and explanations in the parameter description
#### 2. Error Handling
- Use `createErrorResult()` to return business logic errors
- Use `createExceptionResult()` to return exception errors
- Provide meaningful error codes and messages
- Record detailed debugging logs
#### 3. Return Value Design
- Use `createSuccessResult()` to return successful results
- Include useful status information in the returned data
- Maintain consistency in the return format
#### 4. Dependency Check
- Check if necessary plugins are loaded (such as pathfinder)
- Verify that the target object exists (such as blocks, players, entities)
- Ensure that there are necessary items in the backpack
#### 5. Performance Considerations
- Set reasonable timeout times
- Limit the search range (such as maxDistance)
- Avoid infinite loops and long-term blocking
### Available Action Tools
Currently supported action tools:
#### Basic Interaction Actions
- **`chat`** **chat** **chat** - Send a chat message
- Parameters: `message` (string) - The chat message to send
- **`basic_control`** **basic_control** **basic_control** - Basic game control functions
- Parameters:
- `type` (string) - Control type: `toss` | `move` | `jump` | `sneak` | `look_at` | `sleep` | `wake` | `stop_move` | `stop_sneak`
- `item` (string, optional) - Item name or ID (for toss type)
- `count` (number, optional) - Item quantity (for toss type, default 1)
- `direction` (string, optional) - Movement direction (for move type: `forward` | `back` | `left` | `right`)
- `lookType` (string, optional) - Look type (for look_at type: `angle` | `position` | `player` | `entity` | `block`)
- `yaw` (number, optional) - View yaw angle, in radians (for angle look type)
- `pitch` (number, optional) - View pitch angle, in radians (for angle look type)
- `x`, `y`, `z` (number, optional) - Target coordinates (for position look type)
- `force` (boolean, optional) - Whether to force looking (for all look types, default false)
- `player` (string, optional) - Target player name (for player look type)
- `entity` (string, optional) - Target entity type (for entity look type), such as cow, pig, zombie, etc.
- `block` (string, optional) - Target block name (for block look type), such as dirt, stone, diamond_ore, etc.
- `maxDistance` (number, optional) - Search distance (for entity and block look types, default 64)
- **`use_item`** **use_item** **use_item** - Use the item in hand
- Parameters:
- `itemName` (string, optional) - Item name, if not specified, use the currently held item
- `useType` (string, optional) - Use type: `consume` | `activate` | `useOn`, the default is automatically determined based on the item type
- `targetEntityName` (string, optional) - Target entity name, only required when using the `useOn` type
- `targetPlayerName` (string, optional) - Target player name, only required when using the `useOn` type
- `offHand` (boolean, optional) - Whether to use the off-hand, default false
#### Movement and Navigation Actions
- **`move`** **move** **move** - Move to the specified location
- Parameters:
- `type` (string) - Movement type: `coordinate` | `block` | `player` | `entity`
- `useAbsoluteCoords` (boolean, optional) - Whether to use absolute coordinates, default false
- `x`, `y`, `z` (number, optional) - Target coordinates (required when type is coordinate)
- `block` (string, optional) - Target block name (required when type is block)
- `player` (string, optional) - Target player name (required when type is player)
- `entity` (string, optional) - Target entity type (required when type is entity)
- `distance` (number, optional) - Arrival distance, default 1
- `timeout` (number, optional) - Timeout time (seconds), default 60
- `maxDistance` (number, optional) - Maximum movement distance, default 100
- **`follow_player`** **follow_player** **follow_player** - Follow the specified player
- Parameters:
- `player` (string) - Target player name
- `distance` (number, optional) - Following distance (blocks), default 3
- `timeout` (number, optional) - Timeout time (seconds), default 5
- **`swim_to_land`** **swim_to_land** **swim_to_land** - Swim to the nearest land
- Parameters:
- `maxDistance` (number, optional) - Maximum search distance, default 64
- `timeout` (number, optional) - Timeout time (seconds), default 60
#### Block Operation Actions
- **`mine_block`** **mine_block** **mine_block** - Mine a block of the specified type
- Parameters:
- `name` (string) - Block name, such as "dirt", "stone", "coal_ore"
- `count` (number, optional) - Number to mine, default 1
- `direction` (string, optional) - Mining direction: `+y` | `-y` | `+z` | `-z` | `+x` | `-x` (coordinate axis direction), if not specified, search nearby
- `maxDistance` (number, optional) - Search distance, default 48
- `bypassAllCheck` (boolean, optional) - Whether to bypass all checks and mine directly, default false
- **`place_block`** **place_block** **place_block** - Place a block at the specified location
- Parameters:
- `x`, `y`, `z` (number) - Target location coordinates
- `block` (string) - The name of the block to place
- `face` (string, optional) - Placement face: `+y` | `-y` | `+z` | `-z` | `+x` | `-x` (coordinate axis direction)
- `useAbsoluteCoords` (boolean, optional) - Whether to use absolute coordinates, default false
#### Item Crafting Actions
- **`craft_item`** **craft_item** **craft_item** - Craft the specified item
- Parameters:
- `item` (string) - The name of the item to craft
- `count` (number, optional) - Crafting quantity, default 1
- **`start_smelting`** **start_smelting** **start_smelting** - Start smelting items in the furnace (do not wait for completion)
- Parameters:
- `item` (string) - The name of the item to smelt
- `fuel` (string) - The name of the fuel item
- `count` (number, optional) - Smelting quantity, default 1
- **`collect_smelted_items`** **collect_smelted_items** **collect_smelted_items** - Collect the smelted items from the furnace
- Parameters:
- `item` (string, optional) - The name of the smelting product to collect, if not specified, collect all products
- `x`, `y`, `z` (number, optional) - Furnace coordinates
- `useAbsoluteCoords` (boolean, optional) - Whether to use absolute coordinates, default false
- **`use_furnace`** **use_furnace** **use_furnace** - Furnace operation (put in/take out/view items)
- Parameters:
- `container_type` (string, optional) - Container type: `furnace` | `blast_furnace` | `smoker` (default furnace)
- `action` (string, optional) - Operation type: `put` | `take` | `view` (default put)
- `items` (array, optional) - Item array (required for put operation, optional for take operation to specify slot)
- `name` (string, optional) - Item name (required for put operation)
- `count` (number, optional) - Item quantity (default 1)
- `position` (string, optional) - Slot: `input` | `fuel` | `output`
- `x`, `y`, `z` (number, optional) - Furnace coordinates
- `auto_search` (boolean, optional) - Whether to automatically search for nearby containers (default false)
- **`smelt_item`** **smelt_item** **smelt_item** - Smelt items in the furnace (deprecated, it is recommended to use start_smelting + collect_smelted_items)
- Parameters:
- `item` (string) - The name of the item to smelt
- `fuel` (string) - The name of the fuel item
- `count` (number, optional) - Smelting quantity, default 1
#### Storage and Interaction Actions
- **`use_chest`** **use_chest** **use_chest** - Interact with nearby chests, store and retrieve items
- Parameters:
- `action` (string) - Operation type: `store` | `withdraw`
- `item` (string) - Item name
- `count` (number, optional) - Quantity, default 1
#### Combat Actions
- **`kill_mob`** **kill_mob** **kill_mob** - Kill creatures with the specified name
- Parameters:
- `mob` (string) - Target creature name, such as "cow", "pig", "zombie"
- `timeout` (number, optional) - Timeout time (seconds) to wait for the creature to die, default 300
#### Other Actions
### Action Usage Examples
#### Basic Operation Examples
```json
// Send a chat message
{
"tool": "chat",
"arguments": {
"message": "Hello, Minecraft!"
}
}
// Eat an apple
{
"tool": "use_item",
"arguments": {
"itemName": "apple",
"useType": "consume"
}
}
// Throw a snowball
{
"tool": "use_item",
"arguments": {
"itemName": "snowball",
"useType": "activate"
}
}
// Use the currently held item (automatically determine the usage type)
{
"tool": "use_item",
"arguments": {}
}
// Drop an item
{
"tool": "basic_control",
"arguments": {
"type": "toss",
"item": "dirt",
"count": 5
}
}
// Start moving forward
{
"tool": "basic_control",
"arguments": {
"type": "move",
"direction": "forward"
}
}
// Perform a jump
{
"tool": "basic_control",
"arguments": {
"type": "jump"
}
}
// Start sneaking
{
"tool": "basic_control",
"arguments": {
"type": "sneak"
}
}
// Adjust the view to a specific angle
{
"tool": "basic_control",
"arguments": {
"type": "look_at",
"lookType": "angle",
"yaw": 1.57,
"pitch": 0.0,
"force": true
}
}
// Look at a specific coordinate position
{
"tool": "basic_control",
"arguments": {
"type": "look_at",
"lookType": "position",
"x": 100,
"y": 64,
"z": 100,
"force": true
}
}
// Look at a player
{
"tool": "basic_control",
"arguments": {
"type": "look_at",
"lookType": "player",
"player": "Steve",
"force": true
}
}
// Look at the nearest cow
{
"tool": "basic_control",
"arguments": {
"type": "look_at",
"lookType": "entity",
"entity": "cow",
"maxDistance": 50
}
}
// Look at the nearest diamond ore block
{
"tool": "basic_control",
"arguments": {
"type": "look_at",
"lookType": "block",
"block": "diamond_ore",
"maxDistance": 100
}
}
// Sleep (automatically find a nearby bed)
{
"tool": "basic_control",
"arguments": {
"type": "sleep"
}
}
// Wake up
{
"tool": "basic_control",
"arguments": {
"type": "wake"
}
}
// Stop moving
{
"tool": "basic_control",
"arguments": {
"type": "stop_move"
}
}
// Stop sneaking
{
"tool": "basic_control",
"arguments": {
"type": "stop_sneak"
}
}
// Use an item on a player
{
"tool": "use_item",
"arguments": {
"itemName": "saddle",
"useType": "useOn",
"targetPlayerName": "Steve"
}
}
// Use an item on an entity
{
"tool": "use_item",
"arguments": {
"itemName": "shears",
"useType": "useOn",
"targetEntityName": "sheep"
}
}
// Mine stone
{
"tool": "mine_block",
"arguments": {
"name": "stone",
"count": 5
}
}
// Mine stone in the positive Y-axis direction
{
"tool": "mine_block",
"arguments": {
"name": "stone",
"count": 3,
"direction": "+y"
}
}
// Mine coal in the negative Z-axis direction
{
"tool": "mine_block",
"arguments": {
"name": "coal_ore",
"count": 2,
"direction": "-z",
"maxDistance": 20
}
}
// Move to a specific coordinate
{
"tool": "move",
"arguments": {
"type": "coordinate",
"x": 100,
"y": 64,
"z": 200,
"useAbsoluteCoords": true
}
}
```
#### Advanced Operation Examples
> **💡 Smelting Optimization Tip**: To optimize the smelting experience and avoid long waits, it is recommended to use the `start_smelting` + `collect_smelted_items` combination instead of `smelt_item`. This allows you to:
>
> - Return immediately after starting smelting, without blocking other operations
> - Perform other tasks while smelting is in progress
> - Collect the products separately after smelting is complete
```json
// Craft a crafting table
{
"tool": "craft_item",
"arguments": {
"item": "crafting_table",
"count": 1
}
}
// Start smelting iron ore (recommended method)
{
"tool": "start_smelting",
"arguments": {
"item": "iron_ore",
"fuel": "coal",
"count": 3
}
}
// Collect smelted items
{
"tool": "collect_smelted_items",
"arguments": {
"item": "iron_ingot"
}
}
// Smelt iron ore (deprecated, will wait for smelting to complete)
{
"tool": "smelt_item",
"arguments": {
"item": "iron_ore",
"fuel": "coal",
"count": 3
}
}
// Furnace operation example
{
"tool": "use_furnace",
"arguments": {
"action": "put",
"items": [
{"name": "iron_ore", "count": 5, "position": "input"},
{"name": "coal", "count": 2, "position": "fuel"}
]
}
}
// View furnace status
{
"tool": "use_furnace",
"arguments": {
"action": "view"
}
}
// Take products from the furnace
{
"tool": "use_furnace",
"arguments": {
"action": "take",
"items": [
{"position": "output"}
]
}
}
// Follow a player
{
"tool": "follow_player",
"arguments": {
"player": "Steve",
"distance": 5,
"timeout": 30
}
}
```
## MCP Tools
### Query Tools
- `query_state` - Query the game state
- `query_events` - Query the event history
### Action Tools
Action tools are automatically generated based on the action files in the `src/actions/` directory. The tool name format is the snake_case form of the action name. For example:
- `MineBlockAction` → `mine_block` tool
- `PlaceBlockAction` → `place_block` tool
- `FollowPlayerAction` → `follow_player` tool
Each action tool automatically includes:
- Parameter validation based on Zod schema
- Complete parameter type descriptions
- Automatically generated tool descriptions
- Unified error handling and return format
## Development
### Dependencies
- Node.js >= 18.0.0
- pnpm >= 10.6.5
- Python (for compiling certain dependencies)
### Main Dependency Versions
- mineflayer: ^4.32.0
- @modelcontextprotocol/sdk: ^1.17.2
- mineflayer-pathfinder-mai: ^2.4.6
- prismarine-viewer: ^1.33.0
- canvas: ^3.1.2
```bash
# Build
pnpm build
# Test
pnpm test
# Lint
pnpm lint
# Clean build files
pnpm clean
```
## License
MIT
