Dwarf Fortress (DFHack)

dfhack-mcp

AI エージェントにDwarf Fortressの要塞のライブ情報を提供するMCPサーバーです。副操縦士兼早期警告アドバイザーであり、自動操縦ではありません。Claude（または任意の MCP クライアント）を接続して 「要塞の調子はどうですか？」 と尋ねると、実行中のゲームから幸福度、脅威、備蓄品、仕事、健康状態、防衛状況を直接読み取り、平易な言葉で回答します。

デフォルトでは読み取り専用です。 37 個のセンサーおよびリファレンスツールは、ゲームを観察するだけです。要塞を_変更する_少数の操作ツール（マネージャーの指示をキューに登録する、quickfort の設計図を適用する、労働を割り当てる、市民警報を鳴らす、レバーを引く）は、明示的にオプトインした場合にのみ利用でき、有効にするまでは非表示です（操作を参照）。

ツールには次の 2 種類があります。

• センサーは 要塞で今何が起きているか？ に回答します。fort_status、 threats、stocks、jobs_and_labor、military、injuries_and_health、 defenses などがあります。
• リファレンスは Dwarf Fortress の仕組みは？ に回答します。game_data はあなたの 世界の確かな情報源（読み込まれている raw データ）で、wiki_* ツールは一般的な 解説を提供し、identify はこの 2 つを組み合わせて 「この生き物は何で、どう 対処すればよいか」 に回答します。

アドバイスではなく事実を返します。画面をざっと確認するような、すでに要約された JSON を返し、判断はエージェントに委ねます。

各ツールのパラメーター、戻り値の形式、実際の出力例、注意事項については、docs/toolsにあるリファレンスページをご覧ください。

クイックスタート

このパッケージは npm で公開されており、ビルド済みバンドルが含まれているため、ビルドは不要です。npxを使って MCP クライアントから接続します。

{
  "mcpServers": {
    "dfhack": {
      "command": "npx",
      "args": ["-y", "dfhack-mcp"]
    }
  }
}

Claude Desktop、Claude Code、その他の stdio MCP クライアントなら、これだけで準備完了です。npx -y dfhack-mcpは最新リリースを取得して実行します。MCP SDK、zod、 dfhack-remote-node RPC トランスポートなどの実行時依存関係も、npm から自動的に取得されます。

公式 MCP Registryを参照するクライアントでは、このサーバーを io.github.alexanderolvera/dfhack-mcp として検索できます。この登録情報はserver.jsonから生成され、同じ npm パッケージを参照しているため、どちらの方法でも同一のビルドがインストールされます。

あとは要塞を起動して（次のセクションを参照）、エージェントに 「要塞の状況を確認して、緊急の問題があれば教えてください」 のように尋ねるだけです。

バージョンを固定してグローバルインストールしたい場合はこちら。

npm install -g dfhack-mcp     # then set "command": "dfhack-mcp", "args": []

要件

• DFHack を使用して Dwarf Fortress を実行し、要塞を読み込んでいること。 ツールは ライブゲームを読み取ります。要塞が読み込まれていない場合は、その旨を通知します。
• localhost:5000で DFHack Remote RPC が動作していること。 DFHack を使って DF を実行すると、これはデフォルトで有効です。編集が必要な設定ファイルはありません。 （allow_remote設定は_別のマシン_からの接続のみを制御するため、falseのままで 構いません。ローカル MCP サーバーからは、どちらの設定でも接続できます。）接続先を 変更するには、DFHACK_HOST / DFHACK_PORTを指定してください。
• 公開パッケージの実行にはNode 20 以降が必要です。（ソースから開発する場合のみ Node 24 以降が必要です。開発を参照してください。）

何を尋ねられますか？

エージェントがツールを選ぶので、知りたいことを伝えるだけです。以下のツールを使って回答します。

センサー — 要塞の状態

引数は不要です。それぞれ、読み込まれている要塞の状態を報告します。

