MaiCraft

让支持 MCP 的 AI 代理在 Minecraft 中感知环境、规划目标，并通过真实的第一人称操作完成任务。

MaiCraft 是一个客户端必装、服务端可选的 Minecraft Mod。客户端在游戏进程内提供本地 Model Context Protocol（MCP） 服务，把大模型给出的语义目标转换为寻路、采集、合成、交互、建造等具体游戏行为。

MaiCraft 不内置大模型，也不要求额外运行 Python 服务；你仍需准备一个支持 Streamable HTTP MCP 的 AI 客户端和可用模型。服务端未安装 MaiCraft 时使用客户端模式；服务端安装后，按协商到的能力启用原生机器观察、配置、供料和生产验证。

Warning

MaiCraft 目前处于 0.1.0 预览阶段，尚未发布稳定构建，也没有完成覆盖模组整合包的实机验收。请只在备份过的测试世界中使用，不要把它当作无人值守的生产级代理。

主要能力

• 感知与记忆：读取当前状态、周边环境、任务进度、地标和机器快照。
• 移动与探索：前往坐标或语义地点、寻找结构和实体、跨维度旅行，并处理游泳、开门和受限地形改造。
• 生存流程：采集物品、合成、烹饪、交易、整理容器、进食、装备、钓鱼、睡觉和照明。
• 建造与进度目标：根据用途、尺寸、风格和材料策略生成并执行建筑计划，也可组合多个目标形成连续任务。
• 战斗与里程碑：处理防御或明确授权的战斗任务，并支持末影龙、鞘翅等长流程目标。
• 模组机器：从组件关系与工艺模块生成 Create、AE2、Mekanism 和混合设备布局，规划输送网络，分批供料施工，安装 AE2 部件与存储盘，配置已支持的 Mek 接口，并核验机器几何及同步运行证据。
• 可选服务端生产增强：读取真实库存、配方和连接，配置受支持的过滤器、接口与 AE2 样板，按实际加工事件分批投料，再验证真实交付与持续产出窗口。
• Dev 蓝图预览：在世界中显示半透明待建结构和差异轮廓，支持逐层查看；确认前归还玩家操控，确认后执行冻结的方案。
• 只读房屋设计：maicraft:design_build 直接显示蓝图，不移动或施工；普通建造在 Dev 确认之后才开始供料。
• 按需知识资源：自动发现安装模组的 Ponder 教程，按组件和场景读取原始旁白、操作提示及方块状态；支持 MCP Resources 和 perceive(view="knowledge")。
• 任务观察与控制：优先通过 Attention 事件等待取得权威状态、决策和完整终态结果；支持暂停、恢复和取消。
• 游戏聊天与命令：打开原版聊天框逐字输入，再自动提交消息或 / 命令；支持后台运行和人工接管。

MCP 客户端可以提供语义目标或声明式蓝图。MaiCraft 在游戏内负责路径、施工手法、菜单操作、重试和结果校验；调用方不提供远程点击脚本。

MCP 入口与语义能力

MaiCraft 在 MCP 的 tools/list 中注册四个通用入口：

工具	用途
perceive	以 Attention 为首选等待任务事件、决策和结果；也读取游戏状态、能力契约与世界证据
plan	将语义目标编译为计划，但不立即执行
execute	异步启动目标或计划，返回任务 ID 和可直接传给 perceive 的 next_attention
task	显式检查/恢复任务，暂停、恢复、取消，或回答问题；日常等待使用 Attention

以上是服务器在 MCP tools/list 中注册的名称；客户端可以附加服务器前缀来区分不同连接。旧版使用的 maicraft_ 工具名前缀已移除，升级后请让客户端重新获取工具列表，并更新固定工具名配置。

执行后按返回的 next_attention 等待，读取响应中的 task 和 wake_reason，再按新的 next_attention 续等。Attention 直接引用任务记录，即使历史事件已被挤出缓存，也能返回仍保留的任务决策和最终结果；无需轮询 task(get) 或包装同步执行工具。原生资源订阅可使用 maicraft://attention（任务监控）和 maicraft://chatflow（收到的游戏内聊天，供专门对话的 Agent 使用），模型唤醒行为由宿主决定。

四个入口不等于只有四种功能。运行时提供多项 maicraft:* 语义能力，包括 chat、inspect_machine、design_machine、operate_machine、build_machine、connect_mechanical_power、travel、acquire_items、craft、build 和 combat 等。它们作为 goal.ability 交给 plan 或 execute。

每项能力的参数和限制由 perceive(view="abilities") 动态公开。AI 客户端应先读取能力契约，再提交目标，而不是猜测方块坐标、物品栏槽位或内部动作。

