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 世界流体加工复用机器建造与使用入口，按需读取真实菜单报价或原生配方，再完成有限次数的操作与成品回收。
• 可选服务端生产增强：读取真实库存、配方和连接，配置受支持的过滤器、接口与 AE2 样板，按实际加工事件分批投料，再验证真实交付与持续产出窗口。
• Dev 蓝图预览：在世界中显示半透明待建结构和差异轮廓，支持逐层查看；确认前归还玩家操控，确认后执行冻结的方案。
• 只读房屋设计：maicraft:design_build 直接显示蓝图，不移动或施工；普通建造在 Dev 确认之后才开始供料。
• 按需知识资源：自动发现安装模组的 Ponder 教程，按组件和场景读取原始旁白、操作提示及方块状态；支持 MCP Resources 和 perceive(view="knowledge")。
• 任务观察与控制：通过 Attention 等待权威状态、当前决策和结果摘要，完整证据按需找回；支持暂停、恢复和取消。
• 游戏聊天与命令：打开原版聊天框逐字输入，再自动提交消息或 / 命令；支持后台运行和人工接管。

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

MCP 入口与语义能力

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

工具	用途
perceive	以 Attention 为首选等待任务事件、决策和结果；也读取游戏状态、能力契约与世界证据
plan	编译目标而不立即执行；也可凭 plan_id 找回已保存的设计
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 使用），模型唤醒行为由宿主决定。

日常回执保留当前目标、状态、必要的失败事实和下一步入口，原始蓝图、旧尝试和长报告按需读取。宿主可以缓存已读信息；上下文压缩后，用保留的编号找回所需证据，无需重新执行任务。

需要的信息	调用方式
当前任务、待答问题与结果摘要	task(action="get", task_id=...)
原始目标或某次失败证据	task(action="get", task_id=..., path="/goal") 或 path="/attempts"
已保存的计划输入	plan(plan_id=..., path="/goal/parameters")，不重新编译或执行
更多任务或能力目录	同一查询复制 next_offset 到 offset；默认每页 5 项
大份报告、长文档的指定部分	perceive(resource_uri=返回的 resource_uri)，继续读取 next_uri

detail_path 指向保留的完整任务或计划，可能与摘要的字段结构不同。path="" 列出根字段；对象和数组分页返回 items，长文本返回连续的 value。出现 omitted=true 表示该值需要展开，summary 只包含部分事实，不能把未显示的内容当成空数据。

普通业务载荷超过约 8,000 字符时提供冻结回执引用；这是 JSON 载荷的投影预算，不是包含转义的 HTTP 字符数硬上限。maicraft://receipts/... 只读取原快照，不重新观察世界、不延长游戏内 snapshot_id 的有效期。临时回执最多保留 32 份，闲置 30 分钟或服务重启后失效；压缩存储按 64 MiB 预算淘汰旧份，单份超大结果保留到后续淘汰。引用失效时查询仍保留的任务，或重新做对应的只读观察，不能为找回输出重复 execute。

标准 resources/read 读取原始知识或 Schema URI 时保留完整正文和 MIME，供 Harness 程序校验与归档；模型通过 perceive(resource_uri=...) 按需查看摘要或页面。冻结回执 URI 自身仍使用分页格式，调用方须先取得需要的完整证据再确认事件游标或交付设计。

协议消费者升级后应刷新工具列表：普通工具的 JSON 只放在 content[0].text，不再重复提供同一份 structuredContent；短知识正文保留原文，结构化部分仅附资源元数据。Attention 使用 schema_version=3，无任务编号时返回任务索引，指定任务后返回当前状态和必要证据摘要。

四个入口不等于只有四种功能。运行时提供多项 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") 默认返回能力用途的小目录；可先用 query 搜索，再用 focus="maicraft:能力名" 读取选定能力的参数和限制。AI 客户端据此提交语义目标，具体路径与原生操作由 Mod 执行。

例如将以下参数交给 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 中的后续消息。提交结果不确定时不会自动重发。

附魔和世界流体加工通过 operate_machine 的 run_production 共用入口，完整工序契约从 按需加工知识 和 inspect_machine 读取，示例见下方“机器生产目标”。旧 maicraft:enchant 仍兼容原请求与任务恢复，但不再列入默认能力清单；需要旧契约时可显式读取 perceive(view="abilities", focus="maicraft:enchant")。

移动目标还未定位时，可以使用 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", sections=["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 表示信息未知，不代表没有楼层。

