dayz-agentic-modding-mcp

An MCP server that lets an agent build a DayZ mod, check that the client compiles, run a test server and get a structured verdict instead of a log -- and then publish the result to the Steam Workshop.

The server does the work itself: it calls FileBank, the signing tool and the diagnostic executable directly. A project does not need its own build script.

It ships with a Claude Code skill, skills/dayz-modding: what the sources cannot tell an agent about Enforce Script, configs, layouts, persistence and the toolchain, each fact measured on a server and a client. The repository is a Claude Code plugin, dayz-agentic-modding, that installs both (see Install).

A community tool: not affiliated with or endorsed by Bohemia Interactive, the maker of DayZ.

Why a profile

The server knows nothing about any particular mod. Everything specific lives in a two-part profile:

• dayz-mcp.toml — portable, committed to the mod repository: which mods to pack, what a healthy boot looks like.

• dayz-mcp.local.toml — machine-specific, never committed: where the game, the tools and the test stand live.

Mixing the halves is rejected on load: that is how a repository stops building on anyone else's machine. Start from dayz-mcp.example.toml.

A mod is declared once, by name: sources in <root>/Name by default, output @Name/addons/Name.pbo. build.sources can redirect a mod's source elsewhere (e.g. "." for a mod whose config.cpp sits at the repository root itself).

The portable half — dayz-mcp.toml

The machine half — dayz-mcp.local.toml, never committed

The ready line

server_start finishes when expect.ready_line appears in a log written after that boot began. It is the one thing the server cannot work out for itself, and without it two things change: nothing can be waited for, so the boot job starts the server, confirms it is still alive a moment later and finishes saying so; and log_verdict has no line to read counters off, so expect.counters never matches anything. Errors, crashes and the warning budget are still judged. A profile without a ready line is supported, not broken — project_open says so in its notes.

Related MCP server: DayZ API MCP Server

Tools

Layout primitives

Most of layout_build's JSON vocabulary (frame, panel, vbox, label, button, ...) reads as what it says. Two are worth a sentence each, because what they emit is not obvious from the description:

Windows and the ms-gamebar dialog. The first time a virtual controller is attached, Windows tries to open Xbox Game Bar. On a machine that has it, nothing is seen; on one that does not — LTSC, Server, or the Xbox packages removed — the shell cannot resolve the URI and puts up "Get an app to open this ms-gamebar link", once per attach. Nothing here causes it and nothing here can prevent it: the shell reacts to the device arriving, and does the same for a physical Xbox pad. So the call that plugs the pad in says so, with two remedies the machine's owner can apply — turning off Settings → Gaming → Xbox Game Bar → "Allow your controller to open Xbox Game Bar" (HKCU\Software\Microsoft\GameBar\UseNexusForGameBarEnabled = 0), or giving the URI a handler that does nothing.

Signatures, and why the engine's own message sends you the wrong way. Under verifySignatures = 2 a stand refuses every client with code 118 and "missing dta\bin.pbo" — a vanilla file name, with no mention of signatures at all. The cause is usually the keyring: this tool launches the diagnostic executable out of the CLIENT install, so the engine reads keys beside that executable, while dayz.bikey — the key that signs the game's own pbos — ships with the separate DayZServer install. A keys folder that is missing, or holding only a mod's own key, leaves the server unable to verify anything, vanilla included. client_start refuses and names which of the three it is; server_start only warns, because a headless boot with no client is still useful. An unsigned pbo on the client's -mod line is named the same way — including this server's own bridge, which is packed unsigned on purpose.

Three limits the engine imposes on the UI tools, none of them worked around: a plain TextWidget has SetText and no GetText anywhere in enwidgets.c, so a label's string cannot be read at all — what a mod's interface MEANS stays a question for the server-side bridge, where the data is real. A script-level click reaches only the open scripted menu, because Widget has SetHandler and no GetHandler; via="cursor" is there for everything else. And the client has to load the bridge: one pbo carries both halves, so a profile listing it under mods.server_only keeps it off the client's -mod line — that case is refused by name rather than answered with an empty tree.

job_wait is the tool meant to wait, and its timeout is capped at 600 seconds however large a value is passed. Two other tools sleep: server_status samples the log twice, pulse_seconds apart, capped at 10 seconds — that pause is how it tells a slow boot from a hung one — and bridge_status samples the bridge's tick twice, window apart, capped at the same 10 seconds, for the same reason. Everything else returns immediately; work that takes minutes happens behind a job id.

The bridge mod

bridge_build packs bridge/ from this server's own repository into @DZMCP_Bridge beside it. It is the server's mod, not yours: one copy serves every project, nothing is written into your repository except the job record, and no project's signing key is used — a -serverMod pbo is never handed to a client to verify, so it is built unsigned and its output folder is kept free of signatures and keys.

Building it does not load it. That stays your profile's decision, because the bridge is an extra pbo in the stand and a run without it has to remain possible. To attach it, add two lines to dayz-mcp.local.toml (the same two bridge_build's job summary prints):

[mods]
extra       = ["<path printed by bridge_build>/@DZMCP_Bridge"]
server_only = ["@DZMCP_Bridge"]