• fort_status() — 要塞名、日付／季節、人口、富、幸福度の内訳、事前に分類された警報。
• stocks() — 食料／飲料の供給日数に加え、重要資材の数量と、特に少ない／多い品目の一覧。
• threats() — 危険なユニットを種類別に分類し、活動中か封じ込め済みかを表示します。重大な危険／侵略者／アンデッドのフラグに加え、各グループの決定的な特性（罠回避、飛行、炎、糸を吐く、建物破壊、遠距離攻撃）も表示します。
• unmet_needs() — ニーズシステムを集計し、気が散っているドワーフの数で順位付けした未充足ニーズ上位と、それぞれの不足度を表示します。
• jobs_and_labor() — 労働力の稼働状況を表示します。忙しい／待機中の成人（子どもは除外）、待機率、進行中の仕事の内訳を順位順に表示します。
• military() — 分隊、入隊した兵士、充足済みの役職、マップ上の敵に対する準備状況、分隊ごとの装備の不足（制服の不足品）、弾薬、進行中の訓練命令を表示します。
• injuries_and_health() — 負傷者／患者／寝たきり／意識不明者の数に加え、必要な治療（診断、手術、縫合など）を表示します。
• defenses() — 活動中の敵について、マップ上の位置と、要塞の中心および最寄りの跳ね橋までの距離／方向／高度差を表示します。また、操作可能な構造物（橋、レバー、水門、ハッチ、檻の罠、ドア）の一覧も表示します。
• burrows() — 各穴居域の規模と所属メンバーに加え、市民警報用の安全な穴居域セット（設定済み／有効／リンク済みの穴居域）を表示します。civilian_alert の読み取り側です。
• mechanisms() — 各レバーの位置、状態、リンク先（橋／ドア／水門／ハッチ／支柱／武器罠）を表示します。感圧板の起動条件、リンクされていないレバーと橋も表示します。
• moods() — 発生中の不可思議な気分（妖精憑き／秘密主義／憑依／陰鬱／邪悪）があれば、ドワーフ、引き金となるスキル、工房の状態、要求された各素材と要塞の在庫を照合した情報を表示します。「骨を要求しているのに、要塞には1つもない」という事態を早期に把握できます。
• mandates_and_justice() — 貴族に関する負担を表示します。有効な生産命令と輸出禁止、未充足の貴族の部屋に関する要求、司法の状況（未解決事件、処罰待ちの有罪判決、拘束設備の収容能力）を確認できます。
• rooms_and_zones() — 施設の一覧を、それぞれの数と需要側の数を併記して表示します。寝室、食堂、病院、井戸、寺院、酒場、図書館、ギルドホール、空いている棺と埋葬待ちの死者を確認できます。unmet_needs() の供給側の情報です。
• trade() — 隊商の来訪状況と取引所を表示します。取引所の有無／完成状況と荷車の進入可否、到着中の隊商とその状態、商人の任命／在席状況、取引所に運び込まれた商品の数と概算価値を確認できます。
• environment() — 現在の周辺環境を表示します。季節と天候、地表の気温と露出した水が凍っているかどうか、入植地のバイオームの傾向（邪悪／善良／蘇生）を確認できます。また、要塞がすでに突破した各洞窟が開放されているか封鎖されているかも表示します。戦場の霧を尊重します。
• find_unit(query) — 名前の一部または職業で市民を検索します。一致した各人物の簡潔な概要（職業、年齢、ストレス、仕事、分隊、健康状態のフラグ）を表示します。詳しく調べるには citizen に引き継いでください。
• citizen(unit_id) — 1人のドワーフの詳細な人物情報を表示します。社会的なつながり（配偶者／両親／子ども／友人／確執のある相手。それぞれの unit_id で詳細をたどれます）、信仰する神々、際立った性格の極端な傾向、注目すべきスキル、好み／嫌悪、現在のストレスに関連する最近の思考を確認できます。
• site_history() — 世界の年代記に記された要塞の歴史を表示します。創設、ドワーフ語と英語での要塞名とその語源、この場所で過去に起きた包囲戦／戦闘、ここで亡くなった著名人を確認できます。
• artifacts_and_engravings() — 要塞の傑作と注目すべき彫刻を表示します。
• chronicle() — 要塞の最近の出来事を一覧しやすいフィード形式で表示します。

空間情報（戦場の霧を尊重し、未発見のタイルの情報は決して漏らしません）：

• map_overview() — タイルごとの読み取りを行う前に実行する、低コストの概要把握用ツールです。マップの範囲、要塞中心部の座標、地表の z レベル、プレイヤーの活動（採掘・建設）がある z レベル、垂直な柱としての階段を表示します。要塞の規模にかかわらず、サイズは一定です。

