dzstudio-mcp

An MCP server that lets an AI agent build in dzStudio, the in-game object editor for DayZ, together with people. The agent joins a dzStudio collaboration session as a participant without the game: it speaks the open collaboration protocol dzcollab 1 (see PROTOCOL.md of the dzStudio collaboration server), keeps the project state on your machine and applies every operation exactly like the editor does. Everyone in the session sees it as "‹you›'s agent", with a status line saying what it is working on.

The agent works on data, not on screenshots. It never saves: when it is done it asks for review, and a person in the session saves or discards.

Setup (once)

Requires Node.js 22 or newer.

git clone <this repository> dzstudio-mcp
cd dzstudio-mcp
npm install
npm run build

Add it to your MCP client, for example in Claude Code:

claude mcp add dzstudio -- node /path/to/dzstudio-mcp/dist/index.js

or in a client's JSON configuration:

{
  "mcpServers": {
    "dzstudio": {
      "command": "node",
      "args": ["/path/to/dzstudio-mcp/dist/index.js"],
      "env": { "DZSTUDIO_MCP_SERVERS": "home=https://collab.example.org/dzcollab/", "DZSTUDIO_MCP_AGENT_NAME": "Scout" }
    }
  }
}

That is all the configuration there is. From then on you work in the conversation:

1. Servers — the agent adds a server with add_server (a name of your choice and the server's base address), or you name them once in DZSTUDIO_MCP_SERVERS (name=url, comma-separated).

2. Login — login gives you an address and a code; confirm it in the browser and the agent finishes the login. The token is stored on your machine and kept across restarts.

3. Sessions — the agent lists projects and sessions, joins one (by id, by opening a project that has a running session, or with an invitation code), and can be in several sessions at once.

Settings and tokens live in ~/.config/dzstudio-mcp/ (or $XDG_CONFIG_HOME/dzstudio-mcp, %APPDATA%\dzstudio-mcp on Windows, or the directory in DZSTUDIO_MCP_CONFIG_DIR). credentials.json is readable only by you; no tool ever returns a token to the agent.

Class and map data

The world tools compute on static data: per world 256 m tiles with terrain heights, surface, walkable surfaces and static objects, and one class index with boxes, dimensions and shape rasters. By default they come from dzbot (https://uploads.dzbot.de/world-data/, current revisions from https://dzbot.de/api/public/world-data). Another source is set once in config.json:

{ "worldData": { "base": "file:///srv/world-data/" } }

or a mirror with its own pointer:

{ "worldData": { "base": "https://mirror.example.org/world-data/", "pointer": "https://mirror.example.org/world-data.json" } }

A local folder has the published layout (classes/<revision>/…, worlds/<world>/<revision>/…); its newest revisions are used and the map key comes from each manifest. Downloaded files are kept in cache/ of the config directory below their revision and never requested again; every tile and raster is checked against size and SHA-256 from the manifest, a changed file in the cache is loaded once more, and a file that stays wrong is reported as "map data corrupt". The session's map key (e.g. chernarus) picks the world; the revision stays the same for the whole session. Missing data are "unknown", never zero: a class without data has "box unknown", a map without data gives "No map data for ‹map› — project objects only", and a tile that cannot be loaded is named in the answer.

Related MCP server: MCP Server for SketchUp

Tools

Some rules the MCP keeps for the agent: it joins only servers that announce the agents capability, so nobody sees it as a human; it changes an existing object only while holding its lock; it never saves, invites, removes anyone or ends a session; it does not edit loot (loot entries pass through unchanged); after 30 minutes without work it leaves a session and joins again on the next task.

Development

npm test           # unit tests, plus an integration test against the reference collaboration server if Go is installed
npm run typecheck
npm run format

The integration tests build the reference server from ../collab-server (or DZCOLLAB_SOURCE), or use the binary in DZCOLLAB_SERVER, and run it on a free port on 127.0.0.1. One of them drives the whole agent flow through an MCP client: login with a code, joining a person's session, status, a step, review, leaving. Without Go and without a binary they are skipped.

The world tools are tested on a tiny world in test/fixtures/world-data, made with the reference converter. An opt-in test compares every answer with the converter's JavaScript reader on a full converted world: it runs when DZSTUDIO_MCP_WORLD_DATA_REFERENCE (default /tmp/world-data-out) holds one and DZSTUDIO_MCP_WORLD_DATA_READER points to world_data_read.js; DZSTUDIO_MCP_WORLD_DATA_WORLD picks the world (default chernarusplus).

Contributing

Issues and pull requests are welcome, see CONTRIBUTING.md.

License

AGPL-3.0, see LICENSE.