Skip to main content
Glama

dfhack-mcp

An MCP server that gives an AI client live access to Dwarf Fortress through DFHack. It is an access layer: it reports what is true in the running game and executes exactly what it is asked, and it leaves deciding what matters, and what to do about it, to the client. Point Claude (or any MCP client) at it and ask "how's my fort doing?". The client reads happiness, threats, stocks, jobs, health and defenses straight from the game and does the reasoning itself.

Read-only by default. The 39 sensor and reference tools only observe the game. A handful of actuators that change the fort — queue manager orders, apply quickfort blueprints, assign labor, sound the civilian alert, pull a lever — ship behind an explicit opt-in and stay hidden until you enable them (see Taking action).

Two kinds of tools:

  • Sensors answer what is my fort doing right now? — fort_status, threats, stocks, jobs_and_labor, military, injuries_and_health, defenses, and more.

  • Reference answers how does Dwarf Fortress work? — game_data is your world's ground truth (its loaded raws), and dfhack_command_list lists what DFHack itself can do.

It returns facts, not advice: structured JSON in DF's own terms, with no thresholds, triage or strategy text layered on top. Rates, alerts and game knowledge belong to the client. docs/migrating-to-2.0.md lists what moved out of the server in 2.0.

Every tool has a reference page — parameters, return shape, real example output, caveats — in docs/tools.

Quick start

The package is published to npm and ships a prebuilt bundle — there is nothing to build. Point your MCP client at it with npx:

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

That's it for Claude Desktop / Claude Code / any stdio MCP client. npx -y dfhack-mcp fetches and runs the latest release; its runtime dependencies — the MCP SDK, zod, and the dfhack-remote-node RPC transport — are pulled from npm automatically.

Clients that browse the official MCP Registry can find this server there as io.github.alexanderolvera/dfhack-mcp; the listing is generated from server.json and points at the same npm package, so either route installs the identical build.

Then just have your fort running (next section) and ask your agent something like "check on my fort and flag anything urgent."

Prefer a pinned global install?

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

Related MCP server: mcp-devenv

Requirements

  • Dwarf Fortress running with DFHack, with a fort loaded. The tools read the live game; if no fort is loaded they say so.

  • DFHack Remote RPC on localhost:5000. This is on by default whenever DF runs with DFHack — no config file to edit. (The allow_remote setting only governs connections from other machines and can stay false; a local MCP server reaches it either way.) Point elsewhere with DFHACK_HOST / DFHACK_PORT.

  • Node 20+ to run the published package. (Node 24+ only if you develop from source — see Development.)

What you can ask it

Your agent picks the tools; you just describe what you want. The tools below are what it has to work with.

Sensors — the state of your fort

Each reports on the loaded fort, except game_state(), which works at any screen.

Fog of war is on by default. Undiscovered tiles, the units standing on them and undiscovered caverns never appear. What a player may see past that is the client's call, so every fog-gated tool takes the same optional reveal_hidden: true to bypass it, and every response from one reports fog_of_war: "applied" | "bypassed". The fog-gated tools are defenses, environment, fluids, fort_health, fort_status, geology, historical_figure, livestock_and_pastures, map_overview, military, rooms_and_zones, threats, tile_region and unit_appearance. A bypassed full-map scan (fluids, geology) reads every tile, so it takes longer; raise DFHACK_MCP_TIMEOUT_MS on a large map. See CONTRIBUTING's fog-of-war section.

  • game_state() — DFHack and DF versions, game mode (title/fortress/adventure/other), whether a world and map are loaded, paused, the raw clock (year, year_tick, formatted date), and the world/fort identity. The one tool that works with no fort loaded; cheap enough to poll.

  • fort_status(reveal_hidden?) — name, date/season, identity (world, save folder, site, civ), population, wealth, happiness breakdown, recent deaths, hostiles on map.

  • stocks(category?) — raw usable counts of food, drink and key materials, a usable count for every DF item type (optionally one category), and the population to normalize them by.

  • threats(reveal_hidden?) — dangerous units grouped by type; active vs. contained, great-danger/invader/undead flags, plus each group's decisive traits (trapavoid, flier, fire, webber, building-destroyer, ranged).

  • unmet_needs() — the needs system aggregated: the top unmet needs ranked by how many dwarves are distracted, and how starved each is.

  • jobs_and_labor() — workforce utilization: busy vs. idle adults (children excluded), idle %, and a ranked breakdown of active jobs.

  • military(reveal_hidden?) — squads (each with its squad_id, the id squad_orders targets), enlisted soldiers, filled positions, readiness against hostiles on the map, and per-squad roster equipment gaps (missing uniform pieces), ammo, and active training order.

  • injuries_and_health() — wounded / patients / bedridden / unconscious counts, plus the care needed (diagnosis, surgery, suture, …).

  • defenses(reveal_hidden?) — active hostiles with map positions and distance/direction/z-delta to the fort core and nearest drawbridge, plus a controllable-structure inventory (bridges, levers, floodgates, hatches, cage traps, doors).

  • burrows() — every burrow's size and membership, plus the civilian-alert safety-burrow set (configured/active/linked burrows) — the read half of civilian_alert.

  • mechanisms() — every lever's position, state, and linked target(s) (bridge/door/floodgate/hatch/support/weapon-trap); pressure-plate trigger conditions; unlinked levers and bridges.

  • moods() — any active strange mood (fey/secretive/possessed/macabre/fell): the dwarf, driving skill, workshop state, and each demanded material cross-referenced against fort stock — the "demands bones, fort has zero" early warning.

  • mandates_and_justice() — the nobility's overhead: active production mandates and export bans, unmet noble room demands, and justice state (open cases, convictions awaiting punishment, restraint capacity).

  • rooms_and_zones(reveal_hidden?) — the facility inventory, each count paired with its demand-side number: bedrooms, dining halls, the hospital, wells, temples, taverns, libraries, guildhalls, and coffins free vs. dead awaiting burial. The supply-side companion to unmet_needs().

  • trade() — the caravan lifecycle and trade depot: depot existence/completeness and wagon-accessibility, caravans present and their state, broker assignment/presence, and the count and approximate value of goods staged in the depot.

  • environment(reveal_hidden?) — ambient conditions right now: season and weather, surface temperature and whether exposed water is frozen, the embark's biome alignment (evil/good/reanimating), and — for each cavern the fort has already breached — whether it is open or sealed.

  • find_unit(query) — look up citizens by name fragment or profession; a compact dossier per match (profession, age, stress, job, squad, health flags). Chain into citizen for depth.

  • citizen(unit_id) — the full character sheet for one dwarf: social graph (spouse/parents/children/friends/grudges, each with a unit_id you can walk), worshipped deities, notable personality extremes, skills of note, likes/detests, and recent thoughts tied to current stress.

  • unit_appearance(unit_id, reveal_hidden?) — the portrait read for one unit: DF's appearance modifiers (eyes, nose, hair length, build, ...) as raw values with their description band, hair/beard styling, hair/skin/eye colors as DF names them (including age graying), missing parts and scars, and everything worn or wielded with material, quality, wear, dye, and decorations.

  • site_history() — the fort's entry in the world saga: founding, the fort name in Dwarven + English with etymology, prior sieges/battles at the site, and notable figures who died here.

  • historical_figure(hf_id, reveal_hidden?) — one figure's legends entry, dead or alive, fort-dweller or not: name in its native language + English, race/caste, birth and death (cause, site, slayer with hf_id), entity affiliations and positions held, relationships and worshipped deities (each with an hf_id you can walk), site links, kills, and the saga events that involve them.

  • artifacts_and_engravings() — the fort's masterworks and notable engravings.

  • chronicle() — a scannable recent-events feed for the fort.

