# Packwright MCP **Category:** 🎮 Gaming **Repository:** https://github.com/rithwikbabu/packwright-mcp **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/packwright-mcp ## Description Local-first MCP server for creating, validating, testing, and packaging Minecraft Java datapacks. ## Claude Desktop Quick Installation Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "packwright-mcp": { "command": "npx", "args": ["-y","packwright-mcp"] } } ``` ## Documentation & README # Packwright MCP [![CI](https://github.com/rithwikbabu/packwright-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/rithwikbabu/packwright-mcp/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/%40rithwikbabu%2Fpackwright-mcp)](https://www.npmjs.com/package/@rithwikbabu/packwright-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) Packwright MCP is a local-first [Model Context Protocol](https://modelcontextprotocol.io/) server for safely creating, inspecting, validating, testing, and packaging Minecraft Java Edition datapacks and paired resource packs. It gives an MCP client structured tools instead of unrestricted filesystem or shell access. > **NOT AN OFFICIAL MINECRAFT PRODUCT. NOT APPROVED BY OR ASSOCIATED WITH MOJANG OR MICROSOFT.** Packwright does not contain or redistribute Minecraft code, assets, server/client jars, libraries, natives, generated vanilla data, or decompiled sources. The npm package includes only Packwright's original MIT-licensed capture mod. ## Status and compatibility Packwright supports [Minecraft Java Edition **26.2**](https://www.minecraft.net/en-us/article/minecraft-java-edition-26-2) only: datapack format **107.1** and resource-pack format **88.0**. Node.js 20 or newer is required. Default validation, every datapack or paired-project build, vanilla GameTest runs, and official-client visual capture require Java 25 plus the corresponding operator-prepared Minecraft 26.2 cache. Normal authoring, CPU visual drafting/rendering, and an explicitly requested advisory/structural-only validation do not require Java. The server uses the stable MCP TypeScript SDK v2, targets the MCP `2026-07-28` specification, and relies on SDK protocol negotiation for compatible clients. The server is local and stdio-only. It does not install packs into a live world, expose an HTTP endpoint, or support Bedrock behavior packs. ## What it provides - Guarded datapack creation and resource editing with atomic writes and SHA-256 preconditions. - Datapack inspection, resource lookup, and cached Minecraft command/registry search. - Default vanilla-backed validation of every `.mcfunction` command with Minecraft 26.2's real dispatcher, registries, and component codecs. - Always-available structural validation, plus optional diagnostics from an operator-configured external Spyglass process. - Disposable vanilla pack-loading and GameTest execution after explicit setup. - Deterministic ZIP builds that fail when structural or vanilla command validation has errors. - Paired datapack/resource-pack projects with truthful Minecraft `native`, `simulated`, `replacement`, and `requires_mod` profiles plus a separate `compilerSupport` implementation status. - A semantic custom-item model DSL, `minecraft:item_model` bindings, safe PNG import, profile-specific deterministic CPU previews, immutable repair revisions, and guarded multi-file commit. - Eight model-specific visual review profiles: `held_item`, `block`, `placeable`, `armor`, `head_wearable`, `projectile`, `gui_item`, and `entity_model`, each with deterministic scenes, Packwright-authored reference geometry, advisory measurements, and an immutable render report. - Explicitly prepared, protocol-v3 framebuffer capture through the actual Minecraft 26.2 client renderer for items plus strict block, headwear, entity, and placeable representations. Required gameplay/world frames are authoritative for the recorded OpenGL environment; injected scale references, debug hitboxes, and matched empty-subject measurement controls are supplemental QA only. Every artifact carries an exact live-client fixture readback and canonical hash. The official client runs in a disposable deterministic studio with only Packwright's capture mod; the CPU renderer remains the fast deterministic first gate. - Validation of the exact uncommitted proposal over stable datapack/resource-pack snapshots, followed by transactional deterministic ZIPs from the exact committed pack snapshots. - Read-only MCP resources and workflow prompts for review, scaffolding, and GameTest authoring. The visual compiler remains intentionally narrower than the Minecraft capability matrix: `compilerSupport` is `full` for `custom_item`, `limited` for `conditional_item_state`, and `unsupported` for every other target. The automatic compiler still emits custom items only. Protocol-v3 capture independently accepts a strict, declarative, hash-bound representation for `block`, `head_wearable`, `entity_model`, or `placeable` review; this stages existing vanilla identities, replacements, or display simulations but does not claim Packwright compiled a new native block/entity identity. Aggregate client-capture support is `full` for `gui_item`, `limited` for one-handed `held_item`, `block`, `head_wearable`, `entity_model`, and `placeable`, and `unsupported` for `armor` and `projectile`. Unsupported strategies are rejected before Minecraft launches. See the [paired visual compiler guide](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/visual-compiler.md) and [MCP tools, resources, and prompts](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/mcp-reference.md). ## Install and connect Choose an existing directory that will contain the datapack projects Packwright may access. It must be an absolute path. Generic MCP client configuration: ```json { "mcpServers": { "packwright": { "command": "npx", "args": [ "-y", "@rithwikbabu/packwright-mcp@0.5.0", "serve", "--workspace", "/absolute/path/to/datapacks" ] } } } ``` The workspace can instead be passed through the environment: ```json { "mcpServers": { "packwright": { "command": "npx", "args": ["-y", "@rithwikbabu/packwright-mcp@0.5.0"], "env": { "PACKWRIGHT_WORKSPACE": "/absolute/path/to/datapacks" } } } } ``` Using an exact package version is recommended for predictable automation. The server writes protocol messages only to stdout and sends logs to stderr. ## CLI The installed `packwright-mcp` binary defaults to `serve` when no subcommand is supplied: ```text 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 --run --proposal-sha256 --confirm --workspace /absolute/path/to/datapacks packwright-mcp capture --run --proposal-sha256 --confirm --include-scale-reference-views --workspace /absolute/path/to/datapacks packwright-mcp validate --workspace /absolute/path/to/datapacks packwright-mcp test --workspace /absolute/path/to/datapacks packwright-mcp build --workspace /absolute/path/to/datapacks ``` Use `--json` with `doctor`, `setup-version`, `capture`, `validate`, `test`, or `build` for machine-readable output. Run `packwright-mcp --help` for command-specific options. See the [CLI reference](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/cli-reference.md) and [Configuration](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/configuration.md) for all flags, precedence, environment variables, and exit behavior. ## Vanilla setup and testing `setup-version` is an explicit operator action. It records acceptance of the Minecraft EULA, obtains the official 26.2 server jar from Mojang, verifies the SHA-1 declared by Mojang's version manifest, and prepares local validation data. The MCP server never downloads the jar or accepts terms on a model's behalf. ```sh packwright-mcp setup-version 26.2 \ --accept-minecraft-eula \ --workspace /absolute/path/to/datapacks ``` Add `--client-assets` only to prepare the official client jar and asset-index readiness metadata used by asset-aware tooling. Add `--client-capture` to prepare the complete platform-specific launcher runtime, every indexed asset object, required libraries and natives, and pinned Fabric Loader `0.19.3`; it implies the client-assets step. Every downloaded artifact is allow-listed and checked against the Mojang or Packwright-pinned digest. Minecraft client artifacts remain only in the local cache and are never copied into the workspace, npm package, or release artifacts. Semantic compilation still requires custom external textures/models to exist at their normal paths in the paired resource pack; it does not copy them from the client cache. `visual_capture` is a separate, explicitly confirmed MCP operation. It requires Java 25, the completed `--client-capture` setup, and an interactive macOS graphical session capable of creating a real OpenGL window. Packwright creates hash-bound staging archives for the exact datapack/resource-pack proposal and launches the official client in offline developer mode with multiplayer and chat disabled. The resource-pack archive is staged as `resourcepacks/packwright-proposal.zip` and remains active during capture. The datapack archive is staged only as non-loadable provenance at `packwright/provenance/datapack-proposal.zip`; it is never installed in the disposable world, enabled, or selected. The world's loadable `datapacks/` directory must remain empty, the integrated server must select exactly `vanilla`, and its available pack IDs must match Packwright's fixed Minecraft 26.2 built-in allow-list; any selected `file/` pack, unexpected available pack, or filesystem entry aborts capture. The client runs only Packwright's bundled capture mod in a fresh disposable void-style studio, captures through Minecraft's screenshot API, and deletes the disposable game directory afterward. The report attests both activation modes, archive hashes, and selected pack IDs in addition to binding the representation, proposal and full pack snapshots, client/mod, OS/GPU/driver/OpenGL backend, resolution, GUI scale, FOV, render settings, camera, biome, time, weather, observed subject light plus deterministic light-source placement, tick/animation state, settling interval, source framebuffer hashes, and an exact live-client observed-fixture readback/hash for every view. Protocol v3 also requires a hash-bound ordinary-block floor ruler: black and white concrete occupy two fixed adjacent blocks, the capture mod places them through the integrated server, and every completed view records a live client readback plus canonical SHA-256. Because the ruler is ordinary studio geometry, it may provide authoritative world-scale context; the separate injected mannequin remains supplemental. An `equippable_head` plan always includes authoritative armor-stand front and side scenes. The studio records Minecraft's `custom` graphics preset because its fixed cloud, particle, shadow, render-distance, and simulation-distance overrides intentionally differ from an unmodified preset. Protocol v3 accepts static display nodes only, cannot claim a resettable block-atlas animation phase, and requires simulated entity rigs to provide separate exact `idle`, `walk`, and `attack` states. By default, every first-person gameplay scene is `first_person_vanilla`: exact stock composition with no Packwright-injected arm. `includeScaleReferenceViews` adds paired `first_person_scale_reference` frames; `includeDebugHitboxViews` adds supported entity/placeable `debug_hitbox_reference` frames. Those opt-ins, bare-head comparisons, matched empty-subject `measurement_control` frames, and any same-frame injected `comparison_reference` or non-ordinary `world_scale_reference` aid carry `augmented_qa_reference`, appear only in the separate supplemental QA sheet, never enter pack output, and never satisfy authority. The entity profile's `entity_player_scale` mannequin is specifically a supplemental `world_scale_reference`, never authoritative gameplay/world evidence. Ordinary world geometry—and an armor stand when it is the actual declared headwear subject—can remain exact authoritative Minecraft frames. Non-skipped client measurements are derived from the bound framebuffer pixels; unavailable geometric checks are explicitly `skipped` with a reason rather than copied from CPU advisory measurements. A measurement that consumes a supplemental control remains advisory, even when its primary scene is required. Packwright never accepts account credentials, a user save, arbitrary commands/functions, executable content, or unapproved paths, and never falls back to CPU output. For every profile with full or limited client support, production `visual_validate` requires current official-client evidence by default. `visual_commit` requires both the exact verified capture-report SHA-256 and `proposalBindingStatus: "implemented"`. Protocol-v3 block, headwear, entity, and placeable results are currently `capture_only`: they provide exact representation QA but cannot authorize the current item-compiler proposal until that proposal implements the captured representation. A two-handed held item or unsupported representation is rejected rather than receiving incomplete client authority. Pass `requireClientCapture: false` only for explicitly advisory/fast validation; it does not make a supported-profile proposal committable. Profiles whose client implementation is truthfully `unsupported` keep their CPU-only path. Required stock views, including `first_person_vanilla`, equipped player/armor-stand headwear subjects, and ordinary studio/world frames, have `authoritative_environment_capture` authority: they prove what the pinned client rendered for the exact recorded representation and environment. `authorityScope: "required_views_only"` explicitly excludes every bare-head or injected scale/comparison, debug-hitbox, matched measurement-control, and `world_scale_reference` aid—including the `entity_player_scale` mannequin; no supplemental frame or skipped supplemental measurement can replace a missing or failed required view. Every pixel measurement binds an explicit `requiredForReadiness` value. A failed or skipped critical measurement makes capture readiness false and blocks commit; critical warnings and best-effort skips remain visible without being greenwashed as measured passes. Supplemental-control/debug measurements are never critical. Hardware and drivers can legitimately change pixels, so screenshots are not promised byte-identical across GPUs or operating systems. A `passed` capture means the required evidence completed, verified, and has no failed or unavailable critical measurement—not that its appearance was aesthetically approved. After setup, `validate` uses the pinned vanilla runtime by default to parse each logical `.mcfunction` command against Minecraft 26.2's real command dispatcher, loaded datapack registries, and component codecs. This catches invalid command, selector, item/component, particle, attribute, entity, and text-component syntax before packaging. `validate --no-vanilla` is the explicit structural-only escape hatch; builds never provide that bypass. Both command validation and authoritative tests run Java 25 in newly created disposable state. Command validation substitutes inert placeholders for the pack's functions and validates unreferenced command probes, so it does not execute user functions. GameTests receive a freshly allocated universe; a user world path is never accepted. See [Validation and vanilla testing](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/validation-and-testing.md). Function-type GameTests resolve Minecraft's internal `test_function` registry; a datapack `.mcfunction` does not register a Test Function. Use `minecraft:always_pass` only for pack-load/runner smoke coverage, or an existing block-based test structure for behavior-focused tests. Spyglass is deliberately not installed as a runtime dependency. The adapter is compatibility-pinned to Spyglass `0.4.65` and verifies the configured executable's `--version` output before use. An operator who has independently installed and reviewed a safe build may opt in with `PACKWRIGHT_SPYGLASS_COMMAND`; Packwright never downloads or enables it automatically. ## Safety model Packwright resolves every requested path beneath the configured workspace, rejects traversal and symlink escapes, limits scans and payloads, and never recursively deletes directories. Existing files can be replaced or deleted only with explicit intent and the current SHA-256. Raw authoring is limited to supported datapack text formats; binary NBT and `pack.png` may be inspected and packaged but not authored. Visual textures use a dedicated bounded PNG decoder, and accepted cross-pack proposals commit through a journaled transaction with all destination hashes checked first. Read [Security model](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/security-model.md) before granting the server access to valuable projects. Consider source control and `PACKWRIGHT_READ_ONLY=true` for review-only sessions. For common startup, cache, Java, validation, and build failures, see [Troubleshooting](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/troubleshooting.md). Maintainers and contributors can find the component boundaries in [Architecture](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/docs/architecture.md). ## Development ```sh npm ci npm run lint npm run format:check npm run typecheck npm test npm run build npm pack --dry-run ``` Minecraft integration tests are intentionally separate because they download Mojang artifacts and require Java 25 plus explicit EULA acceptance. The official-client capture release gate additionally requires a protected, interactive macOS machine; ordinary CI does not download or launch the client. Contribution setup and test expectations are in [CONTRIBUTING.md](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/CONTRIBUTING.md). ## License and trademarks Packwright MCP is available under the [MIT License](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/LICENSE). External software and service terms are summarized in [THIRD_PARTY_NOTICES.md](https://github.com/rithwikbabu/packwright-mcp/blob/HEAD/THIRD_PARTY_NOTICES.md). Minecraft is a trademark of Microsoft Corporation. This project follows the [Minecraft Usage Guidelines](https://www.minecraft.net/usage-guidelines) and uses no Mojang or Microsoft artwork.