使用说明

Minecraft代理

面向局域网的Minecraft MCP栈：Python MCP服务器+节点Mineflayer网桥。通过Dedalus代理或游戏内控制机器人 以自然语言命令聊天.

v2中的新功能： 技能库、多步骤规划、持久世界记忆、自然语言自由构建、冶炼/熔炉自动化、重试错误恢复以及创意/生存模式切换。

快速启动（一个命令）

让一切运行并命令机器人 游戏内聊天:

打开Minecraft Java版，开始一个世界，然后单击 打开局域网.注意端口（例如。 61246).
暴露您的MCP服务器 因此云代理可以访问它（聊天命令需要）：
```
ngrok http 8000
```
复制 https://... URL（例如。 https://abc123.ngrok.io).
运行一个命令启动器 （网桥+MCP服务器+加入游戏+聊天代理）：
```
export DEDALUS_API_KEY=your_key_here
uv run python run_live_chat.py --join-host 192.168.68.70 --join-port 61246
```
使用计算机的LAN IP --join-host （或 127.0.0.1 如果世界在这台机器上）。使用游戏中显示的端口 --join-port.放 MINECRAFT_PORT 和 MINECRAFT_HOST 在 .env 避免超车 --join-* 每次。添加 --auth offline 跳过Microsoft登录（建议用于局域网）。
在Minecraft聊天，键入自然语言命令。示例：
- mine 10 dirt
- go to the tree
- build a 5x5 house with oak planks
- attack the zombie
- switch to creative mode and give me 64 diamonds
- create a plan to get iron tools

这个项目是什么

Python MCP服务器 –将60多个Minecraft机器人操作作为MCP工具公开（移动、挖掘、放置、攻击、制作、聊天、计划、记忆、构建、冶炼等）。建于迪达勒斯mcp.
节点桥 –通过以下方式连接到真正的Minecraft（Java）客户端 Mineflayer.处理寻路（包括破坏/放置障碍物）、挖掘、放置、战斗、清点、冶炼和斜线命令。
模拟模式 –在没有现场游戏（模拟世界和工具）的情况下测试堆栈。
技能库 –保存和重用多步骤工具序列（受Voyager启发）。
多步规划器 –将目标分解为检查点执行计划。
世界记忆 –跨会话持久存储位置、资源和结构。
创意/生存模式 –创意模式解锁传送、给予、填充、召唤、时间、天气。生存模式保持合法的寻路和资源收集。
自由式建筑 –用自然语言描述结构（房屋、塔楼、桥梁、农场、楼梯、围栏、游泳池、平台、柱子）。
错误恢复 –当工具发生故障时，自动重试替代位置和资源。
自主生存模式 –在聊天中说“开始自主”，机器人就会自己玩游戏（检查→ plan → 执行→ 学习）。说“停止”以返回命令模式。

需求

