dungeondraft-mcp

dungeondraft-mcp

Claude（または任意の MCP クライアント）が Dungeondraft のマップを読み取り、編集、エクスポートできる MCP サーバーです。.dungeondraft_map ファイルを直接操作するため、Dungeondraft を起動しておく必要はありません。また、Universal VTT のエクスポートファイル（.dd2vtt）を Foundry VTT v13 のシーンに変換できます。

「交差点のマップの北東の隅に小さな酒場を作って」「このマップを夜のバージョンにして」「この dd2vtt を Foundry のシーンにして」といった指示ができます。

Dungeondraft または Megasploot とは提携していません。起動中の Dungeondraft 内でリアルタイムに編集するには、battlemap-mcp をご覧ください。2 つは併用できます。

ツール

ツール	機能
list-maps	設定されたフォルダー内の .dungeondraft_map ファイルを検索します
inspect-map	概要を表示します：サイズ、レベル、要素数、地形、パック、使用頻度の高いアセット。種類や範囲を指定して、要素（ノード ID、アセット、グリッド位置）を一覧表示できます
list-assets	組み込みアセットとインストール済みアセットパックを、単語、カテゴリ、タグ、パックで検索します
add-objects	グリッド位置に小物を配置します（回転、拡大縮小、反転、レイヤー、影、色合い）
add-walls	ドアや窓を含む壁のポリラインまたは閉じた部屋を追加します。既存の壁にドアを追加することもできます
add-floors	長方形またはポリゴン上に床のパターン（板張り、石畳、タイル）を追加します
build-room	閉じた壁、対応する床、ドアを一度に作成します
add-lights	点光源を追加します（範囲はマス単位、色、強度）
add-paths	グリッド上の点に沿ってパスアセットを追加します
set-terrain	地形スロットのテクスチャ（1～8）を設定し、レベル全体を塗りつぶすか、柔らかい縁の長方形、円、線を描画します
set-environment	昼夜のバリエーション用に環境光を設定します（プリセット：day、overcast、dusk、night、dark）
remove-elements	範囲内の種類別、またはノード ID で要素を削除します（dry_run に対応）
duplicate-map	バリエーションを作成するためにマップを複製します
export-dd2vtt	マップの壁、ドア、ライトと、Dungeondraft からエクスポートした画像を使って .dd2vtt を作成します
dd2vtt-to-foundry-scene	.dd2vtt を Foundry v13 のシーン JSON（グリッド、壁、ドア、ライト）に変換し、画像を抽出します

すべての編集ツールは level（キー、インデックス、ラベル。既定では最初のレベル）と dry_run を受け取ります。

座標

すべてのツールは、マップの左上を基準に測るグリッドマスを使います。x は右方向、y は下方向です。(3, 4) はグリッドの交点で、(3.5, 4.5) は 3 列目、4 行目のマスの中心です。小数も使用できます。Dungeondraft は内部的に 1 マスを 256 px として保存し、サーバーが変換します。オブジェクトの位置はオブジェクトの中心です。回転は時計回りの度数です。ライトの範囲、パスの幅、地形のぼかし幅はマス単位です。

安全性

• 許可されたフォルダーのみ。 マップの読み書きは、デフォルトで Documents フォルダーに設定されている DD_MCP_ROOTS 内でのみ行われます。.. を含むパスや、許可範囲外を指すリンクは拒否されます。Dungeondraft のインストールフォルダーとアセットフォルダーは読み取り専用です。
• 先にバックアップ。 変更を行う前に、元のファイルを <map>.bak-YYYYMMDD-HHMMSS（UTC）にコピーします。
• 検証済みの書き込み。 新しいマップは一時ファイルに書き込まれ、再解析されて検証されます。バイト単位で完全に往復できること、要素数が編集による追加または削除の内容と一致すること、さらに編集で変更対象として指定されていないすべてのセクションが変更前とバイト単位で完全に一致することを確認します。すべての検証に合格した場合にのみ、一時ファイルを元のファイルに置き換えます。検証に失敗した場合、何も書き込まれません。
• 競合チェック。 ファイルを読み込んだ後にディスク上で変更された場合（たとえば Dungeondraft で保存された場合）、編集は拒否されます。
• ここで編集する前に、Dungeondraft でマップを閉じてください。または、編集後に保存せずに開き直してください。そうしないと、次回の保存時に Dungeondraft によって変更が上書きされます。
• アセットパックのライセンス。 パックから画像データが読み込まれることはありません。pack.json の allow_3rd_party_mapping_software_to_read: false が設定されているパックは名前のみ表示され、内容のインデックス作成は行われません。マップのアセットマニフェストを使用時に補完するため、pack.json のみを読み込みます。

インストール

Node.js 20 以降が必要です。

Claude Code

claude mcp add dungeondraft -s user -e DD_MCP_ROOTS="/path/to/your/maps" -- npx -y dungeondraft-mcp