server_only is what routes it to -serverMod instead of -mod. Without it the stand boots perfectly well and bridge_status reports that the bridge never wrote any state — which is true, and easy to mistake for a broken bridge.

bridge_status also reports the command mailbox. Inside the game only the mod empties it, by claiming the command; on this side bridge_clear and server_start's pre-boot clearing do. So a command sent while the stand was down, or before the bridge was attached, is not discarded and does not expire on its own — it keeps blocking every later send, and a stand booted outside these tools would pick it up. server_start clears both transport files before every boot, so a server started through this tool never runs a command from a previous session; that is hygiene, not a substitute for knowing the command is there. The state comes back as stale_command, and bridge_clear() is the way out of it. Clearing is a separate tool on purpose: throwing away a queued command is a decision, not something a status check should do behind your back. It refuses while the bridge looks alive unless you pass force=True, and either way it reports the command id it discarded.

What bridge_status can tell apart

The tick alone is not enough to judge a bridge, because it restarts at 0 every boot while the state file survives in the profile directory. Every answer carries the channel's own verdict in heartbeat, and the four are genuinely different facts:

Every answer that read a sample also carries session_id — the live world's id — and a restarted answer carries previous_session_id too, so a caller can say which world went away.

no_server, stale_command, no_state_file, invalid_state, unreadable_state and outdated_bridge come before any of that: nothing is running, a command is wedged, the mod is not loaded, the state document is valid JSON with a named field wrong (it says which, and checks twice before saying it), the file never parses at all, or it parses but predates this server's protocol (rebuild it with bridge_build).

The world commands

The world tools talk to the bridge over two JSON files in the server's -profiles directory: a command mailbox (written atomically from this side, deleted by the mod as its claim) and a state file the mod overwrites once a second. Enforce Script has no rename, so the mod cannot write atomically — the reader tolerates torn writes instead, and one failed read is never news. Four facts, all measured on a live stand, decide how to use them:

Server ready is not bridge ready. The bridge starts claiming commands tens of seconds after the server reports ready — the spread observed so far is 18–38 seconds, and it varies boot to boot. A command sent into that window is not rejected — it is claimed late and completes after the caller gave up. So: server_start, wait for the boot job, then world_ready(), then commands. Every world tool also refuses upfront if the tick is not moving, naming world_ready as the remedy.

Every argument value crosses the wire as a string. The mod's parser is strict: a JSON number anywhere in args rejects the whole args block. The tools stringify numbers and booleans themselves and refuse values with no faithful string form (lists, dicts, None). Positions travel as one string, "x y z".

A refusal is a result. The mod's own sentence comes back verbatim as the error: "no player is on the server", "the class does not exist", "the action's own Can() said no". Nobody connected is the normal state of a headless stand, and every verb that needs a player says so instead of silently doing nothing.

The session id protects against yesterday's command. Every command carries the session the bridge most recently published; the mod refuses any command addressed to another session (or none) without executing it. A command written while the stand was down can therefore never fire into a freshly booted world. The tools stamp the session automatically — it only matters if you write the mailbox by hand.

Measured on a live stand, three boots. world_time_set(hour=3, minute=7) moved the clock to 2026-09-20 03:07 and left the date where it was; world_weather_set("fog", 0.9, seconds=2) took the published fog from 0.085 to 0.900 and held it; world_entities(pos="7500 0 7500", radius=150, limit=5) listed 5 of 171 objects with truncated: true. Distances came back at 320 m for a 150 m radius until they were made horizontal, which is what the engine's own radius test measures.

Attachments, carrying and power are engine operations, not mod behaviour

world_attach, world_detach, world_move and world_power ship in this bridge rather than in a project's own copy of the dispatcher, and the line is worth stating: taking an item off a slot, putting one on, carrying one in a pocket instead of a hand, and throwing an energy manager's switch are the same calls whatever mod drew the device (FindAttachment, ServerTakeEntityAsAttachmentEx, ServerTakeEntityToInventory, ServerDropEntity, GetCompEM().SwitchOn). The rule under world_exec is about behaviour a mod defines; none of this is.

