Packwright MCP

Packwright MCP

Packwright MCP 是一个本地优先的 模型上下文协议 MCP 服务，可安全地创建、检查、验证、测试和打包 Minecraft Java Edition 数据包及其配套资源包。它为 MCP 客户端提供结构化工具，而非不受限制的文件系统或 Shell 访问权限。

非 Minecraft 官方产品。未经 Mojang 或 Microsoft 批准，也与其无关。

Packwright 不包含或再分发 Minecraft 代码、资源、服务端/客户端 JAR、库、原生库、生成的原版数据或反编译源代码。npm 包仅包含 Packwright 原创的、采用 MIT 许可证的捕获模组。

状态与兼容性

Packwright 仅支持 Minecraft Java Edition 26.2：数据包格式 107.1，资源包格式 88.0。需要 Node.js 20 或更高版本。默认验证、每次数据包或配套项目构建、原版 GameTest 运行以及官方客户端视觉捕获，都需要 Java 25 和由操作者准备的相应 Minecraft 26.2 缓存。常规创作、CPU 视觉草稿/渲染，以及明确请求的仅提供建议/仅结构验证，则不需要 Java。

该服务使用稳定版 MCP TypeScript SDK v2，目标为 MCP 2026-07-28 规范，并依靠 SDK 协议协商来兼容客户端。

该服务在本地运行，且仅使用 stdio。它不会将数据包安装到正在运行的世界中，不会公开 HTTP 端点，也不支持 Bedrock 行为包。

提供的功能

• 通过原子写入和 SHA-256 前置条件，安全地创建数据包并编辑资源。
• 检查数据包、查找资源，以及搜索缓存的 Minecraft 命令和注册表。
• 默认使用 Minecraft 26.2 的真实命令分发器、注册表和组件编解码器，验证每条 .mcfunction 命令。
• 始终可用的结构验证，以及来自操作员配置的外部 Spyglass 进程的可选诊断信息。
• 完成显式设置后，执行一次性原版数据包加载和 GameTest。
• 确定性构建 ZIP；如果结构验证或原版命令验证存在错误，则构建失败。
• 配对的数据包/资源包项目，提供准确的 Minecraft native、simulated、replacement 和 requires_mod 配置文件，以及单独的 compilerSupport 实现状态。
• 语义化自定义物品模型 DSL、minecraft:item_model 绑定、安全的 PNG 导入、针对特定配置文件的确定性 CPU 预览、不可变修复修订版，以及受保护的多文件提交。
• 八种针对模型的视觉审查配置：held_item、block、placeable、armor、head_wearable、projectile、gui_item 和 entity_model；每种配置都包含确定性场景、由 Packwright 编写的参考几何体、建议性测量值和不可变渲染报告。
• 显式准备后，通过实际 Minecraft 26.2 客户端渲染器进行协议 v3 帧缓冲区捕获，支持物品以及严格的方块、头戴物、实体和可放置物表示。对于已记录的 OpenGL 环境，必需的游戏/世界帧具有权威性；注入的比例参考、调试碰撞箱和匹配的空主体测量控件仅用于补充 QA。每个产物都包含精确的实时客户端夹具回读和规范哈希。官方客户端在一次性确定性工作室中运行，且仅加载 Packwright 的捕获模组；CPU 渲染器仍是快速、确定性的第一道关卡。
• 基于稳定的数据包/资源包快照验证准确的未提交提案，然后根据准确的已提交数据包快照，以事务方式生成确定性 ZIP。
• 用于审查、搭建脚手架和编写 GameTest 的只读 MCP 资源和工作流提示词。

视觉编译器有意支持的范围比 Minecraft 能力矩阵更窄：compilerSupport 对 custom_item 为 full，对 conditional_item_state 为 limited，对所有其他目标均为 unsupported。自动编译器仍只会生成自定义物品。协议 v3 捕获独立接受用于 block、head_wearable、entity_model 或 placeable 审查的严格声明式哈希绑定表示；这会暂存现有原版身份、替换项或显示模拟，但不表示 Packwright 编译了新的原生方块/实体身份。客户端捕获的总体支持情况为：gui_item 是 full；单手 held_item、block、head_wearable、entity_model 和 placeable 是 limited；armor 和 projectile 是 unsupported。不支持的策略会在启动 Minecraft 前被拒绝。请参阅配对视觉编译器指南和 MCP 工具、资源和提示词。

