@dzbot/dzstudio-mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# dzstudio-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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. Add it to your MCP client, for example in Claude Code:
+
+```bash
+claude mcp add dzstudio -e DZSTUDIO_MCP_SERVERS=dzbot=https://collab.dzbot.de/dzcollab/ -e DZSTUDIO_MCP_AGENT_NAME=Scout -- npx -y @dzbot/dzstudio-mcp
+```
+
+or in a client's JSON configuration (Claude Desktop, Cursor and others):
+
+```json
+{
+  "mcpServers": {
+    "dzstudio": {
+      "command": "npx",
+      "args": ["-y", "@dzbot/dzstudio-mcp"],
+      "env": { "DZSTUDIO_MCP_SERVERS": "dzbot=https://collab.dzbot.de/dzcollab/", "DZSTUDIO_MCP_AGENT_NAME": "Scout" }
+    }
+  }
+}
+```
+
+Use your own server's address instead of dzbot's if you run the collaboration server yourself. To run it from a
+checkout instead: `npm install && npm run build`, then `node /path/to/dzstudio-mcp/dist/index.js` as the command.
+
+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.
+
+| Variable | Meaning |
+| --- | --- |
+| `DZSTUDIO_MCP_SERVERS` | Servers added on start if missing: `name=url,name=url` |
+| `DZSTUDIO_MCP_AGENT_NAME` | Short name of the agent (default `Agent`) |
+| `DZSTUDIO_MCP_CONFIG_DIR` | Where settings and tokens are kept |
+| `DZSTUDIO_MCP_CACHE_LIMIT_MB` | Size limit of the map data cache in MB (default 2048) |
+| `DZSTUDIO_MCP_WORLD_DATA` | Class and map data: a folder or a `file://`/`https://` base address (overrides `worldData.base`) |
+| `DZSTUDIO_MCP_WORLD_DATA_POINTER` | Pointer to the current revisions for a base address (overrides `worldData.pointer`) |
+
+### 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`:
+
+```json
+{ "worldData": { "base": "file:///srv/world-data/" } }
+```
+
+or a mirror with its own pointer:
+
+```json
+{ "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.
+
+The cache holds at most 2 GB. Above that, the least recently used tiles and rasters are deleted (and downloaded again
+when a question needs them); nothing of a revision that a session the agent is in works on is ever deleted. Another
+limit is set in MB with `worldData.cacheLimitMb` in `config.json` or `DZSTUDIO_MCP_CACHE_LIMIT_MB`:
+
+```json
+{ "worldData": { "cacheLimitMb": 512 } }
+```
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `list_servers`, `add_server`, `login` | Servers, whether you are signed in, whether they admit agents |
+| `list_projects`, `open_project`, `join_session` | Projects and sessions you may join; join one, or open a project on the server that nobody has open |
+| `list_sessions`, `switch_session`, `leave_session` | The sessions the agent is in; the current one is used when a tool names none |
+| `session_info`, `session_events` | Participants with phase and status, rights, save state; what happened since the last call |
+| `read_scene`, `query_objects` | Groups and objects of the project, by id, group, class, circle or rectangle |
+| `create_objects`, `modify_objects`, `delete_objects` | Each call is one step for everyone; objects are locked first |
+| `release` | Let others edit objects the agent holds |
+| `set_status`, `request_review` | Phase (waiting for work, working, waiting for review) and the status line everyone sees |
+| `world_info` | World, data revisions, game version and export date for the session's map; place names near a point or by text |
+| `world_objects` | Static map objects and project objects whose box touches a circle or rectangle, with transform, distance and size or "box unknown" |
+| `ground_at` | Terrain height, material, water, roads and building floors at up to 1000 points; the highest surface below a height |
+| `object_ground` | How project objects or a hypothetical placement stand: "floats ‹x› m", "‹x› m in the ground", or the corner distances |
+| `check_overlap` | Which map and project objects intersect, as rotated boxes with penetration depth; with `precise`, the collision rasters confirm each intersection (pairs without a raster are compared as boxes and say so); objects without a known box are named |
+| `class_info` | Size, clipping and collision box, radius, flags and raster of classes or models |
+
+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.
+
+**Restarts.** The MCP keeps every session it is in, with its place in the session log and the project state there, in
+`sessions/` of the config directory. When it stops it does not leave; when it starts again it returns to each session
+as the same participant and continues from that place, with what others did in the meantime. If the server cannot take
+it back that way (it was away too long, or the server no longer has the log from there), it joins anew. A session it
+would have left while idle meanwhile, or one that ended, is forgotten.
+
+**Opening a project nobody has open.** When no session is running for a project on the server, `open_project` loads
+its files and builds the project state exactly as dzStudio does when it opens them — the same groups, objects, ids form,
+companion data and order, byte for byte — then starts the session with it, as the only participant. This needs the right
+to save the project (the server checks it) and the class data (for each object, dzStudio notes whether the game knows its
+class; the class data stand in for the game). Where dzStudio's result depends on the running game and not on the files,
+the MCP refuses instead of opening a different state: a group file that places a model by its path (the game places the
+model to learn its origin), or a project with loot turned on. A person then opens it in dzStudio, and the agent joins
+that session. Agents never create a new project.
+
+## Development
+
+```bash
+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`).
+
+| Directory | Content |
+| --- | --- |
+| `src/scene` | The project state outside the game: text form, numbers, chunks, ids, applying operations, building new ones, opening a project from its files |
+| `src/protocol` | The dzcollab 1 client: requests, the session with its poll and send channel |
+| `src/config` | Servers, agent name, tokens and the world data source, configured once |
+| `src/world` | Class and map data: file formats, loading and cache, and the geometry behind the world tools |
+| `src/mcp` | The tools and the MCP wiring |
+
+## Contributing
+
+Issues and pull requests are welcome, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+AGPL-3.0, see [LICENSE](LICENSE).

package/dist/config/config.js

@@ -0,0 +1,172 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { randomToken } from '../scene/ids.js';
+export const DEFAULT_AGENT_NAME = 'Agent';
+const NAME_FORM = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/;
+export function defaultConfigDir(env = process.env) {
+    if (env.DZSTUDIO_MCP_CONFIG_DIR)
+        return env.DZSTUDIO_MCP_CONFIG_DIR;
+    if (process.platform === 'win32' && env.APPDATA)
+        return join(env.APPDATA, 'dzstudio-mcp');
+    return join(env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'dzstudio-mcp');
+}
+/** `DZSTUDIO_MCP_SERVERS="local=http://127.0.0.1:8080/dzcollab/,dzbot=https://…"` */
+export function parseServerList(text) {
+    return text
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => {
+        const i = s.indexOf('=');
+        if (i <= 0)
+            throw new Error(`server entry needs name=url: ${s}`);
+        return { name: s.slice(0, i).trim(), url: s.slice(i + 1).trim() };
+    });
+}
+export function validateServerName(name) {
+    if (!NAME_FORM.test(name))
+        throw new Error('A server name has 1 to 64 characters: letters, digits, space, dot, _ and -');
+}
+export function validateServerUrl(url) {
+    let u;
+    try {
+        u = new URL(url);
+    }
+    catch {
+        throw new Error(`Not a URL: ${url}`);
+    }
+    if (u.protocol !== 'https:' && u.protocol !== 'http:')
+        throw new Error('The base address must be http or https');
+    return u.href.endsWith('/') ? u.href : u.href + '/';
+}
+export class ConfigStore {
+    env;
+    dir;
+    config;
+    credentials;
+    constructor(dir, env = process.env) {
+        this.env = env;
+        this.dir = dir ?? defaultConfigDir(env);
+    }
+    path(name) {
+        return join(this.dir, name);
+    }
+    ensureDir() {
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    }
+    readJson(name) {
+        const p = this.path(name);
+        if (!existsSync(p))
+            return undefined;
+        return JSON.parse(readFileSync(p, 'utf8'));
+    }
+    writeJson(name, value, mode) {
+        this.ensureDir();
+        const p = this.path(name);
+        const tmp = p + '.tmp';
+        writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode });
+        chmodSync(tmp, mode);
+        renameSync(tmp, p);
+    }
+    load() {
+        if (this.config)
+            return this.config;
+        const stored = this.readJson('config.json') ?? {};
+        let dirty = !existsSync(this.path('config.json'));
+        const config = {
+            agentName: stored.agentName || DEFAULT_AGENT_NAME,
+            installationId: /^[0-9a-z]{16}$/.test(stored.installationId ?? '') ? stored.installationId : randomToken(16),
+            servers: Array.isArray(stored.servers)
+                ? stored.servers.filter((s) => s && typeof s.name === 'string' && typeof s.url === 'string')
+                : [],
+        };
+        if (stored.worldData && typeof stored.worldData === 'object')
+            config.worldData = stored.worldData;
+        if (config.installationId !== stored.installationId)
+            dirty = true;
+        if (this.env.DZSTUDIO_MCP_AGENT_NAME && config.agentName !== this.env.DZSTUDIO_MCP_AGENT_NAME) {
+            config.agentName = this.env.DZSTUDIO_MCP_AGENT_NAME;
+            dirty = true;
+        }
+        if (this.env.DZSTUDIO_MCP_SERVERS) {
+            for (const s of parseServerList(this.env.DZSTUDIO_MCP_SERVERS)) {
+                if (!config.servers.some((x) => x.name === s.name)) {
+                    validateServerName(s.name);
+                    config.servers.push({ name: s.name, url: validateServerUrl(s.url) });
+                    dirty = true;
+                }
+            }
+        }
+        this.config = config;
+        if (dirty)
+            this.save();
+        return config;
+    }
+    /** World data settings: `DZSTUDIO_MCP_WORLD_DATA` (and `…_POINTER`) win over config.json, without being stored. */
+    worldData() {
+        const out = {
+            ...this.load().worldData,
+            cacheDir: join(this.dir, 'cache'),
+        };
+        const base = this.env.DZSTUDIO_MCP_WORLD_DATA;
+        if (base) {
+            out.base = /^[a-z]+:\/\//.test(base) ? base : pathToFileURL(resolve(base)).href;
+            delete out.pointer;
+        }
+        if (this.env.DZSTUDIO_MCP_WORLD_DATA_POINTER)
+            out.pointer = this.env.DZSTUDIO_MCP_WORLD_DATA_POINTER;
+        const mb = Number(this.env.DZSTUDIO_MCP_CACHE_LIMIT_MB ?? out.cacheLimitMb);
+        if (Number.isFinite(mb) && mb > 0)
+            out.cacheLimit = Math.round(mb * 1024 * 1024);
+        return out;
+    }
+    save() {
+        if (this.config)
+            this.writeJson('config.json', this.config, 0o600);
+    }
+    server(name) {
+        const servers = this.load().servers;
+        if (!servers.length)
+            throw new Error('No server configured — call add_server');
+        if (name === undefined)
+            return servers[0];
+        const s = servers.find((x) => x.name === name);
+        if (!s)
+            throw new Error(`No server named ${name} — call list_servers`);
+        return s;
+    }
+    addServer(name, url) {
+        validateServerName(name);
+        const entry = { name, url: validateServerUrl(url) };
+        const config = this.load();
+        if (config.servers.some((s) => s.name === name))
+            throw new Error(`A server named ${name} already exists`);
+        config.servers.push(entry);
+        this.save();
+        return entry;
+    }
+    creds() {
+        this.credentials ??= this.readJson('credentials.json') ?? {};
+        return this.credentials;
+    }
+    credential(server) {
+        const c = this.creds()[server];
+        if (!c)
+            return undefined;
+        if (c.expiresAt !== undefined && c.expiresAt <= Date.now())
+            return undefined;
+        return c;
+    }
+    setCredential(server, c) {
+        const all = this.creds();
+        if (c)
+            all[server] = c;
+        else
+            delete all[server];
+        this.writeJson('credentials.json', all, 0o600);
+    }
+}
+//# sourceMappingURL=config.js.map

package/dist/config/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config/config.ts"],"names":[],"mappings":"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"}

package/dist/config/sessions.js

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * The sessions the agent is in, kept in `sessions/` of the config directory: per session a small file with the
+ * participation and a file with the project state at a sequence number (the cursor `resume` continues from).
+ */
+export class SessionStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    base(server, sessionId) {
+        return join(this.dir, createHash('sha256').update(`${server}\u0000${sessionId}`).digest('hex').slice(0, 24));
+    }
+    write(path, data) {
+        if (!existsSync(this.dir))
+            mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+        const tmp = `${path}.${process.pid}.tmp`;
+        writeFileSync(tmp, data, { mode: 0o600 });
+        renameSync(tmp, path);
+    }
+    list() {
+        if (!existsSync(this.dir))
+            return [];
+        const out = [];
+        for (const f of readdirSync(this.dir)) {
+            if (!f.endsWith('.json'))
+                continue;
+            try {
+                const s = JSON.parse(readFileSync(join(this.dir, f), 'utf8'));
+                if (typeof s.sessionId === 'string' && typeof s.participantId === 'string')
+                    out.push(s);
+            }
+            catch {
+                // a broken file is no session to return to
+            }
+        }
+        return out;
+    }
+    save(s) {
+        this.write(`${this.base(s.server, s.sessionId)}.json`, JSON.stringify(s) + '\n');
+    }
+    /** The project state after sequence number `seq`, as its text form. */
+    saveState(server, sessionId, seq, text) {
+        this.write(`${this.base(server, sessionId)}.state`, `${seq}\n${text}`);
+    }
+    state(server, sessionId) {
+        try {
+            const raw = readFileSync(`${this.base(server, sessionId)}.state`, 'utf8');
+            const nl = raw.indexOf('\n');
+            const seq = Number(raw.slice(0, nl));
+            if (nl < 0 || !Number.isSafeInteger(seq) || seq < 0)
+                return undefined;
+            return { seq, text: raw.slice(nl + 1) };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    remove(server, sessionId) {
+        const b = this.base(server, sessionId);
+        rmSync(`${b}.json`, { force: true });
+        rmSync(`${b}.state`, { force: true });
+    }
+}
+//# sourceMappingURL=sessions.js.map

package/dist/config/sessions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.js","sourceRoot":"","sources":["../../src/config/sessions.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ConfigStore } from './config/config.js';
+import { Agent } from './mcp/agent.js';
+import { createServer } from './mcp/server.js';
+const agent = new Agent({ store: new ConfigStore() });
+const server = createServer(agent);
+async function shutdown() {
+    await agent.shutdown().catch(() => undefined);
+    process.exit(0);
+}
+process.on('SIGINT', () => void shutdown());
+process.on('SIGTERM', () => void shutdown());
+process.stdin.on('close', () => void shutdown());
+await server.connect(new StdioServerTransport());
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,WAAW,EAAE,EAAE,CAAC,CAAC;AACtD,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;AAEnC,KAAK,UAAU,QAAQ;IACrB,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;AAC5C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;AAC7C,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK,QAAQ,EAAE,CAAC,CAAC;AAEjD,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC"}