stonecut-map-builder 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stonecut Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# Stonecut Map Builder
 
-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.
+Website: https://stonecut.studio/resources | npm: https://www.npmjs.com/package/stonecut-map-builder | YouTube: https://www.youtube.com/@StonecutStudios (videos coming soon)
+
+Let your AI agent build Minecraft maps for you. Stonecut Map Builder gives Claude Code (or any agent
+that supports MCP) its own private Minecraft test server on your computer. The agent sets it up,
+builds on it, checks its own work block by block, and exports what it made as a schematic you can
+paste on any server. Free and open source under the MIT license.
+
+<!-- VIDEO: how it works (owner sends the link) -->
+
+## Setup
+
+1. Install Node.js 20 or newer from https://nodejs.org (the LTS download).
+2. Have Claude Code installed and signed in.
+3. Add the tool to Claude Code. If the `claude` command works in your terminal:
+   - macOS and Linux: `claude mcp add --scope user stonecut-map-builder -- npx -y stonecut-map-builder`
+   - Windows: `claude mcp add --scope user stonecut-map-builder -- cmd /c npx -y stonecut-map-builder`
+
+   If you only use the Claude Code extension in VS Code, `claude` is usually not on your PATH
+   ("not recognized" / "command not found"). Run the copy bundled with the extension instead:
+   - Windows (PowerShell):
+
+     ```powershell
+     & (Get-ChildItem "$env:USERPROFILE\.vscode\extensions\anthropic.claude-code-*\resources\native-binary\claude.exe" | Sort-Object { [version]($_.FullName -replace '.*claude-code-([\d.]+).*','$1') } | Select-Object -Last 1).FullName mcp add --scope user stonecut-map-builder -- cmd /c npx -y stonecut-map-builder
+     ```
+
+   - macOS and Linux:
+
+     ```sh
+     "$(ls -d ~/.vscode/extensions/anthropic.claude-code-*/resources/native-binary/claude | sort -V | tail -n 1)" mcp add --scope user stonecut-map-builder -- npx -y stonecut-map-builder
+     ```
+4. Start Claude Code (in VS Code: "Developer: Reload Window"), type `/mcp` and check that
+   stonecut-map-builder shows as connected.
+5. Paste the setup prompt from [docs/setup-with-ai.md](docs/setup-with-ai.md). The agent installs
+   the skill (it asks first), asks your Minecraft version and modpack, shows what it will download,
+   and asks you to accept the Minecraft EULA. Nothing is installed without your yes.
+6. It starts the server and gives you an address like `localhost:25565`. Join it from Minecraft
+   (same version), ask the agent to make you operator, then ask it to build.
+
+## Example requests
+
+- "Build a small stone watchtower with a spiral staircase and a lookout on top, next to spawn."
+- "Make a medieval market square with five stalls, a well in the middle and lanterns."
+- "Read back the house you just built and fix anything that looks wrong."
+- "Export the castle as a schematic so I can paste it on my server."
+
+## Works with Stonecut Studio
+
+Make a map or a piece on [stonecut.studio](https://stonecut.studio), download it as a `.schem`, put
+it in your test server's folder, and ask your agent to import it. Then keep building on it with your
+agent: add interiors, change materials, add quests or mobs, and export the result. Big maps are
+bigger than the tool's import limit by default; download single pieces, or raise `maxImportBlocks`
+(see the [reference](docs/reference.md#settings)).
+
+<!-- SHOWCASE: images of builds (owner sends them) -->
+
+## What it supports
+
+- Minecraft Java Edition 1.20.1 and newer, vanilla and NeoForge. More versions and mod loaders are
+  coming.
+- Windows, macOS and Linux. Made for Claude Code; other MCP agents should work.
+- Java for your Minecraft version: Java 17 for 1.20.1 to 1.20.4, Java 21 for 1.20.5 to 1.21.11,
+  Java 25 for 26.1 and newer. The agent tells you if it is missing and where to get it.
+
+## Safety
+
+- The test server only listens on your own computer. Nothing connects to another machine.
+- Server files come only from Mojang and NeoForged, checked against their published hashes.
+- It only works inside the folders you allow. It installs nothing, and clears, replaces or restores nothing, before you say yes.
+- Every change can be undone, and whole-world backups are one request away.
+- Your agent may have other tools, like a shell, that these rules don't cover. Keep your agent's
+  own permission prompts on.
+
+The full rules and every setting are in the [reference](docs/reference.md#safety).
+
+## Troubleshooting
+
+Run `npx -y stonecut-map-builder doctor`. It checks Node, your settings, Java, the test server, the
+skill and whether the tool starts, and says how to fix each problem. It changes nothing. See the
+[reference](docs/reference.md#doctor).
+
+## More
+
+- [Full reference](docs/reference.md): every tool, setting and limit, and manual install.
+- Security reports: [SECURITY.md](SECURITY.md).
+- License: MIT, see [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security
+
+## Reporting a problem
+
+Please report security problems privately through GitHub: open the repository's **Security** tab
+and choose **Report a vulnerability**. Do not open a public issue for a security problem.
+
+Include what you did, what happened, what you expected, and the tool version
+(`npx -y stonecut-map-builder --version`). We aim to answer within 7 days and to publish a fix
+and an advisory once it is fixed.
+
+## Supported versions
+
+Only the latest released version gets security fixes.
+
+## What counts
+
+Anything that breaks the safety rules in the [reference](docs/reference.md#safety), for example:
+
+- a path that reads or writes outside the test server folder, or into the tool's own `.stonecut` folder;
+- RCON or the test server becoming reachable from another computer;
+- a way to run a program, or to add a mod or other code, while `allowModInstall` is off;
+- the RCON password reaching the agent;
+- a download from a source other than Mojang or NeoForged, or one used without a matching hash;
+- a tool that changes something while marked read-only;
+- a way to accept the Minecraft EULA or install something without the person's yes;
+- block names, file contents or schematic data that make the tool send a command nobody asked for.
+  Command blocks and functions inside a schematic or datapack are content the game runs, not a
+  flaw in the tool (see Limits in the reference).
+
+Problems in Minecraft, NeoForge, Java or your agent itself should go to those projects.

package/config.example.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Stonecut Map Builder settings. Every key is optional; see the Safety section of the README.",
+  "serverFolders": [
+    "~/stonecut-map-builder/servers"
+  ],
+  "maxFillBlocks": 100000,
+  "maxReadBlocks": 32768,
+  "maxImportBlocks": 500000,
+  "maxFileBytes": 10485760,
+  "maxEntities": 256,
+  "includeEntities": true,
+  "allowFileWrites": true,
+  "allowModInstall": false,
+  "confirmDestructive": true,
+  "autoBackup": true,
+  "undoHistory": 10,
+  "rconAddress": "127.0.0.1"
+}

package/dist/cli.js

@@ -0,0 +1,45 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CONFIG_ENV, configFile, exampleConfig } from './config.js';
+import { VERSION } from './version.js';
+export const HELP = `stonecut-map-builder ${VERSION}
+
+Without options it runs the MCP server on stdio (an MCP client starts it for you).
+
+Commands:
+  doctor          Check Node, the settings file, Java, the test server, the skill and whether the
+                  MCP server starts, and say how to fix what fails. Changes nothing.
+
+Options:
+  --config-path   Print where the settings file is read from.
+  --init-config   Write the settings file with every setting at its default, if it does not exist.
+  --skill-path    Print the folder of the bundled map-builder skill.
+  --version       Print the version.
+  --help          Print this help.
+
+Environment:
+  ${CONFIG_ENV}   Use this settings file instead of the standard one.`;
+export function skillPath() {
+    return join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', 'map-builder');
+}
+export function initConfig(file = configFile()) {
+    if (existsSync(file))
+        return `Settings file already exists, left unchanged: ${file}`;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(exampleConfig(), null, 2)}\n`);
+    return `Wrote ${file}`;
+}
+export function cliAnswer(argv) {
+    if (argv.includes('--config-path'))
+        return configFile();
+    if (argv.includes('--init-config'))
+        return initConfig();
+    if (argv.includes('--skill-path'))
+        return skillPath();
+    if (argv.includes('--version'))
+        return VERSION;
+    if (argv.includes('--help') || argv.includes('-h'))
+        return HELP;
+    return null;
+}

package/dist/config.js

@@ -0,0 +1,127 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { z } from 'zod';
+import { RCON_HOST } from './safety/address.js';
+// The person's own settings. Nothing here may point at a particular computer: every default comes
+// from the operating system (home folder, standard config folder), and the person can override it.
+export const APP_FOLDER = 'stonecut-map-builder';
+export const CONFIG_ENV = 'STONECUT_MAP_CONFIG';
+/** Standard per-user config folder for this OS. */
+export function configDir(env = process.env, home = homedir(), platform = process.platform) {
+    if (platform === 'win32')
+        return join(env.APPDATA || join(home, 'AppData', 'Roaming'), APP_FOLDER);
+    if (platform === 'darwin')
+        return join(home, 'Library', 'Application Support', APP_FOLDER);
+    return join(env.XDG_CONFIG_HOME || join(home, '.config'), APP_FOLDER);
+}
+export function defaultServerFolder(home = homedir()) {
+    return join(home, APP_FOLDER, 'servers');
+}
+export const DEFAULTS = {
+    maxFillBlocks: 100_000,
+    maxReadBlocks: 32_768,
+    maxImportBlocks: 500_000,
+    maxFileBytes: 10 * 1024 * 1024,
+    maxEntities: 256,
+    includeEntities: true,
+    allowFileWrites: true,
+    allowModInstall: false,
+    confirmDestructive: true,
+    autoBackup: true,
+    undoHistory: 10,
+};
+const folder = z.string().min(1).describe('Absolute path, or one starting with ~/ for the home folder');
+export const configSchema = z.strictObject({
+    serverFolders: z.array(folder).min(1).max(16).optional(),
+    maxFillBlocks: z.number().int().min(1).max(10_000_000).default(DEFAULTS.maxFillBlocks),
+    maxReadBlocks: z.number().int().min(1).max(1_000_000).default(DEFAULTS.maxReadBlocks),
+    maxImportBlocks: z.number().int().min(1).max(20_000_000).default(DEFAULTS.maxImportBlocks),
+    maxFileBytes: z.number().int().min(1).max(512 * 1024 * 1024).default(DEFAULTS.maxFileBytes),
+    maxEntities: z.number().int().min(0).max(10_000).default(DEFAULTS.maxEntities),
+    includeEntities: z.boolean().default(DEFAULTS.includeEntities),
+    allowFileWrites: z.boolean().default(DEFAULTS.allowFileWrites),
+    allowModInstall: z.boolean().default(DEFAULTS.allowModInstall),
+    confirmDestructive: z.boolean().default(DEFAULTS.confirmDestructive),
+    autoBackup: z.boolean().default(DEFAULTS.autoBackup),
+    undoHistory: z.number().int().min(1).max(100).default(DEFAULTS.undoHistory),
+    rconAddress: z
+        .literal(RCON_HOST, { error: `rconAddress can only be ${RCON_HOST}: RCON never listens on a network address in this version` })
+        .default(RCON_HOST),
+    javaPath: z.string().min(1).optional(),
+    $schema: z.string().optional(),
+    _comment: z.string().optional(),
+});
+export function expandHome(p, home = homedir()) {
+    if (p === '~')
+        return home;
+    if (p.startsWith('~/') || p.startsWith('~\\'))
+        return join(home, p.slice(2));
+    return p;
+}
+export function configFile(env = process.env, home = homedir()) {
+    const override = env[CONFIG_ENV]?.trim();
+    return override ? resolve(expandHome(override, home)) : join(configDir(env, home), 'config.json');
+}
+export function loadConfig(env = process.env, home = homedir()) {
+    const file = configFile(env, home);
+    const fileExists = existsSync(file);
+    let raw = {};
+    if (fileExists) {
+        try {
+            raw = JSON.parse(readFileSync(file, 'utf8').replace(/^/, ''));
+        }
+        catch (e) {
+            throw new Error(`Config file ${file} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    const parsed = configSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new Error(`Config file ${file} has a problem:\n${z.prettifyError(parsed.error)}`);
+    const c = parsed.data;
+    const serverFolders = (c.serverFolders ?? [defaultServerFolder(home)]).map((f) => {
+        const p = expandHome(f, home);
+        if (!isAbsolute(p))
+            throw new Error(`Config file ${file}: server folder "${f}" must be a full path or start with ~/`);
+        return resolve(p);
+    });
+    const javaPath = c.javaPath ? resolve(expandHome(c.javaPath, home)) : undefined;
+    return {
+        file,
+        fileExists,
+        stateDir: env[CONFIG_ENV]?.trim() ? dirname(file) : configDir(env, home),
+        serverFolders,
+        maxFillBlocks: c.maxFillBlocks,
+        maxReadBlocks: c.maxReadBlocks,
+        maxImportBlocks: c.maxImportBlocks,
+        maxFileBytes: c.maxFileBytes,
+        maxEntities: c.maxEntities,
+        includeEntities: c.includeEntities,
+        allowFileWrites: c.allowFileWrites,
+        allowModInstall: c.allowModInstall,
+        confirmDestructive: c.confirmDestructive,
+        autoBackup: c.autoBackup,
+        undoHistory: c.undoHistory,
+        rconAddress: c.rconAddress,
+        ...(javaPath ? { javaPath } : {}),
+    };
+}
+/** The example config with every setting at its default, as written by --init-config. */
+export function exampleConfig() {
+    return {
+        _comment: 'Stonecut Map Builder settings. Every key is optional; see the Safety section of the README.',
+        serverFolders: [`~/${APP_FOLDER}/servers`],
+        maxFillBlocks: DEFAULTS.maxFillBlocks,
+        maxReadBlocks: DEFAULTS.maxReadBlocks,
+        maxImportBlocks: DEFAULTS.maxImportBlocks,
+        maxFileBytes: DEFAULTS.maxFileBytes,
+        maxEntities: DEFAULTS.maxEntities,
+        includeEntities: DEFAULTS.includeEntities,
+        allowFileWrites: DEFAULTS.allowFileWrites,
+        allowModInstall: DEFAULTS.allowModInstall,
+        confirmDestructive: DEFAULTS.confirmDestructive,
+        autoBackup: DEFAULTS.autoBackup,
+        undoHistory: DEFAULTS.undoHistory,
+        rconAddress: RCON_HOST,
+    };
+}

package/dist/content.js

@@ -0,0 +1,7 @@
+export function textResult(value) {
+    return { content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] };
+}
+export function errorResult(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { isError: true, content: [{ type: 'text', text: message }] };
+}

package/dist/context.js

@@ -0,0 +1,122 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { findJava, pickJava } from './mc/java.js';
+import { detectLaunch, metaPath, ServerError, TestServer, writeMeta } from './mc/testserver.js';
+import { readProperties } from './mc/properties.js';
+import { World } from './ops/world.js';
+import { checkAllowedFolder } from './safety/paths.js';
+// What the MCP server remembers between calls: the settings, the one active test server, and
+// setup plans waiting for the person's yes. Calls that touch the server run one at a time.
+export class Context {
+    config;
+    plans = new Map();
+    active = null;
+    worldOps = null;
+    chain = Promise.resolve();
+    constructor(config) {
+        this.config = config;
+    }
+    get stateFile() {
+        return join(this.config.stateDir, 'state.json');
+    }
+    /** Runs fn after every earlier call has finished. */
+    serial(fn) {
+        const p = this.chain.then(fn, fn);
+        this.chain = p.catch(() => undefined);
+        return p;
+    }
+    remembered() {
+        if (!existsSync(this.stateFile))
+            return null;
+        try {
+            const s = JSON.parse(readFileSync(this.stateFile, 'utf8'));
+            return s.activeServer ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Servers made by this tool inside the allowed folders. */
+    knownServers() {
+        const out = [];
+        for (const root of this.config.serverFolders) {
+            if (existsSync(metaPath(root)))
+                out.push(root);
+            if (!existsSync(root))
+                continue;
+            for (const d of readdirSync(root, { withFileTypes: true })) {
+                if (d.isDirectory() && existsSync(metaPath(join(root, d.name))))
+                    out.push(join(root, d.name));
+            }
+        }
+        return out;
+    }
+    /** The server to use when none is active yet: the remembered one, else the first known one. Only reads. */
+    findServer() {
+        const candidates = [this.remembered(), ...this.knownServers()].filter((p) => !!p && existsSync(metaPath(p)));
+        for (const dir of candidates) {
+            try {
+                return TestServer.open(checkAllowedFolder(this.config.serverFolders, dir));
+            }
+            catch {
+                // no longer allowed or unreadable; try the next one
+            }
+        }
+        return null;
+    }
+    /** The active server, or null if there is none yet. */
+    current() {
+        if (this.active)
+            return this.active;
+        const found = this.findServer();
+        return found ? this.setActive(found.dir) : null;
+    }
+    server() {
+        const s = this.current();
+        if (!s)
+            throw new ServerError('There is no test server yet. Ask the person which Minecraft version and modpack they use, then call plan_setup.');
+        return s;
+    }
+    world() {
+        const s = this.server();
+        if (!this.worldOps || this.worldOps.server !== s)
+            this.worldOps = new World(s, this.config);
+        return this.worldOps;
+    }
+    setActive(dir) {
+        const checked = checkAllowedFolder(this.config.serverFolders, dir);
+        if (this.active && this.active.dir !== checked)
+            this.active.closeConnections();
+        this.active = TestServer.open(checked);
+        this.worldOps = null;
+        mkdirSync(this.config.stateDir, { recursive: true });
+        writeFileSync(this.stateFile, `${JSON.stringify({ activeServer: checked }, null, 2)}\n`);
+        return this.active;
+    }
+    /** Makes an existing server folder (inside an allowed folder) the active one, adopting it if this tool did not make it. */
+    async adopt(dir) {
+        const checked = checkAllowedFolder(this.config.serverFolders, dir);
+        if (existsSync(metaPath(checked)))
+            return { server: this.setActive(checked), adopted: false };
+        const launch = detectLaunch(checked);
+        if (!launch)
+            throw new ServerError(`${checked} has no server.jar and no NeoForge install; it does not look like a Minecraft server folder`);
+        const javaFound = await findJava(this.config.javaPath ? [this.config.javaPath] : []);
+        const java = pickJava(javaFound, 21) ?? pickJava(javaFound, 17);
+        if (!java)
+            throw new ServerError('No Java 17 or newer found. Run plan_setup to see where to get it.');
+        const props = readProperties(checked);
+        writeMeta(checked, {
+            minecraft: 'unknown',
+            loader: launch.type === 'jar' ? 'vanilla' : 'neoforge',
+            javaPath: java.path,
+            javaMajor: java.major,
+            memoryMb: 4096,
+            launch,
+            rconPort: Number(props.get('rcon.port') ?? 25575),
+            createdAt: new Date().toISOString(),
+            createdByTool: false,
+        });
+        return { server: this.setActive(checked), adopted: true };
+    }
+}