• tile_region(z?, x0?, y0?, x1?, y1?) — 1 つの z レベルの指定範囲を、ASCII グリッドと自己説明的な凡例で表示します。未発見のタイルは ? のままです。すべてのパラメーターは省略可能です。指定なしの場合は要塞中心部の 60×40 の範囲、z のみを指定した場合はそのレベルの重心、それ以外の場合は指定した角の範囲を表示します。最大サイズは 100×100 です（大きすぎる要求はエラーにせず、範囲を制限します）。マップを表示しますが、設計は行いません。

  グリフ	意味	グリフ	意味
  ?	未発見（戦場の霧）	+	建設された床
  #	未採掘の石／壁	~	水／小川
  ,	未採掘の土（砂／粘土／ローム）	%	マグマ
  .	採掘済みの床／歩行可能な地面	W	工房／溶鉱炉
  F	防壁	S	物資置き場
  r	坂道	M	機械（歯車／車軸／ポンプ／水車／風車）
  v	坂道の上部	n	家具（ベッド／椅子／テーブル／ドアなど）
  < > x	上り／下り／上下階段	(space)	開けた空間
  T	木

• geology(reveal_hidden?) — 1 回の呼び出しで地質調査を行います（デフォルトでは、判明している情報のみ）。地表の z レベル、露出している地層の構成と素材名、帯水層（軽度か重度か、および z レベルの範囲）、発見済みの洞窟、マグマ海に到達しているかどうか、地表の水を表示します。reveal_hidden: true を指定すると戦場の霧を無視します（デバッグ／ネタバレ用の切り替えで、デフォルトではオフです）。

リファレンス — DF の仕組み

wiki_* は HTTP のみを使用し、ゲームなしで動作します。game_data／identify は ロード済みのワールドを読み取ります。

• game_data(query, kind?) — 6 種類（creature、material、plant、reaction、item、building。デフォルトは creature）にわたる、あなたのワールドの raws を取得します。Wiki には載らないことのある、手続き生成されたクリーチャー（デーモン、忘れられた獣、タイタン）についての正確な情報源です。query にはトークン（DEMON_4、INORGANIC:IRON）、名前（"plump helmet"）、またはクリーチャーの場合は現在の unit_id を指定します。有力な一致が 1 件の場合は完全な情報を返し、複数の場合は候補を選ぶための一覧を返します。一致がない場合は {"match_count":0,"matches":[]} を返します。
• identify(query) — 1 回の呼び出しで「このクリーチャーは何者で、どう対処すればよいか」を調べます。game_data（あなたのワールドの raws）と wiki_lookup（戦略）を組み合わせます。情報の詳細を返します（flags[]／interactions[] には、TRAPAVOID → 機械式トラップは効かない のような情報が含まれます）。さらに、要約した Wiki の抜粋を 1～2 件返します。脅威が現れたときに使ってください。
• wiki_search(query) — DF Wiki を検索し、候補となるページタイトルと、整形済みのスニペットを返します（DF2014 名前空間を優先します）。
• wiki_lookup(title, section?, refresh?) — Wiki の記事を取得し、読みやすいテキストとして返します。DF2014 に固定され、リダイレクトに従い、セクションの指定にも対応し、キャッシュの有効期間は約 30 日です。

操作の実行（アクチュエーター）

デフォルトでは、上記のツールはすべてゲームを読み取るだけです。アクチュエーターは要塞を_変更_するため、明示的な切り替え設定を設けています。DFHACK_MCP_ACTUATORS を設定するとツール一覧に表示され、設定しなければサーバーは読み取り専用のままです。

{
  "mcpServers": {
    "dfhack": {
      "command": "npx",
      "args": ["-y", "dfhack-mcp"],
      "env": { "DFHACK_MCP_ACTUATORS": "1" }
    }
  }
}

すべてのアクチュエーターは同じプレビュー → 確認 → 適用 → 元に戻すという安全手順を使うため、変更が不意に適用されることはありません。