安装并连接

选择一个现有目录，用于存放 Packwright 可以访问的数据包项目。该目录必须是绝对路径。

通用 MCP 客户端配置：

{
  "mcpServers": {
    "packwright": {
      "command": "npx",
      "args": [
        "-y",
        "@rithwikbabu/[email protected]",
        "serve",
        "--workspace",
        "/absolute/path/to/datapacks"
      ]
    }
  }
}

也可以通过环境变量传入工作区：

{
  "mcpServers": {
    "packwright": {
      "command": "npx",
      "args": ["-y", "@rithwikbabu/[email protected]"],
      "env": {
        "PACKWRIGHT_WORKSPACE": "/absolute/path/to/datapacks"
      }
    }
  }
}

建议使用精确的软件包版本，以确保自动化行为可预测。服务仅向标准输出写入协议消息，并将日志发送到标准错误。

CLI

未提供子命令时，已安装的 packwright-mcp 二进制文件默认运行 serve：

packwright-mcp serve --workspace /absolute/path/to/datapacks
packwright-mcp doctor --workspace /absolute/path/to/datapacks
packwright-mcp setup-version 26.2 --accept-minecraft-eula --workspace /absolute/path/to/datapacks
packwright-mcp setup-version 26.2 --accept-minecraft-eula --client-assets --workspace /absolute/path/to/datapacks
packwright-mcp setup-version 26.2 --accept-minecraft-eula --client-capture --workspace /absolute/path/to/datapacks
packwright-mcp capture <project-id> --run <sha256> --proposal-sha256 <sha256> --confirm --workspace /absolute/path/to/datapacks
packwright-mcp capture <project-id> --run <sha256> --proposal-sha256 <sha256> --confirm --include-scale-reference-views --workspace /absolute/path/to/datapacks
packwright-mcp validate <pack> --workspace /absolute/path/to/datapacks
packwright-mcp test <pack> --workspace /absolute/path/to/datapacks
packwright-mcp build <pack> --workspace /absolute/path/to/datapacks

对 doctor、setup-version、capture、validate、test 或 build 使用 --json，以获取机器可读的输出。运行 packwright-mcp <command> --help 查看特定命令的选项。有关所有标志、优先级、环境变量和退出行为，请参阅 CLI 参考 和配置。

原版设置与测试

setup-version 是一项明确的操作员操作。它会记录对 Minecraft EULA 的接受情况，从 Mojang 获取官方的 26.2 服务端 jar，验证 Mojang 版本清单中声明的 SHA-1，并准备本地验证数据。MCP 服务绝不会下载该 jar，也不会代表模型接受条款。

packwright-mcp setup-version 26.2 \
  --accept-minecraft-eula \
  --workspace /absolute/path/to/datapacks

