@mairwunnx/minecraft-mcp 0.0.0-stage → 2.0.0

package/dist/tools/server.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import { unwrap } from "../client.js";
+import { waitForEvent } from "../events.js";
+import { tool } from "../tool.js";
+import { cursor, format, limit, player } from "./common.js";
+export function serverTools(ctx) {
+    const { api, token } = ctx;
+    tool(ctx, {
+        name: "get_server_status",
+        title: "Server status",
+        description: "Version, Paper build, MOTD, players online and max, uptime, difficulty, view distance, worlds, tick rate, and current load: TPS over 1, 5, and 15 minutes (20 is perfect), milliseconds per tick, memory used and max in MB, loaded chunks, and entities. detail adds tick time percentiles (under 50 ms keeps 20 TPS), CPU, and chunks, entities, and the most common entity types per world.",
+        scope: "read",
+        effect: "read",
+        input: { detail: z.boolean().optional().describe("Add percentiles, CPU, and per-world load") },
+        run: async (args) => {
+            const [status, performance] = await Promise.all([
+                unwrap(api.GET("/server"), token),
+                args.detail ? unwrap(api.GET("/server/performance"), token) : undefined,
+            ]);
+            return performance ? { ...status, performance } : status;
+        },
+    });
+    tool(ctx, {
+        name: "list_plugins",
+        title: "Plugins",
+        description: "Installed plugins with version and whether they are enabled.",
+        scope: "read",
+        effect: "read",
+        input: {},
+        run: () => unwrap(api.GET("/server/plugins"), token),
+    });
+    tool(ctx, {
+        name: "get_events",
+        untrusted: true,
+        title: "Event history",
+        description: "Recorded events, newest first: player.join, player.leave, player.kick, player.death, player.advancement, player.chat (if the server records chat), world.night_skipped, entity.boss_killed, raid.start, raid.finish, server.status. Filter by type, player, and time.",
+        scope: "read",
+        effect: "read",
+        input: {
+            types: z.array(z.string()).optional().describe('Event types, such as ["player.death"]'),
+            player: z.string().optional().describe("Player name or UUID"),
+            from: z.string().optional().describe("ISO-8601 time; only events at or after it"),
+            to: z.string().optional().describe("ISO-8601 time; only events before it"),
+            order: z.enum(["newest", "oldest"]).optional(),
+            limit,
+            cursor,
+        },
+        run: (args) => unwrap(api.GET("/events", {
+            params: {
+                query: {
+                    type: args.types?.join(","),
+                    player: args.player,
+                    from: args.from,
+                    to: args.to,
+                    order: args.order,
+                    limit: args.limit ?? 50,
+                    cursor: args.cursor,
+                },
+            },
+        }), token),
+    });
+    tool(ctx, {
+        name: "wait_for_event",
+        untrusted: true,
+        title: "Wait for something to happen",
+        description: "Wait until an event happens live and get it, or time out. Types are WebSocket topics: player.join, player.leave, player.death, player.advancement, player.chat (if the server records chat), player.command (admin), player.respawn, player.level_up, player.sleep, player.world_change, player.kill, player.craft, block.break, block.place, world.weather, world.night_skipped, entity.boss_killed, raid.start, raid.finish, server.status, and more. Narrow it to one player or world. Use it for “tell me when Steve logs in” or “wait until night is skipped”. Keep timeoutSeconds within what your client lets a tool run.",
+        scope: "read",
+        effect: "read",
+        input: {
+            types: z.array(z.string().min(1)).min(1).describe('Such as ["player.join"]'),
+            player: player.optional().describe("Only this player's events"),
+            world: z.string().optional().describe("Only this world's events"),
+            timeoutSeconds: z.number().int().min(1).max(300).default(60),
+        },
+        run: (args) => waitForEvent({ url: ctx.url, token }, { types: args.types, player: args.player, world: args.world, timeoutMs: args.timeoutSeconds * 1000 }),
+    });
+    tool(ctx, {
+        name: "broadcast",
+        title: "Broadcast",
+        description: "Send a chat message, title, or action bar text to everyone online.",
+        scope: "admin",
+        effect: "write",
+        input: {
+            message: z.string().min(1),
+            kind: z.enum(["chat", "title", "actionbar"]).default("chat"),
+            subtitle: z.string().optional().describe("Only for titles"),
+            format,
+        },
+        run: (args) => unwrap(api.POST("/server/broadcast", { body: args }), token),
+    });
+    tool(ctx, {
+        name: "run_command",
+        untrusted: true,
+        title: "Run a console command",
+        description: "Run any console command as the server console, without the leading slash, and get its output. Powerful: prefer a specific tool when one exists. Every call is audit-logged.",
+        scope: "admin",
+        effect: "destructive",
+        input: { command: z.string().min(1).describe("Such as `weather clear` or `give Steve minecraft:bread 16`") },
+        run: (args) => unwrap(api.POST("/server/commands", { body: args }), token),
+    });
+    tool(ctx, {
+        name: "get_server_log",
+        untrusted: true,
+        title: "Console log",
+        description: "Recent console lines, oldest first: errors, warnings, plugin messages, joins, chat, and commands players ran. WorldAPI keeps them from its own start (1000 by default) and blanks out its tokens. Filter by the lowest level and by text, such as a player's name or a plugin's.",
+        scope: "admin",
+        effect: "read",
+        input: {
+            level: z
+                .enum(["trace", "debug", "info", "warn", "error", "fatal"])
+                .optional()
+                .describe("Only this level and above"),
+            grep: z.string().min(1).optional().describe("Only lines that contain this text, ignoring case"),
+            limit: z.number().int().min(1).optional().describe("Newest matching lines to return; 100 by default"),
+        },
+        run: (args) => unwrap(api.GET("/server/logs", { params: { query: args } }), token),
+    });
+    tool(ctx, {
+        name: "restart_server",
+        title: "Restart the server",
+        description: "Restart after a countdown in chat: players see warnings at set marks, then every world and player is saved and the server stops. Whatever runs the server must start it again (Docker's restart policy, a start script loop); otherwise it stays off. Scheduling again replaces a pending restart; cancel calls it off. Everyone online gets disconnected, so confirm with the user first.",
+        scope: "admin",
+        effect: "destructive",
+        input: {
+            countdownSeconds: z.number().int().min(0).max(3600).default(60),
+            message: z.string().optional().describe("Said with each warning, such as the reason"),
+            cancel: z.boolean().optional().describe("Call off a pending restart instead"),
+        },
+        run: (args) => args.cancel
+            ? unwrap(api.DELETE("/server/restart"), token)
+            : unwrap(api.POST("/server/restart", { body: { countdownSeconds: args.countdownSeconds, message: args.message } }), token),
+    });
+    tool(ctx, {
+        name: "save_worlds",
+        title: "Save worlds",
+        description: "Save every world, and player data, to disk now.",
+        scope: "admin",
+        effect: "idempotent",
+        input: { players: z.boolean().default(true) },
+        run: (args) => unwrap(api.POST("/server/save", { body: args }), token),
+    });
+    tool(ctx, {
+        name: "get_access",
+        title: "Whitelist, operators, and bans",
+        description: "Who may play and who runs the server: whether the whitelist is on and enforced and who is on it, the operators, and banned players and IP addresses with reasons and expiry.",
+        scope: "admin",
+        effect: "read",
+        input: {},
+        run: async () => {
+            const [whitelist, operators, bans] = await Promise.all([
+                unwrap(api.GET("/server/whitelist"), token),
+                unwrap(api.GET("/server/ops"), token),
+                unwrap(api.GET("/server/bans"), token),
+            ]);
+            return { whitelist, operators, bans };
+        },
+    });
+    tool(ctx, {
+        name: "manage_whitelist",
+        title: "Change the whitelist",
+        description: "Turn the whitelist on or off, enforce it, and add or remove players by name or UUID.",
+        scope: "admin",
+        effect: "idempotent",
+        input: {
+            enabled: z.boolean().optional(),
+            enforced: z.boolean().optional().describe("Kick online players who aren't on the list"),
+            add: z.array(z.string()).optional(),
+            remove: z.array(z.string()).optional(),
+        },
+        run: (args) => unwrap(api.PATCH("/server/whitelist", { body: { ...args, add: args.add ?? [], remove: args.remove ?? [] } }), token),
+    });
+    tool(ctx, {
+        name: "set_operator",
+        title: "Grant or revoke operator",
+        description: "Make a player an operator, or take it away.",
+        scope: "admin",
+        effect: "idempotent",
+        input: { player, op: z.boolean() },
+        run: (args) => unwrap(api.PATCH("/server/ops", {
+            body: args.op ? { add: [args.player], remove: [] } : { add: [], remove: [args.player] },
+        }), token),
+    });
+    const ban = z.object({
+        reason: z.string().optional(),
+        durationSeconds: z.number().int().positive().optional().describe("Leave out for a permanent ban"),
+    });
+    tool(ctx, {
+        name: "manage_bans",
+        title: "Ban or pardon",
+        description: "Ban players by name or UUID, or IP addresses; anyone online who is banned gets kicked. Pardon lifts a ban. Give any of the four lists in one call.",
+        scope: "admin",
+        effect: "destructive",
+        input: {
+            ban: z.array(ban.extend({ player: z.string().min(1) })).optional(),
+            pardon: z.array(z.string().min(1)).optional().describe("Player names or UUIDs"),
+            banIps: z.array(ban.extend({ ip: z.string().min(1) })).optional(),
+            pardonIps: z.array(z.string().min(1)).optional(),
+        },
+        run: (args) => unwrap(api.PATCH("/server/bans", {
+            body: {
+                ban: args.ban ?? [],
+                pardon: args.pardon ?? [],
+                banIps: args.banIps ?? [],
+                pardonIps: args.pardonIps ?? [],
+            },
+        }), token),
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/stats.js

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { unwrap } from "../client.js";
+import { tool } from "../tool.js";
+import { cursor, limit } from "./common.js";
+export function statsTools(ctx) {
+    const { api, token } = ctx;
+    tool(ctx, {
+        name: "get_leaderboard",
+        title: "Leaderboards",
+        description: "Players ranked by a statistic; ties share a place. Presets: playtime (hours), diamonds, advancements, mobs, travel (km), deaths, blocks, fish, damage (hearts), netherite (ancient debris mined), experience (xp gained; a lower bound, since vanilla keeps no lifetime total). Or any statistic as `category:key`, such as `custom:jump`, `mined:diamond_ore`, `killed:*`. Without a statistic, lists the presets and their units.",
+        scope: "read",
+        effect: "read",
+        input: {
+            statistic: z.string().min(1).optional(),
+            limit: z.number().int().min(1).max(500).optional().describe("10 by default"),
+        },
+        run: (args) => args.statistic
+            ? unwrap(api.GET("/leaderboards/{statistic}", {
+                params: { path: { statistic: args.statistic }, query: { limit: args.limit ?? 10 } },
+            }), token)
+            : unwrap(api.GET("/leaderboards"), token),
+    });
+    tool(ctx, {
+        name: "get_recipes",
+        title: "Recipes",
+        description: "How to make an item (`item`) or what an item is good for (`uses`), or both: crafting grids with their shape, furnace, smoker, blast furnace, and campfire cooking with time and experience, stonecutting, and smithing. Plugin recipes count too. Each ingredient lists the items that fit.",
+        scope: "read",
+        effect: "read",
+        input: {
+            item: z.string().min(1).optional().describe("What the recipe makes, such as `minecraft:torch`"),
+            uses: z.string().min(1).optional().describe("What the recipe takes, such as `minecraft:coal`"),
+            limit,
+            cursor,
+        },
+        run: (args) => {
+            if (!args.item && !args.uses)
+                throw new Error("Give item, uses, or both");
+            return unwrap(api.GET("/recipes", { params: { query: { ...args, limit: args.limit ?? 20 } } }), token);
+        },
+    });
+    tool(ctx, {
+        name: "get_aggregates",
+        title: "Server totals",
+        description: "Everyone's statistics added up: hours played, blocks mined and the top block, mobs killed and the top mob, deaths, advancements, world day.",
+        scope: "read",
+        effect: "read",
+        input: {},
+        run: () => unwrap(api.GET("/aggregates"), token),
+    });
+}
+//# sourceMappingURL=stats.js.map

package/dist/tools/worlds.js

@@ -0,0 +1,172 @@
+import { z } from "zod";
+import { unwrap } from "../client.js";
+import { tool } from "../tool.js";
+import { player, world } from "./common.js";
+export function worldTools(ctx) {
+    const { api, token } = ctx;
+    const path = (name) => ({ params: { path: { world: name } } });
+    tool(ctx, {
+        name: "list_worlds",
+        title: "Worlds",
+        description: "Loaded worlds with their dimension key and player count.",
+        scope: "read",
+        effect: "read",
+        input: {},
+        run: () => unwrap(api.GET("/worlds"), token),
+    });
+    tool(ctx, {
+        name: "get_world",
+        title: "World",
+        description: "Time of day (dayTime 0–23999: 0 sunrise, 6000 noon, 13000 night, 18000 midnight), day number, moon phase, ticks until night, whether beds work, weather, difficulty, PvP, spawn, the world border, game rule values, and load. ruleDetails adds each game rule's type and default; size adds chunks ever generated, explored area in km², and size on disk.",
+        scope: "read",
+        effect: "read",
+        input: {
+            world,
+            ruleDetails: z.boolean().optional().describe("Add every game rule with its type and default"),
+            size: z.boolean().optional().describe("Add explored area and size on disk"),
+        },
+        run: async (args) => {
+            const [view, gameRuleDetails, size] = await Promise.all([
+                unwrap(api.GET("/worlds/{world}", path(args.world)), token),
+                args.ruleDetails ? unwrap(api.GET("/worlds/{world}/gamerules", path(args.world)), token) : undefined,
+                args.size ? unwrap(api.GET("/worlds/{world}/stats", path(args.world)), token) : undefined,
+            ]);
+            return { ...view, ...(gameRuleDetails && { gameRuleDetails }), ...(size && { size }) };
+        },
+    });
+    tool(ctx, {
+        name: "locate_structure",
+        title: "Find a structure",
+        description: "The nearest structure of a type, from a point or the world spawn. `type` is a key such as `stronghold`, `ancient_city`, `trial_chambers`, or a prefix such as `village` that matches every village kind. Searching blocks the server thread for a moment, so keep the radius modest.",
+        scope: "read",
+        effect: "read",
+        input: {
+            world,
+            type: z.string().min(1),
+            x: z.number().int().optional(),
+            z: z.number().int().optional(),
+            radius: z.number().int().min(1).optional().describe("Search radius in chunks"),
+            unexplored: z.boolean().optional().describe("Only structures nobody found yet"),
+        },
+        run: (args) => unwrap(api.GET("/worlds/{world}/structures/nearest", {
+            params: {
+                path: { world: args.world },
+                query: { type: args.type, x: args.x, z: args.z, radius: args.radius, unexplored: args.unexplored },
+            },
+        }), token),
+    });
+    tool(ctx, {
+        name: "find_nearby",
+        title: "Find nearby blocks or biomes",
+        description: "The nearest blocks of some types and the nearest biome, around a point or a player. Blocks take keys or tags: `minecraft:diamond_ore`, `#minecraft:logs`, `#minecraft:iron_ores`. Block search reads only loaded chunks (those near players), 32 blocks around by default and 64 at most, and says how many chunks in range it couldn't read. Biome search asks the world generator, so it reaches unexplored land, 1024 blocks around by default. Without x and z it searches around the player: the user's own when WORLDAPI_PLAYER is set.",
+        scope: "read",
+        effect: "read",
+        input: {
+            blocks: z.array(z.string().min(1)).optional().describe('Such as ["minecraft:diamond_ore", "#minecraft:logs"]'),
+            biomes: z.array(z.string().min(1)).optional().describe('Such as ["minecraft:cherry_grove"]; the nearest of any'),
+            world: z.string().optional().describe("World name; the player's world, or `world`, when left out"),
+            x: z.number().int().optional(),
+            y: z.number().int().optional().describe("Needed for blocks when x and z are given"),
+            z: z.number().int().optional(),
+            player: player.optional().describe("Search around this player instead of x, y, z"),
+            radius: z.number().int().min(1).optional().describe("Block search radius"),
+            biomeRadius: z.number().int().min(1).optional().describe("Biome search radius"),
+            limit: z.number().int().min(1).max(100).optional().describe("Blocks to return, nearest first; 10 by default"),
+        },
+        run: async (args) => {
+            if (!args.blocks?.length && !args.biomes?.length)
+                throw new Error("Give blocks, biomes, or both");
+            let { world: name, x, y, z } = args;
+            if (x === undefined || z === undefined) {
+                const who = args.player ?? ctx.player;
+                if (!who)
+                    throw new Error("Give x and z, or a player");
+                const view = await unwrap(api.GET("/players/{player}", { params: { path: { player: who } } }), token);
+                const at = "location" in view ? view.location : undefined;
+                if (!at)
+                    throw new Error(`${who}'s location isn't known`);
+                name ??= at.world;
+                x = Math.floor(at.x);
+                y = Math.floor(at.y);
+                z = Math.floor(at.z);
+            }
+            return unwrap(api.GET("/worlds/{world}/search", {
+                params: {
+                    path: { world: name ?? "world" },
+                    query: {
+                        blocks: args.blocks?.join(","),
+                        biome: args.biomes?.join(","),
+                        x,
+                        y,
+                        z,
+                        radius: args.radius,
+                        biomeRadius: args.biomeRadius,
+                        limit: args.limit,
+                    },
+                },
+            }), token);
+        },
+    });
+    tool(ctx, {
+        name: "set_world",
+        title: "Change a world",
+        description: "Change any of these at once; only what you give changes. The time of day (dayTime 0–23999: 0 sunrise, 1000 morning, 6000 noon, 13000 night, 18000 midnight), or move the clock forward with addTicks (24000 is a day). The weather (clear, rain, thunder), optionally for durationTicks (20 per second). The difficulty, PvP, and the world spawn.",
+        scope: "write:world",
+        effect: "write",
+        input: {
+            world,
+            dayTime: z.number().int().min(0).max(23999).optional(),
+            addTicks: z.number().int().optional().describe("Moves the clock forward; 24000 ticks are one day"),
+            weather: z.enum(["clear", "rain", "thunder"]).optional(),
+            durationTicks: z.number().int().positive().optional().describe("How long the new weather lasts"),
+            difficulty: z.enum(["peaceful", "easy", "normal", "hard"]).optional(),
+            pvp: z.boolean().optional().describe("Whether players can hurt each other"),
+            spawn: z
+                .object({ x: z.number().int(), y: z.number().int(), z: z.number().int(), angle: z.number().optional() })
+                .optional()
+                .describe("New world spawn point"),
+        },
+        run: (args) => unwrap(api.PATCH("/worlds/{world}", {
+            ...path(args.world),
+            body: {
+                dayTime: args.dayTime,
+                addTime: args.addTicks,
+                weather: args.weather,
+                weatherDurationTicks: args.weather && args.weather !== "clear" ? args.durationTicks : undefined,
+                clearWeatherDurationTicks: args.weather === "clear" ? args.durationTicks : undefined,
+                difficulty: args.difficulty,
+                pvp: args.pvp,
+                spawn: args.spawn && { ...args.spawn, angle: args.spawn.angle ?? 0 },
+            },
+        }), token),
+    });
+    tool(ctx, {
+        name: "set_gamerule",
+        title: "Set game rules",
+        description: 'Set one or more game rules at once, such as { "keep_inventory": true, "players_sleeping_percentage": 50 }. get_world with ruleDetails lists the names and types.',
+        scope: "write:world",
+        effect: "idempotent",
+        input: { world, rules: z.record(z.string(), z.union([z.boolean(), z.number().int()])) },
+        run: (args) => unwrap(api.PATCH("/worlds/{world}/gamerules", { ...path(args.world), body: args.rules }), token),
+    });
+    tool(ctx, {
+        name: "set_world_border",
+        title: "Change the world border",
+        description: "Resize (optionally over time) or move the world border, or change its damage and warnings.",
+        scope: "write:world",
+        effect: "idempotent",
+        input: {
+            world,
+            size: z.number().positive().optional().describe("Width in blocks"),
+            transitionSeconds: z.number().int().min(0).optional(),
+            centerX: z.number().optional(),
+            centerZ: z.number().optional(),
+            damageAmount: z.number().min(0).optional(),
+            damageBuffer: z.number().min(0).optional(),
+            warningDistance: z.number().int().min(0).optional(),
+            warningTimeTicks: z.number().int().min(0).optional(),
+        },
+        run: ({ world: name, ...body }) => unwrap(api.PATCH("/worlds/{world}/border", { ...path(name), body }), token),
+    });
+}
+//# sourceMappingURL=worlds.js.map

package/dist/version.js

@@ -0,0 +1,35 @@
+import { readFileSync } from "node:fs";
+/** This package's version, read from package.json so a release changes it in one place. */
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+/** The oldest WorldAPI whose endpoints match the generated client. */
+export const MIN_WORLDAPI = "2.0.0";
+/** Compares two x.y.z versions; anything that isn't one (a dev build) counts as new enough. */
+export function olderThan(version, minimum) {
+    const parse = (text) => /^(\d+)\.(\d+)\.(\d+)/.exec(text)?.slice(1).map(Number);
+    const have = parse(version);
+    const need = parse(minimum);
+    if (!have || !need)
+        return false;
+    for (let i = 0; i < 3; i++) {
+        if (have[i] !== need[i])
+            return (have[i] ?? 0) < (need[i] ?? 0);
+    }
+    return false;
+}
+/**
+ * Asks WorldAPI for its version and warns when it's older than this server expects. It never
+ * stops the start: most tools still work, and the warning says which side to update.
+ */
+export async function checkWorldApi(api, log) {
+    try {
+        const { data } = await api.GET("/server");
+        const version = data?.worldApiVersion;
+        if (version && olderThan(version, MIN_WORLDAPI))
+            log(`WorldAPI ${version} is older than ${MIN_WORLDAPI}, which this server expects; update the plugin, or some tools will fail`);
+        return version;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=version.js.map