Packwright MCP

Packwright MCP

Packwright MCP は、Minecraft Java Edition のデータパックと、それに対応するリソースパックを安全に作成、調査、検証、テスト、パッケージ化するためのローカルファーストな Model Context Protocol サーバーです。制限のないファイルシステムやシェルへのアクセスではなく、構造化されたツールを MCP クライアントに提供します。

MINECRAFT の公式製品ではありません。MOJANG または MICROSOFT による承認を受けておらず、両社とは無関係です。

Packwright には、Minecraft のコード、アセット、サーバー／クライアントの JAR、ライブラリ、ネイティブライブラリ、生成されたバニラデータ、逆コンパイルされたソースは含まれておらず、再配布もされません。npm パッケージに含まれるのは、Packwright 独自の MIT ライセンスのキャプチャー MOD のみです。

ステータスと互換性

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 プレビュー、不変の修復リビジョン、保護された複数ファイルのコミット。
• モデル固有の 8 つのビジュアルレビュー用プロファイル：held_item、block、placeable、armor、head_wearable、projectile、gui_item、entity_model。それぞれに決定論的なシーン、Packwright が作成した参照ジオメトリ、参考用の測定値、不変のレンダーレポートが用意されています。
• 明示的に準備したプロトコル v3 のフレームバッファーキャプチャ。Minecraft 26.2 の実際のクライアントレンダラーを通じてアイテムをキャプチャし、ブロック、頭部装備、エンティティ、設置可能オブジェクトを厳密に表現します。記録された OpenGL 環境では、必要なゲームプレイ／ワールドフレームが信頼できる判定基準です。注入されたスケール参照、デバッグ用ヒットボックス、対象なしの条件を一致させた測定用コントロールは、補足的な QA にのみ使用されます。すべてのアーティファクトには、実行中のクライアントから読み戻した正確なフィクスチャと正規化ハッシュが含まれます。公式クライアントは Packwright のキャプチャ MOD のみを使用する、破棄可能で決定論的なスタジオ内で実行されます。CPU レンダラーは、引き続き高速で決定論的な最初のゲートとして機能します。
• 安定したデータパック／リソースパックのスナップショットに対する、未コミットの提案そのものの検証。その後、正確にコミットされたパックのスナップショットから、トランザクション方式で決定論的な ZIP を生成します。
• レビュー、ひな形の作成、GameTest の作成向けの読み取り専用 MCP リソースとワークフロープロンプト。

ビジュアルコンパイラーが対応する範囲は、Minecraft の機能マトリックスより意図的に狭くなっています。compilerSupport は custom_item では full、conditional_item_state では limited、その他すべてのターゲットでは unsupported です。自動コンパイラーが出力するのは、引き続きカスタムアイテムのみです。プロトコル v3 のキャプチャでは、block、head_wearable、entity_model、placeable のレビュー用に、厳密で宣言的なハッシュ紐付け表現を個別に受け入れます。これは既存のバニラ ID、置き換え、表示シミュレーションを用意するものであり、Packwright が新しいネイティブなブロック／エンティティ ID をコンパイルしたとは主張しません。クライアントキャプチャの総合対応状況は、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 リファレンスと設定を参照してください。

Vanilla のセットアップとテスト

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 を追加します。プラットフォーム固有のランタイム一式、インデックスに登録されたすべてのアセットオブジェクト、必要なライブラリとネイティブライブラリ、固定バージョンの Fabric Loader 0.19.3 を準備するには、--client-capture を追加します。このオプションを指定すると、--client-assets の処理も実行されます。ダウンロードされるすべての成果物は許可リストに登録され、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に同梱されたキャプチャMODのみを使用し、新しい使い捨ての空中型スタジオで実行され、MinecraftのスクリーンショットAPIを通じてキャプチャした後、使い捨てのゲームディレクトリを削除します。レポートでは、表現、提案、パックの完全なスナップショット、クライアント／MOD、OS／GPU／ドライバー／OpenGLバックエンド、解像度、GUIスケール、FOV、レンダリング設定、カメラ、バイオーム、時刻、天候、観測された被写体の照明と決定論的な光源配置、ティック／アニメーションの状態、安定化時間、ソースフレームバッファーのハッシュ、および各ビューにおける正確なライブクライアント観測フィクスチャの読み戻し／ハッシュに加えて、両方の有効化モード、アーカイブのハッシュ、選択されたパックIDを証明します。プロトコルv3では、ハッシュで紐付けられた通常ブロックの床定規も必須です。黒色と白色のコンクリートを隣接する2つの固定ブロックに配置し、キャプチャMODが統合サーバーを通じて設置します。各完了ビューには、ライブクライアントでの読み戻しと正規化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フレームとして使用できます。スキップされないクライアント測定値は、紐付けられたフレームバッファーのピクセルから導出されます。利用できない幾何学的チェックは、CPUによる参考測定値で代用せず、理由とともに明示的にskippedとされます。補助的なコントロールを使用する測定値は、主シーンが必須であっても参考値にとどまります。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 はデフォルトでピン留めされたバニラランタイムを使用し、各論理 .mcfunction コマンドを、Minecraft 26.2 の実際のコマンドディスパッチャー、読み込まれたデータパックレジストリ、コンポーネントコーデックに照らして解析します。これにより、パッケージ化の前に、無効なコマンド、セレクター、アイテム／コンポーネント、パーティクル、属性、エンティティ、テキストコンポーネントの構文を検出できます。validate --no-vanilla は構造のみを検証するための明示的な回避手段ですが、ビルドでこの回避手段が提供されることはありません。

コマンド検証と権威あるテストはどちらも、新たに作成された使い捨て状態で Java 25 を実行します。コマンド検証では、パックの関数を無害なプレースホルダーに置き換えて、参照されていないコマンドプローブを検証するため、ユーザー関数は実行されません。GameTest には新しく割り当てられたユニバースが渡されます。ユーザーワールドのパスは受け付けません。検証とバニラテストを参照してください。

関数タイプの GameTest は、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 デコーダーを使用します。また、採用されたパック間の提案は、すべての送信先ハッシュを事前に確認したうえで、ジャーナル付きトランザクションを通じてコミットされます。

サーバーに価値のあるプロジェクトへのアクセスを許可する前に、Security model をお読みください。レビューのみのセッションでは、ソース管理の利用と PACKWRIGHT_READ_ONLY=true の設定を検討してください。

起動、キャッシュ、Java、検証、ビルドに関する一般的な問題については、Troubleshooting をご覧ください。メンテナーとコントリビューターは、Architecture でコンポーネントの境界を確認できます。

開発

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 License の下で利用できます。外部ソフトウェアとサービスの利用条件は、THIRD_PARTY_NOTICES.md にまとめられています。

Minecraft は Microsoft Corporation の商標です。このプロジェクトは Minecraft Usage Guidelines に従っており、Mojang または Microsoft のアートワークは使用していません。