npm package: @iflow-mcp/changingself-maicraft-mcp-server
Description: 基于mineflayer构建的 Minecraft MCP Server，主要用于MaiBot直播Minecraft
Author: ChangingSelf
Latest version: 1.10.6

# Maicraft

基于 [mineflayer](https://github.com/PrismarineJS/mineflayer) 构建的 Minecraft MCP Server。

主要用于和[Amaidesu](https://github.com/MaiM-with-u/Amaidesu)项目配合（maicraft插件现已独立成新的仓库[MaiM-with-u/Maicraft](https://github.com/MaiM-with-u/Maicraft)），让[MaiBot](https://github.com/MaiM-with-u/MaiBot)游玩Minecraft游戏。

当然，也可以像普通MCP Server一样使用本项目。

部分高级动作的实现参考自 [mineland](https://github.com/cocacola-lab/MineLand)

## 安装

请提前配置好minecraft服务器，无论是minecraft客户端直接开局域网游戏，或是minecraft服务器，都支持，版本会自动检测。

推荐的游戏版本：1.20.4

1.21.4也支持，但mineflayer在此版本有些问题，更高的版本可能会有问题，1.21.8目前测出来是不支持的。

### 方法一：使用npx执行npm包来配置

```json
{
  "mcpServers": {
    "maicraft": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "maicraft@latest",
        "--host","127.0.0.1",
        "--port","25565",
        "--username","Mai",
         "--auth", "offline"
      ]
    }
  }
}

```

这里的@latest表示使用最新版本，你也可以替换为其他版本。

### 方法二：提前全局下载

你可以提前全局安装maicraft，然后再按照方法一进行配置，这样启动时会使用你全局下载的maicraft而不是npx下载的，这样可以避免调用它的时候过慢（因为需要临时下载），缺点是你需要手动升级。

```bash
npm install maicraft -g
```

### 方法三：本地构建

当你的网络不太好，可以使用本地构建。首先clone本地项目

```bash
git clone git@github.com:ChangingSelf/maicraft-mcp-server.git
cd maicraft-mcp-server
pnpm install
pnpm run build
```

然后配置为：

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "node",
      "args": [
        "/path/to/maicraft-mcp-server/dist/main.js",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "EvilMai",
      ]
    }
  }
}
```

如果你不想每次都 `pnpm run build`，也可以直接指定为 `main.ts`，只不过需要tsx来执行

```json
{
  "mcpServers": {
    "minecraft": {
      "command": "npx",
      "args": [
        "tsx"
        "/path/to/maicraft-mcp-server/src/main.ts",
        "--host",
        "localhost",
        "--port",
        "25565",
        "--username",
        "EvilMai",
      ]
    }
  }
}
```

## 配置

Maicraft 支持两种配置方式：命令行参数和配置文件。

### 方式一：命令行参数（推荐）

最简单的方式是直接在启动时使用命令行参数，无需创建配置文件：

```bash
# 基本连接参数
--host <地址>           # Minecraft 服务器地址（默认：127.0.0.1）
--port <端口>           # 服务器端口（默认：25565）
--username <用户名>     # 机器人用户名
--auth <认证方式>       # offline | microsoft | mojang（默认：offline）

# 日志配置
--log-level <级别>      # DEBUG | INFO | WARN | ERROR（默认：INFO）

# 事件过滤
--events-disabled <事件列表>  # 要禁用的事件，用逗号分隔
```

**快速开始示例：**

```bash
# 连接本地服务器
npx -y maicraft --host 127.0.0.1 --username MyBot

# 连接远程服务器并启用调试日志
npx -y maicraft --host mc.example.com --port 25565 --username Bot --log-level DEBUG

# 禁用聊天事件减少噪音
npx -y maicraft --host 127.0.0.1 --username Bot --events-disabled chat,playerJoined
```

### 方式二：配置文件（适合复杂配置）

如果你需要复杂的配置，或者想保存配置以便重复使用，可以使用配置文件：

首先获取配置文件模板：

#### npx 用户

```bash
# 复制配置文件模板到当前目录
npx -y maicraft --init-config
```

#### 源码安装用户

```bash
# 复制配置文件模板
cp config-template.yaml config.yaml
```

然后编辑 `config.yaml` 配置你的设置：

```yaml
minecraft:
  host: 127.0.0.1        # Minecraft 服务器地址
  port: 25565            # 服务器端口
  username: MaiBot       # 机器人用户名
  auth: offline          # 认证方式：offline | microsoft | mojang