仅在需要准备官方客户端 jar 和资源索引就绪元数据供具备资源感知能力的工具使用时，才添加 --client-assets。添加 --client-capture 可准备完整的平台专用启动器运行时、索引中的所有资源对象、必需的库和原生文件，以及固定版本的 Fabric Loader 0.19.3；该选项会包含客户端资源步骤。每个下载的工件都经过允许列表检查，并根据 Mojang 或 Packwright 固定的摘要进行校验。Minecraft 客户端工件仅保留在本地缓存中，绝不会复制到工作区、npm 包或发布工件中。语义编译仍要求自定义外部纹理／模型位于配套资源包中的正常路径；它不会从客户端缓存复制这些文件。 visual_capture 是一项独立且需要明确确认的 MCP 操作。它要求 Java 25、已完成 --client-capture 设置，以及能够创建真实 OpenGL 窗口的交互式 macOS 图形会话。Packwright 会为确切的数据包／资源包提案创建与哈希绑定的暂存归档，并在离线开发者模式下启动官方客户端，同时禁用多人游戏和聊天。资源包归档会暂存为 resourcepacks/packwright-proposal.zip，并在截图期间保持启用。数据包归档仅作为不可加载的来源凭证，暂存于 packwright/provenance/datapack-proposal.zip；它绝不会安装到一次性世界中、启用或选中。世界的可加载 datapacks/ 目录必须保持为空，集成服务器必须仅选中 vanilla，且其可用数据包 ID 必须与 Packwright 固定的 Minecraft 26.2 内置允许列表一致；任何被选中的 file/ 数据包、意外出现的可用数据包或文件系统条目都会中止截图。客户端只运行 Packwright 随附的截图模组，在全新的一次性虚空风格工作室中，通过 Minecraft 的截图 API 进行截图，之后删除一次性游戏目录。报告会证明两种启用模式、归档哈希和选中的数据包 ID，并绑定表示形式、提案和完整数据包快照、客户端／模组、操作系统／GPU／驱动程序／OpenGL 后端、分辨率、GUI 缩放、FOV、渲染设置、摄像机、生物群系、时间、天气、观测到的主体光照以及确定性光源位置、刻画／动画状态、稳定等待时间、源帧缓冲区哈希，以及每个视图对应的精确实时客户端观测夹具读回数据／哈希。协议 v3 还要求使用与哈希绑定的普通方块地面标尺：黑色和白色混凝土占据两个固定的相邻方块，截图模组通过集成服务器放置这些方块，每个完成的视图都会记录实时客户端读回数据及规范 SHA-256。由于标尺是普通工作室几何体，它可提供权威的世界尺度参照；单独注入的人体模型仅作补充。equippable_head 方案始终包含权威的盔甲架正面和侧面场景。工作室会记录 Minecraft 的 custom 图形预设，因为其中固定的云、粒子、阴影、渲染距离和模拟距离覆盖项有意不同于未修改的预设。协议 v3 仅接受静态展示节点，不能声明可重置的方块图集动画相位，并要求模拟实体骨架提供独立且精确的 idle、walk 和 attack 状态。

默认情况下，每个第一人称游戏场景都是 first_person_vanilla：采用精确的原版构图，不注入 Packwright 手臂。includeScaleReferenceViews 会添加成对的 first_person_scale_reference 帧；includeDebugHitboxViews 会为受支持的实体／可放置物添加 debug_hitbox_reference 帧。这些可选项、裸头对比、与之匹配的空主体 measurement_control 帧，以及任何同帧注入的 comparison_reference 或非普通 world_scale_reference 辅助视图，都会标记为 augmented_qa_reference，仅显示在单独的补充 QA 表中，绝不进入数据包输出，也不能满足权威性要求。实体配置中的 entity_player_scale 人体模型明确属于补充性的 world_scale_reference，绝不是权威的游戏内／世界证据。普通世界几何体——以及在盔甲架确实是所声明头饰主体时的盔甲架——可以作为精确的权威 Minecraft 帧保留。未跳过的客户端测量均基于已绑定的帧缓冲区像素得出；不可用的几何检查会明确标记为 skipped 并注明原因，而不会照搬 CPU 建议测量值。即使主场景为必需场景，凡是使用补充控制项的测量仍仅具参考性。Packwright 绝不接受账户凭据、用户存档、任意命令／函数、可执行内容或未经批准的路径，也绝不会回退到 CPU 输出。 对于获得完整或有限客户端支持的每个配置，生产环境中的 visual_validate 默认要求提供当前官方客户端的证据。visual_commit 要求同时提供准确的已验证捕获报告 SHA-256 和 proposalBindingStatus: "implemented"。目前，协议 v3 的方块、头戴物品、实体和可放置物品结果均为 capture_only：它们提供准确的表示形式 QA，但在提案实现所捕获的表示形式之前，不能授权当前的物品编译器提案。对于双手持有的物品或不受支持的表示形式，系统会直接拒绝，而不会授予不完整的客户端授权。仅在明确用于参考性或快速验证时，才传入 requireClientCapture: false；这不会让受支持配置的提案变为可提交状态。客户端实现确实为 unsupported 的配置仍可使用仅 CPU 的路径。

