@mairwunnx/minecraft-mcp 2.1.0 → 2.2.0

package/README.RU.md

@@ -100,7 +100,7 @@ MCP_HTTP_TOKEN=a-long-random-secret WORLDAPI_URL=... WORLDAPI_TOKEN=... \
 
 Права берутся из WorldAPI: `admin` включает `read`, `write:world` и `write:players`, но не `code`.
 
-**Чтение** (`read`, 27)
+**Чтение** (`read`, 29)
 
 - `get_server_status`: версия, игроки, аптайм, TPS, память; `detail` добавляет перцентили тика, CPU и нагрузку по мирам
 - `list_plugins`, `get_events`, `wait_for_event`: плагины, записанные события и ожидание живого
@@ -110,6 +110,7 @@ MCP_HTTP_TOKEN=a-long-random-secret WORLDAPI_URL=... WORLDAPI_TOKEN=... \
 - `list_entities`, `get_entity`: мобы и предметы вокруг точки
 - `list_players`, `list_online_players`, `get_player`, `get_player_inventory`, `get_player_effects`, `get_player_statistics`, `get_player_advancements`, `get_player_sessions`, `check_permission`
 - `get_leaderboard`, `get_aggregates`, `get_recipes`: рейтинги, итоги сервера и как скрафтить что угодно
+- `list_extensions`, `read_extension`: данные, которыми другие плагины делятся через WorldAPI, — какие бы плагины ни стояли на сервере; их события тоже приходят через `get_events` и `wait_for_event`
 
 **Мир** (`write:world`, 10)
 
