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

npm install maicraft -g

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

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

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

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

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

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

# 连接本地服务器
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 -y maicraft --init-config

# 复制配置文件模板
cp config-template.yaml config.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              # 其他事件...

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

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

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

# 开发模式（热重载，适合开发调试）
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

# 需要先安装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

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

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

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

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

# 安装依赖
pnpm install

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

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

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

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

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

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]

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

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

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

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

# 基础连接参数
--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 工具列表（黑名单）

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

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

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

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      # 灯笼

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/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 由基类自动提供
}

// 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} 次` };
  },
});

// 发送聊天消息
{
  "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
  }
}

// 合成工作台
{
  "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
  }
}

# 构建
pnpm build

# 测试
pnpm test

# 代码检查
pnpm lint

# 清理构建文件
pnpm clean