# 日志配置
logging:
  level: INFO            # 日志级别：DEBUG | INFO | WARN | ERROR
  enableFileLog: true    # 是否启用文件日志
  useStderr: true        # MCP 模式建议开启

# 可选：禁用特定事件
disabledEvents:
  - chat                 # 聊天事件
  - playerJoined         # 玩家加入
  # - death              # 其他事件...

# 其他高级配置...
# ……
```

**提示：** 你也可以混合使用两种方式，先用配置文件设置基础配置，再用命令行参数覆盖特定设置。

## 启动

现在你可以直接启动 Maicraft：

#### 方式一：npx 用户

```bash
# 直接启动（结合上面的命令行参数使用）
npx -y maicraft --host 127.0.0.1 --username MyBot

# 或使用配置文件启动
npx -y maicraft /path/to/config.yaml
```

#### 方式二：源码安装用户

```bash
# 开发模式（热重载，适合开发调试）
pnpm dev

# 生产模式（需要先构建）
pnpm build
pnpm start
```

启动成功后，你会看到类似以下的输出：

````
[INFO] Maicraft 客户端已启动，按 Ctrl+C 退出
[INFO] 日志文件位置: /path/to/logs/maicraft-2024-01-15T10-30-00.log
[INFO] WebSocket日志服务器已启动: ws://localhost:20915/ws/mcp-logs
````

## 测试

#### 方式一：npx 用户

```bash
# 需要先安装mcp-inspector
npm install -g @modelcontextprotocol/inspector

# 列出已注册的工具
mcp-inspector --cli --config mcp-inspector.json --server maicraft --method tools/list

# 调用 query_state 进行烟囱测试
mcp-inspector --cli --config mcp-inspector.json --server maicraft --method tools/call --tool-name query_state
```

#### 方式二：源码安装用户

```bash
# 列出已注册的工具
pnpm mcp:tools

# 调用 query_state 进行烟囱测试
pnpm mcp:state
```

## 快速调试

### 方法一：直接调试

无需下载任何源码，直接运行如下命令：

```bash
npx @modelcontextprotocol/inspector@0.16.5 npx -y maicraft@latest --host ChangingSelf.xyz --port 50226 --username MaiBot --auth offline
```

之后会弹出一个浏览器网页，点击这个网页左下角的“connect”按钮，若右侧出现“List Tools”的按钮，说明成功配置好了，可以直接通过UI界面进行调试操作。

指定inspector的0.16.5版本的原因是，左下角会有stderr的输出。本mcp server支持的是stdio类型，所以为了避免日志影响stdio，这里将所有的日志都重定向到了stderr。

### 方法二：源码调试

如果你已经克隆了项目源码，可以直接使用源码进行调试：

```bash
# 克隆项目（如果还没有）
git clone https://github.com/ChangingSelf/Maicraft.git
cd Maicraft

# 安装依赖
pnpm install