@@ -189,9 +190,9 @@ npm run pack:mcpb    # бандл для Claude Desktop в build/
 
 [WorldAPI](https://github.com/MairwunNx/minecraft-worldapi) — 🌍 плагин для Paper, который выводит сервер в HTTP; этот сервер работает через него.
 
-[MCBuddy Server](https://github.com/mcbuddy-ai/mcbuddy-server) — 🛠️⚡ бэкенд MCBuddy, ИИ-помощника для Minecraft на OpenRouter.
+[Allay Server](https://github.com/allay-ai/server) — 🛠️⚡ бэкенд Allay, ИИ-помощника для Minecraft, на OpenRouter.
 
-[MCBuddy Spigot](https://github.com/mcbuddy-ai/mcbuddy-spigot) — 💬 приводит MCBuddy в игру: спросите ИИ о чём угодно через `/ask` прямо в чате. 🎮
+[Allay](https://github.com/allay-ai/minecraft) — 🪽 приводит Allay в игру: спрашивайте ИИ о чём угодно командой `/ask` прямо в чате. 🎮
 
 ## От того же автора
 

package/README.md

@@ -25,18 +25,6 @@ It talks to [WorldAPI](https://github.com/MairwunNx/minecraft-worldapi), a Paper
 - 📝 **Prompts** for common jobs: a server health check, a lag hunt, a grief investigation, a new player’s guide, and where a player is.
 - 🔌 **Every client.** Claude Code, Claude Desktop in one click, Cursor, and anything else that speaks MCP, over stdio or HTTP.
 
-## Try it live
-
-Moonlands, my hard survival server with friends, runs WorldAPI and lets anyone read it. Point the agent there without a token and ask about a real server:
-
-```sh
-claude mcp add moonlands -e WORLDAPI_URL=https://minecraft.mairwunnx.com/worldapi/api/v1 -- npx -y @mairwunnx/minecraft-mcp
-```
-
-[![Play on Moonlands: pure vanilla, hard mobs, AI, claims. minecraft.mairwunnx.com](https://raw.githubusercontent.com/MairwunNx/minecraft-mcp/master/media/og-adv-image.png)](https://minecraft.mairwunnx.com)
-
-Join at `minecraft.mairwunnx.com`. The site has the live map, player stats, and the hall of fame.
-
 ## Install
 
 You need a server with [WorldAPI](https://github.com/MairwunNx/minecraft-worldapi) and a token from it: run `/worldapi token create agent` in game and pick the scopes. Clients that start the server themselves need Node.js 22 or newer.
@@ -100,7 +88,7 @@ Clients connect to `http://host:3333/mcp` and send `Authorization: Bearer <MCP_H
 
 Scopes come from WorldAPI: `admin` includes `read`, `write:world`, and `write:players`, but not `code`.
 
-**Read** (`read`, 27)
+**Read** (`read`, 29)
 
 - `get_server_status`: version, players, uptime, TPS, memory; `detail` adds tick percentiles, CPU, and load per world
 - `list_plugins`, `get_events`, `wait_for_event`: plugins, recorded events, and waiting for a live one
@@ -110,6 +98,7 @@ Scopes come from WorldAPI: `admin` includes `read`, `write:world`, and `write:pl
 - `list_entities`, `get_entity`: mobs and items around a point
 - `list_players`, `list_online_players`, `get_player`, `get_player_inventory`, `get_player_effects`, `get_player_statistics`, `get_player_advancements`, `get_player_sessions`, `check_permission`
 - `get_leaderboard`, `get_aggregates`, `get_recipes`: rankings, server totals, and how to craft anything
+- `list_extensions`, `read_extension`: data other plugins share through WorldAPI, whatever the server runs; their events come through `get_events` and `wait_for_event` too
 
 **World** (`write:world`, 10)
 
@@ -189,9 +178,9 @@ AI wrote most of the code and the documentation from my task descriptions, and I
 
 [WorldAPI](https://github.com/MairwunNx/minecraft-worldapi)—🌍 the Paper plugin that puts your server on HTTP; this server talks to it.
 
-[MCBuddy Server](https://github.com/mcbuddy-ai/mcbuddy-server)—🛠️⚡ the backend for MCBuddy, an AI assistant for Minecraft, built on OpenRouter.
+[Allay Server](https://github.com/allay-ai/server)—🛠️⚡ the backend for Allay, an AI helper for Minecraft, built on OpenRouter.
 
-[MCBuddy Spigot](https://github.com/mcbuddy-ai/mcbuddy-spigot)—💬 brings MCBuddy into the game: ask the AI anything with `/ask`, right in the chat. 🎮
+[Allay](https://github.com/allay-ai/minecraft)—🪽 brings Allay into the game: ask the AI anything with `/ask`, right in the chat. 🎮
 
 ## From the same author
 

package/dist/server.js

@@ -4,6 +4,7 @@ import { registerPrompts } from "./prompts.js";
 import { registerResources } from "./resources.js";
 import { blockTools } from "./tools/blocks.js";
 import { entityTools } from "./tools/entities.js";
+import { extensionTools } from "./tools/extensions.js";
 import { playerTools } from "./tools/players.js";
 import { scriptTools } from "./tools/scripts.js";
 import { serverTools } from "./tools/server.js";
@@ -41,6 +42,7 @@ export function buildServer(config, scopes, feed, fetchImpl) {
     playerTools(ctx);
     statsTools(ctx);
     scriptTools(ctx);
+    extensionTools(ctx);
     registerResources(server, ctx.api, config.token, feed);
     registerPrompts(server);
     return { server, tools: ctx.registered };

package/dist/tools/extensions.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { unwrap } from "../client.js";
+import { tool } from "../tool.js";
+export function extensionTools(ctx) {
+    const { api, token } = ctx;
+    tool(ctx, {
+        name: "list_extensions",
+        title: "Plugins’ data",
+        description: "Other plugins on the server that share their own data through WorldAPI: each one’s namespace, its resources (paths to read with `read_extension`), and its event topics (`ext.<namespace>.<event>`, which `get_events` and `wait_for_event` take like any type). What’s here depends on the server; call this first instead of guessing.",
+        scope: "read",
+        effect: "read",
+        untrusted: true,
+        input: {},
+        run: () => unwrap(api.GET("/extensions"), token),
+    });
+    tool(ctx, {
+        name: "read_extension",
+        title: "Read a plugin’s data",
+        description: 'One resource of a plugin from `list_extensions`, read from the plugin as it is now. Fill the path’s `{parameters}`, such as `players/Steve` for `players/{player}`; `query` passes the resource’s own options, such as `{ "limit": "5" }`.',
+        scope: "read",
+        effect: "read",
+        untrusted: true,
+        input: {
+            namespace: z
+                .string()
+                .regex(/^[a-z0-9_-]{1,32}$/)
+                .describe("The namespace, such as one `list_extensions` shows"),
+            path: z.string().min(1).describe("The resource path with its parameters filled in"),
+            query: z.record(z.string(), z.string()).optional(),
+        },
+        run: (args) => {
+            // Each segment is encoded on its own, so the path's slashes stay slashes.
+            const segments = args.path.split("/").filter(Boolean).map(encodeURIComponent).join("/");
+            const url = `/extensions/${args.namespace}/${segments}`;
+            return unwrap(api.GET(url, { params: { query: args.query } }), token);
+        },
+    });
+}
+//# sourceMappingURL=extensions.js.map

package/dist/tools/server.js

@@ -33,7 +33,7 @@ export function serverTools(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.",
+        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, and plugins’ own `ext.<namespace>.<event>` types from `list_extensions`. Filter by type, player, and time.",
         scope: "read",
         effect: "read",
         input: {

package/dist/tools/stats.js

@@ -7,7 +7,7 @@ export function statsTools(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.",
+        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), tamed (animals tamed, WorldAPI 2.4 and newer; also a lower bound). 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: {

package/dist/version.js

@@ -2,7 +2,7 @@ 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";
+export const MIN_WORLDAPI = "2.3.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);

package/openapi/worldapi.json

@@ -49,6 +49,9 @@
     },
     {
       "name": "Scripts"
+    },
+    {
+      "name": "Extensions"
     }
   ],
   "paths": {
@@ -271,6 +274,187 @@
         }
       }
     },
+    "/extensions": {
+      "get": {
+        "operationId": "getExtensions",
+        "summary": "Other plugins’ data: their namespaces, resources, and event topics",
+        "description": "Plugins register these through the extension bridge (see the reference). Anonymous clients see only what the plugin marks public.\n\nScope: `read`.",
+        "tags": [
+          "Extensions"
+        ],
+        "x-scope": "read",
+        "security": [
+          {
+            "bearer": [
+              "read"
+            ]
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/components/schemas/ExtensionInfo"
+                  }
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or unknown token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The token lacks the scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit hit; see Retry-After",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "The server thread didn't answer in time",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "/extensions/{namespace}/{path}": {
+      "get": {
+        "operationId": "getExtensionsNamespacePath",
+        "summary": "One resource of a plugin, read from the plugin as it is now",
+        "description": "Query parameters pass through to the plugin; each resource documents its own.\n\nScope: `read`.",
+        "tags": [
+          "Extensions"
+        ],
+        "x-scope": "read",
+        "security": [
+          {
+            "bearer": [
+              "read"
+            ]
+          }
+        ],
+        "parameters": [
+          {
+            "name": "namespace",
+            "in": "path",
+            "required": true,
+            "description": "namespace",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "path",
+            "in": "path",
+            "required": true,
+            "description": "path",
+            "schema": {
+              "type": "string"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "OK",
+            "content": {
+              "application/json": {
+                "schema": {}
+              }
+            }
+          },
+          "400": {
+            "description": "Invalid request",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "Missing or unknown token",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "403": {
+            "description": "The token lacks the scope",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "404": {
+            "description": "Not found",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "429": {
+            "description": "Rate limit hit; see Retry-After",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          },
+          "503": {
+            "description": "The server thread didn't answer in time",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ErrorBody"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/leaderboards": {
       "get": {
         "operationId": "getLeaderboards",
@@ -348,7 +532,7 @@
       "get": {
         "operationId": "getLeaderboardsStatistic",
         "summary": "Players ranked by a statistic, ties sharing a place",
-        "description": "Online players count live. Use a preset or any statistic as `category:key`, such as `custom:jump`, `mined:diamond_ore`, or `killed:*`. The `experience` preset starts each player from the game's `XpTotal` (experience since their last death, so a lower bound) and adds every pickup after that, since vanilla keeps no lifetime statistic.\n\nScope: `read`.",
+        "description": "Online players count live. Use a preset or any statistic as `category:key`, such as `custom:jump`, `mined:diamond_ore`, or `killed:*`. The `experience` preset starts each player from the game's `XpTotal` (experience since their last death, so a lower bound) and adds every pickup after that, since vanilla keeps no lifetime statistic. The `tamed` preset starts from the pets each player owns in the world, counted once, and adds every taming after that.\n\nScope: `read`.",
         "tags": [
           "Leaderboards"
         ],
@@ -10186,6 +10370,88 @@
         ],
         "additionalProperties": false
       },
+      "ExtensionInfo": {
+        "type": "object",
+        "properties": {
+          "namespace": {
+            "type": "string"
+          },
+          "plugin": {
+            "type": "string"
+          },
+          "version": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "resources": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExtensionResourceInfo"
+            }
+          },
+          "topics": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ExtensionTopicInfo"
+            }
+          }
+        },
+        "required": [
+          "namespace",
+          "plugin",
+          "version",
+          "description",
+          "resources",
+          "topics"
+        ],
+        "additionalProperties": false
+      },
+      "ExtensionResourceInfo": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "public": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "path",
+          "description",
+          "public"
+        ],
+        "additionalProperties": false
+      },
+      "ExtensionTopicInfo": {
+        "type": "object",
+        "properties": {
+          "topic": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "public": {
+            "type": "boolean"
+          },
+          "recorded": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "topic",
+          "description",
+          "public",
+          "recorded"
+        ],
+        "additionalProperties": false
+      },
       "FillRequest": {
         "type": "object",
         "properties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mairwunnx/minecraft-mcp",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "mcpName": "com.mairwunnx/minecraft-mcp",
   "description": "MCP server that lets AI agents read and manage a Minecraft server through WorldAPI",
   "keywords": [