Python 3.10+ （例如通过 uv)
节点20+, npm 10+
《我的世界》Java版 用于真正的局域网游戏（世界对局域网或服务器开放）
Dedalus API密钥 对于代理人(DEDALUS_API_KEY 在 .env 或环境）
吸烟（或类似）如果您希望云代理对游戏内聊天做出响应

设置

uv sync --extra dev
npm --prefix bridge install

复制示例env文件并填写您的值：

cp .env.example .env
# Edit .env: set DEDALUS_API_KEY, MINECRAFT_PORT (e.g. your LAN port), etc.

环境变量(`.env` 格式）

变量	目的	默认值/示例
`DEDALUS_API_KEY`	Dedalus API密钥（聊天代理必需）	（必需）
`MINECRAFT_HOST`	Minecraft服务器主机 `join_game`	`127.0.0.1`
`MINECRAFT_PORT`	Minecraft服务器端口（例如“Open to LAN”中的LAN端口）	`25565` → 设置为例如。 `61246`
`MINECRAFT_USERNAME`	游戏内机器人用户名	`DedalusBot`
`AGENT_MCP_URL`	代理使用的MCP URL。默认值为本地。设置为云代理的公共URL。	（可选）
`MCP_SERVER_URL`	脚本的本地MCP服务器URL	`http://127.0.0.1:8000/mcp`
`DEDALUS_MODEL`	代理模型	`openai/gpt-5.2`
`MINECRAFT_MCP_DATA_DIR`	持久数据目录（技能、记忆、计划、会话）	`.minecraft_mcp_data`

跑步方式

1.一个命令：桥接+MCP+加入+聊天代理

export DEDALUS_API_KEY=your_key_here
uv run python run_live_chat.py --join-host YOUR_LAN_IP --join-port LAN_PORT --agent-mcp-url https://YOUR_NGROK_URL/mcp

2.手动：网桥+MCP服务器在单独的终端中

1号航站楼-大桥

npm --prefix bridge run start -- --listen-host 0.0.0.0 --listen-port 8787

终端2–MCP服务器

uv run python -m minecraft_dedalus_mcp.server --host 0.0.0.0 --port 8000 --bridge-url http://127.0.0.1:8787

3号航站楼-加入游戏

uv run python run_join_game.py --host YOUR_LAN_IP --port LAN_PORT

3.模拟模式（无Minecraft）

export DEDALUS_API_KEY=your_key_here
uv run minecraft-dedalus-run-sim

MCP工具（60+）

核心行动

类别	工具
连接	`join_game`, `leave_game`
状态	`get_bot_status`, `inspect_world`, `get_block_at`
运动	`go_to_known_location`, `look_at`, `jump`, `set_sprint`, `set_sneak`, `stop_movement`, `safe_move_to`
采矿	`mine_resource`, `dig_block`
建筑	`place_block`, `use_block`, `build_structure`, `build_from_description`
精心制作	`craft_items`, `smelt_item`
库存	`equip_item`, `drop_item`, `eat`, `auto_eat`, `ensure_has_item`
实体	`attack_entity`, `mount_entity`, `dismount`, `interact_entity`
其他	`sleep`, `wake`, `collect_items`, `fish`, `send_chat`, `read_chat`

规划与情报

类别	工具
规划	`create_plan`, `get_plan_status`, `get_next_plan_step`, `complete_plan_step`, `fail_plan_step`, `list_plans`
技能	`save_skill`, `find_skills`, `get_skill`, `list_skills`, `record_skill_success`, `remove_skill`
记忆	`remember_location`, `recall_locations`, `find_nearest_location`, `remember_resource`, `find_resource`, `get_memory_summary`
会话	`get_session_summary`, `get_recent_actions`, `get_recent_failures`
恢复	`execute_with_recovery`
剧本	`recommend_next_goal`

创意模式（需要 `set_mode('creative')`)

工具	说明
`set_mode`	切换 `creative` 和 `survival`
`get_mode`	检查当前模式
`run_command`	执行任何斜线命令
`teleport`	即时传送到（x，y，z）
`give_item`	将物品交给机器人
`fill_blocks`	用积木填充一个体积
`set_time`	设置一天中的时间
`set_weather`	设定天气
`summon_entity`	生成实体
`kill_entities`	通过选择器杀死实体

自由形态建筑

用自然语言描述一个结构 build_from_description:

uv run python run_tool.py build_from_description '{"description": "a 7x7x5 house with a door", "origin_x": 10, "origin_y": 64, "origin_z": 10, "material": "oak_planks"}'

支持的结构类型： 房屋、小屋、小屋、塔楼、炮塔、墙壁、桥梁、平台、地板、楼梯、台阶、围栏、围墙、游泳池、农场、柱子。

尺寸： 包含 WxLxH （例如。 5x5x4)在自定义尺寸的描述中。默认为5x5x4。

多步骤规划

制定计划，将目标分解为工具调用步骤：

# Create a plan
uv run python run_tool.py create_plan '{"goal": "get stone tools"}'

# Check status
uv run python run_tool.py get_plan_status '{"plan_id": "abc123"}'

# Get next step to execute
uv run python run_tool.py get_next_plan_step '{"plan_id": "abc123"}'

内置计划模板： gather_wood, get_stone_tools, get_iron_tools, build_shelter, hunt_food, explore_area, prepare_nether.

技能库

保存可重用的工具序列并按关键字检索它们：

# Save a skill
uv run python run_tool.py save_skill '{"name": "early_game", "description": "Get wood, craft tools", "tool_sequence": "[{\"tool\": \"mine_resource\", \"args\": {\"name\": \"oak_log\", \"count\": 4}}]", "tags": "early,tools"}'

# Find skills
uv run python run_tool.py find_skills '{"query": "wood crafting"}'

创造模式

切换到创意模式以使用上帝模式命令：

# Switch to creative
uv run python run_tool.py set_mode '{"mode": "creative"}'

# Teleport instantly
uv run python run_tool.py teleport '{"x": 100, "y": 80, "z": 100}'

# Give items
uv run python run_tool.py give_item '{"item": "diamond_block", "count": 64}'

# Fill a volume
uv run python run_tool.py fill_blocks '{"x1": 0, "y1": 64, "z1": 0, "x2": 10, "y2": 64, "z2": 10, "block": "gold_block"}'

# Switch back to survival
uv run python run_tool.py set_mode '{"mode": "survival"}'

如果在生存模式下调用创意工具，则会返回错误。机器人在这两种模式下都保留了寻路、规划、记忆和技能能力。

自主生存模式

机器人可以自己玩游戏——主动检查世界、设定目标、计划、执行和学习。它只在您告诉它时激活，并在收到命令时停止。

来自游戏内聊天

start autonomous     → bot starts playing on its own
stop                 → bot stops and waits for commands
mine 10 dirt         → any direct command also stops autonomous mode
start autonomous     → resume autonomous play

触发短语： start autonomous, play on your own, survive, do your thing, autoplay. 停止短语： stop, pause, halt, wait, come here.

运作原理

每个自主循环：

