DX12 Engine MCP server

起動中の DX12 Engine エディタを Claude Code / Codex から 叩いてゲームを作るための MCP サーバ。エディタ(C++)が 127.0.0.1:8787 で待ち受ける TCP ブリッジに 改行区切り JSON で繋ぐ。ゲーム(封印ランタイム)ではブリッジは起動しない＝外から触れない。

• 配布リポジトリ: https://github.com/ryuto-alt/dx12-mcp （エンジン本体には同梱されない）
• ソース・オブ・トゥルース: エンジンリポジトリの tools/mcp-server（publish.ps1 で dx12-mcp へ同期）
• 必要環境: Node.js v24+（.ts を型ストリップで直接実行。tsc ビルド不要）、起動中の DX12 Engine エディタ

インストール

git clone https://github.com/ryuto-alt/dx12-mcp "$env:USERPROFILE\dx12-mcp"
cd "$env:USERPROFILE\dx12-mcp"
./install.ps1        # Linux/macOS: ./install.sh

%USERPROFILE%\dx12-mcp に置くと、エディタの「MCP / AI Bridge」窓が自動検出して 登録コマンドをワンクリックでコピーできる。install スクリプトは Node v24+ を確認し、 npm install + 自己テスト(エンジン不要)を実行して、絶対パス解決済みの登録コマンドを表示する。

接続

Claude Code

claude mcp add dx12-engine -- node "$env:USERPROFILE\dx12-mcp\index.ts"

または .mcp.json（テンプレ: .mcp.json.example）:

{
  "mcpServers": {
    "dx12-engine": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\dx12-mcp\\index.ts"]
    }
  }
}

注意: 既定では env に DX12_MCP_PORT を書かないこと。書くとポート自動探索 (%TEMP%/dx12_mcp.port)が無効化される。ポートを固定したい時だけ書く。

Codex (~/.codex/config.toml)

[mcp_servers.dx12-engine]
command = "node"
args = ["C:\\Users\\<you>\\dx12-mcp\\index.ts"]

構成

• engineClient.ts … TCP フレーミング + id 相関の薄いクライアント（ポートは env DX12_MCP_PORT → %TEMP%/dx12_mcp.port → 8787 の順で自動解決。別マシンは DX12_MCP_HOST）
• index.ts … MCP サーバ本体(stdio)。112 ツールを公開（全量はエンジンリポジトリの docs/MCP.md 参照）
• sceneTools.ts … 地形/スカルプト/診断の引数正規化と共通 zod 部品（純ロジック・エンジン非依存）
• test.ts … mock エンジンで framing/相関/エラーを検証(node test.ts)
• sceneTools.test.ts … 引数正規化・列挙定数・zod スキーマの回帰テスト(node sceneTools.test.ts)
• AGENTS.md … AI エージェント向け運用ガイド（典型ワークフロー・禁止パターン）

ツール(抜粋)

生成/削除/シーン読込/Play/Stop は遅延同期: エンジンはフレーム境界で実処理し、完了後に 本物の結果(entityId 等)を同期で返す。「name で list して探す」旧パターンは不要。

使い方

1. エディタ(DX12Engine.exe)を起動してシーンを開く（ブリッジが 8787〜8797 で待ち受け）
2. AI から dx12_ping → 疎通確認
3. dx12_create_entity / dx12_set_component / dx12_attach_lua_component でシーンを組む
4. dx12_play → dx12_screenshot / dx12_get_log で結果を確認