situation 与 surroundings 支持用 sections 点名所需段。默认周边观察返回附近实体、告示牌、安全信息与设备，不等待大范围地形，并在 additional_sections 提示可选的 terrain_overview。例如 sections=["elevators"] 只取电梯楼层；点名地形才等待采样。本次未产出的指定段在 sections_unavailable 中列出，大段内容仍可通过冻结回执展开。

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 的服务器时，普通客户端感知、建造及已有原生操作继续可用。

选定能力的契约附带 server_assistance 概要：ready 表示已协商，client_only 表示客户端模式。完整后端诊断使用 perceive(view="abilities", focus="maicraft:server_assistance")。具体操作仍需满足模组、权限、距离、材料和原生状态条件；超时或结果未知不会触发重复操作或擅自切换后端重做。

建筑规模与资源配置

客户端首次启动会生成 UTF-8 文件 config/maicraft-building.properties，包含每个配置项的中文说明。编辑后重启客户端生效；已有文件不会被默认值覆盖。数字无效时仅该项回退到默认值，并在日志及能力预算中说明。

配置项	默认值	含义
maxTargets	262144	一份建筑的最终目标数，包含明确的空气目标
maxObjects	8192	作者对象、组件及展开节点预算
maxRadius	512	相对锚点的坐标半径，单位为格
preview.maxCells	262144	预览方块和部件总数
preview.distance	256	预览绘制距离，单位为格
preview.frameMillis	2.0	每帧准备和刷新预览的工作预算，毫秒
maxProjectBytes	134217728	冻结施工单文件上限，128 MiB

配置还包含模型文件、蓝图导入、NBT 解压、采样工作量、临时支撑、MCP 请求及任务记录的容量。完整说明见内置蓝图文档。perceive(view="abilities", focus="maicraft:build") 的 planning_budget 返回本实例实际生效的值；建筑预算与机器自主规划预算分别管理。

默认容量可容纳一个 120×80×18 格、包含全部内部空气的大厅。完整目标仍会展开到内存；提高上限不会自动加载远处区块，也不代表已验证对应规模的帧率或施工速度。每帧预算在工作单元之间检查，不能中断一次原生模型或显卡操作。调低限额使旧任务无法恢复时，旧文件会保留，恢复前拒绝新的持久化执行；提高限额并重启后再恢复原任务。

清障白名单

客户端首次启动生成 config/maicraft-clearance.json，寻路挖路与建造清场共用。它是方块 ID／#方块标签 的 JSON 数组，修改后重启生效；空数组或无效配置禁止自动清障。默认明确列出原版自然地形、矿石、原木、树叶与植被，不依赖服务端安装 MaiCraft；模组地形可自行加入注册 ID 或同步的标签，例如 "#c:ores"。按方块类型判断，因此玩家放置的同种泥土、石头、原木也会命中名单。

寻路遇到名单外方块会绕行；没有可行路线就失败。施工遇到名单外障碍会停止，并通过 clearance_report 向 LLM 返回维度、方块 ID、坐标、冲突数量和最近的水平选址偏移。偏移建议在已加载地形中核对整份蓝图，搜索半径 16 格；未知区块或预算不足会注明。建议仅证明目标格的清障条件，仍须重新检查地基、通路和新场地；不会自动搬迁已有工程。替换许可、保护区域、流体与不可破坏限制继续生效，自有临时支撑仍按原清理流程回收。

已建机器的现状与差异

build_machine 完成后会自动保存机器编号、名称、原地范围和设计蓝图，并在完成结果中附上一轮 blueprint_diff。该差异只报告观察结果，不触发重建或把完成的施工改判为失败；施工过程中不持续扫描。perceive(view="machines") 的 recorded_machines 可找回这些记录。

inspect_machine 支持 mode: "full" | "diff"，默认 full。例如把下面的目标交给 plan / execute，并替换实际的机器编号：

{
  "ability": "maicraft:inspect_machine",
  "outcome": "查看已建机器的实际布局",
  "parameters": {"machine_id": "<完工结果中的 machine_id>", "mode": "full"}
}

full 返回 as_built_blueprint，其中方块 ID、状态和相对位置全部从当前地图读取，包含范围内后来更换或添加的方块；不会复述存档中的旧设计。默认使用完工时记录的整机范围，也可用 radius 指定观察范围。它是地图方块状态的观察格式；库存、接口配置与生产证据仍在各自的原生观察中。

diff 才与保存的设计比较，区分缺块、错块、状态不符、应为空的格子被占用，以及未加载的未知格子。没有设计记录的旧机器仍可读取 full，但不能凭空生成设计差异。两种模式均支持 offset / limit；有 has_more 时按 next_offset 继续。分页是分别读取的现场观察，未加载区域不会被当成空气或由旧蓝图补齐。