例如将以下参数交给 execute，会自动打开聊天框、逐字输入并发送；plan 只校验和规划，不打开界面：

{
  "goal": {
    "ability": "maicraft:chat",
    "outcome": "在游戏里向大家问好",
    "parameters": {"text": "大家好，我回来了！", "typing_interval_ms": 100}
  },
  "request_key": "greeting-001"
}

text 以 / 开头时走原版命令流程，例如 /home；服务器命令和客户端模组命令沿用当前玩家的权限与加载器处理。文字必须为单行，长度最多 256 个 UTF-16 字符，空白按原版规则整理。每个完整显示字符默认间隔 100 毫秒，可设置为 50–1000 毫秒；全部输入后停留 250 毫秒再自动提交。中文、组合 emoji 和重音组合不会被拆开显示。

无需窗口前台或模拟键盘。任务可从失焦产生的不可见暂停画面开始；保留玩家手动打开的暂停菜单、容器和已有聊天草稿。低帧率下输入会变慢，不会一次补打很多字。按 Esc 关闭或手动编辑/切换界面会取消自动发送；任务暂停会释放界面，恢复后继续原草稿。

同一次逻辑发送的网络重试应复用 request_key，新的消息使用新的键。结果中的 delivery_status="submitted_to_client" 表示已调用原版提交入口，服务器接收和命令执行效果仍需观察 Attention 中的后续消息。提交结果不确定时不会自动重发。

移动目标还未定位时，可以使用 maicraft:travel 的 semantic_target="platform" 与 direction="down"，让 Mod 边移动边寻找下方平台，无须给坐标。transport_mode="jetpack" 保持同一次飞行控制，在平台进入局部观察后转入着陆；ground 使用普通步行寻路，auto 可选择可用的喷气背包。

所有平台搜索都使用 semantic_target="platform"，通过 direction 选择方向（up、down、forward、backward、left、right 或四个英文方位，默认 forward）。相对方向在任务开始时固定；区域搜索半径 max_distance 默认 64，范围 8–128 格。普通坐标移动仍支持省略 Y 和到达容差，exact=true 用于需要准确站位的动作。

perceive(view="surroundings") 的 terrain_overview 提供地形缩略信息：大致方位、相对高度、水平范围、surface_material 材质、支撑样本及未知区域。预览覆盖已加载地形的水平半径 128 格、向下 256 格，按距离使用 4／8／32 格采样间距。同一次请求会等待后续客户端帧补充结果；达到采样或响应预算后返回明确的完整／部分采样状态。远处不同材质的支撑面会优先保留，未采到的平台不代表不存在。

飞行航点允许高度偏差和观察区域内到达，后续路径仍检查真实身体碰撞。静止飞艇的已验证下降柱支持关包快速下降；确认无伤的短落可以直接关包到地面。地面移动会退出喷气背包飞行模式，落地保护也会在材料就绪后退出缓慢悬停；下一次飞行任务按需重新启用背包。

电梯的实际楼层见 surroundings.elevators，也可用 perceive(view="situation", focus="maicraft:travel") 读取。maicraft:travel 支持 elevator_floor="top"、bottom、next_up、next_down 或同步列表中的楼层 ID／名称；可用 elevator_id 指定轿厢，交通模式使用 auto 或 elevator，无须填写目的地高度。

使用 elevator_floor="ask"，或仅指定 transport_mode="elevator" 而不提供目的地，会先到电梯附近同步楼层，再返回 waiting_for_decision。LLM 用 task(action="answer") 的 retry 和 details.parameters 选择 elevator_id、elevator_floor。同步楼层是中间步骤，实际乘梯并出梯后才完成移动目标；needs_sync 表示信息未知，不代表没有楼层。

maicraft:travel_dimension 和 maicraft:reach_milestone 可设置 prepare_portal=true，在没有观察到有效传送门时准备入口。下界门优先复用完整黑曜石框、补齐标准小门的缺块，或在附近已加载的安全空地新建十块黑曜石框，再使用打火石或已有火焰弹点火。建造和修复还需 may_alter_terrain=true；缺料按 material_policy 和 allowed_sources 获取，临时施工支撑也计入供料需求。

末地入口会复用已加载的完整门框，必要时通过原生末影之眼寻找要塞；核对十二个门框的朝向，只为没有眼的格子补眼。搜索和嵌眼需要 allow_rare_consumables=true。准备期间保留 protected_labels 和上层区域保护，供料后重新检查现场；点击必须得到原生确认，并观察到完整传送门表面后才继续穿门。不会制造末地门框或末地返回门，受阻和未确认的操作会返回原因。