1. プレビュー（ドライラン）。 エージェントは操作内容をすべて指定してツールを呼び出しますが、確認トークンは付けません。何が変わるかを正確に示す preview が返されます。内容は助言ではなく事実です。さらに、使い切りの confirm_token も返されます。何も書き込まれません。 操作を指定どおりに適用できない場合（例：ブループリントの形式が不正な場合）、プレビューで理由が報告され、トークンは発行されません。
2. 適用。 エージェントは同じ引数にトークンを加えて、もう一度呼び出します。サーバーは、_操作対象_がプレビュー後に変更されていないことを再確認します。変更されていた場合、トークンは無効になり、エージェントは再度プレビューします。成功すると、undo ハンドルと、変更を確認する対応センサーからの readback が返されます。

トークンは使い切りで、対象に限定されます。砦の別の場所で無関係な変更があっても無効にはなりませんが、対象が変更されると無効になります。各アクチュエーターには、それぞれの取り消し方法が指定されています。

マネージャーの作業指示

• work_order_list(after_id?) — 読み取り専用で、常に利用できます。 砦のマネージャーの注文を事実として返します。id、作業種別、出力アイテム／素材、総量／残量、繰り返し頻度、割り当てられた工房、注文ごとの検証状態が含まれます。カーソルを使ったページ分けに対応し、上限は256件です。
• work_order_create(job_type, amount, frequency?, material?, item_type?) — 新しい注文をキューに追加します。プレビューでは would_duplicate と manager_present が示されます。取り消し方法：work_order_cancel。
• work_order_cancel(order_id) — idを指定して注文を1件削除します。undoハンドルは再作成用の仕様で、工房の割り当てや条件を完全に復元できない場合は faithful フラグが付きます。

Quickfortブループリント — エージェントが作成したquickfort CSVから採掘／ゾーンを指定します。別途読み取りセンサーはありません。トークンなしの blueprint_apply がプレビューを兼ねます。

• blueprint_apply(csv, anchor_x, anchor_y, anchor_z, mode) — #dig または #zone ブループリントから指定します。左上のセルがアンカーに対応します。ドライランではquickfort独自の統計情報を解析し、影響を受けるタイル、範囲、およびその下にある戦場の霧のタイルをプレビューします（事実を示すもので、ブロックされることはありません）。ブループリントの形式が不正な場合、トークンなしでブロックされます（quickfortでは一部だけ適用されるため）。v1の対象範囲はdigとzoneのみです。build／place は拒否されます。取り消し方法：blueprint_undo。
• blueprint_undo(csv, anchor_x, anchor_y, anchor_z, mode) — quickfort標準の取り消し機能を使って、dig／zoneの指定を取り消します（同じcsv／アンカー／modeを使用）。トークンにはセルごとのダイジェストが署名されるため、セルに何らかのずれがあると無効になります。

作業詳細による労働割り当て

• work_details() — 読み取り専用で、常に利用できます。 すべての作業詳細（ゲーム内の労働グループ）について、名前、モード、有効にする労働トークン、割り当てられた市民を返します（id順、上限200件。完全な member_count も含まれます）。
• assign_work_detail(unit_id, detail, enabled) — 市民を1人、作業詳細1件に追加または削除します。プレビューでは currently_member、resulting_members_count、only_member が報告されます。すでに指定どおりの場合は、何もしないプレビューが返されます。取り消し方法：enabled を反転させて同じ呼び出しを行います。

緊急対応

• burrows() — 読み取り専用で、常に利用できます。 各バロウのサイズと所属メンバーに加え、市民警報の状態も返します。configured（砦でこれまでに設定されたことがあるか）、active（現在鳴っているか）、関連付けられたバロウのidが含まれます。
• civilian_alert(burrow, enabled) — 市民警報の安全対象セットにバロウを1件追加または削除します。enabled=true の場合、まだ警報が鳴っていなければ鳴らします。enabled=false の場合、セットが完全に空になったときにのみ警報を止めます。取り消し方法：enabled を反転させて同じ呼び出しを行います。
• mechanisms() — 読み取り専用で、常に利用できます。 すべてのレバー／感圧板について、位置と接続先（橋／ドア／水門／ハッチ／支持構造物／武器トラップ）を返します。接続されていないレバーや橋も含まれます。
• pull_lever(lever_id, urgent?) — 指定したレバーを引く作業をドワーフ用のキューに追加します（urgent の既定値は今すぐ実行する優先度です）。これは作業をキューに追加するだけです。物理的な切り替えは、適用時ではなくドワーフが作業を完了した時点で行われます。取り消し方法：同じレバーをもう一度引きます。