机器生产目标

沿用“生成结构 → 建造机器 → 使用机器”：design_machine 设计结构，build_machine 施工，已有场地用 operate_machine 的 operation: "run_production" 执行工序。也可在 build_machine 中提供 production 与 allow_use: true，先完成施工，再运行同一工序。机器蓝图里的源流体最终通过原生桶操作装配，并核验源格与桶的变化。

production 支持两个版本。v1 保留源、工序、接口、输送路径、配置与观察窗口，用于机器网络和持续产出验收。v2 用简短的 {schema_version:2, process, offset?, parameters} 指定有限原生过程；process 是机制，不按每种产物新增能力，offset 相对观察或建造锚点。

先用 inspect_machine 观察实际目标，取得新鲜 snapshot_id 和同一目标标签；native_processes 按现场匹配返回机制契约及只读配方观察。完整格式按需读取 maicraft://knowledge/processes，也可使用 perceive(view="knowledge", resource_uri="maicraft://knowledge/processes")。例如把下列参数交给 execute，用已观察的附魔台为一把背包铁镐附魔；尖括号内容须替换为实际观察值：

{
  "goal": {
    "ability": "maicraft:operate_machine",
    "outcome": "为一把铁镐附魔并取回",
    "target": {"kind": "landmark", "label": "<观察时使用的场地标签>"},
    "parameters": {
      "operation": "run_production",
      "snapshot_id": "<inspect_machine 返回的 snapshot_id>",
      "allow_use": true,
      "material_policy": "inventory_only",
      "production": {
        "schema_version": 2,
        "process": "minecraft:enchanting",
        "parameters": {"item_id": "minecraft:iron_pickaxe", "offer_tier": 1, "max_levels_spent": 1, "max_lapis": 1}
      }
    }
  },
  "request_key": "enchant-pickaxe-001"
}

AE2 世界流体加工沿用同一结构，换成现场流体位置的标签与快照，并使用 process: "ae2:transform"、parameters: {"recipe_id":"<现场返回的配方 ID>","batches":1}。配方、投入数量和环境条件来自原生观察；附近已有成品不能当成本次产物。

加工使用可完整观察的有界接收区，保留原模组的投掷、漂移和延迟反应。若实际早投材料也能充当触发物，无法保证逐次投料回执，任务会在消费前报告此限制。已确认产物由通用拾取流程按身份收取；拾取或同步中断时，pending_output 保留已生成物品的证据。

v2 加工只消费现有主背包原料；直接运行的材料策略仅接受 inventory_only。施工材料仍按 build_machine 的既有材料策略补给，加工缺料时组合已有 acquire_items 流程再运行，不会隐式自动补齐。

附魔过程会打开原生 GUI，读取真实报价，只提交指定档位一次，核验费用与附魔，取回成品并关闭界面。等级门槛与实际扣除等级不同，隐藏随机词条不作保证；报价、预算或空间不满足时停止。结果中的 item_return_verified、gui_closed 分别说明取回和关闭是否已核验。

同一请求的网络重试复用 request_key。过程支持暂停、取消和手动接管；开始持久化消费预约后禁止普通自动重试，刷新快照也不会重置同一消费身份。出现 outcome_uncertain 时先检查现场、物品与经验，再决定后续恢复目标。

v1 网络配方、配置、供料与生产证明仍依赖协商到的服务端能力；精确格式见能力契约、加工知识与蓝图说明。未安装服务端时，普通建造与原版附魔等客户端原生过程仍可用；需要服务端证据的目标会明确说明缺少的能力。

v1 成功要求真实加工事件、声明的时间跨度和目标物品的原生交付。世界流体加工的 native_recipe_verified 表示原生配方事件已验证；仅观察到产物拾取与背包变化时，evidence_scope="client_observed_output_and_inventory"，不宣称原生配方事件已确认。这些有限过程也不证明持续产线；库存增加、机器旋转或一次接口调用成功都不能单独证明持续生产。

机器记忆与后台生产

固定设备可以把动力、电力等声明为 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 可执行 v1 网络样本或 v2 有限过程；v1 的样本最小跨度与允许的加工间隔分别配置，无需为了调试刻意跑很长一批。
• 在下一批开始前，调用 operate_machine 的 watch_production，提供新鲜 snapshot_id、v1 production 和 allow_use: true。登记时就近核对必要位置，成功只表示监测已登记，随后释放角色；v2 过程不支持后台监测。
• 后台只读原生加工、配送和收货状态，通过 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