检查 --电话 recommend_next_goal 决定做什么
计划 --LLM代理看到目标+所有60多种工具，并决定其方法
执行 --每个周期最多运行25次工具调用（采矿、工艺、建造、战斗、冶炼等）
学习 --从成功的序列中节省位置、资源和技能
重复 --等待5秒，然后开始下一个循环

机器人会在聊天中宣布它在做什么，这样你就可以观看了。速率限制会自动处理（暂停和重试）。

独立演示（无聊天轮询）

uv run python run_demo_autonomous.py

按Ctrl+C停止。

演示脚本

脚本	演示内容
run_demo_autonomous.py	自主生存：机器人自己玩直到停止
run_demo_skill_library.py	保存、搜索和检索可重复使用的技能
run_demo_planning.py	制定计划，执行步骤，跟踪进度
run_demo_memory.py	记住地点、资源；跨会话回忆
run_demo_freeform_build.py	根据描述建造房屋、塔楼、桥梁、农场
run_demo_smelt.py	熔炉熔炼（生铁→ 铁锭）
run_demo_error_recovery.py	使用替代位置/资源自动重试
run_demo_creative.py	创意模式命令：传送、给予、填充、召唤
run_demo_full_agent.py	完整工作流程：计划→ 执行→ 记住→ 保存技能→ 建造
run_demo_move.py	将机器人向东移动5个街区
run_demo_break.py	打破附近的一个街区
run_demo_attack_player.py	攻击另一名玩家，直到他们离开

运行任何演示（运行桥接器+MCP服务器）：

uv run python run_demo_skill_library.py
uv run python run_demo_creative.py
uv run python run_demo_full_agent.py

持久化数据

MCP服务器将数据存储在 MINECRAFT_MCP_DATA_DIR （默认值 .minecraft_mcp_data/):

文件	内容
`skills.json`	已保存技能库
`world_memory.json`	地点、资源、结构
`session_history.json`	操作日志（最近500个操作）
`plans.json`	具有步骤状态的任务计划

数据在服务器重新启动后仍然存在。删除目录以重新开始。

项目布局

bridge/                         Node Mineflayer bridge (real + simulate)
src/minecraft_dedalus_mcp/
  ├── server.py                 MCP server + 60+ tool definitions
  ├── bridge_client.py          HTTP client to bridge
  ├── models.py                 Pydantic models
  ├── constants.py              Domain constants
  ├── playbook.py               Survival goal recommendations
  ├── skills/
  │   └── store.py              Skill library (save, find, replay)
  ├── planning/
  │   ├── planner.py            Multi-step task planner with checkpoints
  │   └── blueprints.py         Freeform building (NL → block plans)
  ├── memory/
  │   ├── world_memory.py       Persistent world knowledge
  │   └── session.py            Session action history
  ├── modes/
  │   ├── base.py               Game mode manager
  │   ├── creative.py           Creative mode actions
  │   └── survival.py           Survival mode helpers
  └── recovery/
      └── retry.py              Error recovery with retry strategies
run_live_chat.py                One-command launcher
run_chat_agent.py               Chat polling + agent
run_demo_*.py                   Demo scripts for each capability
tests/                          Pytest (e2e with sim bridge)
docs/research.md                Research notes

故障排除

微软登录提示阻止机器人 --通行证 --auth offline 完全跳过Microsoft身份验证。这适用于局域网世界和离线模式服务器。看离线身份验证在......下面
代理表示“MCP服务器不可用” --使用ngrok和pass --agent-mcp-url.
ENETUNEREACH或环保 --错误的主机/端口或游戏未向局域网开放。
mine_resource返回已挖掘的值：0 --块名称不匹配。使用 inspect_world 检查姓名。
创意工具回归“需要创意模式” --呼叫 set_mode('creative') 第一。
冶炼失败 --确保附近有炉子，燃料+物品有库存。

离线身份验证（跳过Microsoft登录）

默认情况下， run_live_chat.py 和 run_join_game.py 使用 --auth microsoft，这会触发Microsoft帐户登录流程。如果你在玩 局域网世界 或一个 离线模式服务器，您可以完全跳过此步骤：

# One-command launcher
uv run python run_live_chat.py --auth offline --join-host 192.168.68.70 --join-port 61246

# Manual join
uv run python run_join_game.py --auth offline --host 192.168.68.70 --port 61246

这 --auth offline flag告诉Mineflayer在没有Microsoft/Mojang帐户的情况下进行连接。机器人将加入任何 --username 您指定（默认 DedalusBot).这是开始本地局域网世界的最简单方法。

局限性

模拟模式测试工具流，而不是真正的Mineflayer物理。
自由形式建筑从关键字生成确定性蓝图；真正新颖的形状需要延伸 blueprints.py.
创意模式要求机器人在服务器上具有斜线命令的操作员权限。
冶炼等待固定时间输出；非常大的批次可能会超时。
技能库使用关键字搜索，而不是嵌入（简单快速，但语义较少）。