必需的标准视图，包括 first_person_vanilla、已装备头戴物品的玩家／盔甲架主体，以及普通的摄影棚／世界画面，均具有 authoritative_environment_capture 权限：它们证明固定版本的客户端针对准确记录的表示形式和环境渲染了什么。authorityScope: "required_views_only" 明确排除所有裸头或注入的比例／对比辅助视图、调试碰撞箱、匹配测量控制项和 world_scale_reference 辅助项，包括 entity_player_scale 人偶；任何补充帧或跳过的补充测量都不能替代缺失或失败的必需视图。每项像素测量都会绑定一个明确的 requiredForReadiness 值。关键测量失败或被跳过都会使捕获就绪状态变为 false，并阻止提交；关键警告和尽力而为的跳过项仍会显示，不会被粉饰成通过的测量结果。补充控制项／调试测量绝不会是关键项。硬件和驱动程序可能会合理地改变像素，因此不保证不同 GPU 或操作系统上的截图逐字节一致。捕获结果为 passed 表示必需证据已完成并通过验证，且没有失败或不可用的关键测量；这不代表其外观已获审美认可。

完成设置后，validate 默认使用固定版本的原版运行时，针对 Minecraft 26.2 的真实命令分派器、已加载的数据包注册表和组件编解码器解析每条逻辑 .mcfunction 命令。这会在打包前捕获无效的命令、选择器、物品／组件、粒子、属性、实体和文本组件语法。validate --no-vanilla 是明确的仅结构验证绕过选项；构建流程绝不提供此绕过选项。

命令验证和权威测试都在新建的一次性状态中运行 Java 25。命令验证会用惰性占位符替换数据包的函数，并验证未引用的命令探测项，因此不会执行用户函数。GameTests 会获得新分配的游戏环境；绝不接受用户世界路径。参见验证与原版测试。

函数类型的 GameTests 会解析 Minecraft 内部的 test_function 注册表；数据包的 .mcfunction 不会注册 Test Function。仅在覆盖数据包加载／运行器冒烟测试时使用 minecraft:always_pass，或使用现有的基于方块的测试结构来进行以行为为重点的测试。

Spyglass 不会作为运行时依赖项安装，这是有意为之。适配器固定兼容 Spyglass 0.4.65，并会在使用前验证所配置可执行文件的 --version 输出。独立安装并审查过安全构建版本的操作者，可通过 PACKWRIGHT_SPYGLASS_COMMAND 选择启用；Packwright 绝不会自动下载或启用它。

安全模型

Packwright 会将每个请求路径解析到配置的工作区内，拒绝路径遍历和符号链接逃逸，限制扫描范围和负载大小，并且绝不会递归删除目录。只有在明确要求且提供当前 SHA-256 的情况下，才能替换或删除现有文件。原始创作仅限受支持的数据包文本格式；可以检查并打包二进制 NBT 和 pack.png，但不能创作。视觉纹理使用专用的有界 PNG 解码器；通过验证的跨数据包提案会通过带日志的事务提交，并在操作前检查所有目标文件的哈希值。

在授予服务访问重要项目的权限前，请阅读安全模型。仅用于审查的会话可考虑使用源代码管理和 PACKWRIGHT_READ_ONLY=true。

有关常见的启动、缓存、Java、验证和构建故障，请参阅故障排除。维护者和贡献者可在架构中了解组件边界。

开发

npm ci
npm run lint
npm run format:check
npm run typecheck
npm test
npm run build
npm pack --dry-run

Minecraft 集成测试有意与其他测试分开，因为它们会下载 Mojang 构件，并且需要 Java 25 和明确接受 EULA。官方客户端捕获发布门禁还要求使用受保护的交互式 macOS 机器；普通 CI 不会下载或启动客户端。贡献者设置和测试要求见 CONTRIBUTING.md。

许可证和商标

Packwright MCP 根据 MIT 许可证提供。外部软件和服务的条款汇总于 THIRD_PARTY_NOTICES.md。

Minecraft 是 Microsoft Corporation 的商标。本项目遵循 Minecraft 使用指南，且不使用 Mojang 或 Microsoft 的任何美术素材。