They exist because a worn device could not be reached at all: world_spawn attaches a NEW item to whatever is in HANDS, world_set knows health and quantity, and world_action needs the item in hands too — so on a live stand a flat battery could not come out, a fresh one could not go in, and nothing could switch a device on, which left every action whose condition reads IsWorking() untestable from outside the game. All three name the item the only way a tool that has never seen it can: "hands", "player" (the character's own worn slots), or a config class looked up on the player — hands first, then worn attachments and cargo, recursively, first match by IsKindOf. world_move covers the other half of the same gap: carry it, do not hold it is where a test of a worn or pocketed device starts, world_spawn puts an item in one place and leaves it, and the move between hands, inventory and ground is a drag inside the inventory screen — a gesture no tool can make.

Each one reads the result back out of the engine rather than reporting the call's own bool: whether the slot is empty now, whether the item's own inventory location says it landed in that slot, whether the manager says switched-on and working. That is the same rule as ui_text reading its field back, and for the same reason — SwitchOn() does nothing at all when the device cannot switch on, and says nothing about it.

An inventory move lands one tick after the frame that asked for it (measured 2026-09-07): ServerTakeEntityToInventory answered true and the slot still held the battery in that same frame, and the very next command found the slot empty and the battery in cargo — so a read-back taken where the call returns reports a failure for a move that worked. attach, detach and move defer their own verdict by a tick, the same DeferCompletion(1) ui_load uses to let a widget reach its first layout pass, and cost about a second more than the other world verbs for it. attach spends that tick on more than a yes: it names the slot the item landed in, read off the item's own inventory location, so a call that named no slot still comes back with the name world_detach will want.

One tick is not always enough (measured 2026-09-08). A move whose source is the hands does not go straight into the inventory: HumanInventory turns it into a HandEventMoveTo and posts it to the hand state machine, which applies it on the player's next command-handler frame — later than the bridge's next tick when the player is busy. Attaching the item held in hands to a player slot answered failed once for a move that had in fact worked. So the three verbs look again, up to five ticks (still inside the mod's own 30 s hard limit and well inside this side's 45 s wait), and the answer names the wait it spent: ... after 2 tick(s). A move that never lands is still refused by the mod in its own words, with the tick count, rather than by a timeout.

Actions, and why there is no verb dictionary

A semantic verb like "hand in the sample" lies: in a real mod the same words mean different things depending on which device is near, the player's faction, and what is already unlocked. That context is not enumerable, so the bridge does not try. world_action takes an action's class name, a target and the held item, and asks the engine to run it through its own gate — the same one a key press goes through. Applicability is decided by the action's own Can(), and its refusal is a meaningful test result, not a tool failure. The distinguishable answers: manager busy, player already acting, player sprinting, unknown action class, and "the action's own Can() said no". "Accepted" is not success either — the command stays running until the engine actually releases the action, and every failure path releases the manager so the player can still act afterwards.

world_exec is the escape hatch

Anything a mod exposes that is not an action — "how many points in the faction pool" — goes through world_exec(verb, args): an arbitrary verb over the same transport. Every answer is marked non_standard: this server does not know the verb, does not validate it, and does not answer for what the mod does with it. A verb the bridge build does not know comes back listing the verbs it does. A project that needs its own verb edits its own copy of the bridge's dispatcher (the comment above KnownVerbs() in bridge/scripts/5_Mission says exactly where); there is no registration machinery on purpose — a verb this server typed and validated would be a verb this server answers for.

The client: three input layers, and why there are three

The bridge reaches the server. What it cannot do is look at the client's screen or act through the client — walk a character across ground, open a menu, fill a field a mod drew. The client_* tools are that, and they use three different tracts because no one of them can do the other two's work. Every line below is a measurement against a live client, not a design intention.

Keyboard emulation does not move the character, and window messages do nothing at all. SendInput scancodes with the foreground verified: 25 s of forward, 0 m. PostMessage/SendMessage WM_KEYDOWN into the main window and its children: 0 m, and no reaction from the menus either. The engine reads movement from raw input and ignores emulated keys, which is why no tool here offers a window message.

The virtual gamepad does move it, unfocused, and it is ANALOG — the reason it stays even where a key would do. Measured in one run with a third-party application holding the foreground throughout:

stick fully forward,   10.0 s  ->  38.40 m   (3.84 m/s)
stick at 0.3 forward,   8.0 s  ->  11.34 m   (1.42 m/s)

Same tract, same character, 2.7× the speed from stick deflection alone. "The character is walking, not running" cannot be expressed with a key, which knows only on and off. In the same run the character walked about 141 m of its own accord, and the mod's own count of objects within 10 m of it went 1 → 0 → 1 as it left the spot and came back — a state change caused by presence, which a teleport cannot produce.

Some of the interface answers the pad, and some does not. Measured, with the game window behind another application the whole time: back opens and closes the inventory, start opens the pause menu, b closes it — all at the default 0.1 s tap, so a tap is long enough for the engine to latch. But a moved nothing, at 0.1 s or at 0.5 s, and neither did the d-pad inside those screens: the client did not switch to controller-navigation mode, so there was no focused element for a confirm to act on. Treat menu dismissal as a gamepad job and menu confirmation as unproven.

The eyes need no focus either. A capture is a live frame with the window at the very bottom of the z-order (lit_fraction 0.9997 unfocused, 0.9997 focused in the same session). The one state that defeats them is a minimized window, whose client area collapses to 0×0 — refused with a reason rather than saved as a valid-looking empty picture.

All of that background behaviour rests on one client setting, pauseMode (GAME → UPDATE IN BACKGROUND). At the value measured here the client keeps drawing and simulating while unfocused, which is why the frame is live and the stick still moves the character. At "no graphics" both would stop silently — a frozen frame looks exactly like a live one. So client_start and client_status READ that setting and warn; they never write it, because it belongs to whoever owns the machine.

Two more profile settings ride along on the same launch line. client.file_patching adds -filePatching (the stand's server config needs allowFilePatching = 1 or the client is refused at connect), and machine.window — or a per-call window= override — adds -x/-y.

client_type is the only tool that takes the screen, and it is honest about it: the answer carries foreground_taken and a sentence saying the person at the machine could not type into their own window while it ran. It verifies the foreground with GetForegroundWindow after asking for it, because SetForegroundWindow returns success having done nothing when Windows refuses — and typing blind sends the keystrokes into whatever window the person is actually using. When the foreground cannot be had, nothing is typed and the refusal names the process holding it.

ViGEm is emulation of a real device and this is a test stand. The driver is signed and installs without a reboot, and the gamepad is a new device rather than a filter over the machine's own keyboard and mouse — a filter driver was tried here once and cost the machine's owner all keyboard and mouse input until it was unwound by hand. None of that is a promise about anticheat on a live server, and nothing in this phase makes one.

The knowledge index

An agent writing a mod keeps asking the game the same questions: is there such an API, what is it called, where is it declared, who overrides it. Answering them meant unpacking scripts.pbo and sweeping the text — and every session paid again. knowledge_* turns that work into a question.

It is a plain SQLite file in the project's own .dayz-mcp/, built by this server out of the game, the mods a project declares and the project's own sources. No embeddings, no external service, no key.

Three layers, and why their rhythms differ

One index built in one go would be wrong within a minute of being right: the game moves a few times a year, a dependency a few times a month, and the project between one agent turn and the next. So each layer is built, aged and measured on its own, and every build is incremental — unchanged sources are skipped by size and modification time, and only=[path] skips even the walk that discovers them.

An answer carries the age of the layer it came from

Staleness is measured, not guessed: a layer records the size and modification time of every source it read, and that is compared against the files as they are now.

• Every answer names the layers it used and how old each one is. An answer with no results names every layer it searched — "not found" is worth exactly as much as the layers behind it are current.

• The project layer's freshness is measured on every search, whether or not it contributed. That is the dangerous case: an agent adds a class, asks about it, and a layer built a minute ago says "not found" — a confident statement about code that exists.

• A search over a layer that was never built is refused, and the refusal names the call that builds it. "Not found" and "not looked" are different facts, and only one of them is safe to act on.

• Narrowing carries the same trap one level down, so an empty narrowed answer reports where the name does exist: asking kind='class' about a name the game declares only in a config gets a true "no" that reads as "the game has no such class".

Config classes live under kind='config', not kind='class'. Counted in this machine's own index of the game: 88 102 config classes against 43 595 script declarations of every kind put together, so mixed into one kind they bury every script answer. Separated, "does the game have an item class called X" is a question you can ask exactly.

What it does not answer

The index answers what exists: class, method, signature, where declared, who overrides. It does not answer what is right — that modded class X extends X compiles and silently fails to apply, that _co costs the alpha channel, that binarize takes directories rather than files. None of that is derivable from the sources; it was learned the hard way and lives in the modding skill and in the mod itself. The index does not try to replace either, and it does not try to understand what a field means or why a class is there.

Semantic search is deliberately not here

The decision was made by measurement, not caution: every lookup that shaped this server's earlier phases was a lookup by name. And an embedding index would break the rule the rest of this server keeps — install it and it works, with no external service and no key. The predecessor project this one deliberately did not build on documents its knowledge layer as local and free while its code imports a paid embedding client, fails without a key and carries hard-coded prices. Its two search tools also hang forever, because the client behind them was created without a timeout; hence the ceiling every search here runs under. If exact search turns out not to be enough, semantic search is a separate phase with one condition: the model ships inside the delivery.

The measured numbers

On this machine — the game with 2810 script files, 35 installed mods, one real project of 41 sources — through the tools, not their internals:

The index on disk: 74.7 MB for a real project's three layers; 110 MB for the 523 dependency archives on their own. Those archives are 92 GB, and none of them is unpacked.

Call sites are what the index pays for. The game's own scripts hold 43 579 declarations and 113 703 call sites, and recording the second set roughly doubles the index: measured on the game layer alone, 23.8 MB and 3.7 s to build without them, 49.6 MB and 4.5 s with. That is the price of being able to answer "who calls this", and it is stated here rather than discovered later on a full disk.

Incrementality, on the real project: a full rebuild 136 ms; one edited file found by the walk 8.8 ms (15×); the same file named through only= 5.8 ms (23×). On a 2810-file tree the walk dominates and only= is worth far more — but on a project of this size, 15× is what an ordinary rebuild actually buys.

The ceiling bites for real: a query measured at 77 ms, run under a 19.3 ms ceiling, was stopped at 19.9 ms, and the connection went on answering.

The asset pipeline

Getting a model from Blender into a mod is ten steps, and until this phase all of them were run by hand. The value is not in launching the tools. It is that every tool in this chain is structurally unable to report failure, and each of those silences had already cost days.

Measured on the real binaries, not assumed:

So the rule this whole namespace is built on: the verdict is read off the artifact, never off the tool's report. The exit code is recorded and believed in neither direction.

The root is declared, not assumed

binarize has no project-root option at all — the full switch list was enumerated against the real binary. The root is the working directory of the process. The same command, the same input, a different directory, and out comes a valid ODOL with plausible texture paths that the engine renders untextured, with a success code and no complaint. The exporting Blender add-on has the same root in a preference of its own, remembered from whatever project was open last: on the machine this was developed on it pointed at a directory from an unrelated session, and against a wrong root the add-on does not fail either — it strips the drive letter, keeps the rest, and writes paths that look like paths.

build.project_root is that directory, stated once in the portable half of the profile. The server makes it the binarizer's working directory — through a drive letter of its own, see below — and pushes it into the add-on for the duration of the run, so what the add-on has stored decides nothing (it is reported, so you can go and fix it). That is what makes a wrong root impossible rather than detectable, and it is why the key is required before anything model-shaped will run at all.

The refusals it produces happen before a process exists — measured at 0.0003 s — and a refused build leaves the model the mod already ships byte for byte untouched.

A drive of its own for every build

binarize reads the whole drive before it reads a model. Read off the running process: for the first minutes its one busy thread sits inside FindNextFileW with a handle on the root of the drive its working directory is on, and nothing is read from the model until that walk is over. So how long a build takes is the size of the disk, not of the model:

asset_build therefore maps a free drive letter onto build.project_root with subst, starts binarize from it with the source named on the letter, and removes the letter when the process is gone. A letter whose root is the declared root is that root, so nothing about the artifact changes: C3 and C4, the two checks that fail from a wrong working directory, both succeed, and the files come out the same size to within three bytes. The job's artifact records the directory the tool really ran from (cwd).

Every build maps a letter of its own and removes only its own — one that already points at the same root may be another server's build in flight. With no letter free the build runs from the folder itself, as correct as before and as slow, and its summary says so, because minutes spent walking a drive look exactly like a hang. The walk goes through junctions too, so whatever is linked into the root is walked with it: an unpacked game tree of 103,359 files turned the tenth of a second into half a second.

Twelve checks on the artifact, and four of them refuse

asset_check runs them without building anything and without DayZ Tools, because a fresh clone must be able to ask whether what it is shipping is healthy. Four refuse: a built model is there and is an ODOL (C1), no reference escapes the mod (C3), a material was actually inlined (C4), and nothing already binarized is offered back to binarize (C10). The rest warn: dangling references, an rvmat pointing into another mod, a transparency lost to DXT1 (C7), an animation that never reached the artifact, a model.cfg that is not the one the artifact was built from, a structural fingerprint that no longer matches what the last build deployed. Every finding says what to do.

C4 is the one worth knowing about. When binarize resolves an rvmat it copies that material's own stage textures into the model — fresnel, #(argb,8,8,3), env_land_co.paa, _nohq, _smdi — strings no MLOD contains. Six artifacts out of six were separated correctly by that one test, and it found a broken model on this machine that nobody knew about.

The Blender step is optional

asset_export is the only tool here that needs Blender, and everything downstream works on a .p3d from anywhere — a hand export, a partner's file, a model committed years ago. A machine with no Blender builds and ships a mod perfectly well; the refusal says so rather than presenting it as a broken installation. It does need the exporting add-on to be enabled in the Blender it finds, and it never writes Blender's user preferences back (verified: the preferences file was byte-identical after every run).

Export and build are two calls rather than one, because each half has its own verdict and a build refused by one and allowed by the other is not a decision.

Byte-equality is never promised

Neither half of this pipeline is reproducible, and the design says so instead of pretending:

• The export. Seven exports of one unchanged source file — three from one session, three from another, and one made by hand in the GUI months earlier — gave seven different SHA-256s at a constant 334,032 bytes. The difference is the order of one internal block.

• binarize. Four runs on one unchanged input gave three different results: the size moved by 5 bytes and two 8-byte fragments leaked out of compressed regions.

So a model is never cached or compared by content hash. What is compared is a structural fingerprint — the file's kind, its LOD count and its set of names. Across all seven of those exports that fingerprint was one value.

The measured numbers

One small model, on this machine, through the tools:

Both logs are almost entirely boilerplate, and what is muted is counted rather than dropped: Blender's 169 lines came down to 4, and binarize's 91 to 6 — one of those six being the model's only genuine complaint.

Chained end to end, the export and the build reproduced a model that had been made by hand months earlier: same kind, same 4 LODs, the same 50 strings, and a size one byte apart.

What none of it answers

Whether the model looks right, is scaled right, is wound right, has a collision. Nothing outside the game answers that. C1–C12 shorten the road to it; they do not replace it.

The Workshop

workshop_publish is the last step of a mod's life on this machine and the only tool here whose effect is somewhere else, so it is built the way server_signatures is: everything that could publish the wrong thing is refused before a byte leaves, the answer says what is about to happen, and the item is read back afterwards rather than taken on Steam's word.

What goes up is what mod_build made. The @Name folder, whole -- addons/ with the pbos and their .bisign, keys/, mod.cpp, meta.cpp -- which is also what Publisher uploads. A junction or symlink inside that folder is refused rather than followed: Steam would upload the tree behind it, and the tree behind it is usually the sources.

meta.cpp says which item. Publisher leaves three lines in the folder it published from (protocol = 1; publishedid = N; name = "...";) and the launcher reads the id back out of them. The copy subscribers receive adds a fourth, timestamp = <int64>;, and CRLF line ends (read off a subscribed item 2026-09-19; the fourth decodes as the .NET DateTime.ToBinary() of the moment Publisher wrote the file, and nothing reads it back); the reader here takes either shape, and this server writes the three lines the id lives in -- Steam took that file for an update the same day. Otherwise it does the same. With the file, the item it names is updated; without it, an item is created and the same three lines are written into the folder before the content goes up, so subscribers receive the id inside the folder, and Publisher can carry on from a folder this server created. Keep that file with the sources -- a deleted build folder takes the item id with it. A meta.cpp that exists but carries no readable id is refused, not treated as absent, because a guess there publishes a duplicate.

A new item is private. Unless visibility says otherwise, an item is created hidden, so nothing is public before its page has been looked at; workshop_publish(mod, visibility="public", content=False) opens it without touching its files. An update leaves untouched whatever it was not given: no title means the title stays.

Required items are a section, not a sentence. The DayZ Launcher pulls an item's dependencies from the Workshop's Required Items list, not from its description, so workshop_publish(mod, requires=[...], content=False) puts Workshop ids there (ISteamUGC::AddDependency) and remove_requires takes them off. The job reads the item's current list first, through a details query with children, changes only what differs, and reads the list back into the summary -- a repeated call changes nothing. A refused change fails the job by name, after any listing update in the same call has already gone through, and the summary says so.

workshop_publish(mod, previews=[...], content=False) adds pictures to the item's screenshot strip (each under 1 MB, png/jpg/gif, relative to the project or absolute). Every call adds: Steam keeps what the page already shows, so a picture is sent once, and taking one down is done on the item's page. The binding is the flat export SteamAPI_ISteamUGC_AddItemPreviewFile of the game's DLL, measured 2026-09-27: five images accepted in one update, shown on the page.

content=False edits the listing and nothing else. Title, description, preview, visibility and tags go up; the folder's files do not, so the build folder may hold anything -- an unreleased build, no pbo at all -- and only its meta.cpp is read, for the item id. It is the way to fix a description without shipping whatever happens to be built. It cannot create an item, because an item without content is nothing, and it refuses when nothing was given. Sending the content again is cheap in any case: Steam moves only the files that changed (the first live update here, an unchanged 0.55 MB mod, took 10 s end to end and uploaded one 58-byte file, measured 2026-09-19), but it does stamp a new update on the item's page.

How it reaches Steam, and why from another process. There is no HTTP route for Workshop content, and Publisher has no command line -- measured 2026-09-19, its binaries carry the strings of a WPF dialog and nothing else -- so the upload goes the way Publisher's own does, ISteamUGC through the running Steam client, using the game's own steam_api64.dll, found beside the game the way FileBank is found beside the tools. No SDK is shipped or needed: the DLL exports the flat C API, and steamugc.py binds the dozen calls an upload takes with ctypes, trying interface versions newest first so a DLL from a newer game build still answers. That module runs as its own process per upload (python -m dayz_mcp.steamugc spec.json result.json), because SteamAPI_Init marks the account "in game" for the process's lifetime, a fault inside the DLL takes its process down, and a second Init after Shutdown in one process is not something Valve supports. The app id is the game's, the same number Publisher runs under, handed to the DLL both ways it looks for one -- the environment and steam_appid.txt in the working directory. Measured the same day: from a plain Python process, with the client running, SteamAPI_Init succeeds, the app id reads back, and the two result structs are the 24 and 16 bytes #pragma pack(push, 8) makes them.

What Steam needs from the machine. The Steam client running, logged into the account that owns the game and the item. That is the one refusal the job makes rather than the tool -- SteamAPI_Init is the only thing that can answer it -- and it is the first thing the job does, before anything is sent. An account that has not accepted the Workshop legal agreement can still create and update, but its item stays hidden until it has; Steam says so in the result, and the job summary repeats it with the link.

Read back. After a successful submit the job reads the item through the public GetPublishedFileDetails listing -- no key, no login -- and the summary says what it showed: the title, when it was last updated, and whether that is this upload. A private item is not in that listing at all, and the summary says that instead. workshop_status is the same read on demand, beside what is on disk, with stale -- the newest pbo is younger than the item's last update -- as the one fact derived from both.

Known limitations

• A Workshop upload needs the Steam client, and the account it is logged into. workshop_publish cannot log in and must not: it uses whatever session the running client holds, and the job refuses when there is none or when that account does not own the game. The public listing it reads back does not show private items, so a freshly created item reads as "not visible" until it is made public.

• Stale-pbo detection is mtime-based, not content-based. mod_build refuses a freshly built pbo that is older than its sources -- the usual cause is a running server still holding the old file open, so packing silently produced nothing. But git checkout changes a file's modification time without changing its content, so a perfectly good pbo built right after switching branches can trip this check too. If mod_build reports "stale pbo" immediately after a branch switch, this is the likely reason, not a real packing failure -- rebuild and it will pass. A mature tool in this space moved to a content hash for exactly this reason; that is future work here, not done in this phase (see packer.py, pack_one).

• A mod source folder is packed whole. mod_build refuses to pack a mod whose source directory contains anything matching build.exclude (the seven-pattern default is listed above) rather than silently shipping it inside the published pbo. It refuses regardless of build.exclude when the source contains this server's own artifacts -- the signing keys, either half of the profile, the job store, the mod's previous build -- because packing those publishes the private signing key, and no project should have to configure that away. By default it does not stage a filtered copy first: a copy is always newer than the sources, which would permanently disable the stale-pbo check above if that check measured the copy. build.stage = true opts into copying anyway -- safe only because the stale-pbo comparison always measures the original source tree, never the copy. This is the layout a mod whose source is the repository root needs (it always contains at least .git).

• A verdict judges the whole log, not just your mod's lines. log_verdict reads the log of the stand it is pointed at, so a stand shared with other mods counts their warnings against your expect.max_warnings budget and their errors as reasons. Two projects sharing one machine.stand_root will see each other's baseline. Either give each project its own stand, or set the budget knowing what else is loaded. A project-scoped filter, symmetric with expect.error_regex, is the obvious refinement and is not implemented.

• expect.noise cannot rescue a line that already counts as an error. Classification is ordered forbid → crash → error → noise → warning, so a line containing ERROR or FATAL (or one of your forbid strings) is decided before noise is consulted. That order is deliberate -- noise matching first would let an innocuous substring swallow a fatal line -- but it means noise can only suppress warnings and ordinary lines, never demote an error-level one.

• client_verdict is an errors-and-crashes verdict, not a readiness one. [expect] describes the server's log: its ready line and counters are printed by a mod's server-side init, and max_warnings is a budget counted over that same log. A client .RPT contains none of it, so those three keys are deliberately not applied here and the answer lists them in not_applied. forbid, error_regex and noise are about the text of a log line and still apply. There is no client-side ready line to declare; whether the client got in is answered by the player count client_start waits on, not by its log.

• The client tools join a stand this session did not start; client_chat cannot. client_start will happily connect to whatever is already on the port, and says whose it is. But chat is delivered server-side, through the same channel as the world_* tools, and that channel acts only on a server this session started — so on a borrowed stand everything except client_chat works. The refusal names the pids holding the port rather than suggesting a server_start that would refuse them.

• Chat is not reachable from the gamepad, and confirming a menu is not either. The game binds its chat line to Enter and nothing else, and there is no on-screen keyboard, so text is either a bridge message (client_chat, free) or real keystrokes (client_type, costs the foreground). client_type("", submit=True) sends Enter alone, which is how the chat line is opened — and, on the evidence above, the only confirm the tool set has.

• Every knowledge search pays a walk of the project tree. That walk is how the project layer's staleness is measured on every answer, which is the one property the index exists for. It costs 3.0 ms on a real 41-source mod (whose tree holds about 1800 entries) and 21 ms on a tree of 2810 files. Caching it for a second or two would remove the cost and restore exactly the window of silence the design refuses; if it ever becomes too expensive, that trade has to be made deliberately, not by accident.

• A build always goes through a job, and the job costs more than a small build does. Turnaround measured at 70–95 ms against a 6 ms project rebuild: job_wait polls at 100 ms. The single shape is deliberate — a caller must not have to know which build blocks — and nothing forces you to wait, because the next search measures the layer itself.

• The dependency layer is measured against the profile as it is now. Add a mod to mods.required and its archives arrive as added; remove one and its archives read as missing. That is the requirement (the declared set is part of what the layer is built from) but it looks like the index went stale when what actually changed was the profile.

• core always includes the game's configs, and that is most of its cost. 70 s with them against about 4 s for the scripts alone. There is no switch: without the configs "is there an item class called X" cannot be answered, and a second axis would make the staleness measurement ambiguous — the walk would not know whether to expect the Addons archives.

• knowledge_show answers nearest-layer-first. For a class a dependency reopens with modded class, the mod's declaration comes before the game's. That is the right order and a surprising one; pass layer='core' for the game's own.

• Conditional compilation is indexed, not resolved. 4.9% of the game's script lines sit inside #ifdef, including about a hundred class declarations. This server drives server, client and diagnostic builds, so there is no single correct set of defines: everything is indexed and the guard is recorded on the declaration. A name can therefore be reported that a particular build excludes — the alternative, filtering by one guess at the defines, would deny the existence of methods that are in the running build.

• C12's fingerprint carries the file's size, and binarize's size is not stable. Rebuilding a model that nobody edited produced an artifact one byte larger than the shipped one, with the same kind, the same LOD count and the same fifty strings — and a different digest, because the size is part of it. The step is not always that small: of five rebuilds in a row of another unchanged model, four landed within three bytes of each other and one came out 230 bytes larger, with the same LODs and the same strings. So C12 can warn about a rebuild that changed nothing. It warns rather than refuses for exactly this reason, and the parts it is built from are reported beside it so the comparison can be made by hand. Splitting the digest into a stable half and a size is the obvious refinement and is not done.

• A build that is killed outright leaves its drive letter behind. asset_build maps a letter onto the model root for the run and removes it when the run is over. If the server process itself is killed in between, the letter stays until the next logon (subst Z: /D removes it by hand). The next build takes another letter instead of borrowing that one, because a letter that already points at the same root may just as well be a build in flight in another server, and nothing tells the two apart.

• A partial export warns; it does not refuse. With the exporter's own default arguments a model came out carrying 2 of its 5 LODs and passing every other check. This server does not pass those arguments, so it should not happen — but an object marked as a LOD and not linked into the scene counts on one side of the comparison and not the other, which is a legitimate reason for the counts to differ, so a refusal would have false positives. Read E3.

• The containment rule cannot see every wrong root. It refuses a root that does not hold the mod's prefix folder, which is the measured failure. A root that does hold a folder of that name — a repository whose own mod directory is spelled like the prefix, for instance — passes it, and what catches that case is C10 or C3/C4 one layer down. Measured: pointed at such a root, the build refused, deployed nothing and left the shipped artifact untouched, but the refusal came from the job rather than from the call.

• asset_export needs the exporting add-on enabled in Blender, and cannot install it. Blender is launched with the machine owner's real preferences, because starting it with --factory-startup takes the add-on away entirely. Their other add-ons are kept off the search path for the run (two of the ones installed here reach the network as they start and are blamed for crashes), which Blender reports as "Add-on not loaded" in the log — that line is this server's own doing, not a fault.

• A binarised config has no body to show. knowledge_show(body=True) reads a declaration back out of the file or archive it was indexed from, but a config.bin holds the binary form while the index holds what CfgConvert made of it. The answer says so instead of returning nothing.

Testing

python -m pip install -e ".[dev]"
python -m pytest

That is the hermetic suite: everything runs against fixtures, on any machine, in about eighty seconds.

Corpus tests

A second half of the suite runs the readers and the checks against REAL artifacts — a binarized model that works in game, one built from the wrong directory, a texture whose alpha survived conversion and one whose did not, an unpacked scripts.pbo, a folder of installed mods. Those artifacts are not in this repository and never will be: they are gigabytes, and most of them belong to somebody's mod rather than to this server. The tests find them through environment variables named after the PROPERTY under test, never after the mod they came from, and skip when a variable is unset.

Set them once per machine: copy tests/samples.local.example.toml to tests/samples.local.toml (git-ignored) and fill in your own paths. That file is read by tests/conftest.py before any test module is imported — which is when the skips are decided — and never overrides a variable the environment already carries, so a one-off DAYZ_MCP_SAMPLE_ODOL=... pytest still wins.

The cheap half then runs by default. The expensive half — anything that launches DayZ Tools or Blender, or indexes a whole corpus — carries the corpus marker and stays out of the default run, because it takes minutes rather than seconds:

python -m pytest -m corpus

The one sample a normal machine does not already have is the vanilla layout corpus, because the game ships it packed. Unpack it once with this server's own formula, then point DAYZ_GUI_LAYOUTS at the result:

python -c "import subprocess; from pathlib import Path; from dayz_mcp.packer import bankrev_cmd; from dayz_mcp.paths import BANKREV_REL, find_tools; subprocess.run(bankrev_cmd(Path(find_tools()) / BANKREV_REL, Path(r'<game>/dta/gui.pbo'), Path(r'<corpus>')))"

<corpus>/gui/gui/layouts is then the directory to name. If you regenerate data/layout-vocab.json at all, regenerate it from the same unpack, so the vocabulary and the parse test are talking about one build of the game.

Install

As a Claude Code plugin

The plugin brings the server and the dayz-modding skill. In Claude Code:

/plugin marketplace add covalschi/dayz-agentic-modding-mcp
/plugin install dayz-agentic-modding@dayz-agentic-modding

The plugin starts the server with uv run --frozen, so uv (Astral's Python package manager) must be on PATH; the first start builds the environment from uv.lock (seconds). A project still needs its dayz-mcp.toml and dayz-mcp.local.toml ("Why a profile" above). The gamepad stays optional: the plugin does not install the client extra.

What the plugin runs, sends and fetches

Everything runs on your machine, under your user, and only when a tool is called.

• Programs it starts: DayZ Tools (FileBank, DSSignFile, CfgConvert, BankRev, binarize, ImageToPAA), the DayZ server and client that the project's dayz-mcp.local.toml names, and, only for the tools that need them, Blender and the ViGEm virtual gamepad. The game's own server and client talk to Steam as DayZ always does.

• Input it sends: keyboard, mouse and gamepad input to the DayZ client it started (the client_* and ui_* tools).

• Files it writes: the mod's packed and signed output, the stand's profiles and logs, and its own state, the knowledge index included, in the project's .dayz-mcp/ folder.

• Network:

  • workshop_publish uploads the mod's files and listing to the Steam Workshop through the Steam client you are logged into (steam_api64.dll from the game folder);

  • workshop_status, and workshop_publish when it reads an upload back, ask Steam's public ISteamRemoteStorage/GetPublishedFileDetails endpoint for the item, without a key;

  • server_mods sends A2S queries (UDP) to the game server address you give it.

Nothing else leaves the machine: no telemetry, no other endpoint.

By hand

python -m pip install -e ".[dev]"

Register in your MCP client:

{ "mcpServers": { "dayz": { "command": "dayz-mcp" } } }

The skill on its own is the folder skills/dayz-modding: copy it, or link it, into ~/.claude/skills/.

Licence

GPL-3.0-or-later. See NOTICE.md. The skill in skills/dayz-modding has its own licence: its text is CC BY-SA 4.0 and its code (samples, template, scripts) MIT, so a mod built from them can carry any licence (skills/dayz-modding/LICENSE.md).