Spatial (with fog applied, undiscovered tiles never leak):

  • map_overview(reveal_hidden?) — cheap orientation to run before any per-tile read: map extents, the fort-core coordinate, the surface z-level, the z-levels carrying player activity (digging/construction), and stairways as vertical columns. Fixed-size regardless of fort size.

  • tile_region(z?, x0?, y0?, x1?, y1?, reveal_hidden?) — a bounded window of one z-level as an ASCII grid plus a self-describing legend. Undiscovered tiles stay ? unless reveal_hidden. All params optional: none → a 60×40 window on the fort core; z alone → that level's centroid; explicit corners otherwise. Hard-capped at 100×100 (oversized requests are clamped, never errored). Renders the map; never designs it.

    glyph

    meaning

    glyph

    meaning

    ?

    undiscovered (fog of war)

    +

    constructed floor

    #

    undug stone / wall

    ~

    water / brook

    ,

    undug soil (sand/clay/loam)

    %

    magma

    .

    dug floor / walkable ground

    W

    workshop / furnace

    F

    fortification

    S

    stockpile

    r

    ramp

    M

    machine (gear/axle/pump/wheel/windmill)

    v

    ramp top

    n

    furniture (bed/chair/table/door/etc)

    < > x

    up / down / up-down stair

    (space)

    open space

    T

    tree

  • geology(reveal_hidden?) — a one-call geological survey: surface z-level, the exposed layer stack with material names, the aquifer (light vs. heavy, z-range), discovered caverns, whether the magma sea is reached, and surface water.

Reference — how DF works

game_data reads a loaded world; dfhack_command_list works without one.

  • game_data(query, kind?) — your world's raws across six kinds (creature, material, plant, reaction, item, building; default creature). Ground truth for procedural creatures (demons, forgotten beasts, titans) that never reach the wiki. query is a token (DEMON_4, INORGANIC:IRON), a name ("plump helmet"), or — for creatures — a live unit_id. One strong hit → a full dossier; several → a disambiguation list; none → {"match_count":0,"matches":[]}.

  • dfhack_command_list(filter?) — every command DFHack itself ships (built-ins, plugins, scripts) from DFHack's own ls: name, one-line help, and tags, plus the tag list from tags. filter is a tag or a name substring. Reports what exists, not what to run; works without a fort.

Taking action (actuators)

By default every tool above only reads the game. The actuators change the fort, so they ship behind an explicit switch — set DFHACK_MCP_ACTUATORS and they appear in the tool list; leave it unset and the server is strictly read-only.

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

Every actuator uses the same preview → confirm → apply → undo safety loop, so a change is never a surprise:

  1. Preview (dry-run). The agent calls the tool with the operation fully specified but no confirmation token. It gets back a preview of exactly what would change — facts, never advice — plus a single-use confirm_token. Nothing is written. If the operation can't be applied as asked (e.g. a malformed blueprint), the preview reports why and no token is issued.

  2. Apply. The agent calls again with the same arguments plus that token. The server re-checks that the thing being acted on hasn't changed since the preview; if it has, the token is void and the agent re-previews. On success it gets an undo handle and a readback from the matching sensor confirming the change.

Tokens are single-use and target-scoped: an unrelated change elsewhere in the fort does not void them, but a change to the target does. Each actuator names its own reversal path.