# 启动调试界面（开发模式）
pnpm mcp:ui
```

这会启动一个基于源码的调试界面，无需打包，直接运行TypeScript源码。

如果你需要更灵活的调试，也可以手动配置：

创建mcp-inspector.json配置文件

```json
{
  "mcpServers": {
    "maicraft": {
      "type": "stdio",
      "command": "tsx",
      "args": ["src/main.ts", "./config.yaml"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}
```

```bash
# 启动调试界面
mcp-inspector --config mcp-inspector.json --server maicraft
```

## 日志输出

Maicraft 提供多种方式查看日志：控制台输出、文件日志、WebSocket 实时流。

### 日志文件

日志文件默认保存在项目根目录的 `logs/` 文件夹中，文件名格式为：

````
logs/maicraft-YYYY-MM-DDTHH-mm-ss.log
````

### WebSocket 日志流

程序启动时会自动启动 WebSocket 服务器，用于实时传输日志：

- **端点**: `ws://localhost:20915/ws/mcp-logs`
- **默认端口**: 20915
- **用途**: 用于 [maicraft-web-ui](https://github.com/ChangingSelf/maicraft-web-ui) 等工具实时查看日志

可以通过配置修改 WebSocket 服务器设置：

```yaml
websocket:
  enabled: true           # 是否启用WebSocket日志服务器
  port: 20915             # WebSocket服务器端口
  host: "localhost"       # WebSocket服务器监听地址
```

## 架构

```mermaid
graph LR
  A[main.ts 启动器] -->|读取| C[config.yaml]
  A --> L[Logger]
  A --> MC[MinecraftClient]
  A --> AE[ActionExecutor]
  A --> MCP[MaicraftMcpServer]

  MC -->|使用| B[mineflayer Bot]
  B -->|事件| MC
  MC -->|gameEvent| A

  MCP -->|动作工具| AE
  MCP -->|连接/状态| MC
  AE -->|使用 Bot 执行动作| B
  
  AE -->|自动发现| ACT[src/actions/*.ts]
  ACT -->|schema + execute| AE
  AE -->|自动生成| MCP_TOOLS[MCP Tools]
```

### 动作系统架构

```mermaid
graph TD
  A[Action File] -->|继承| B[BaseAction]
  A -->|定义| C[schema: z.ZodTypeAny]
  A -->|实现| D[execute: bot, params => Promise&lt;ActionResult&gt;]
  
  B -->|自动提供| E[validateParams]
  B -->|自动提供| F[getParamsSchema]
  B -->|自动提供| G[getMcpTools]
  
  G -->|生成| H[MCP Tool: action_name_snake_case]
  C -->|校验| I[参数类型安全]
  C -->|描述| J[自动生成参数文档]
```

### 时序：调用动作（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: 动作执行（寻路/采集等）
    Bot-->>AE: result
    AE-->>Server: { success, data }
    Server-->>Client: structuredContent
  else Bot not ready
    Server-->>Client: { ok:false, error: service_unavailable }
  end
```

### 时序：事件处理

```mermaid
sequenceDiagram
  participant Bot as mineflayer Bot
  participant MC as MinecraftClient
  participant Main as main.ts

  Bot->>MC: 原始游戏事件
  MC->>MC: 过滤 disabledEvents（黑名单）
  MC-->>Main: gameEvent
```

## 详细配置

### 命令行参数

Maicraft 支持多种命令行参数，可以覆盖配置文件中的设置：

```bash
# 基础连接参数
--host <地址>           # Minecraft 服务器地址（默认：127.0.0.1）
--port <端口>           # 服务器端口（默认：25565）
--username <用户名>     # 机器人用户名
--password <密码>       # 服务器密码（在线模式需要）
--auth <认证方式>       # offline | microsoft | mojang（默认：offline）
--version <版本>        # Minecraft 版本（可选，自动检测）

# 日志配置
--log-level <级别>      # DEBUG | INFO | WARN | ERROR（默认：INFO）

# 事件过滤（黑名单机制）
--events-disabled <事件列表>  # 要禁用的事件类型，用逗号分隔
                              # 示例：--events-disabled chat,playerJoined,health
                              # 支持的事件：chat, playerJoined, playerLeft, death, spawn, rain, kicked, spawnReset, health, entityHurt, entityDead, playerCollect

# MCP 配置
--mcp-name <名称>       # MCP 服务器名称
--mcp-version <版本>    # MCP 服务器版本

# 工具过滤
--tools-enabled <工具列表>    # 启用的 MCP 工具列表（白名单）
--tools-disabled <工具列表>  # 禁用的 MCP 工具列表（黑名单）
```

#### 事件禁用参数示例

```bash
# 禁用聊天和玩家加入事件
npx -y maicraft --events-disabled chat,playerJoined

# 禁用所有生命值相关事件
npx -y maicraft --events-disabled health,entityHurt,entityDead

# 禁用天气和玩家收集事件
npx -y maicraft --events-disabled rain,playerCollect
```

### 基础配置

在 `config.yaml` 中配置 Minecraft 服务器连接：

```yaml
minecraft:
  host: 127.0.0.1        # 服务器地址
  port: 25565            # 端口
  username: MaiBot       # 机器人用户名
  auth: offline          # 认证方式：offline | microsoft | mojang
  version: "1.19.0"      # 游戏版本（可选）

# 禁用的事件类型列表（黑名单机制）
# 列出要禁用的游戏事件类型，默认情况下所有事件都会被启用
disabledEvents:
  # - chat                 # 聊天事件
  # - playerJoined         # 玩家加入
  # - playerLeft           # 玩家离开
  # - death                # 玩家死亡
  # - spawn                # 玩家重生
  # - rain                 # 天气变化
  # - kicked               # 玩家被踢出
  # - spawnReset           # 重生点重置
  # - health               # 生命值更新
  # - entityHurt           # 实体受伤
  # - entityDead           # 实体死亡
  # - playerCollect        # 玩家收集物品

# 不能破坏的方块列表配置
# 机器人路径查找时会避免破坏这些方块
blocksCantBreak:
  - chest        # 箱子
  - furnace      # 熔炉
  - bed          # 床
  - door         # 门
  - trapdoor     # 活板门
  - sign         # 告示牌
  - torch        # 火把
  - lantern      # 灯笼

maxMessageHistory: 100   # 事件历史缓存数量


### 路径查找配置

#### 不能破坏的方块列表

`blocksCantBreak` 配置项用于指定机器人在路径查找时不能破坏的方块列表。当机器人需要移动到某个位置时，它会避免破坏这些重要的方块。

```yaml
# 不能破坏的方块列表配置
blocksCantBreak:
  - chest        # 箱子
  - furnace      # 熔炉
  - bed          # 床
  - door         # 门
  - trapdoor     # 活板门
  - sign         # 告示牌
  - torch        # 火把
  - lantern      # 灯笼
```

**配置说明：**

- 如果不配置此选项，将使用默认列表：`['chest', 'furnace']`
- 可以设置为空数组 `[]` 来允许破坏所有方块
- 方块名称使用 Minecraft 的英文名称（如 `chest`、`furnace` 等）
- 如果配置了未知的方块名称，会在日志中显示警告信息

**常见方块名称参考：**

- `chest` - 箱子
- `furnace` - 熔炉
- `crafting_table` - 工作台
- `bed` - 床
- `door` - 门
- `trapdoor` - 活板门
- `sign` - 告示牌
- `torch` - 火把
- `lantern` - 灯笼
- `anvil` - 铁砧
- `enchanting_table` - 附魔台
- `brewing_stand` - 酿造台


### MCP 工具配置

Maicraft 支持多种工具过滤模式，推荐使用黑名单模式：

```yaml
mcp:
  name: "Maicraft MCP"
  version: "1.0.0"
  tools:
    # 方式1：黑名单模式（推荐）- 屏蔽指定工具，其他全部可用
    disabled:
      - use_chest
      - smelt_item
    
    # 方式2：白名单模式 - 仅暴露指定工具
    # enabled:
    #   - mine_block
    #   - place_block
    #   - follow_player
    
    # 方式3：同时使用 - 白名单允许的集合减去黑名单
    # enabled:
    #   - mine_block
    #   - place_block
    #   - chat
    # disabled:
    #   - chat
    
    # 方式4：不配置 - 默认暴露所有工具
    # （删除或注释掉 tools 部分）
```

## 动作开发

### 动作系统特性

- **自动发现**：将动作文件放在 `src/actions/` 目录即可自动发现
- **参数校验**：基于 Zod 的自动参数校验
- **类型安全**：完整的 TypeScript 类型支持
- **MCP 集成**：自动生成对应的 MCP 工具

### 编写新动作

#### 方式1：继承基类（推荐）

```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 = '执行我的自定义动作';
  
  // 定义参数校验 schema
  schema = z.object({
    target: z.string().describe('目标对象'),
    count: z.number().int().min(1).optional().describe('执行次数（可选）'),
  });

  async execute(bot: Bot, params: MyActionParams) {
    try {
      // 实现动作逻辑
      const count = params.count ?? 1;
      
      // ... 具体实现
      
      return this.createSuccessResult(`成功执行动作 ${count} 次`);
    } catch (error) {
      return this.createExceptionResult(error, '执行失败', 'EXECUTION_ERROR');
    }
  }
  
  // validateParams、getParamsSchema、getMcpTools 由基类自动提供
}
```

#### 方式2：函数式定义

```typescript
// src/actions/MyAction.ts
import { defineAction } from '../minecraft/ActionInterface';
import { z } from 'zod';

export const MyAction = defineAction({
  name: 'myAction',
  description: '执行我的自定义动作',
  schema: z.object({
    target: z.string().describe('目标对象'),
    count: z.number().int().min(1).optional().describe('执行次数（可选）'),
  }),
  async execute(bot, params) {
    // 实现动作逻辑
    const count = params.count ?? 1;
    
    // ... 具体实现
    
    return { success: true, message: `成功执行动作 ${count} 次` };
  },
});
```

### 动作自动注册

1. 将动作文件放在 `src/actions/` 目录
2. 文件会被自动发现并注册
3. 对应的 MCP 工具会自动生成（工具名为动作名的 snake_case 形式）
4. 例如：`MyAction` → `my_action` 工具

### 动作开发最佳实践

#### 1. 参数设计原则

- 使用清晰的参数名称，避免缩写
- 为可选参数提供合理的默认值
- 使用 Zod schema 进行严格的参数校验
- 在参数描述中提供示例和说明

#### 2. 错误处理

- 使用 `createErrorResult()` 返回业务逻辑错误
- 使用 `createExceptionResult()` 返回异常错误
- 提供有意义的错误代码和消息
- 记录详细的调试日志

#### 3. 返回值设计

- 使用 `createSuccessResult()` 返回成功结果
- 在返回数据中包含有用的状态信息
- 保持返回格式的一致性

#### 4. 依赖检查

- 检查必要的插件是否已加载（如 pathfinder）
- 验证目标对象是否存在（如方块、玩家、实体）
- 确保背包中有必要的物品

#### 5. 性能考虑

- 设置合理的超时时间
- 限制搜索范围（如 maxDistance）
- 避免无限循环和长时间阻塞

### 可用的动作工具

当前支持的动作工具：

#### 基础交互动作

- **`chat`** **chat** **chat** - 发送聊天消息

  - 参数：`message` (字符串) - 要发送的聊天消息

- **`basic_control`** **basic_control** **basic_control** - 基础游戏控制功能

  - 参数：

    - `type` (字符串) - 控制类型：`toss` | `move` | `jump` | `sneak` | `look_at` | `sleep` | `wake` | `stop_move` | `stop_sneak`
    - `item` (字符串，可选) - 物品名称或ID (用于 toss 类型)
    - `count` (数字，可选) - 物品数量 (用于 toss 类型，默认 1)
    - `direction` (字符串，可选) - 移动方向 (用于 move 类型：`forward` | `back` | `left` | `right`)
    - `lookType` (字符串，可选) - 注视类型 (用于 look_at 类型：`angle` | `position` | `player` | `entity` | `block`)
    - `yaw` (数字，可选) - 视角偏航角，弧度 (用于 angle 注视类型)
    - `pitch` (数字，可选) - 视角俯仰角，弧度 (用于 angle 注视类型)
    - `x`, `y`, `z` (数字，可选) - 目标坐标 (用于 position 注视类型)
    - `force` (布尔值，可选) - 是否强制看向 (用于所有注视类型，默认 false)
    - `player` (字符串，可选) - 目标玩家名称 (用于 player 注视类型)
    - `entity` (字符串，可选) - 目标实体类型 (用于 entity 注视类型)，例如 cow, pig, zombie 等
    - `block` (字符串，可选) - 目标方块名称 (用于 block 注视类型)，例如 dirt, stone, diamond_ore 等
    - `maxDistance` (数字，可选) - 搜索距离 (用于 entity 和 block 注视类型，默认 64)


- **`use_item`** **use_item** **use_item** - 使用手中物品

  - 参数：

    - `itemName` (字符串，可选) - 物品名称，不指定则使用当前手持物品
    - `useType` (字符串，可选) - 使用类型：`consume` | `activate` | `useOn`，默认为根据物品类型自动判断
    - `targetEntityName` (字符串，可选) - 目标实体名称，仅在使用 `useOn` 类型时需要
    - `targetPlayerName` (字符串，可选) - 目标玩家名称，仅在使用 `useOn` 类型时需要
    - `offHand` (布尔值，可选) - 是否使用副手，默认 false





#### 移动与导航动作

- **`move`** **move** **move** - 移动到指定位置

  - 参数：

    - `type` (字符串) - 移动类型：`coordinate` | `block` | `player` | `entity`
    - `useAbsoluteCoords` (布尔值，可选) - 是否使用绝对坐标，默认 false
    - `x`, `y`, `z` (数字，可选) - 目标坐标 (当 type 为 coordinate 时必需)
    - `block` (字符串，可选) - 目标方块名称 (当 type 为 block 时必需)
    - `player` (字符串，可选) - 目标玩家名称 (当 type 为 player 时必需)
    - `entity` (字符串，可选) - 目标实体类型 (当 type 为 entity 时必需)
    - `distance` (数字，可选) - 到达距离，默认 1
    - `timeout` (数字，可选) - 超时时间(秒)，默认 60
    - `maxDistance` (数字，可选) - 最大移动距离，默认 100


- **`follow_player`** **follow_player** **follow_player** - 跟随指定玩家

  - 参数：

    - `player` (字符串) - 目标玩家名称
    - `distance` (数字，可选) - 跟随距离(格)，默认 3
    - `timeout` (数字，可选) - 超时时间(秒)，默认 5


- **`swim_to_land`** **swim_to_land** **swim_to_land** - 游向最近的陆地

  - 参数：

    - `maxDistance` (数字，可选) - 最大搜索距离，默认 64
    - `timeout` (数字，可选) - 超时时间(秒)，默认 60





#### 方块操作动作

- **`mine_block`** **mine_block** **mine_block** - 挖掘指定类型的方块

  - 参数：

    - `name` (字符串) - 方块名称，例如 "dirt", "stone", "coal_ore"
    - `count` (数字，可选) - 需要挖掘的数量，默认 1
    - `direction` (字符串，可选) - 挖掘方向：`+y` | `-y` | `+z` | `-z` | `+x` | `-x`（坐标轴方向），不指定时在附近搜索
    - `maxDistance` (数字，可选) - 搜索距离，默认 48
    - `bypassAllCheck` (布尔值，可选) - 是否绕过所有检查直接挖掘，默认 false


- **`place_block`** **place_block** **place_block** - 在指定位置放置方块

  - 参数：

    - `x`, `y`, `z` (数字) - 目标位置坐标
    - `block` (字符串) - 要放置的方块名称
    - `face` (字符串，可选) - 放置面向：`+y` | `-y` | `+z` | `-z` | `+x` | `-x`（坐标轴方向）
    - `useAbsoluteCoords` (布尔值，可选) - 是否使用绝对坐标，默认 false





#### 物品制作动作

- **`craft_item`** **craft_item** **craft_item** - 合成指定物品

  - 参数：

    - `item` (字符串) - 要合成的物品名称
    - `count` (数字，可选) - 合成数量，默认 1


- **`start_smelting`** **start_smelting** **start_smelting** - 在熔炉中开始熔炼物品（不等待完成）

  - 参数：

    - `item` (字符串) - 要熔炼的物品名称
    - `fuel` (字符串) - 燃料物品名称
    - `count` (数字，可选) - 熔炼数量，默认 1


- **`collect_smelted_items`** **collect_smelted_items** **collect_smelted_items** - 从熔炉中收集已熔炼完成的物品

  - 参数：

    - `item` (字符串，可选) - 要收集的熔炼产物名称，不指定则收集所有产物
    - `x`, `y`, `z` (数字，可选) - 熔炉坐标
    - `useAbsoluteCoords` (布尔值，可选) - 是否使用绝对坐标，默认 false


- **`use_furnace`** **use_furnace** **use_furnace** - 熔炉操作（放入/取出/查看物品）

  - 参数：

    - `container_type` (字符串，可选) - 容器类型：`furnace` | `blast_furnace` | `smoker` (默认 furnace)
    - `action` (字符串，可选) - 操作类型：`put` | `take` | `view` (默认 put)
    - `items` (数组，可选) - 物品数组 (put操作必需，take操作可选用于指定槽位)

      - `name` (字符串，可选) - 物品名称 (put操作必需)
      - `count` (数字，可选) - 物品数量 (默认 1)
      - `position` (字符串，可选) - 槽位：`input` | `fuel` | `output`

    - `x`, `y`, `z` (数字，可选) - 熔炉坐标
    - `auto_search` (布尔值，可选) - 是否自动查找附近容器 (默认 false)


- **`smelt_item`** **smelt_item** **smelt_item** - 在熔炉中熔炼物品（已弃用，建议使用 start_smelting + collect_smelted_items）

  - 参数：

    - `item` (字符串) - 要熔炼的物品名称
    - `fuel` (字符串) - 燃料物品名称
    - `count` (数字，可选) - 熔炼数量，默认 1





#### 存储与交互动作

- **`use_chest`** **use_chest** **use_chest** - 与附近箱子交互，存取物品

  - 参数：

    - `action` (字符串) - 操作类型：`store` | `withdraw`
    - `item` (字符串) - 物品名称
    - `count` (数字，可选) - 数量，默认 1





#### 战斗动作

- **`kill_mob`** **kill_mob** **kill_mob** - 击杀指定名称的生物

  - 参数：

    - `mob` (字符串) - 目标生物名称，例如 "cow", "pig", "zombie"
    - `timeout` (数字，可选) - 等待生物死亡的超时时间(秒)，默认 300





#### 其他动作


### 动作使用示例

#### 基础操作示例

```json
// 发送聊天消息
{
  "tool": "chat",
  "arguments": {
    "message": "Hello, Minecraft!"
  }
}

// 食用苹果
{
  "tool": "use_item",
  "arguments": {
    "itemName": "apple",
    "useType": "consume"
  }
}

// 扔雪球
{
  "tool": "use_item",
  "arguments": {
    "itemName": "snowball",
    "useType": "activate"
  }
}

// 使用当前手持物品（自动判断使用类型）
{
  "tool": "use_item",
  "arguments": {}
}

// 丢弃物品
{
  "tool": "basic_control",
  "arguments": {
    "type": "toss",
    "item": "dirt",
    "count": 5
  }
}

// 开始向前移动
{
  "tool": "basic_control",
  "arguments": {
    "type": "move",
    "direction": "forward"
  }
}

// 执行跳跃
{
  "tool": "basic_control",
  "arguments": {
    "type": "jump"
  }
}

// 开始潜行
{
  "tool": "basic_control",
  "arguments": {
    "type": "sneak"
  }
}

// 调整视角到特定角度
{
  "tool": "basic_control",
  "arguments": {
    "type": "look_at",
    "lookType": "angle",
    "yaw": 1.57,
    "pitch": 0.0,
    "force": true
  }
}

// 看向特定坐标位置
{
  "tool": "basic_control",
  "arguments": {
    "type": "look_at",
    "lookType": "position",
    "x": 100,
    "y": 64,
    "z": 100,
    "force": true
  }
}

// 看向玩家
{
  "tool": "basic_control",
  "arguments": {
    "type": "look_at",
    "lookType": "player",
    "player": "Steve",
    "force": true
  }
}

// 看向最近的牛
{
  "tool": "basic_control",
  "arguments": {
    "type": "look_at",
    "lookType": "entity",
    "entity": "cow",
    "maxDistance": 50
  }
}

// 看向最近的钻石矿石方块
{
  "tool": "basic_control",
  "arguments": {
    "type": "look_at",
    "lookType": "block",
    "block": "diamond_ore",
    "maxDistance": 100
  }
}

// 睡觉（自动寻找附近的床）
{
  "tool": "basic_control",
  "arguments": {
    "type": "sleep"
  }
}

// 醒来
{
  "tool": "basic_control",
  "arguments": {
    "type": "wake"
  }
}

// 停止移动
{
  "tool": "basic_control",
  "arguments": {
    "type": "stop_move"
  }
}

// 停止潜行
{
  "tool": "basic_control",
  "arguments": {
    "type": "stop_sneak"
  }
}

// 对玩家使用物品
{
  "tool": "use_item",
  "arguments": {
    "itemName": "saddle",
    "useType": "useOn",
    "targetPlayerName": "Steve"
  }
}

// 对实体使用物品
{
  "tool": "use_item",
  "arguments": {
    "itemName": "shears",
    "useType": "useOn",
    "targetEntityName": "sheep"
  }
}

// 挖掘石头
{
  "tool": "mine_block",
  "arguments": {
    "name": "stone",
    "count": 5
  }
}

// 向Y轴正方向挖掘石头
{
  "tool": "mine_block",
  "arguments": {
    "name": "stone",
    "count": 3,
    "direction": "+y"
  }
}

// 向Z轴负方向挖掘煤炭
{
  "tool": "mine_block",
  "arguments": {
    "name": "coal_ore",
    "count": 2,
    "direction": "-z",
    "maxDistance": 20
  }
}

// 移动到指定坐标
{
  "tool": "move",
  "arguments": {
    "type": "coordinate",
    "x": 100,
    "y": 64,
    "z": 200,
    "useAbsoluteCoords": true
  }
}
```

#### 高级操作示例

> **💡 熔炼优化提示**：为了优化熔炼体验并避免长时间等待，建议使用 `start_smelting` + `collect_smelted_items` 的组合替代 `smelt_item`。这样可以：
> 
> - 开始熔炼后立即返回，不阻塞其他操作
> - 在熔炼进行时执行其他任务
> - 熔炼完成后单独收集产物

```json
// 合成工作台
{
  "tool": "craft_item",
  "arguments": {
    "item": "crafting_table",
    "count": 1
  }
}

// 开始熔炼铁矿石（推荐方式）
{
  "tool": "start_smelting",
  "arguments": {
    "item": "iron_ore",
    "fuel": "coal",
    "count": 3
  }
}

// 收集熔炼产物
{
  "tool": "collect_smelted_items",
  "arguments": {
    "item": "iron_ingot"
  }
}

// 熔炼铁矿石（已弃用，会等待熔炼完成）
{
  "tool": "smelt_item",
  "arguments": {
    "item": "iron_ore",
    "fuel": "coal",
    "count": 3
  }
}

// 熔炉操作示例
{
  "tool": "use_furnace",
  "arguments": {
    "action": "put",
    "items": [
      {"name": "iron_ore", "count": 5, "position": "input"},
      {"name": "coal", "count": 2, "position": "fuel"}
    ]
  }
}

// 查看熔炉状态
{
  "tool": "use_furnace",
  "arguments": {
    "action": "view"
  }
}

// 从熔炉取出产物
{
  "tool": "use_furnace",
  "arguments": {
    "action": "take",
    "items": [
      {"position": "output"}
    ]
  }
}

// 跟随玩家
{
  "tool": "follow_player",
  "arguments": {
    "player": "Steve",
    "distance": 5,
    "timeout": 30
  }
}

```

## MCP 工具

### 查询工具

- `query_state` - 查询游戏状态
- `query_events` - 查询事件历史

### 动作工具

动作工具会根据 `src/actions/` 目录中的动作文件自动生成，工具名格式为动作名的 snake_case 形式。例如：

- `MineBlockAction` → `mine_block` 工具
- `PlaceBlockAction` → `place_block` 工具
- `FollowPlayerAction` → `follow_player` 工具

每个动作工具都会自动包含：

- 基于 Zod schema 的参数校验
- 完整的参数类型说明
- 自动生成的工具描述
- 统一的错误处理和返回格式

## 开发

### 依赖要求

- Node.js >= 18.0.0
- pnpm >= 10.6.5
- Python (用于编译某些依赖)

### 主要依赖版本

- 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
# 构建
pnpm build

# 测试
pnpm test

# 代码检查
pnpm lint

# 清理构建文件
pnpm clean
```

## 许可证

MIT