Claude Desktop

以下を claude_desktop_config.json に追加し（Settings → Developer → Edit Config）、Claude Desktop を再起動します。

{
  "mcpServers": {
    "dungeondraft": {
      "command": "npx",
      "args": ["-y", "dungeondraft-mcp"],
      "env": {
        "DD_MCP_ROOTS": "C:\\Users\\you\\Documents\\Dungeondraft"
      }
    }
  }
}

Windows で Node が PATH にない場合は、"command": "C:\\Program Files\\nodejs\\npx.cmd" のようにフルパスを指定してください。

ソースからインストール

git clone https://github.com/casancam/Dungeondraft-MCP.git && cd Dungeondraft-MCP
npm install && npm run build
claude mcp add dungeondraft -s user -e DD_MCP_ROOTS="/path/to/maps" -- node "$PWD/dist/index.js"

設定

変数	デフォルト	説明
DD_MCP_ROOTS	Documents フォルダー	サーバーによるマップの読み書きが許可されるフォルダー。; で区切ります
DUNGEONDRAFT_DIR	自動検出（下記参照）	Dungeondraft のインストールフォルダー（Dungeondraft.pck を含むフォルダー）。組み込みアセットの一覧表示と検証に使用します
DD_ASSET_DIRS	なし	*.dungeondraft_pack ファイルを含む Dungeondraft アセットフォルダー。; で区切ります。カスタムパックを使用する場合に設定します

DUNGEONDRAFT_DIR は C:\Program Files\Dungeondraft で自動検出されます（検証済み）。また、/opt/Dungeondraft と /Applications/Dungeondraft.app/Contents/Resources でも検出されます（どちらも未検証）。設定しなくてもサーバーは動作しますが、書き込み前に組み込みアセット名が検証されません。

Dungeondraft → Foundry VTT

1. Dungeondraft で、File → Export → Universal VTT を選び、設定済みのフォルダーに保存します。
2. dd2vtt-to-foundry-scene を実行します。image_src に、Foundry で画像を配置するパスを設定します（例：maps/tomb.png）。
3. 抽出した画像を、そのパスにある Foundry（または The Forge Assets Library）にアップロードします。
4. Foundry でシーンを作成して右クリックし、Import Data を選択して、<name>.foundry-scene.json を指定します。

光源の半径は dim = range × grid distance および bright = dim / 2 で計算されます。Dungeondraft は画像に照明を焼き込むため、Foundry の照明が二重に見える場合は include_lights: false を指定してください。.dd2vtt では窓とドアを区別できないため、窓はドアとしてエクスポートされます。

export-dd2vtt は、エクスポート後に壁、ドア、または照明を変更した場合に使用します。マップ画像のレンダリングには Dungeondraft が必要なため、Dungeondraft からマップ全体を PNG/WEBP でエクスポートし、その画像をツールに指定してください。ライブの Foundry 内インポーターに必要な内容については、docs/foundry-import.md を参照してください。

既知の制限

• 水、洞窟、塗装された素材、屋根、テキストは保持されますが、編集できません。テキストと床のパターンは一覧表示および削除が可能です。
• 床のパターンは地形の上に描画されます。set-terrain は、ストロークがパターンの下に隠れている場合に警告します。
• export-dd2vtt は objects_line_of_sight を書き込みません。
• Windows で、Dungeondraft 0.9.4～1.2.0.1 のマップファイル（フォーマット 2 および 3）を使ってテスト済みです。

開発

npm install
npm run fixtures       # download public sample maps used by some tests (not redistributed)
npm test               # vitest
npm run build
node scripts/smoke.mjs # end-to-end over MCP stdio on a temp copy of the test map

テストでは、実際の Dungeondraft 1.2.0.1 のマップ（test/fixtures/mcp_test.dungeondraft_map）、公開サンプルマップ（フォーマット 2 および 3、最大 14 MB、4 レベル）、合成アセットパックを使用します。以下を確認します。

• バイト単位で完全に一致するラウンドトリップ
• サンプル内のすべてのドアに対するドア配置
• 編集後も変更していないセクションがそれぞれ同一であること
• マップから UVTT へのジオメトリが Dungeondraft 独自の .dd2vtt エクスポートと一致すること
• パックの一覧表示、検証、オプトアウトフラグ

Dungeondraft のインストールまたはダウンロードしたサンプルが必要なテストは、それらがない場合はスキップされます。ファイル形式に関する注記と各主張の検証方法については、docs/research.md をご覧ください。

クレジット

• フォーマットの調査は、Ryex/Dungeondraft-GoPackager（パック形式）とArkenforge の Universal VTT に関する注記を基にしています。
• テスト用のサンプルマップは、GitHub の Akesari12、pleonr、watermelonwolverine、lordhaywire が提供しています。テスト実行時にダウンロードされ、同梱されていません。

ライセンス

MIT