Manager work orders

  • work_order_list(after_id?) — read-only, always available. The fort's manager orders as facts: id, job type, output item/material, amount total/left, repeat frequency, bound workshop, and per-order validation state. Paged (cap 256) with a cursor.

  • work_order_create(job_type, amount, frequency?, material?, item_type?) — queue a new order; the preview flags would_duplicate and manager_present. Reversal: work_order_cancel.

  • work_order_cancel(order_id) — remove one order by id; the undo handle is a recreate spec (with a faithful flag when a workshop binding or conditions can't be fully restored).

Quickfort blueprints — designate dig/zone from an agent-drafted quickfort CSV. There's no separate read sensor: blueprint_apply without a token is the preview.

  • blueprint_apply(csv, anchor_x, anchor_y, anchor_z, mode) — designate from a #dig or #zone blueprint; the top-left cell maps to the anchor. The dry-run parses quickfort's own stats and previews tiles affected, footprint, and fog-of-war tiles under it (a fact, never blocked). A malformed blueprint blocks with no token (quickfort would partially apply). v1 scope: dig + zone only — build/place are rejected. Reversal: blueprint_undo.

  • blueprint_undo(csv, anchor_x, anchor_y, anchor_z, mode) — revert a dig/zone designation via quickfort's native undo (same csv/anchor/mode). The token signs a per-cell digest, so any per-cell drift voids it.

Labor via work details

  • work_details() — read-only, always available. Every work detail (the game's labor groups): name, mode, the labor tokens it enables, and its assigned citizens (id-sorted, capped at 200 with the full member_count).

  • assign_work_detail(unit_id, detail, enabled) — add or remove one citizen to/from one detail. The preview reports currently_member, resulting_members_count, and only_member; an already-satisfied request previews as a no-op. Reversal: the same call with enabled inverted.

Emergency response

  • burrows() — read-only, always available. Every burrow's size and membership, plus the civilian alert's own state: configured (has the fort ever set one up), active (is it sounding right now), and the linked burrow ids.

  • civilian_alert(burrow, enabled) — add or remove one burrow from the civilian-alert safety set. enabled=true also sounds the alarm if it wasn't already; enabled=false only silences it once the set becomes fully empty. Reversal: the same call with enabled inverted.

  • mechanisms() — read-only, always available. Every lever/pressure-plate's position and linked target(s) (bridge/door/floodgate/hatch/support/weapon-trap), plus unlinked levers and bridges.

  • pull_lever(lever_id, urgent?) — queue a job for a dwarf to pull a named lever (urgent defaults to do-now priority). This queues the job; the physical toggle happens once a dwarf completes it, not on apply. Reversal: pull the same lever again.

  • squad_orders(squad_id, order, ...) — order a squad to move to a tile, kill named units, or cancel its orders. The highest-stakes actuator here: it sends real dwarves into real combat, and the ones who die stay dead. Orders replace rather than stack (DF treats a squad's order list as its whole standing instruction set), so an apply first clears what the squad was already doing. A kill target on an undiscovered tile is refused — targeting it would act on knowledge the fort doesn't have. Reversal: order="cancel", which releases the squad; it does not walk anyone back or un-fight a fight.

Saving the game

  • game_save() — checkpoint the fort with a quicksave before a large or risky change, so a bad batch can be rolled back by loading the save. Takes no arguments; the dry-run previews the fort and game date being frozen. Two facts to know: the write is asynchronous (DF commits it over the next few frames — the readback confirms the quicksave dispatched, not that the file landed) and it routes through DF's autosave, so it lands in a rotating "autosave" folder per your DF settings rather than overwriting the loaded save. Irreversible: to roll back, load the appropriate save/autosave in DF. Fortress mode only.

Running DFHack's own commands

dfhack_command_list shows everything DFHack can do. dfhack_command_run(command, args?, confirm_token?) runs a small, hand-reviewed allowlist of those commands, and only when DFHACK_MCP_COMMANDS=1 is set. That gate is separate from DFHACK_MCP_ACTUATORS, and neither one enables the other. Any other command line returns {"error":"not allowlisted"} and never reaches DFHack.

The allowlist is matched per subcommand:

  • Read-only, run directly: seedwatch [status], instruments [list], prospect [-s <sections>] [-v] (revealed map only; all/hell are refused).

  • Mutating, preview → confirm: enable seedwatch, disable seedwatch, seedwatch <PLANT_ID|all> <target>, seedwatch clear, instruments order <name> [qty]. DFHack has no dry-run for these, so the preview reports the state the command acts on. The apply result reports the undo: the prior seedwatch targets to restore, or the created manager order ids to cancel with work_order_cancel.

The full allowlist, with each entry's safety note, is in docs/tools/dfhack_command_run.md.

Configuration

All optional, set in your MCP client's env for the server:

Variable

Default

Effect

DFHACK_HOST

127.0.0.1

Host where DFHack's Remote RPC is listening.

DFHACK_PORT

5000

Port for DFHack's Remote RPC.

DFHACK_MCP_ACTUATORS

(unset)

Set to 1 to expose the write actuators (off = strictly read-only).

DFHACK_MCP_COMMANDS

(unset)

Set to 1 to expose dfhack_command_run, which runs an allowlist of DFHack's own commands (separate from the actuator gate).

DFHACK_MCP_DEV

(unset)

Set to 1 to expose run_lua, a raw DFHack Lua escape hatch (reads and writes game state; for tool authors only).

DFHACK_MCP_QUERY_DIR

src/dfhack-queries/ (dev) / dist/dfhack-queries/ (bundled)

Overrides the directory from which the MCP query scripts are loaded.

DFHACK_MCP_TIMEOUT_MS

30000

Per-call deadline, in milliseconds, for each DFHack RPC call. A call that misses it returns TIMEOUT, resets the connection, and is never retried.

Errors

Every error payload carries a stable, machine-readable code next to the human-readable error message, so a client can tell the states apart without matching message text:

{ "error": "no fort loaded", "code": "NO_FORT" }

code

Meaning

NOT_CONNECTED

DFHack could not be reached, even after one reconnect attempt.

NO_FORT

DFHack is reachable, but no fort is loaded.

NO_GAME

No world is loaded at all (game_data).

NOT_FOUND

The id you passed (a unit, a historical figure) does not exist.

INVALID_ARGUMENT

The call was well-formed, but the arguments or the game state reject it (for example, a stale confirm_token, or a command outside the allowlist).

TIMEOUT

DFHack accepted the call but did not answer within DFHACK_MCP_TIMEOUT_MS. The call is not retried, so it may have partly run.

SCRIPT_ERROR

The query script or DFHack command ran and failed.

NOT_CONNECTED, TIMEOUT, SCRIPT_ERROR and the actuators' INVALID_ARGUMENT come back as MCP tool errors (isError: true). The others (the no-fort guard, a missing id) are ordinary tool output. Arguments that fail a tool's input schema are rejected by the MCP SDK before the tool runs, as plain text with no code.

Troubleshooting

  • {"error":"no fort loaded","code":"NO_FORT"} — DFHack is reachable but you're at the title screen or in the menus. Load a fort in Fortress mode.

  • "code":"TIMEOUT" — DFHack is reachable but did not answer in time (the game is hung, a modal dialog is open, or a long save is running). The next call reconnects. Raise DFHACK_MCP_TIMEOUT_MS if your fort is large enough that a normal call takes longer than 30 seconds.

  • An error about not reaching DFHack — Dwarf Fortress isn't running with DFHack, or the RPC port differs. Confirm DF is up with DFHack and that DFHACK_HOST / DFHACK_PORT match (defaults 127.0.0.1:5000).

  • The tools don't show up in your client — restart the MCP client so it relaunches the server; a running server won't pick up a config change.

  • The write tools are missing — that's the default. Set DFHACK_MCP_ACTUATORS=1 (see Taking action).

  • dfhack_command_run is missing — it has its own gate. Set DFHACK_MCP_COMMANDS=1 (see Running DFHack's own commands).

  • First call after loading a fort errors once, then works — a freshly-started DFHack can reject the very first tool call while it finishes registering the query scripts; retry once.

Development

To hack on the server itself, clone and run the TypeScript entry directly (Node 24+ — it runs the sources via type-stripping, no build step):

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

Point an MCP client at the checkout with "command": "node", "args": ["/absolute/path/to/dfhack-mcp/src/index.ts"].

All version-fragile DFHack field access lives in real .lua scripts under src/dfhack-queries/ (one per tool), invoked by name with native argv — so a DF/DFHack version bump is a localized fix and query parameters are injection-safe by construction. Each tool is a thin TypeScript wrapper in src/tools/.

Facts, not advice. Tools sense — they return what is true about the fort and the world, the way a player reads a screen. They do not say what to build or how to fight; that judgment is the agent's. A field that says what to do is advice — leave it out.

Every tool is verified against a live fort with the tiered harness (npm run verify:t0 … t2) — never mocks. See CONTRIBUTING.md for the tool-authoring split and the verification workflow, and docs/VERIFY.md for the harness tiers.

License

ISC — see LICENSE.md.

Available Tools

37 tools
artifacts_and_engravingsArtifacts and engravingsA

The fort's art, as labeled facts. Returns the named ARTIFACTS (paginated), SITE-SCOPED BY DEFAULT — only artifacts belonging to the loaded fort, which is almost always what is meant by "our artifacts". Pass scope="world" for every artifact in the world (an old world holds hundreds that have nothing to do with your fort; in world scope each row carries site_local so the two are still distinguishable). artifact_count always reflects the scope actually applied, and artifact_count_world always gives the unfiltered world total. Each artifact carries its name (dwarven + translated), item type and base material, created value, quality, maker (with a live unit_id ONLY when the maker is a living current citizen, else just the historical-figure name), the decorations on it (bands/covered/rings/images with their materials), and any engraved inscription text (e.g. a slab's secret). Plus an aggregated ENGRAVINGS summary for the map: engravings grouped BY SUBJECT with counts (never itemized per tile), a quality histogram, and the top engravers. IMPORTANT precondition on engraving subjects: DF does not populate the world's art-image table in fortress mode (art_images_loaded is false on every fort observed so far), so the human-readable scene an engraving depicts is NOT available — subjects_resolvable=false and each subject is keyed by its stable image reference ("image #2:158") instead. This is reported, never fabricated, but do not plan on describing what the fort's art depicts: the engraving read is reliable for counts, quality distribution, and which dwarves did the engraving, not for iconography. Use limit + next_cursor to page through artifacts; see caps for all documented limits. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: limit, scope, cursor.

burrowsBurrowsA

The fort's burrows as facts: each burrow's id, name, exact tile_count (dfhack.burrows.isAssignedBlockTile summed over every assigned block — the precise painted area, not a bounding box), assigned_units (citizens/animals manually confined to it, id-sorted and capped at 200 — assigned_units_total is always the full count and assigned_units_truncated flags when capped), and civilian_alert_linked — whether this burrow is currently one of the safety burrows for the civilian alert (see civilian_alert). civilian_alert reports the alert's own state: configured (has the fort ever set up a civilian-alert slot — false on a fresh fort), active (is it sounding right now — civilians already fleeing to the linked burrow(s)), and burrows (the linked burrow ids). Pairs with the civilian_alert actuator, which toggles a named burrow in or out of this set. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

chronicleChronicleA

The fort's announcement/report stream (combat, deaths, moods, artifacts, sieges, migrants, ...) as triaged, cursor-addressable events. Reads the rolling, front-pruned report window. Each event carries a stable id (monotonic and save/load-stable); pass the returned top-level cursor back as since to fetch only newer events (id > since). Omitting since returns the most recent limit events (default 50, max 200), oldest-to-newest. If since predates the retained window the response sets pruned:true (earlier events are gone — not silently omitted). Events are triaged into categories (death, birth, marriage, battle, siege, mood, artifact, migrants, diplomacy, cave-in, megabeast, other); filter with categories. Combat spam is tamed: repeat_count is honored, wrapped continuation lines fold into their event, and long consecutive battle runs collapse into a single marker (collapsed:true with collapsed_count) so one siege cannot flood the window — see battle_collapsed. Facts only: unit refs appear only when a report names a speaker (speaker_id != -1); combat reports carry no reliable unit, so they get a pos tile anchor instead. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: limit, since, categories.

citizenCitizenA

A deep dossier on ONE citizen, chained by unit_id from find_unit (or chronicle). Where find_unit stays compact, this is the depth: the walkable social graph (spouse, parents, children, friends, grudges — each with a unit_id you can pass back into citizen() to walk the graph), worshipped deities with worship strength, NOTABLE personality extremes (only the top/bottom facets, not the full 50-facet dump), skills of note, likes/detests, physical highlights, and recent thoughts as the game phrases them (raw caption templates that may contain unfilled [quality]/[deity]/[relation] placeholders, surfaced verbatim), tied to current stress. Friends are positive-affection acquaintances; grudges are bonds gone negative with no positive love to offset them (each carries its raw love/trust/respect scores plus negative_dims naming the negative dimensions, as labeled facts). Empty categories degrade to []. Facts only — it senses, it does not advise. Returns {"error":...} for a missing unit_id or {"error":"no fort loaded"} if no fort is active.

Inputs: unit_id (required).

defensesDefensesA

Where the threats are versus what you have to fight them with. Returns active hostiles the fort has DISCOVERED (same fog-of-war gate and same count as threats()' active_hostiles and military()'s hostiles_on_map — a unit standing on an undiscovered tile is never listed and never leaks its position or creature token) with map positions and their geometry to the fort core and to the nearest drawbridge (dist = 8-directional tile count (Chebyshev), dz = z-levels with + meaning above the threat, dir = compass bearing; the nearest bridge is chosen on 3D distance, so a bridge many z-levels away never wins on horizontal proximity alone), plus an inventory of controllable defensive structures (drawbridges with positions, levers, floodgates, hatches, cage traps, locked doors). Terrain-aware: each threat is classified inside/outside the fort's walled perimeter — "inside" means its tile shares a walkability group with your citizens, i.e. a hostile could walk to your population through connected open space without breaching a wall (walk_group 0 = no walkable footing, e.g. a flier over open air). A perimeter_terrain field reads the busiest citizen level via the terrain substrate: an ASCII tile grid (with legend) plus counts of walls, fortifications (with positions), and open-to-sky vs covered vs undiscovered tiles. Facts only — decide the tactics yourself, and use identify() for a creature's trait facts (e.g. cage traps do not hold a TRAPAVOID creature). Caveats: inside/outside is walking connectivity, so a FLIER or BUILDING_DESTROYER can reach you while reported "outside" — cross-reference its traits. perimeter_terrain is a single z-level and does not synthesize a multi-z approach vector; undiscovered tiles are fog of war ("?") and never leak their real type. Which lever raises which bridge is not recorded in the raws, so bridges and levers are reported separately, not linked. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

environmentEnvironmentA

The fort's ambient conditions right now: current season and dominant weather (none/rain/snow), the surface temperature with whether exposed water is currently frozen (the freezing point is 10000 DF units; composes with geology()'s freeze-in-winter fact), the alignment of the biomes visible at embark (evil / good / reanimating booleans), and — for each cavern the fort has ALREADY breached — whether it is open to fort pathing or sealed off. Fog-of-war honest: reports NOTHING about undiscovered cavern layers (a fort that has breached none returns an empty caverns list). Small fixed-size payload. Per-tile savagery is unavailable in this DFHack build, so no savage flag is reported. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

farmingFarmingA

The fort's farm plots and seed stock as facts — the early-survival pipeline that stocks (food OUTPUTS) and game_data (what is plantable, in the abstract) don't cover. Each plot's tile size, whether it's open to the sky right now (open_to_sky — light/weather exposure, NOT a surface-vs-underground fact: a roofed surface plot is open_to_sky:false, indistinguishable here from a genuinely underground one), its crop assignment for each of the 4 seasons (SPRING/SUMMER/AUTUMN/WINTER; crop is the plant token or absent if that season is fallow), whether that crop is eligible to grow in that season (the plant raw's own season flag — absent when the season is fallow). no_crop_assigned flags a plot with no crop assigned in ANY season; no_eligible_crop flags a plot with no season holding BOTH an assigned crop AND eligibility (a strict superset of no_crop_assigned — a plot can have crops assigned yet still qualify if none of them are actually eligible for their season). seed_totals[]/seed_totals_count/seed_totals_truncated sums seed counts by plant across the whole fort (forbidden/dumped/rotten/trader-bound seeds excluded, capped at 100 distinct plants) — the single source for seed stock; join a plot season's crop token against it rather than looking for a per-plot seed count, which would just repeat the same fort-wide number under every plot growing that crop. plots[] is capped at 200 (plots_total/plots_truncated track the real count and any overflow). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

find_unitFind unitA

Look up citizens by a name fragment or profession (case-insensitive, matches either). Returns a compact dossier per match: profession, age, stress level, current job, squad, and health flags (wounded/patient/unconscious). Useful for questions like "how is the chief medical dwarf" or "find Urist". Each match carries a unit_id — pass it to citizen() for a deep dossier (personality, the walkable social graph, worship, skills, preferences, recent thoughts). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: query (required).

fluidsFluidsA

Water and magma engineering facts the Earthworks tier (tile_region, geology) does not cover: aquifer layers, standing/flowing water, the magma sea's top, flood exposure at the fort interior, and well water-source depth. Revealed-only, fog-of-war safe — undiscovered tiles never contribute to any field here, the same as tile_region/defenses. aquifer_layers[] groups contiguous revealed z-levels sharing the same light/heavy classification (a mix of both within a run of z-levels reads "mixed") with light_tiles/heavy_tiles tile counts (capped at 50 layers). water_layers[] is a per-z-level aggregate of revealed standing/flowing water tiles (tiles, salt_tiles/fresh_tiles, stagnant_tiles/flowing_tiles, max_depth 1..7) — NOT flood-filled into discrete named bodies (no connectivity analysis is attempted; a single lake spanning two z-levels appears as two rows) — capped at 200 z-levels. ice_layers[] is the frozen peer of water_layers[]: a per-z-level count of revealed ICE tiles (walkable_tiles = ice you can stand on, e.g. a frozen river surface; solid_tiles = ice wall you would have to mine; the two always sum to tiles), capped at 200 z-levels. Frozen water is NOT water as far as the engine is concerned — it has no flow and becomes a solid tile — so a river or brook that freezes over DISAPPEARS from water_layers[] entirely and shows up here instead. A fort reading water_layers: [] alongside a populated ice_layers[] has surface water that exists but is frozen, which is also when wells report source "frozen" and jobs cancel for "No water source". magma_sea is the highest revealed z-level with at least 20 revealed magma tiles (a size floor meant to separate a real magma sea from a small pool/volcano pipe), omitted (not a null field) if no such level is revealed. flood_risk_tiles[] lists revealed FULL-depth (max_depth 7/7) water tiles chebyshev-adjacent to a tile in the same walkable group as any citizen — a flood-EXPOSURE fact (this water sits next to fort-reachable space right now), not a prediction of whether or when it floods anything; capped at 50 (flood_risk_total/flood_risk_truncated track the real count). wells[] extends rooms_and_zones' well read with each well's x/y and the water source found scanning down from it (source: water/magma/frozen/unknown, depth_to_source in z-levels; depth_to_source is absent if the source is unknown or the scan hit a hidden tile first) — capped at 20. scan.complete is false if the fort-wide tile budget was hit before reaching z=0 (scan.last_z_scanned marks where it stopped); every field above is still fog-of-war-safe when that happens, just possibly missing deep layers. Facts only — no dig/pump/floodgate recommendations. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

fort_healthFort healthA

The fort's computational health as facts — FPS death is the true endgame boss, and nothing else reports it. fps/gfps are the engine's own currently calculated simulation/graphics frame rates (df.global.enabler.calculated_fps/calculated_gfps — the same numbers DF's own FPS counter shows), not an average or a history. items.total is the fort-wide item-object count (df.global.world.items.all, unfiltered by forbidden/dump/rotten/construction state — every item DF is tracking counts toward this, since object count, not usable stock, is what costs simulation time); items.stone/corpses/clothes break out the three clutter candidates the issue names (stone: BOULDER; corpses: CORPSE + CORPSEPIECE + REMAINS; clothes: the wearable slots ARMOR/SHOES/HELM/GLOVES/PANTS) — these are raw totals and will run higher than stocks' counts, which filter to usable/in-play items only; the two answer different questions (clutter vs usable stock) and are not duplicates. units.active/units.dead_on_map split df.global.world.units.active by isDead — active is every currently-simulated living unit (citizens, tame animals, wildlife, hostiles, visitors), dead_on_map is a dead unit whose body hasn't yet been cleaned up into a corpse item; both are fog-of-war filtered (mcp_unitVisibility), like every other unit-enumerating tool in this server, so an undiscovered cavern's unrevealed population is never counted here even though it still costs real simulation time — this tool intentionally undercounts true computational load rather than leak an unexplored area's population as an aggregate number. Stray/unassigned animal count is intentionally NOT duplicated here: call livestock_and_pastures and read its unassigned_count. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

fort_statusFort statusA

One-call situational overview of the currently loaded Dwarf Fortress fort: name, in-game date and season, population, created wealth, a happiness breakdown (miserable/unhappy/content/happy), recent_deaths, and a pre-triaged list of alerts worth attention. recent_deaths covers deaths recorded AT THIS SITE within the last game year: how many were the fort's own citizens, what killed them (citizen_causes, e.g. THIRST/STARVATION/STRUCK_DOWN), how many of those citizens were slain BY another citizen (the murder/loyalty-cascade signal, which no other tool reports), and how many of the dead were outsiders rather than fort members. Citizenship is the victim's membership in the fort group, so another civilization's dwarves killed at your gate count as outsiders, not as your losses. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

game_dataGame dataA

Look up the LOADED WORLD's raws (ground truth for THIS world) and return curated, labeled facts. This is the authoritative source for procedural creatures (demons, forgotten beasts, titans) that never appear on the wiki. Covers six kinds via the kind filter (default creature): creature, material, plant, reaction, item, building. Pass a token (e.g. "DEMON_4", "INORGANIC:IRON", "MAKE_SOAP_FROM_TALLOW"), a name (case-insensitive substring, e.g. "flame phantom", "plump helmet"), or — for creature — a live unit_id (all digits). A single strong hit returns a full dossier for that kind; several return a disambiguation list; none returns {"match_count":0,"matches":[]}. Returns {"error":"no game loaded"} if no game is active.

Inputs: query (required), kind.

geologyGeologyA

A one-call geological survey of the embark, REVEALED-INFO ONLY by default. Returns surface_z_max — the highest open-to-sky ground z-level found ANYWHERE on the embark (NOT map_overview()'s surface_z_at_core, which is the surface directly above the fort centre only; on a sloped map the two legitimately differ by many z-levels); the layer stack the fort has exposed (each band z_top..z_bottom with a kind — soil/sedimentary/metamorphic/igneous — and the in-game material names, e.g. "limestone", that game_data/wiki_lookup resolve); the aquifer (presence, light vs. heavy type, and z-range, enough to fuse with wiki_lookup("Aquifer")); the caverns actually DISCOVERED (each with z-range and whether it holds water); whether the magma sea has been reached; and surface water (brook, river, murky-pool count, and permanent_freeze — whether the biome's base temperature keeps surface water frozen year-round, glacier/tundra, the well-gating fact; not a seasonal winter claim). Undiscovered caverns and an unreached magma sea are OMITTED (fog of war stays honest). Set reveal_hidden=true to BYPASS FOG OF WAR and also surface every undiscovered cavern (caverns_hidden) and the magma sea z-range (magma_hidden) — a debug/spoiler switch, default false. Reports what is there, not where to dig. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: reveal_hidden.

hauling_routesHauling routesA

The fort's minecart hauling infrastructure: routes, each route's stops, and the vehicle (minecart) objects fort-wide. routes[] is {id, name?, stops[], vehicles[]}. Each stop is {id, name?, pos:{x,y,z}, stockpiles[], conditions[], parked_vehicle_id?} — stockpiles[] is {building_id, take, give} for every stockpile linked to that stop (take = the cart picks items up from that stockpile, give = the cart drops items into it; a link can be both). conditions[] is that stop's departure conditions — {direction, mode, timeout, load_percent, at_most, desired} — mode is how a dwarf moves the cart onward (Push/Ride/Guide), direction is the initial departure heading, and at_most/desired describe the load_percent threshold that must be met before the cart leaves. parked_vehicle_id is the vehicle currently sitting at that exact stop right now, absent if none is. A route's own vehicles[] ({vehicle_id, current_stop_id?}) is the set of vehicles assigned to run that route — DF assigns vehicles at the route level, not per stop; current_stop_id is which of that route's own stops the vehicle currently occupies, absent if in transit or unknown. The top-level vehicles[] is every hauling vehicle fort-wide (minecarts and other cart- type haulers; battering rams excluded) as {vehicle_id, item_id, backing_item_exists, route_id?, on_track} — backing_item_exists is whether the vehicle's backing item still exists (a vehicle can persist as a stale reference after its physical cart is destroyed or stolen, regardless of whether it is assigned to a route); route_id is absent for a vehicle not currently assigned to any route. Both routes[] (capped 100, see routes_total/routes_truncated) and the top-level vehicles[] (capped 200, see vehicles_total/vehicles_truncated) are sorted by id. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

identifyIdentifyA

One-call "what is this creature and how do I handle it": fuses THIS WORLD's raws (ground truth) with the DF wiki (strategy). Pass a creature token (e.g. "DEMON_4"), a name ("flame phantom"), or a live unit_id (all digits) — same contract as game_data. Returns the creature dossier (flags, attacks, interactions — e.g. a TRAPAVOID flag means cage traps cannot hold it) plus 1-2 trimmed wiki strategy excerpts. Procedural creatures (demons, forgotten beasts, titans) have no wiki page, so strategy leans on their traits plus the most relevant trait page (fire, building destroyer). Use this instead of a bare wiki lookup so world-specific facts are never missed. Multiple matches return a disambiguation list; returns {"error":"no game loaded"} if no game is active.

Inputs: query (required).

injuries_and_healthInjuries and healthA

The fort's medical picture, counted on CURRENT condition rather than on history. wounded = dwarves carrying at least one wound with live damage (bleeding, pain, swelling, an unset fracture, a severed part, infection). old_wounds_only = dwarves whose every wound has resolved to a scar or to an inert record — DF never deletes a healed wound, so these keep a wound entry forever and are NOT casualties. patients = dwarves the game itself flags as needing healthcare, bedridden = flagged should-not-move. unconscious counts only genuine unconsciousness: a normally SLEEPING dwarf also carries a nonzero unconscious counter, so sleepers are excluded and reported as asleep instead. care_needs breaks down what care the game is asking for (diagnosis, surgery, suture, dressing, crutch, ...) so gaps in medical coverage are visible; it is empty when no dwarf currently needs care. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

jobs_and_laborJobs and laborA

Workforce utilization: how many working-age dwarves are busy vs. idle (children/babies excluded from the labor pool), the idle percentage, and a ranked breakdown of what jobs the fort is currently working on. High idle can mean unassigned labor or nothing queued. cancellations aggregates recent job-cancellation OCCURRENCES (the currently-retained report buffer, roughly the last few months of play) by their reason text, sorted most-frequent first — counting occurrences, not report rows: DF collapses consecutive identical cancellations into one report and tallies the extras separately, so a reason repeating many times (e.g. "Equipment mismatch") is weighted by its true frequency, not undercounted as a handful of rows. chronicle sees the same announcements one at a time but never aggregates them. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

livestock_and_pasturesLivestock and pasturesA

The fort's tame animal economy as facts — every prior tool sees hostiles (threats) or nothing at all here. tame_total/pets/livestock split ownership; by_group[]/by_group_total/by_group_truncated count tame animals by species/sex/adult-or-not, capped at 100 distinct combinations. grazers reports total vs pastured, plus the individual animals NOT in any pasture zone — a grazer with no pasture cannot graze and silently starves; this is normally invisible (juveniles graze too, so grazer status is NOT gated on adulthood). egg_layers reports counts only (total, fort-wide nestbox count, how many are pastured without a nestbox in reach, how many are unpastured) since the consequence (missed eggs) is mild and the population is usually large — gated on adulthood (a juvenile of an egg-laying caste cannot actually lay yet, matching DFHack's own autonestbox behavior). marked_for_slaughter and trained (training_level Trained..MasterfullyTrained — DF's single shared training-quality scale, NOT which discipline the animal was trained for; it does not persist war-vs-hunting per animal) list individual animals, capped. cages[]/cages_truncated lists occupied cages with their occupants (dfhack.buildings.getCageOccupants); each cage's own occupants[] is independently capped too (occupants_total/occupants_truncated), so a single densely-packed cage trap can't inflate the response either. unassigned_count is animals with no pasture, cage, or chain — DFHack's zone tool calls this "unassigned" (roaming loose); reported as a count only since it is commonly large and often intentional (e.g. free-roaming cats). Every unit fact here is gated through the fog-of-war visibility check — an undiscovered cavern's wildlife never leaks in. The tame-animal enumeration (tame_total/pets/livestock/by_group/grazers/egg_layers/marked_for_slaughter/trained/unassigned_count) is ADDITIONALLY restricted to this fort's own civ, so a caravan's or diplomat's pack animal is excluded; cages[].occupants[] intentionally skips that restriction — a cage's contents (which may include a captured wild or hostile creature) are a structural fact independent of ownership, still fog-of-war gated. The tame-animal enumeration also requires isActive/not isDead (a dead animal's unit record never counts). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

mandates_and_justiceMandates and justiceA

The fort's nobility overhead as facts. Active production mandates (a noble's make-N-of-an-item quota with its remaining count and days to deadline) and export bans, listed by item. Unmet noble room demands (an appointed noble holds no room zone of a type their position requires: office, bedroom, dining, tomb). Justice state: open criminal cases, convictions awaiting punishment (prison sentences, scheduled beatings and hammerstrikes), and restraint capacity (chains + cages actually CONSTRUCTED vs. how many are free, with placed-but-not-yet-built ones counted separately in restraints_unbuilt) so you can see whether a sentence can be served. Reports what the nobles demand and the justice backlog, not what to build about it; threshold restatements are in alerts. Lists are capped (see the *_truncated flags). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

map_overviewMap overviewA

Cheap spatial orientation to run BEFORE any per-tile terrain read: map extents (x/y/z tile counts), the fort-core coordinate (the same 3D citizen centroid defenses() reports), surface_z_at_core — the surface z-level directly above the fort center, i.e. the highest open-to-sky ground tile in THAT ONE COLUMN, or null if the core is not under open sky (this is NOT geology()'s surface_z_max, which is the highest open-to-sky ground tile anywhere on the embark; on a sloped map the two legitimately differ by many z-levels, so pick the one you mean) — the z-levels that carry player activity (construction and pending digging, listed separately and as a union), and stairways collapsed to traversable single-column vertical runs (x, y, z_top, z_bottom); a run only spans levels that actually connect by DF stair rules, so a helical shaft splits into its climbable segments. The payload is fixed-size regardless of fort size: activity is a set of z-levels, never per-tile, and stair columns are RANKED BY HEIGHT (tallest run first) then capped, so when a fort exceeds the cap the tallest shafts survive and only trivial fragments are dropped (stair_columns_truncated flags the overflow; stair_columns_total gives the full count). Fog-of-war honest: undiscovered tiles never leak. Use it to decide which z-levels and area to pull grids for. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

mechanismsMechanismsA

The fort's lever/pressure-plate wiring as facts — players (and an AI co-pilot) routinely forget which lever raises which bridge; this makes it legible. levers[] lists every lever with its position, current state (0/1 — the physical orientation, NOT which way any linked gate is), linked_targets (every building its mechanism items connect to — bridge/door/floodgate/hatch/support/weapon-trap — with that target's id, type, position, and a state string (raised/lowered/raising/lowering for a Bridge, closed/open/closing/opening for a Floodgate, closed/open (no transitional state) for a Door/Hatch, retracted/unretracted/retracting/unretracting for a Weapon spike) when the target exposes one), and pending_pull_jobs (PullLever jobs already queued on it, so a caller can see a pull is already in flight before queuing another). pressure_plates[] lists every plate's linked_targets the same way, plus triggers — the configured trip conditions (citizens, creatures with a weight range, a minecart-weight range on track, or water/magma depth ranges). unlinked_levers is the ids of levers wired to nothing (dead ends); unlinked_bridges is bridges no lever or plate in the fort currently operates (must be hand-opened/closed, or are permanently fixed). levers[]/pressure_plates[]/unlinked_levers[]/unlinked_bridges[] are each capped at 200 (id-sorted) with their own *_truncated flag — lever_count/plate_count/bridge_count are always the true totals regardless of truncation. Pairs with the pull_lever actuator. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

militaryMilitaryA

The fort's military: number of squads, how many living present dwarves are actually enlisted (soldiers), filled squad positions, and readiness read against hostiles currently on the map (great-danger split out). Each squad also reports: roster[] — one row per FILLED position whose occupant is a LIVING, PRESENT unit (a dead or off-map holder still counts toward filled but is omitted here, so gear sitting on a corpse never generates a false alert) — that soldier's uniform_complete flag, and (only when incomplete) uniform[], aggregated by item type (ARMOR/HELM/PANTS/GLOVES/SHOES/SHIELD/WEAPON/...) into assigned_count (items the uniform calls for — a required-but-never-found item still counts as 1) vs missing_count (of those, how many are not currently worn/wielded — DF's own uniform-unstick logic, or never assigned at all) — this is the tool-API spec's originally-promised "equipment_gaps" (e.g. "8 of them have no armor"), previously unfulfilled; a fully-equipped soldier's uniform[] is empty (uniform_complete says so already) to keep the payload proportional to actual gaps, not fort size. ammo — the squad's configured ammunition specs (item type, target_amount — the squad's shared configured total, NOT per-soldier — and how many are currently assigned) and ammo_items_assigned, the total ammo items currently carried by the squad; training — the active training-schedule month's sleep_mode, uniform_mode, and active_orders (both undefined/empty when the fort has never customized that routine's month). alerts also flags any roster member with an incomplete uniform by name. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

moodsStrange moodsA

Any active strange mood (fey/secretive/possessed/macabre/fell) and its material countdown. For each moody dwarf: the mood type, the driving skill, the workshop claimed (or that none is yet, via workshop_status: unclaimed/gathering/working), the raw mood countdown, and every demanded material cross-referenced against fort stock — needed, gathered so far, and how many the fort actually has (have). The early warning is "demands bones, fort has zero": it reports the demand vs. the stock, not what to go collect. Returns {"active":[]} when no strange mood is in progress (the common case), and {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

nobles_and_administratorsNobles and administratorsA

The fort's appointed positions (manager, bookkeeper, broker, chief medical dwarf, sheriff, expedition leader/mayor, militia commander/captain, hammerer, and any higher noble the site has grown into) as facts: each position's holder(s) or vacancy — each holder always carries histfig_id, plus unit_id when that historical figure has a loaded unit on this map (a holder living off-map still has no unit_id). A vacant position is a common, otherwise-invisible cause of "why won't this validate" — work_order_create needs a manager, trade needs a broker, mandates_and_justice punishments need a hammerer. superseded_by names the position a role hands its responsibilities to once filled (e.g. sheriff -> captain of the guard, expedition leader -> mayor) — a vacancy there is often expected, not a problem. Also reports the bookkeeper's precision level (0-4, higher = more accurate stock counts, set on the Nobles screen), whether a mayoral election is currently forced/pending, and whether the civilization's monarch has arrived at the site (and if so, hastily). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

petitionsPetitionsA

The fort's outstanding agreements as facts: location petitions (temple/guildhall requests from a deity's worshippers or a guild) and residency/citizenship petitions (a migrant or visitor asking to join the fort), each with its petitioner, agreed date, and resolution status. location_petitions[] carries building (TEMPLE/GUILDHALL), tier (1 = temple/guildhall, 2 = complex/grand), the petitioning deity (temple) or guild profession (guildhall) when one was named, age_days since the petition was raised, and warned_ready (the fort has already been told the location can be established — a still-outstanding petition with warned_ready true is the classic silent-failure case: agreed to but never actually zoned). residency_petitions[] carries kind (Residency/Citizenship), age_days, and deadline_days (days left before the petitioner's patience runs out, null if no timeout is tracked). Both carry awaiting_decision (true if the petition sits in the fort's pending decision queue right now) and status (outstanding/satisfied/denied/expired, derived from the agreement's own flags — see the doc for how this maps to DFHack fields). This is the demand-fulfillment counterpart to rooms_and_zones's temple/guildhall inventory (needed_by_worshippers there is inferred from citizen worship with no formal petition yet; a row here is an actual agreement DF is tracking) — compose the two rather than expecting either to duplicate the other. Lists are capped at 50 each (see the *_truncated flags). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

rooms_and_zonesRooms and zonesA

The fort's facility inventory, each count paired with its demand-side number where one exists: bedrooms (assigned/unassigned vs. adults without one), dining halls and seats, the hospital (beds, traction benches, whether a well is inside, and medical supplies physically stocked), wells (working state and water source: water/frozen/magma/unknown), temples (dedicated deities, whether an all-inclusive temple exists, and deities worshipped by citizens that lack a dedicated temple), taverns, libraries, guildhalls, and coffins free vs. dead awaiting burial (loose corpses of the fort's own race). ghosts reports active apparitions currently on the map (active[], fog-of-war gated) plus unquiet_dead_count — this civ's dead who are world-flagged as unquiet ghosts (flags.ghost) and NOT represented in the visible active[] list. This is deliberately not the same as "confirmed absent locally": a ghost hidden behind fog of war is excluded from active[] (never leaked) but still counted here, since the world-level ghost fact is fair game even when its exact location isn't. The supply-side companion to unmet_needs(). Reports what the fort has, not what to build. Wells are capped (wells_truncated flags the overflow); bedroom and coffin detail is aggregated to counts. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

site_historySite historyA

This fort's entry in the PERMANENT world saga (the durable history event log, not the pruned live report stream). Returns the founding (year, in-game date, and owning civilization in both Dwarven and English), the fort name in Dwarven and English with a word-by-word etymology, prior sieges/battles fought AT this site (attacker/defender civ and general, capped at 20, most-recent-first), and the notable historical figures who died here (name, race, cause, slayer, capped at 25). Scoped strictly to the loaded site. A young fort with no war history degrades to empty battle/death lists (not an error). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

stockpilesStockpilesA

The fort's hauling/logistics picture: every stockpile as a fact sheet, plus fort-wide backlog signals stockpiles alone don't surface. piles[] is one row per stockpile building: id, exact bounds (x1/y1/x2/y2/z — the bounding box; an irregularly-shaped pile's real footprint can be smaller, see size), size (the pile's real tile count — for an irregular pile this reads its room.extents occupancy map rather than the bounding box, so holes/excluded tiles are correctly excluded), categories[] (which of the 17 top-level stockpile groups this pile accepts — animals/food/furniture/corpses/refuse/stone/ammo/coins/bars_blocks/gems/finished_goods/leather/cloth/wood/weapons/armor/sheet; note Ore has no flag of its own in DF's own stockpile_group_set — it rides under stone — and Misc (organic/inorganic) is a refuse sub-filter, not a top-level category, so neither appears in this list), barrels_allowed/bins_allowed (the pile's max_barrels/max_bins > 0 — DF stores 0 there specifically to mean "no containers of this kind," not "unlimited"), max_wheelbarrows (raw count; 0 here means no wheelbarrow is assigned so DF queues one haul job per item, NOT "wheelbarrows disallowed" — this one has no allowed/disallowed reading, unlike barrels/bins), links_only (DF's own "take from links only" toggle), give_to[]/take_from[] (ids of stockpiles this pile explicitly feeds into / pulls from via the g/q-t hauling-route UI, each capped at 50 with its own _truncated flag), item_count (exact count of non-rotten/non-dump/non-forbidden/non-construction/non-trader items physically sitting on the pile's tiles right now — via each item's resolved position, so items inside a bin or barrel parked on the pile count too — regardless of whether the pile's own categories[] actually accept that item, since this is a positional fact, not a settings-compliance check), and occupied_tiles (how many of the pile's size tiles have at least one qualifying item on them right now — a directly-counted fact, bounded [0, size], NOT a percentage or a capacity estimate: an earlier draft derived a fullness_pct from a placeholder items-per-tile constant that produced numbers with no real relationship to DF's actual per-tile capacity (which varies by item size and container packing — a barrel-heavy tile can hold far more than one item) and was dropped as a fabricated fact; occupied_tiles/size is a defensible coverage ratio if you want one, but it is spatial coverage, not capacity headroom). Fort-wide: unstored_backlog[] groups loose items (on the ground, not rotten/dump/forbidden/under-construction/trader-owned, and not sitting on ANY stockpile's tiles) by their raw DF item type token, with unstored_backlog_item_count as the grand total and a 150-distinct-type cap; this is the hauling backlog the issue asks for. rotting_outside_stockpiles is the same idea for the ROTTEN subset specifically (food/organic matter that has already decayed while lying outside any stockpile, i.e. hauling arrived too late) — {count, by_type[], by_type_truncated}. dump_flagged_count is an exact, unfiltered count of every item currently designated for dumping, wherever it sits. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

stocksStocksA

Food and drink as estimated days-of-supply for the current population, plus counts of critical materials (wood, fuel, cloth, tanned hides, stone) and lists of notably low or high stocks. Days-of-supply assume ~2 food and ~5 drink per dwarf per season. clothing reports the citizens wearing worn (wear >= 2 — "X" heavily-worn/threadbare, or "XX" tattered/mangled; DF's own 4-stage scale is item -> x-item-x -> X-item-X -> XX-item-XX -> destroyed) shoes/armor/pants/gloves/helm — a chronic, easy-to-miss stress source — and how many citizens currently have no shoes worn at all (a count, since the population involved is usually the whole fort). Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

threatsThreatsA

Dangerous units currently on the map, grouped by creature type. Separates ACTIVE hostiles from CONTAINED ones (caged/chained), flags great-danger creatures (megabeasts, titans, demons, forgotten beasts), invaders, and the undead, and returns a pre-triaged alerts list. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

tile_regionTile regionA

A bounded window of ONE z-level rendered as an ASCII character grid plus a self-describing legend (every response carries the legend for exactly the glyphs it uses). Renders terrain shape (undug stone #, undug soil ",", dug floor ., ramps r/v, up/down stairs </>/x, fortifications F, trees T), constructed floor +, water ~ and magma %, and building footprints collapsed to FOUR CLASSES — workshop/furnace W, stockpile S, machine M, furniture n — never per-building detail. The grid glyph is depth-blind; a separate sparse liquids list carries per-tile [{x,y,type,depth}] (flow_size 1..7). Undiscovered tiles are ? (fog of war) and are NEVER painted over. All five parameters are OPTIONAL: with none, returns a fixed DEFAULT 60x40 window centered on the fort core (the busiest citizen z-level and that level's citizen centroid); pass z alone to recenter on THAT level's own citizen centroid; pass z,x0,y0,x1,y1 for an explicit rectangle. The window is hard-capped at 100x100 per side — an oversized request is CLAMPED (never errored) with truncated:true and the original size echoed in requested. Facts only: it renders the map, it does not design or suggest layouts. Read-only. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: z, x0, x1, y0, +1 more.

tradeTrade and caravansA

The trade picture right now: whether a trade depot exists, is complete, and is wagon-accessible (DF's own pathability check, not merely built); which caravans are present and their lifecycle state (none / approaching / at depot / leaving, with days remaining where knowable) and civ; whether a broker is assigned, present, at the depot, and their current job; and the count and approximate value of goods staged in the depot. Each caravan also reports manifest (count, approximate value, and a by-category breakdown of goods the caravan itself is carrying, before anything is unloaded to the depot — distinct from goods_at_depot) and agreements (active liaison price agreements as price_pct_min/max, 100 = no markup, e.g. 200 = double price: export rows are items this fort earns a bonus selling to the caravan, by DF's item type; import rows are items this fort pays a premium buying from the caravan, by DF's own request-tab category — a different, coarser taxonomy than item type, so the two lists will not line up 1:1). If reading either one fails against a real caravan (a field-path or calculation error, not simply "nothing to report"), that caravan's row carries manifest_error/agreements_error (the raw error string) instead of the field, so a live check can tell a genuine bug apart from an empty result. Reports the state and the numbers, not what to trade. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

unmet_needsUnmet needsA

Why the fort is stressed: the dwarven needs system aggregated across all citizens. Returns the top unmet needs (e.g. prayer, drink, socializing) ranked by how many dwarves are distracted, each with the worst focus level (how starved the need is), plus how many dwarves have at least one unmet need. Reading worst_focus: it is DF's raw focus_level — 0 is neutral, positive means recently satisfied (caps at 400), negative means starved. There is NO single floor: the minimum is -16320 x that dwarf's need_level for that need, so a level-1 need bottoms out at -16320, a level-2 need at -32640, a level-5 need at -81600. An identical worst_focus repeating across several needs is therefore normal — those needs share a need_level and are all fully starved — not a clamp or a quantization artifact; and a larger magnitude on one need does not by itself mean it is more starved than another, since the two may have different floors. Compare against the floor, not against zero. Reports which needs are unmet, not how to fix them (look that up or reason from the need type). Complements fort_status happiness. Returns {"error":"no fort loaded"} if no fort is active.

Inputs: no named parameters.

wiki_lookupWiki lookupA

Fetch a Dwarf Fortress wiki article as clean, readable text, pinned to the DF2014 namespace. Follows redirects (multi-hop) and honors section fragments (e.g. "Weapon trap" resolves to the Weapon Trap section of the Trap page). Cache-first to disk (~30-day TTL); pass refresh:true to bypass. Pure HTTP — works without the game running. Returns {title, url, text, from_cache, resolved_from?} or {error} if the page is not found.

Inputs: title (required), refresh, section.

work_detailsWork detailsA

List the fort’s work details (the labor-management groups) as facts: each detail’s name, mode (OnlySelectedDoesThis / EverybodyDoesThis / NobodyDoesThis / Default), the labor tokens it enables, and its assigned citizens. The member list is id-sorted and capped at 200 per detail — member_count is always the full count and members_truncated flags when the list is capped; member_names gives readable names parallel to members. Both parameters are OPTIONAL narrowing: detail (exact name) returns ONLY that detail; members_after (a unit id) starts each member list after that id — a truncated detail carries members_cursor (its last listed id) to pass back as members_after for the next page. READ-ONLY and always available (not behind the actuator gate); also the readback sensor for assign_work_detail.

Inputs: detail, members_after.

work_order_listWork order listA

List the fort’s active manager (work) orders as facts: id, job type, output item/material tokens, amount total/left, repeat frequency, bound workshop, condition count, and per-order validation state (active + validated; validated:false means the order cannot currently be fulfilled). Also reports whether a manager noble is assigned. count is the fort total; the page is sorted by id and capped at 256 — when capped, truncated:true and next_cursor gives the after_id for the next page. READ-ONLY and always available (not behind the actuator gate); also the readback sensor for work_order_create / _cancel.

Inputs: after_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 37 tools

    Disambiguation4/5

    Each tool targets a distinct subsystem (wiki, artifacts, burrows, etc.), and the extremely detailed descriptions make them individually clear. However, several tools overlap in reporting hostiles (threats, defenses, military) and terrain/water facts (environment, geology, fluids), so an agent could initially hesitate before picking the right one. The primary purposes differ enough that only minor confusion exists.

    Naming Consistency4/5

    All names use consistent lowercase snake_case and are mostly plural nouns or noun phrases (e.g., stockpiles, rooms_and_zones). A few are verb+noun (find_unit, wiki_lookup) or a bare verb (identify), which is a minor deviation but still follows the same casing style and remains readable. The pattern is predictable overall.

    Tool Count2/5

    At 37 tools, this server sits well above the 25-tool threshold the rubric marks as too many. While Dwarf Fortress is complex, several tools could be consolidated (e.g., threats/defenses/military, environment/geology/fluids), inflating the surface without a proportional increase in distinct capabilities. The count feels heavy rather than lean.

    Completeness5/5

    The tool surface offers comprehensive read-only coverage of the loaded fort: units, labor, military, health, supplies, structures, trade, and world data. Chaining is well-designed (find_unit -> citizen, wiki_search -> wiki_lookup) and there are no obvious dead ends. The only missing features are actuator tools, which are outside this server's stated read-only scope.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A local-first MCP server that gives AI coding agents persistent memory and controlled commands. Features a git-backed markdown knowledge vault with FTS5 search, surgical section edits, token-aware context budgeting, and a sandboxed command engine with human approval gates. Works with Claude Code, Cursor, Copilot, Gemini, and more.
      62
      601 npm
      1
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives your AI assistant full awareness of your local dev environment — running processes, Docker containers, git state, open ports, log files, and more.
      7 npm
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that gives AI agents structured access to a personal Obsidian knowledge vault, with semantic search, organization through Maps of Content, and git-backed history.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that lets an AI agent operate a Logseq (DB) graph through safe, high-level tools for reading and managing notes, tasks, and projects without needing to know Logseq's internals.
      1
      MIT