Content
# Maicraft
Based on [mineflayer](https://github.com/PrismarineJS/mineflayer) built MCP Server.
Mainly used with [Amaidesu](https://github.com/MaiM-with-u/Amaidesu) project (Maicraft plugin has now been independently developed into a new 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.
Some advanced actions are implemented with reference to [mineland](https://github.com/cocacola-lab/MineLand)
## Installation
Please configure the Minecraft server in advance, whether it's a Minecraft client directly opening a LAN game or a Minecraft server, both are supported, and the version will be automatically detected.
Recommended game version: 1.20.4
1.21.4 is also supported, but mineflayer has some issues with this version, and higher versions may have problems. 1.21.8 is currently not supported.
### Method 1: Using 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: Global installation in advance
You can install maicraft globally in advance, and then configure it according to method 1. This way, it will use the globally installed maicraft instead of the npx downloaded one, which can avoid slow invocation due to temporary download. The disadvantage is that you need to manually upgrade.
```bash
npm install maicraft -g
```
### Method 3: Local build
When your network is not 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 run `pnpm run build` every time, you can also specify `main.ts` directly, but you need tsx to execute
```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 simplest way is to directly use command-line parameters when starting, 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> # Bot username
--auth <authentication> # 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 configuration)
If you need complex configuration or want to save the configuration for repeated use, you can use a configuration file:
First, get the configuration file template:
#### npx users
```bash
# Copy configuration file template to current directory
npx -y maicraft --init-config
```
#### Source installation users
```bash
# Copy 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 # Bot 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 # MCP mode is recommended to enable
# 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, set the basic configuration with the configuration file, and then use command-line parameters to override specific settings.
## Start
Now you can directly start Maicraft:
#### Method 1: npx users
```bash
# Direct start (use 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 installation users
```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 an 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 users
```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 installation users
```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, directly run the following command:
```bash
npx @modelcontextprotocol/inspector@0.16.5 npx -y maicraft@latest --host ChangingSelf.xyz --port 50226 --username MaiBot --auth offline
```
Then a browser page will pop up, click the "connect" button in the lower left corner of this page, if "List Tools" button appears on the right, it means the configuration is successful, and you can directly debug through the UI interface.
The reason for specifying inspector version 0.16.5 is that there will be stderr output in the lower left corner. This mcp server supports stdio type, so in order to avoid logs affecting stdio, all logs are redirected to stderr.
### Method 2: Source debugging
If you have cloned the project source code, you can directly use the source code for debugging:
```bash
# Clone the project (if not yet)
git clone https://github.com/ChangingSelf/Maicraft.git
cd Maicraft
# Install dependencies
pnpm install
# Start debugging interface (development mode)
pnpm mcp:ui
```
This will start a debugging interface based on the source code, no need to build, directly run the TypeScript source code.
If you need more flexible debugging, you can also manually configure:
Create `mcp-inspector.json` configuration file
```json
{
"mcpServers": {
"maicraft": {
"type": "stdio",
"command": "tsx",
"args": ["src/main.ts", "./config.yaml"],
"env": {
"NODE_ENV": "development"
}
}
}
}
```
```bash
# Start 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 streaming.
### Log files
Log files are saved in the `logs/` folder in the project root directory by default, and the file name format is:
````
logs/maicraft-YYYY-MM-DDTHH-mm-ss.log
````
### WebSocket log stream
The WebSocket server will be automatically started when the program starts, used for real-time transmission of logs:
- **Endpoint**: `ws://localhost:20915/ws/mcp-logs`
- **Default port**: 20915
- **Purpose**: Used for [maicraft-web-ui](https://github.com/ChangingSelf/maicraft-web-ui) and other tools to view logs in real-time
You can modify the WebSocket server settings through configuration:
```yaml
websocket:
enabled: true # Whether to enable 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 tool| AE
MCP -->|connection/status| MC
AE -->|use Bot to execute action| B
AE -->|auto-discovery| 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 -->|verify| I[parameter type safety]
C -->|description| J[automatically generate parameter documentation]
```
### Timing: Call 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
```
### Timing: Event processing
```mermaid
sequenceDiagram
participant Bot as mineflayer Bot
participant MC as MinecraftClient
participant Main as main.ts
Bot->>MC: original game event
MC->>MC: filter disabledEvents (blacklist)
MC-->>Main: gameEvent
```
## Detailed configuration
### Command-line parameters
Maicraft supports multiple command-line parameters, which can override 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> # Bot username
--password <password> # Server password (required for online mode)
--auth <authentication> # 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> # Enabled MCP tool list (whitelist)
--tools-disabled <tool list> # Disabled MCP tool list (blacklist)
```
#### Event disable parameter example
```bash
# Disable chat and player join events
npx -y maicraft --events-disabled chat,playerJoined
# Disable all life-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 Minecraft server connection in `config.yaml`:
```yaml
minecraft:
host: 127.0.0.1 # Server address
port: 25565 # Port
username: MaiBot # Bot username
auth: offline # Authentication method: offline | microsoft | mojang
version: "1.19.0" # Game version (optional)
# Disabled event type list (blacklist mechanism)
```
# Tool List
## Disabled Events Configuration
disabledEvents:
# - chat # Chat event
# - playerJoined # Player joined event
# - playerLeft # Player left event
# - death # Player death event
# - spawn # Player spawn event
# - rain # Weather change event
# - kicked # Player kicked event
# - spawnReset # Spawn point reset event
# - health # Health update event
# - entityHurt # Entity hurt event
# - entityDead # Entity death event
# - playerCollect # Player collect item event
## Blocks That Cannot Be Broken
blocksCantBreak:
- chest # Chest
- furnace # Furnace
- bed # Bed
- door # Door
- trapdoor # Trapdoor
- sign # Sign
- torch # Torch
- lantern # Lantern
maxMessageHistory: 100 # Event history cache size
### Pathfinding Configuration
#### Blocks That Cannot Be Broken
The `blocksCantBreak` configuration item is used to specify the list of blocks that the robot cannot break during pathfinding. When the robot needs to move to a certain position, it will avoid breaking these important blocks.
```yaml
# Blocks that cannot be broken configuration
blocksCantBreak:
- chest # Chest
- furnace # Furnace
- bed # Bed
- door # Door
- trapdoor # Trapdoor
- sign # Sign
- torch # Torch
- lantern # Lantern
```
**Configuration Description:**
- If this option is not configured, the default list will be used: `['chest', 'furnace']`
- You can set it to an empty array `[]` to allow breaking all blocks
- Block names use Minecraft's English names (e.g., `chest`, `furnace`, etc.)
- If an unknown block name is configured, a warning message will be displayed in the log
**Common Block Names Reference:**
- `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 Server Configuration
Minecraft 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) - Shield specified tools, all others 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 - Whitelist allows collection minus blacklist
# enabled:
# - mine_block
# - place_block
# - chat
# disabled:
# - chat
# Method 4: Not configured - Default expose all tools
# (Delete or comment out tools section)
```
## Action Development
### Action System Features
- **Auto-discovery**: Place action files in the `src/actions/` directory for automatic discovery
- **Parameter validation**: Automatic parameter validation based on Zod
- **Type safety**: Complete TypeScript type support
- **MCP integration**: Automatically generate corresponding MCP tools
### Writing New Actions
#### Method 1: Inherit 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('Execution count (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 provided by base class automatically
}
```
#### 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('Execution count (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 action files in the `src/actions/` directory
2. Files will be automatically discovered and registered
3. Corresponding MCP tools will be automatically generated (tool name in snake_case form of 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 descriptions in parameter descriptions
#### 2. Error Handling
- Use `createErrorResult()` to return business logic errors
- Use `createExceptionResult()` to return exception errors
- Provide meaningful error codes and messages
- Record detailed debug logs
#### 3. Return Value Design
- Use `createSuccessResult()` to return successful results
- Include useful status information in return data
- Keep return format consistent
#### 4. Dependency Check
- Check if necessary plugins are loaded (e.g., pathfinder)
- Verify target objects exist (e.g., blocks, players, entities)
- Ensure necessary items are in inventory
#### 5. Performance Considerations
- Set reasonable timeouts
- Limit search ranges (e.g., maxDistance)
- Avoid infinite loops and long-time blocking
### Available Action Tools
Current supported action tools:
#### Basic Interaction Actions
- **`chat`** **chat** **chat** - Send chat messages
- Parameters: `message` (string) - 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 count (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, radians (for angle look type)
- `pitch` (number, optional) - View pitch angle, radians (for angle look type)
- `x`, `y`, `z` (number, optional) - Target coordinates (for position look type)
- `force` (boolean, optional) - Whether to force look (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), e.g., cow, pig, zombie, etc.
- `block` (string, optional) - Target block name (for block look type), e.g., 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 item in hand
- Parameters:
- `itemName` (string, optional) - Item name, not specified uses current hand item
- `useType` (string, optional) - Use type: `consume` | `activate` | `useOn`, defaults to automatic judgment based on item type
- `targetEntityName` (string, optional) - Target entity name, only for useOn type
- `targetPlayerName` (string, optional) - Target player name, only for useOn type
- `offHand` (boolean, optional) - Whether to use off-hand, default false
#### Movement and Navigation Actions
- **`move`** **move** **move** - Move to specified position
- 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 (when type is coordinate)
- `block` (string, optional) - Target block name (when type is block)
- `player` (string, optional) - Target player name (when type is player)
- `entity` (string, optional) - Target entity type (when type is entity)
- `distance` (number, optional) - Arrival distance, default 1
- `timeout` (number, optional) - Timeout (seconds), default 60
- `maxDistance` (number, optional) - Maximum movement distance, default 100
- **`follow_player`** **follow_player** **follow_player** - Follow specified player
- Parameters:
- `player` (string) - Target player name
- `distance` (number, optional) - Follow distance (blocks), default 3
- `timeout` (number, optional) - Timeout (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 (seconds), default 60
#### Block Operation Actions
- **`mine_block`** **mine_block** **mine_block** - Mine specified block type
- Parameters:
- `name` (string) - Block name, e.g., "dirt", "stone", "coal_ore"
- `count` (number, optional) - Number of blocks to mine, default 1
- `direction` (string, optional) - Mining direction: `+y` | `-y` | `+z` | `-z` | `+x` | `-x` (coordinate axis direction), not specified searches 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 block at specified position
- Parameters:
- `x`, `y`, `z` (number) - Target position coordinates
- `block` (string) - 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 specified item
- Parameters:
- `item` (string) - Item to craft
- `count` (number, optional) - Craft count, default 1
- **`start_smelting`** **start_smelting** **start_smelting** - Start smelting item in furnace (does not wait for completion)
- Parameters:
- `item` (string) - Item to smelt
- `fuel` (string) - Fuel item
- `count` (number, optional) - Smelt count, default 1
- **`collect_smelted_items`** **collect_smelted_items** **collect_smelted_items** - Collect smelted items from furnace
- Parameters:
- `item` (string, optional) - Smelted item to collect, not specified collects 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/take/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 (put operation required, take operation optional for slot)
- `name` (string, optional) - Item name (put operation required)
- `count` (number, optional) - Item count (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 item in furnace (deprecated, recommend using start_smelting + collect_smelted_items)
- Parameters:
- `item` (string) - Item to smelt
- `fuel` (string) - Fuel item
- `count` (number, optional) - Smelt count, default 1
#### Storage and Interaction Actions
- **`use_chest`** **use_chest** **use_chest** - Interact with nearby chest, access items
- Parameters:
- `action` (string) - Operation type: `store` | `withdraw`
- `item` (string) - Item name
- `count` (number, optional) - Count, default 1
#### Combat Actions
- **`kill_mob`** **kill_mob** **kill_mob** - Kill specified mob
- Parameters:
- `mob` (string) - Target mob name, e.g., "cow", "pig", "zombie"
- `timeout` (number, optional) - Wait for mob death timeout (seconds), default 300
#### Other Actions
### Action Usage Examples
#### Basic Operation Examples
```json
// Send a chat message
{
"tool": "chat",
"arguments": {
"message": "Hello, Minecraft!"
}
}
// Consume an apple
{
"tool": "use_item",
"arguments": {
"itemName": "apple",
"useType": "consume"
}
}
// Throw a snowball
{
"tool": "use_item",
"arguments": {
"itemName": "snowball",
"useType": "activate"
}
}
// Use the current held item (automatically determine usage type)
{
"tool": "use_item",
"arguments": {}
}
// Discard 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 angle 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 +y direction
{
"tool": "mine_block",
"arguments": {
"name": "stone",
"count": 3,
"direction": "+y"
}
}
// Mine coal ore in the -z direction
{
"tool": "mine_block",
"arguments": {
"name": "coal_ore",
"count": 2,
"direction": "-z",
"maxDistance": 20
}
}
// Move to a specified 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 combination of `start_smelting` and `collect_smelted_items` instead of `smelt_item`. This allows:
>
> - Starting smelting immediately and returning without blocking other operations
> - Performing other tasks while smelting is in progress
> - Collecting the smelted items separately after smelting is complete
```json
// 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 state
{
"tool": "use_furnace",
"arguments": {
"action": "view"
}
}
// Take items 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 game state
- `query_events` - Query event history
### Action Tools
Action tools are automatically generated based on the action files in the `src/actions/` directory, with tool names in snake_case format. For example:
- `MineBlockAction` → `mine_block` tool
- `PlaceBlockAction` → `place_block` tool
- `FollowPlayerAction` → `follow_player` tool
Each action tool includes:
- Parameter validation based on Zod schema
- Complete parameter type description
- Automatically generated tool description
- Unified error handling and return format
## Development
### Dependency Requirements
- 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