例如，前往下界可使用 details.parameters={"destination_dimension":"minecraft:the_nether","prepare_portal":true,"may_alter_terrain":true}；前往末地再设置 allow_rare_consumables=true。未开启 prepare_portal 时保持只使用已有有效传送门的行为。

快速开始

运行要求

项目	要求
Minecraft	1.21.1
Java	21
Fabric	Fabric Loader 0.18.1+，并安装 Fabric API
NeoForge	21.1.233+
安装位置	客户端必装，服务端可选

从源码构建

当前没有稳定版下载，请克隆仓库后自行构建：

git clone https://github.com/LittleSadSheep/MaiCraftMod.git
cd MaiCraftMod
.\gradlew.bat build --no-daemon --no-parallel --max-workers=1

Linux 或 macOS 使用：

./gradlew build --no-daemon --no-parallel --max-workers=1

构建产物位于：

• Fabric：fabric/build/libs/maicraft-fabric-1.21.1-<version>.jar
• NeoForge：neoforge/build/libs/maicraft-neoforge-1.21.1-<version>.jar

将与你的加载器匹配、文件名不含 sources 的 JAR 放入客户端 mods 目录。Fabric 版本还需要 Fabric API。

要启用服务端增强，在服务器 mods 目录中安装对应加载器的 MaiCraft JAR；建议客户端与服务端使用相同版本。单人世界由同一个客户端安装提供集成服务端支持。连接未安装 MaiCraft 的服务器时，普通客户端感知、建造及已有原生操作继续可用。

perceive(view="abilities") 返回 server_assistance：ready 表示已协商，client_only 表示客户端模式。具体操作仍需满足模组、权限、距离、材料和原生状态条件；超时或结果未知不会触发重复操作或擅自切换后端重做。

机器生产目标

在 build_machine 中提供 production 清单和 allow_use: true，可以在同一个任务中完成施工、配置、逐批供料及产出验证。已有机器使用 operate_machine 的 operation: "run_production"。两者都依赖当前 inspect_machine 快照及协商到的服务端能力。

清单描述源、工序、接口、输送路径、配置与观察窗口；精确格式以能力契约及内置蓝图说明为准。未安装服务端时，不带 production 的普通建造保持可用；需要生产证明的目标会明确说明缺少的能力。

成功要求真实加工事件、声明的时间跨度和目标物品的原生交付。库存增加、机器旋转或一次接口调用成功都不能单独证明持续生产；有限窗口成功也不保证今后永不断料。

机器记忆与后台生产

固定设备可以把动力、电力等声明为 external_inputs，优先接入主城已有设施。每种介质默认只设一个入口；确需分网时最多三个，且每个入口都要说明理由。语义设计为入口列出 consumers，布局器生成真实被动连接器和内部支路；显式蓝图则保存入口的相对坐标、方块及连接面。入口本身不会产生应力、电能或物资。

施工与外部接线分开执行：先用不带 production 的 build_machine 建成设备，再重新观察机器，用 modify_machine 的 connect_external_input 指定 input_id 和主城设施的 source_label。最后才按需 run_production。perceive(view="machines") 的 utility_installations 会保存接口和历史施工状态，标签可用 机器名/入口ID 定位；历史记录不证明现在仍已通电。

当前自动接线覆盖 Create 竖轴接口和 FE／Mek 电缆，使用真实材料并核对精确接入面。流体、化学品和物品可声明布局接口，自动外部接线尚需对应的原生资源出入验证，当前会在修改前报告不支持。旋转、电量、连接和实际生产各有独立证据，接通并不表示已达到持续吞吐量。

supply_preference 默认为 external；有意自建能源时使用 onsite 并填写 onsite_reason。生存预检会指出已知创造专用物品；只有真实携带该物品或观察到整合包提供的配方产物证据才放行这项检查，普通缺料仍按材料策略处理，配方证据也不代表材料已经齐全。

MaiCraft 会增量记录附近已加载区块里的机器和容器，不为发现设备额外寻路或加载远处区块。perceive(view="machines") 同时列出现场快照、记住的设备、登记的产线及后台监测任务；focus 可指定设备 ID、产线标签或 产线标签/节点ID。用途线索与原生观察分开显示，自动发现不会把相邻方块猜成已经验证的完整工厂。

机器档案保存在游戏目录 config/maicraft/machines/，按存档或服务器地址与玩家身份区分。已登记生产清单保留节点、接口、坐标关系和历史调试证据。重连后历史记录不会自动变成当前状态或修改权限；修改前仍需重新观察现场。

直播和日常使用可采用“短时调试 → 登记后台观察 → 通过真实界面备料/启动 → 去做其他事情”的流程：

