stonecut-map-builder 0.0.0-stage → 0.1.0

package/dist/safety/paths.js

@@ -0,0 +1,103 @@
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+// Keeps every file the tools touch inside one folder. Checks the text of the path first
+// (no absolute paths, no "..", no drive letters or Windows device names), then resolves symlinks,
+// junctions and Windows short names (PROGRA~1) of everything that already exists and checks again.
+// The path it returns is that resolved one, so later checks on names see the real names.
+export class PathError extends Error {
+}
+const WINDOWS_DEVICE = /^(con|prn|aux|nul|com[0-9¹²³]|lpt[0-9¹²³]|conin\$|conout\$)(\..*)?$/i;
+const caseInsensitive = process.platform === 'win32' || process.platform === 'darwin';
+// Hidden folders ignore letter case on every system: Linux folders can be case-folded too.
+function fold(p) {
+    return p.toLowerCase();
+}
+function norm(p) {
+    return caseInsensitive ? p.toLowerCase() : p;
+}
+/** True when child is root itself or inside it. Both must be absolute and resolved. */
+export function isInside(root, child) {
+    const rel = relative(norm(root), norm(child));
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+function realOrSelf(p) {
+    try {
+        return realpathSync.native(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Real path of the deepest part of p that exists, with the missing rest appended. */
+function realDeepest(p) {
+    let existing = p;
+    const rest = [];
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing)
+            break;
+        rest.unshift(existing.slice(parent.length).replace(/^[\\/]+/, ''));
+        existing = parent;
+    }
+    return rest.length ? join(realOrSelf(existing), ...rest) : realOrSelf(existing);
+}
+/**
+ * Resolves a path given relative to root. Throws PathError if it is absolute, uses "..",
+ * names a Windows device or stream, or ends up outside root after following links. Returns the
+ * path with links and short names resolved as far as it exists.
+ */
+export function resolveInside(root, userPath, options = {}) {
+    if (typeof userPath !== 'string' || userPath.trim() === '')
+        throw new PathError('Path is empty');
+    if (userPath.includes('\0'))
+        throw new PathError('Path contains a NUL character');
+    const cleaned = userPath.replace(/\\/g, '/');
+    if (cleaned.startsWith('/') || /^[A-Za-z]:/.test(cleaned) || isAbsolute(userPath)) {
+        throw new PathError(`Use a path relative to the server folder, not an absolute path: ${userPath}`);
+    }
+    const parts = cleaned.split('/').filter((s) => s !== '' && s !== '.');
+    if (parts.length === 0)
+        return realDeepest(resolve(root));
+    for (const part of parts) {
+        if (part === '..')
+            throw new PathError(`".." is not allowed in paths: ${userPath}`);
+        if (part.includes(':'))
+            throw new PathError(`":" is not allowed in paths: ${userPath}`);
+        if (WINDOWS_DEVICE.test(part))
+            throw new PathError(`"${part}" is a reserved name on Windows`);
+        if (/[. ]$/.test(part))
+            throw new PathError(`Path parts may not end with a dot or space: ${part}`);
+    }
+    const hidden = (options.hidden ?? []).map(fold);
+    if (hidden.includes(fold(parts[0])))
+        throw new PathError(`${parts[0]} is the tool's own folder and cannot be read or changed`);
+    const rootReal = realDeepest(resolve(root));
+    const target = resolve(rootReal, ...parts);
+    if (!isInside(rootReal, target))
+        throw new PathError(`Path leaves the server folder: ${userPath}`);
+    const real = realDeepest(target);
+    if (!isInside(rootReal, real))
+        throw new PathError(`Path leads outside the server folder through a link: ${userPath}`);
+    const first = relative(rootReal, real).split(sep)[0] ?? '';
+    if (first !== '' && hidden.includes(fold(first)))
+        throw new PathError(`${userPath} leads into the tool's own folder, which cannot be read or changed`);
+    return real;
+}
+/** The path relative to root, with forward slashes, for showing to the agent. */
+export function shown(root, p) {
+    return relative(realDeepest(resolve(root)), p).split(sep).join('/');
+}
+/**
+ * Checks that an absolute folder is one of the allowed folders or inside one, after following
+ * links. Returns the resolved folder.
+ */
+export function checkAllowedFolder(allowed, folder) {
+    if (!isAbsolute(folder))
+        throw new PathError(`Give the server folder as a full path: ${folder}`);
+    const real = realDeepest(resolve(folder));
+    for (const root of allowed) {
+        if (isInside(realDeepest(resolve(root)), real))
+            return real;
+    }
+    throw new PathError(`${folder} is not inside an allowed server folder. Allowed: ${allowed.join(', ')}. The person can add folders under "serverFolders" in the config file.`);
+}

package/dist/schemas.js

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+import { BlockError, checkBlockFilter, checkBlockState, checkSnbt, COORD_LIMIT, MAX_COMMAND_BYTES } from './mc/blocks.js';
+// Input shapes shared by the tools. Everything is checked here before any command is built.
+const passes = (fn) => (s) => {
+    try {
+        fn(s);
+        return true;
+    }
+    catch (e) {
+        if (e instanceof BlockError)
+            return false;
+        throw e;
+    }
+};
+export const coord = z.number().int('Coordinates are whole numbers').min(-COORD_LIMIT).max(COORD_LIMIT);
+export const vec3 = z.tuple([coord, coord, coord]).describe('[x, y, z]');
+export const blockState = z
+    .string()
+    .max(300)
+    .refine(passes(checkBlockState), 'Not a block state. Use namespace:name[property=value,...], for example minecraft:oak_stairs[facing=north]')
+    .describe('Block state, for example "minecraft:stone" or "minecraft:oak_stairs[facing=north,half=top]"');
+export const blockFilter = z
+    .string()
+    .max(300)
+    .refine(passes(checkBlockFilter), 'Use a block state or a block tag such as #minecraft:logs')
+    .describe('Only replace this block (state or #tag)');
+export const snbt = z
+    .string()
+    .max(MAX_COMMAND_BYTES)
+    .refine(passes(checkSnbt), 'Block data must be one SNBT compound {...} on one line')
+    .describe('Optional block entity data in SNBT, for example {Items:[...]} for a chest');
+export const dimension = z
+    .enum(['overworld', 'the_nether', 'the_end'])
+    .default('overworld')
+    .describe('Dimension. Default overworld.');
+export const skipBackup = z
+    .boolean()
+    .optional()
+    .describe('Only for areas too big for an undo snapshot, after backup_world. Default false.');
+export const confirm = z
+    .boolean()
+    .optional()
+    .describe('Set true only after the person agreed to this change (needed while confirmDestructive is on).');
+export const serverRelPath = z.string().min(1).max(512).describe('Path inside the test server folder, for example "world/datapacks/my_pack/pack.mcmeta"');
+export const schemPath = serverRelPath
+    .refine((p) => p.toLowerCase().endsWith('.schem'), 'File name must end with .schem')
+    .describe('Path inside the test server folder ending in .schem, for example "schematics/house.schem"');
+export const command = z
+    .string()
+    .min(1)
+    .max(MAX_COMMAND_BYTES)
+    .refine((c) => !/[\r\n\0]/.test(c), 'One command, on one line')
+    .describe('A server command without the leading slash, for example "time set day"');
+export const includeEntities = z
+    .boolean()
+    .optional()
+    .describe('Include entities (item frames, paintings, armor stands, mobs, minecarts, boats). Default: includeEntities in the config (on).');

package/dist/schematic/sponge.js

@@ -0,0 +1,264 @@
+import { gzipSync } from 'node:zlib';
+import { get, nbt, NbtError, need, num, unpackNbt, writeNbt } from '../nbt/nbt.js';
+export class SchematicError extends Error {
+}
+export function indexOf(s, x, y, z) {
+    return x + z * s.width + y * s.width * s.length;
+}
+export function blockAt(s, x, y, z) {
+    return s.palette[s.blocks[indexOf(s, x, y, z)]];
+}
+// ---- varints (unsigned LEB128, as the spec uses) ----
+export function encodeVarints(values) {
+    const out = [];
+    for (let i = 0; i < values.length; i++) {
+        let v = values[i];
+        while (v >= 0x80) {
+            out.push((v & 0x7f) | 0x80);
+            v >>>= 7;
+        }
+        out.push(v);
+    }
+    return Int8Array.from(out, (b) => (b > 127 ? b - 256 : b));
+}
+export function decodeVarints(bytes, count) {
+    const out = new Uint32Array(count);
+    let p = 0;
+    for (let i = 0; i < count; i++) {
+        let value = 0;
+        let shift = 0;
+        for (;;) {
+            if (p >= bytes.length)
+                throw new SchematicError('Block data ends early');
+            const b = bytes[p++] & 0xff;
+            value |= (b & 0x7f) << shift;
+            if ((b & 0x80) === 0)
+                break;
+            shift += 7;
+            if (shift > 28)
+                throw new SchematicError('Block data has a varint that is too long');
+        }
+        out[i] = value >>> 0;
+    }
+    if (p !== bytes.length)
+        throw new SchematicError('Block data has extra bytes after the last block');
+    return out;
+}
+// ---- reading ----
+function dims(root) {
+    const read = (k) => {
+        const v = num(root, k);
+        if (v === undefined)
+            throw new SchematicError(`Schematic has no ${k}`);
+        return v & 0xffff;
+    };
+    return { width: read('Width'), height: read('Height'), length: read('Length') };
+}
+function readPalette(p) {
+    const palette = [];
+    for (const [state, t] of p.value) {
+        if (t.type !== 'int')
+            throw new SchematicError('Palette values must be ints');
+        if (t.value < 0 || t.value > 1_000_000)
+            throw new SchematicError('Palette index out of range');
+        if (palette[t.value] !== undefined)
+            throw new SchematicError(`Palette index ${t.value} is used twice`);
+        palette[t.value] = state;
+    }
+    return palette;
+}
+function readPos(c, where) {
+    const p = get(c, 'Pos', 'intArray');
+    if (!p || p.value.length !== 3)
+        throw new SchematicError(`${where}: Pos must be 3 ints`);
+    return [p.value[0], p.value[1], p.value[2]];
+}
+function readBlockEntities(list, version, size) {
+    if (!list || list.type !== 'list')
+        return [];
+    const out = [];
+    for (const t of list.value) {
+        if (t.type !== 'compound')
+            continue;
+        const pos = readPos(t, 'Block entity');
+        if (pos.some((v, i) => v < 0 || v >= size[i]))
+            throw new SchematicError('Block entity outside the schematic');
+        const id = get(t, 'Id', 'string')?.value ?? get(t, 'id', 'string')?.value;
+        if (!id)
+            throw new SchematicError('Block entity without Id');
+        let data;
+        const nested = get(t, 'Data', 'compound');
+        if (version >= 3 && nested) {
+            data = nbt.compound(new Map(nested.value));
+        }
+        else {
+            data = nbt.compound(new Map(t.value));
+        }
+        for (const k of ['Pos', 'Id', 'id', 'x', 'y', 'z'])
+            data.value.delete(k);
+        out.push({ pos, id, data });
+    }
+    return out;
+}
+/**
+ * Most bytes a schematic of maxBlocks blocks may take unpacked: room for its block data and plenty of
+ * block entities, and far less than a decompression bomb would make.
+ */
+export function schematicByteLimit(maxBlocks) {
+    return 64 * 1024 * 1024 + maxBlocks * 16;
+}
+export function readSponge(file, options = {}) {
+    let rootTag;
+    try {
+        rootTag = (options.maxBlocks === undefined ? unpackNbt(file) : unpackNbt(file, schematicByteLimit(options.maxBlocks), 1_000_000 + options.maxBlocks * 4)).tag;
+    }
+    catch (e) {
+        throw new SchematicError(`Not a readable schematic: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const root = get(rootTag, 'Schematic', 'compound') ?? rootTag;
+    const version = num(root, 'Version');
+    if (version !== 1 && version !== 2 && version !== 3) {
+        throw new SchematicError(`Unsupported schematic version ${version ?? 'missing'} (Sponge versions 2 and 3 are supported)`);
+    }
+    const { width, height, length } = dims(root);
+    const volume = width * height * length;
+    if (volume === 0)
+        throw new SchematicError('Schematic is empty');
+    if (options.maxBlocks !== undefined && volume > options.maxBlocks) {
+        throw new SchematicError(`Schematic has ${volume} blocks (${width}x${height}x${length}), over the limit of ${options.maxBlocks}`);
+    }
+    const off = get(root, 'Offset', 'intArray');
+    const offset = off && off.value.length === 3 ? [off.value[0], off.value[1], off.value[2]] : [0, 0, 0];
+    const dataVersion = num(root, 'DataVersion') ?? 0;
+    let paletteTag;
+    let dataTag;
+    let entitiesTag;
+    try {
+        if (version === 3) {
+            const blocks = need(root, 'Blocks', 'compound', 'Schematic');
+            paletteTag = need(blocks, 'Palette', 'compound', 'Blocks');
+            dataTag = need(blocks, 'Data', 'byteArray', 'Blocks').value;
+            entitiesTag = blocks.value.get('BlockEntities');
+        }
+        else {
+            paletteTag = need(root, 'Palette', 'compound', 'Schematic');
+            dataTag = need(root, 'BlockData', 'byteArray', 'Schematic').value;
+            entitiesTag = root.value.get('BlockEntities') ?? root.value.get('TileEntities');
+        }
+    }
+    catch (e) {
+        if (e instanceof NbtError)
+            throw new SchematicError(e.message);
+        throw e;
+    }
+    const palette = readPalette(paletteTag);
+    const blocks = decodeVarints(dataTag, volume);
+    for (let i = 0; i < blocks.length; i++) {
+        if (palette[blocks[i]] === undefined)
+            throw new SchematicError(`Block ${i} uses palette index ${blocks[i]} that is not in the palette`);
+    }
+    const blockEntities = readBlockEntities(entitiesTag, version, [width, height, length]);
+    const entities = readEntities(root.value.get('Entities'), version, options.maxEntities);
+    const meta = get(root, 'Metadata', 'compound');
+    const originTag = meta ? get(get(meta, 'Stonecut', 'compound') ?? nbt.compound({}), 'Origin', 'intArray') : undefined;
+    const origin = originTag && originTag.value.length === 3 ? [originTag.value[0], originTag.value[1], originTag.value[2]] : undefined;
+    return {
+        schematic: { width, height, length, offset, dataVersion, palette, blocks, blockEntities, entities, ...(origin ? { origin } : {}) },
+        version: version === 3 ? 3 : 2,
+    };
+}
+function readEntityPos(c) {
+    const p = c.value.get('Pos');
+    if (!p || p.type !== 'list' || p.value.length !== 3)
+        return null;
+    const v = p.value.map((t) => (t.type === 'double' || t.type === 'float' || t.type === 'int' ? t.value : NaN));
+    return v.every(Number.isFinite) ? [v[0], v[1], v[2]] : null;
+}
+function readEntities(list, version, max) {
+    if (!list || list.type !== 'list')
+        return [];
+    if (max !== undefined && list.value.length > max)
+        throw new SchematicError(`Schematic has ${list.value.length} entities, over the limit of ${max}`);
+    const out = [];
+    for (const t of list.value) {
+        if (t.type !== 'compound')
+            continue;
+        const pos = readEntityPos(t);
+        const id = get(t, 'Id', 'string')?.value ?? get(t, 'id', 'string')?.value;
+        if (!pos || !id)
+            throw new SchematicError('Entity without Pos or Id');
+        const nested = get(t, 'Data', 'compound');
+        const data = nbt.compound(new Map(version >= 3 && nested ? nested.value : t.value));
+        if (!(version >= 3 && nested))
+            for (const k of ['Pos', 'Id'])
+                data.value.delete(k);
+        data.value.delete('id');
+        out.push({ pos, id, data });
+    }
+    return out;
+}
+const posList = (v) => nbt.list('double', v.map((x) => nbt.double(x)));
+// ---- writing ----
+function u16(v) {
+    if (!Number.isInteger(v) || v < 1 || v > 0xffff)
+        throw new SchematicError('Schematic sides must be 1-65535');
+    return nbt.short(v > 0x7fff ? v - 0x10000 : v);
+}
+/** Drops palette entries no block uses and renumbers the rest in order of first use. */
+export function compactPalette(s) {
+    const map = new Map();
+    const palette = [];
+    const blocks = new Uint32Array(s.blocks.length);
+    for (let i = 0; i < s.blocks.length; i++) {
+        const old = s.blocks[i];
+        let next = map.get(old);
+        if (next === undefined) {
+            next = palette.length;
+            map.set(old, next);
+            palette.push(s.palette[old]);
+        }
+        blocks[i] = next;
+    }
+    return { ...s, palette, blocks };
+}
+export function writeSponge(input, version = 3) {
+    const s = compactPalette(input);
+    if (s.blocks.length !== s.width * s.height * s.length)
+        throw new SchematicError('Block count does not match the size');
+    const palette = nbt.compound(new Map(s.palette.map((state, i) => [state, nbt.int(i)])));
+    const data = nbt.byteArray(encodeVarints(s.blocks));
+    const common = [
+        ['Version', nbt.int(version)],
+        ['DataVersion', nbt.int(s.dataVersion)],
+        [
+            'Metadata',
+            nbt.compound({ Date: nbt.long(BigInt(Date.now())), ...(s.origin ? { Stonecut: nbt.compound({ Origin: nbt.intArray(s.origin) }) } : {}) }),
+        ],
+        ['Width', u16(s.width)],
+        ['Height', u16(s.height)],
+        ['Length', u16(s.length)],
+        ['Offset', nbt.intArray(s.offset)],
+    ];
+    if (version === 2) {
+        const entities = s.blockEntities.map((be) => nbt.compound(new Map([['Pos', nbt.intArray(be.pos)], ['Id', nbt.string(be.id)], ...be.data.value])));
+        const root = nbt.compound(new Map([
+            ...common,
+            ['PaletteMax', nbt.int(s.palette.length)],
+            ['Palette', palette],
+            ['BlockData', data],
+            ['BlockEntities', nbt.list('compound', entities)],
+            // Version 2 keeps entity data flat next to Pos and Id, so the world position inside the data is left out.
+            ['Entities', nbt.list('compound', (s.entities ?? []).map((e) => nbt.compound(new Map([
+                    ...[...e.data.value].filter(([k]) => k !== 'Pos' && k !== 'Id' && k !== 'id'),
+                    ['Pos', posList(e.pos)],
+                    ['Id', nbt.string(e.id)],
+                ]))))],
+        ]));
+        return gzipSync(writeNbt('Schematic', root));
+    }
+    const entities = s.blockEntities.map((be) => nbt.compound({ Pos: nbt.intArray(be.pos), Id: nbt.string(be.id), Data: be.data }));
+    const blocks = nbt.compound({ Palette: palette, Data: data, BlockEntities: nbt.list('compound', entities) });
+    const mobs = (s.entities ?? []).map((e) => nbt.compound({ Pos: posList(e.pos), Id: nbt.string(e.id), Data: e.data }));
+    const inner = nbt.compound(new Map([...common, ['Blocks', blocks], ['Entities', nbt.list('compound', mobs)]]));
+    return gzipSync(writeNbt('', nbt.compound({ Schematic: inner })));
+}

package/dist/server.js

@@ -0,0 +1,16 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { GUIDE } from './guide.js';
+import { backupTools } from './tools/backup.js';
+import { blockTools } from './tools/blocks.js';
+import { registerTools } from './tools/define.js';
+import { fileTools } from './tools/files.js';
+import { schematicTools } from './tools/schematic.js';
+import { serverTools } from './tools/server.js';
+import { setupTools } from './tools/setup.js';
+import { SERVER_NAME, VERSION } from './version.js';
+export const ALL_TOOLS = [...setupTools, ...serverTools, ...blockTools, ...schematicTools, ...backupTools, ...fileTools];
+export function createServer(ctx) {
+    const server = new McpServer({ name: SERVER_NAME, version: VERSION }, { instructions: GUIDE });
+    registerTools(server, ctx, ALL_TOOLS);
+    return server;
+}

package/dist/tools/backup.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+import { backupWorld, restoreWorld } from '../ops/backup.js';
+import { confirm } from '../schemas.js';
+import { tool } from './define.js';
+export const backupTools = [
+    tool({
+        name: 'backup_world',
+        title: 'Back up the whole world',
+        description: "Copies the whole world folder into the server's own backup folder (the server pauses saving while it copies, so the copy is consistent). Do this before big changes, for example before importing a large map or anything too big for an undo snapshot. The tool never deletes backups.",
+        input: {},
+        readOnly: false,
+        destructive: false,
+        idempotent: false,
+        run: async (_a, ctx) => {
+            const s = ctx.server();
+            return backupWorld(s, (await s.status()).rcon);
+        },
+    }),
+    tool({
+        name: 'restore_world',
+        title: 'Restore a world backup',
+        description: 'Replaces the world with a backup from backup_world. The server must be stopped. The current world is not deleted: it is moved into the backup folder as replaced-<time>. status lists the backups.',
+        input: {
+            name: z.string().min(1).max(80).describe('Backup name from status, for example world-2026-01-31T12-00-00-000'),
+            confirm,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: false,
+        needsOk: (a) => `replace the current world with the backup ${a.name} (the current world is kept as a backup)`,
+        run: async (a, ctx) => {
+            const s = ctx.server();
+            if ((await s.status()).running)
+                throw new Error('Stop the server first (stop_server), then restore.');
+            return restoreWorld(s, a.name);
+        },
+    }),
+];

package/dist/tools/blocks.js

@@ -0,0 +1,140 @@
+import { z } from 'zod';
+import { checkBlockFilter, checkBlockState, checkSnbt } from '../mc/blocks.js';
+import { boxVolume, makeBox } from '../mc/box.js';
+import { describeArea, describeEntities } from '../ops/readout.js';
+import { blockFilter, blockState, confirm, dimension, includeEntities, skipBackup, snbt, vec3 } from '../schemas.js';
+import { tool } from './define.js';
+const area = { from: vec3.describe('One corner [x, y, z]'), to: vec3.describe('The opposite corner [x, y, z], inclusive') };
+export const blockTools = [
+    tool({
+        name: 'place_blocks',
+        title: 'Place blocks',
+        description: 'Places single blocks, up to 10000 per call. The tool packs neighbouring equal blocks into /fill commands, places torches, doors, plants, redstone and liquids after the blocks that hold them, and snapshots the area first so undo can put it back. Later entries at the same spot win.',
+        input: {
+            blocks: z
+                .array(z.object({ pos: vec3, block: blockState, data: snbt.optional() }))
+                .min(1)
+                .max(10_000)
+                .describe('Blocks to place: [{pos: [x, y, z], block: "minecraft:stone"}, ...]'),
+            dimension,
+            skip_backup: skipBackup,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        run: async (a, ctx) => ctx.world().place(a.blocks.map((b) => ({ pos: b.pos, state: checkBlockState(b.block), ...(b.data ? { snbt: checkSnbt(b.data) } : {}) })), { dimension: a.dimension, ...(a.skip_backup ? { skipBackup: true } : {}) }),
+    }),
+    tool({
+        name: 'fill_blocks',
+        title: 'Fill boxes',
+        description: 'Fills one or more boxes with a block, in order. Boxes over 32768 blocks are split for you. mode: replace (default), hollow (walls, inside cleared), outline (walls only, inside kept), keep (only air is filled), destroy (drops items). replace_only limits it to one block or #tag. Snapshots the area first for undo.',
+        input: {
+            fills: z
+                .array(z.object({
+                ...area,
+                block: blockState,
+                mode: z.enum(['replace', 'hollow', 'outline', 'keep', 'destroy']).optional(),
+                replace_only: blockFilter.optional(),
+            }))
+                .min(1)
+                .max(256),
+            dimension,
+            skip_backup: skipBackup,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        run: async (a, ctx) => ctx.world().fill(a.fills.map((f) => ({
+            box: makeBox(f.from, f.to),
+            state: checkBlockState(f.block),
+            ...(f.mode ? { mode: f.mode } : {}),
+            ...(f.replace_only ? { filter: checkBlockFilter(f.replace_only) } : {}),
+        })), { dimension: a.dimension, ...(a.skip_backup ? { skipBackup: true } : {}) }),
+    }),
+    tool({
+        name: 'copy_blocks',
+        title: 'Copy an area',
+        description: 'Copies the box from..to so its lowest corner lands at destination (with /clone). skip_air keeps what is already at the destination where the source is air. Snapshots the destination first for undo.',
+        input: {
+            ...area,
+            destination: vec3.describe('Where the lowest corner of the copy goes [x, y, z]'),
+            skip_air: z.boolean().optional().describe('Do not copy air. Default false.'),
+            dimension,
+            skip_backup: skipBackup,
+        },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        run: async (a, ctx) => ctx.world().copy(makeBox(a.from, a.to), a.destination, a.skip_air ?? false, { dimension: a.dimension, ...(a.skip_backup ? { skipBackup: true } : {}) }),
+    }),
+    tool({
+        name: 'clear_blocks',
+        title: 'Clear an area to air',
+        description: 'Sets every block in the box to air (containers are emptied, nothing drops). With include_entities (default on) it also removes the entities in the box first, without drops; players are never touched. Snapshots the area, entities included, for undo.',
+        input: { ...area, include_entities: includeEntities, dimension, confirm, skip_backup: skipBackup },
+        readOnly: false,
+        destructive: true,
+        idempotent: true,
+        needsOk: (a) => `clear ${boxVolume(makeBox(a.from, a.to))} blocks from ${a.from.join(' ')} to ${a.to.join(' ')}`,
+        run: async (a, ctx) => ctx.world().clear(makeBox(a.from, a.to), { dimension: a.dimension, ...(a.skip_backup ? { skipBackup: true } : {}) }, a.include_entities ?? ctx.config.includeEntities),
+    }),
+    tool({
+        name: 'read_entities',
+        title: 'List the entities in an area',
+        description: 'Lists the entities whose position is inside the box: item frames, paintings, armor stands, mobs, minecarts, boats, items. For each: id, position, rotation, UUID, custom name, what it is tied to (lead) and its data as SNBT (shortened unless full: true). Players are not listed. The server saves first and the tool reads the saved entity files, so it changes nothing. Limited to maxEntities.',
+        input: {
+            ...area,
+            full: z.boolean().optional().describe('Give each entity its complete data. Default false (common fields only, shortened).'),
+            dimension,
+        },
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => {
+            const box = makeBox(a.from, a.to);
+            const list = await ctx.world().entitiesIn(box, a.dimension);
+            ctx.world().checkEntities(list.length, 'The area has');
+            return describeEntities(list, box, a.full ?? false);
+        },
+    }),
+    tool({
+        name: 'read_blocks',
+        title: 'Read the blocks in an area',
+        description: 'Returns the blocks in a box with their full states, block entity ids and a count per block. The server saves the world first and the tool reads the saved chunks, so it changes nothing. Limited to maxReadBlocks per call (32768 by default, for example 32x32x32); read big builds in parts. format "layers" (default) is compact, one line per row; "list" gives every non-air block as [x, y, z, state].',
+        input: {
+            ...area,
+            format: z.enum(['layers', 'list']).default('layers'),
+            dimension,
+        },
+        readOnly: true,
+        destructive: false,
+        idempotent: true,
+        run: async (a, ctx) => {
+            const box = makeBox(a.from, a.to);
+            const v = boxVolume(box);
+            if (v > ctx.config.maxReadBlocks) {
+                throw new Error(`That area is ${v} blocks; read_blocks reads at most ${ctx.config.maxReadBlocks} per call (maxReadBlocks in the config). Read it in smaller boxes.`);
+            }
+            return describeArea(await ctx.world().read(box, a.dimension), box, a.format);
+        },
+    }),
+    tool({
+        name: 'undo',
+        title: 'Undo the last change',
+        description: 'Puts back the area changed by the most recent change (place, fill, copy, clear, import, or run_command with backup_area), from the snapshot taken before it: blocks, and entities when the snapshot has them (entities added since are removed, removed ones are summoned again). Call again to go further back; status lists what can be undone.',
+        input: { confirm },
+        readOnly: false,
+        destructive: true,
+        idempotent: false,
+        needsOk: (_a, ctx) => {
+            const last = ctx.world().undo.latest();
+            return last ? `undo "${last.entry.label}" (${last.entry.blocks} blocks from ${last.entry.box.min.join(' ')} to ${last.entry.box.max.join(' ')})` : null;
+        },
+        run: async (_a, ctx) => {
+            const r = await ctx.world().undoLast();
+            if (!r)
+                throw new Error('Nothing to undo');
+            return r;
+        },
+    }),
+];

package/dist/tools/define.js

@@ -0,0 +1,37 @@
+import { errorResult, textResult } from '../content.js';
+export function tool(spec) {
+    return spec;
+}
+export class NeedsOkError extends Error {
+}
+export async function runTool(ctx, spec, args) {
+    try {
+        return await ctx.serial(async () => {
+            if (spec.needsOk && ctx.config.confirmDestructive && args.confirm !== true) {
+                const what = spec.needsOk(args, ctx);
+                if (what) {
+                    throw new NeedsOkError(`Needs the person's OK first: ${what}. Tell them what will change, and if they agree call ${spec.name} again with confirm: true. (confirmDestructive is on in the config.)`);
+                }
+            }
+            return textResult(await spec.run(args, ctx));
+        });
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+}
+export function annotations(spec) {
+    return {
+        title: spec.title,
+        readOnlyHint: spec.readOnly,
+        destructiveHint: spec.readOnly ? false : spec.destructive,
+        idempotentHint: spec.readOnly ? true : spec.idempotent,
+        openWorldHint: spec.openWorld ?? false,
+    };
+}
+export function registerTools(server, ctx, specs) {
+    for (const spec of specs) {
+        const config = { title: spec.title, description: spec.description, inputSchema: spec.input, annotations: annotations(spec) };
+        server.registerTool(spec.name, config, (args) => runTool(ctx, spec, args));
+    }
+}