ゲームの保存

• game_save() — 大規模またはリスクの高い変更を加える前にクイックセーブで要塞のチェックポイントを作成しておくと、問題のある一連の変更をセーブデータの読み込みで元に戻せます。引数はありません。ドライランでは、凍結される要塞とゲーム内の日付を確認できます。知っておくべき点は2つあります。書き込みは非同期です（DFはその後の数フレームにわたって保存を確定するため、読み戻しで確認できるのはクイックセーブの 送信 までであり、ファイルが書き込まれたことではありません）。また、DFのオートセーブを経由するため、読み込み中のセーブデータを上書きするのではなく、DFの設定に応じてローテーションする「autosave」フォルダーに保存されます。取り消しはできません。元に戻すには、DFで適切なセーブデータ／オートセーブを読み込んでください。要塞モード専用です。

設定

すべて任意です。MCP クライアントのサーバー用 env に設定します。

変数	デフォルト	効果
DFHACK_HOST	127.0.0.1	DFHack の Remote RPC が待ち受けているホストです。
DFHACK_PORT	5000	DFHack の Remote RPC 用ポートです。
DFHACK_MCP_ACTUATORS	(未設定)	書き込みアクチュエーターを公開するには 1 に設定します（オフの場合は厳密に読み取り専用です）。
DFHACK_MCP_DEV	(未設定)	run_lua を公開するには 1 に設定します。これは生の DFHack Lua 用のエスケープハッチです（ゲーム状態の読み取りと書き込みを行います。ツール開発者専用です）。

トラブルシューティング

• {"error":"no fort loaded"} — DFHack には接続できていますが、タイトル画面またはメニューにいます。要塞モードで要塞を読み込んでください。
• DFHack に接続できないというエラー — Dwarf Fortress が DFHack とともに起動していないか、RPC ポートが異なります。DF が DFHack とともに起動していること、および DFHACK_HOST / DFHACK_PORT が一致していることを確認してください（デフォルトは 127.0.0.1:5000 です）。
• クライアントにツールが表示されない — MCP クライアントを再起動し、サーバーを再起動させてください。起動中のサーバーは設定変更を反映しません。
• 書き込みツールが見つからない — これはデフォルトの動作です。DFHACK_MCP_ACTUATORS=1 に設定してください（操作を参照）。
• 要塞を読み込んだ後の最初の呼び出しだけエラーになり、その後は動作する — 起動直後の DFHack は、クエリスクリプトの登録が完了するまで最初のツール呼び出しを拒否することがあります。もう一度試してください。

開発

サーバー自体を開発するには、リポジトリをクローンし、TypeScript のエントリーポイントを直接実行します（Node 24+ — 型消去を使ってソースを実行するため、ビルド手順は不要です）。

git clone https://github.com/alexanderolvera/dfhack-mcp.git
cd dfhack-mcp
npm install        # or: npm run bootstrap  (installs + runs the T0 contract check)
node src/index.ts

"command": "node", "args": ["/absolute/path/to/dfhack-mcp/src/index.ts"] を指定して、チェックアウトしたリポジトリを MCP クライアントに接続します。

バージョンによって変わりやすい DFHack のフィールドアクセスはすべて、src/dfhack-queries/ 以下の実際の .lua スクリプト（ツールごとに1つ）にまとめられており、ネイティブの argv を使って名前で呼び出されます。そのため、DF／DFHack のバージョンが上がっても修正箇所は限定され、クエリパラメーターは構造上インジェクションされないようになっています。各ツールは src/tools/ にある薄い TypeScript ラッパーです。

助言ではなく、事実を。 ツールは 状況を把握 します。プレイヤーが画面を読むように、要塞や世界についての事実を返します。何を建てるか、どう戦うかは指示しません。その判断はエージェントが行います。何をすべきか を示すフィールドは助言にあたるため、含めないでください。

各ツールは、段階的なハーネス（npm run verify:t0 … t2）を使って実際に稼働している要塞で検証されており、モックは使いません。ツールの作成方法の分担と検証ワークフローについては CONTRIBUTING.md、ハーネスの各段階については docs/VERIFY.md を参照してください。

ライセンス

ISC — LICENSE.md を参照してください。