• run_production 用于需要前台供料和验证的有限样本；样本最小跨度与允许的加工间隔分别配置，无需为了调试刻意跑很长一批。
• 在下一批开始前，调用 operate_machine 的 watch_production，提供新鲜 snapshot_id、production 和 allow_use: true。登记时就近核对必要位置，成功只表示监测已登记，随后释放角色。
• 后台只读原生加工、配送和收货状态，通过 Attention 发出 machine_production_completed 或 machine_production_attention；不会自行补料、改配置或反复巡视。cancel_watch 使用返回的 job_id 停止监测，不关闭机器。
• 监测不强制加载区块，未加载时保持未知；当前监测限于同一玩家连接与维度，重连、换维度或重新进入世界后需重新登记。默认最多一小时，具体额度以能力契约为准。

有原生 GUI 的供料容器、已接入的机器配置和固定 AE2 终端会实际打开对应界面；服务端请求绑定该菜单和具体目标，并同步真实库存变化。Create 的世界交互面板等没有容器 GUI 的操作沿用原生世界交互。

连接 MCP 客户端

1. 启动装有 MaiCraft 的 Minecraft 客户端。
2. 在游戏中执行 /maicraft status，确认 MCP 显示为可用。
3. 在支持 Streamable HTTP 的 MCP 客户端中添加以下地址：

http://127.0.0.1:8766/mcp

4. 进入世界后，让 AI 客户端先读取 perceive 提供的能力，再开始任务。

默认服务只监听本机回环地址，但当前默认配置不启用 Bearer Token。不要通过端口转发、反向代理或隧道将 8766 端口暴露给其他设备或公网。

当前限制

• 执行仍由客户端控制真实玩家。服务端增强补充权威状态和受检查的原生操作；未观察到的信息保持未知。
• 自动化会操作本地玩家的真实身体、物品和方块。破坏地形、攻击、丢弃物品或修改机器等行为需要明确授权，但测试世界和备份仍然必不可少。
• 机器编译器支持已建模的组件、工艺模块与接口。未知模组结构或介质会返回具体编译问题；机器摆放、配置、成型和实际产出使用分别可核验的证据。
• AE2、Create、Mekanism 及其他模组的兼容能力仍在扩展；特殊 GUI、过滤器、侧面配置和动态配方可能无法操作。
• 目前真实生产事件覆盖 Create 压机、磨粉机、粉碎轮及受支持的 Mek 配方缓存，目标物品交付使用 Mek 原生物流事件。流体、化学品运输、持续化学消耗和复杂多方块工艺不能据此视为已完整验证；具体不支持项会保留在结果中。
• Fabric 与 NeoForge 构建可以通过自动回归测试，但这不能替代真实客户端、服务器和整合包测试。

开发

仓库采用多加载器结构：

目录	内容
common/	MCP、语义任务、第一人称执行、寻路与共享游戏逻辑
fabric/	Fabric 通用与客户端入口、加载器配置
neoforge/	NeoForge 通用与客户端入口、加载器配置
third_party/baritone/	内嵌寻路代码及其许可证

完整验证：

.\gradlew.bat check --no-daemon --no-parallel --max-workers=1

开发启动至少运行对应加载器的 classes 任务以更新类和资源，例如 :neoforge:classes。仅运行 compileJava 不会更新 Mod 元数据或 Mixin 配置；发布包使用 build 或 assemble。

提交问题时请附上 Minecraft 版本、加载器及版本、相关模组列表、复现步骤，以及日志中与 MaiCraft 有关的片段。欢迎提交聚焦单一问题的 Issue 和 Pull Request。

许可证

MaiCraft 作为整体以 GNU General Public License v3.0 only 发布（SPDX：GPL-3.0-only）。本项目是经过修改的作品，自 2026 年 7 月 30 日起由 LittleSadSheep 修改和维护。

仓库包含以下第三方来源：

• 部分代码派生自 minecraft-numen 的 1.21.1 分支，原许可证为 LGPL-3.0-only。本仓库依照 GNU GPLv3 第 7 条移除该副本的 LGPLv3 额外许可，将修改后的 Numen 派生代码按 GPL-3.0-only 分发；原项目及贡献者仍保留其版权。本仓库不包含 Numen 的美术、音频或品牌资产。
• 内嵌寻路代码来自 Baritone，基于上游提交 5f259b7f 修改。与 Numen 派生代码相同，本仓库依照 GNU GPLv3 第 7 条移除该副本的 LGPLv3 额外许可及非许可性附加条款，并按 GPL-3.0-only 分发；来源和修改说明见 third_party/baritone/。
• 使用 MultiLoader-Template 提供的多加载器项目结构。

鸣谢

• Minecraft 与 Mojang Studios
• minecraft-numen
• Baritone
• MultiLoader-Template