awesome-mineflayer-mcp 1.0.2 → 1.3.0

package/NOTICE

@@ -0,0 +1,29 @@
+awesome-mineflayer-mcp
+Copyright (c) 2026 Ryker Geesaman
+
+This product is licensed under the MIT License (see LICENSE).
+
+It is built on, and at runtime depends on, the following third-party packages.
+Each is the property of its respective authors and is distributed under its own
+license (all MIT at the time of writing — consult each package for exact terms):
+
+  Model Context Protocol
+    - @modelcontextprotocol/sdk          (MIT)  https://github.com/modelcontextprotocol/typescript-sdk
+
+  Mineflayer ecosystem (PrismarineJS)
+    - mineflayer                         (MIT)  https://github.com/PrismarineJS/mineflayer
+    - mineflayer-pathfinder              (MIT)  https://github.com/PrismarineJS/mineflayer-pathfinder
+    - mineflayer-pvp                     (MIT)  https://github.com/PrismarineJS/mineflayer-pvp
+    - mineflayer-collectblock            (MIT)  https://github.com/PrismarineJS/mineflayer-collectblock
+    - mineflayer-tool                    (MIT)  https://github.com/PrismarineJS/mineflayer-tool
+    - mineflayer-auto-eat                (MIT)  https://github.com/link-discord/mineflayer-auto-eat
+    - mineflayer-armor-manager           (MIT)  https://github.com/PrismarineJS/MineflayerArmorManager
+    - minecraft-data                     (MIT)  https://github.com/PrismarineJS/minecraft-data
+    - prismarine-item                    (MIT)  https://github.com/PrismarineJS/prismarine-item
+    - vec3                               (MIT)  https://github.com/PrismarineJS/node-vec3
+
+  Validation
+    - zod                                (MIT)  https://github.com/colinhacks/zod
+
+Minecraft is a trademark of Mojang Synergies AB. This project is not affiliated
+with, endorsed by, or sponsored by Mojang or Microsoft.

package/README.md

@@ -4,7 +4,7 @@
 [![node](https://img.shields.io/node/v/awesome-mineflayer-mcp.svg)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
 
-A production-ready [Model Context Protocol](https://modelcontextprotocol.io) server that gives an LLM agent **standalone-equivalent control** over a [Mineflayer](https://github.com/PrismarineJS/mineflayer) Minecraft bot — movement, mining, crafting, inventory, combat, containers, chat, and much more — exposed as **110 strongly-typed tools** across 23 groups, with full bot lifecycle management and dual (poll + push) event streaming.
+A production-ready [Model Context Protocol](https://modelcontextprotocol.io) server that gives an LLM agent **standalone-equivalent control** over a [Mineflayer](https://github.com/PrismarineJS/mineflayer) Minecraft bot — movement, mining, crafting, inventory, combat, containers, chat, and much more — exposed as **123 strongly-typed tools** across 26 groups, plus **guided prompts**, **vision** (real first-person screenshots + schematic maps), persistent **waypoints**, build/dig **macros**, and dual (poll + push) event streaming, with full bot lifecycle management. Tool results carry both human-readable text and machine-readable `structuredContent`.
 
 Backed by the Mineflayer ecosystem: `mineflayer-pathfinder` (A\* navigation), `mineflayer-pvp` (combat), `mineflayer-collectblock` (gathering), `mineflayer-tool` (auto tool-select), `mineflayer-auto-eat`, and `mineflayer-armor-manager`.
 
@@ -13,9 +13,18 @@ Backed by the Mineflayer ecosystem: `mineflayer-pathfinder` (A\* navigation), `m
 ## Requirements
 
 - **Node.js ≥ 20** (developed on 22.16)
-- A Minecraft server to connect to (Java Edition). The bot auto-detects the server version.
+- A Minecraft server to connect to (Java Edition). The bot auto-detects the server version. Don't have one? See [Get a server to test against](#get-a-minecraft-server-to-test-against).
 - For online-mode servers: a Microsoft account (`auth: "microsoft"`).
 
+### Supported versions
+
+| | Supported |
+|---|---|
+| Minecraft (Java) | the range supported by the bundled `mineflayer` 4.37 / `minecraft-data` (roughly **1.8 → 1.21.x**); version is auto-detected, or pass `version` explicitly |
+| Node.js | **20, 22** (LTS) |
+
+A few tools only work on newer versions/features (e.g. `elytra_fly`, chat signing). On a version mismatch the bot is kicked with an `outdated client/server` message — pass an explicit `version`.
+
 ## Installation
 
 Run it on demand with **npx** (no install needed):
@@ -55,16 +64,88 @@ Add it to your client's MCP server configuration. The recommended form uses `npx
 
 If you installed it globally, use `"command": "awesome-mineflayer-mcp"` with `"args": []` instead.
 
+## Get a Minecraft server to test against
+
+If you don't already have a server, spin up a throwaway **offline-mode** one with Docker (no account needed):
+
+```bash
+# from a clone of this repo:
+docker compose up -d        # offline 1.20.4 server on localhost:25565
+docker compose logs -f      # wait for "Done (…)! For help, type "help""
+```
+
+…or a one-liner without the repo:
+
+```bash
+docker run -d --name mc -p 25565:25565 -e EULA=TRUE -e ONLINE_MODE=FALSE -e VERSION=1.20.4 itzg/minecraft-server
+```
+
+Then connect: `connect_bot { host: "localhost", username: "DevBot", auth: "offline" }`. Tear it down with `docker compose down -v` (or `docker rm -f mc`). Don't expose an offline-mode server to the public internet.
+
+## Autonomous operation (default account)
+
+For hands-off use, configure a **default account** so the bot connects automatically on startup — no `connect_bot` call required. Run the interactive setup:
+
+```bash
+npx awesome-mineflayer-mcp setup
+```
+
+It asks for the server host/port, an **offline** or **Microsoft** account, and whether to auto-connect on startup, then writes `~/.awesome-mineflayer-mcp/config.json` (**no password is stored**). For a Microsoft account it runs the device-code sign-in **once** and caches the token under `profilesFolder`, so later startups need no prompt.
+
+On startup the server auto-connects the configured account (verify with `get_connection_status`). The agent can also call **`connect_default`** to (re)connect it or **`get_default_account`** to inspect it.
+
+### Configure without the wizard (env vars)
+
+You can set the default account entirely from your MCP client config — handy for headless deploys. Environment variables override the config file:
+
+```json
+{
+  "mcpServers": {
+    "mineflayer": {
+      "command": "npx",
+      "args": ["-y", "awesome-mineflayer-mcp"],
+      "env": {
+        "MCP_DEFAULT_HOST": "play.example.net",
+        "MCP_DEFAULT_USERNAME": "MyBot",
+        "MCP_DEFAULT_AUTH": "offline",
+        "MCP_AUTO_CONNECT": "true"
+      }
+    }
+  }
+}
+```
+
+For Microsoft auth in a headless setup, run `setup` once locally first (or point `MCP_PROFILES_FOLDER` at a directory with a pre-cached token).
+
 ## Configuration (environment variables)
 
 | Variable | Default | Purpose |
 |---|---|---|
-| `MCP_DISABLE_GROUPS` | _(none)_ | Comma-separated tool-group keys to disable (see catalog). Trim the surface for clients that struggle with 110 tools. |
+| `MCP_DISABLE_GROUPS` | _(none)_ | Comma-separated tool-group keys to disable (see catalog). Trim the surface for clients that struggle with a large tool list. |
 | `MCP_CHARACTER_LIMIT` | `25000` | Max characters returned by any single tool call (truncated with a marker). |
 | `MCP_EVENT_BUFFER` | `1000` | Size of the in-memory event ring buffer. |
 | `MCP_THROTTLE_MS` | `250` | Minimum spacing between pushed resource-update / log notifications. |
 | `MCP_PROXIMITY_RADIUS` | `32` | Radius (blocks) for proximity-filtered events (entity spawns, sounds). |
 | `MCP_ACTION_TIMEOUT_MS` | `60000` | Default timeout for long actions when the caller omits one. |
+| `MCP_DEFAULT_HOST` / `MCP_DEFAULT_PORT` | — | Default server to auto-connect on startup. |
+| `MCP_DEFAULT_USERNAME` | — | Default account name (offline) or email (microsoft). |
+| `MCP_DEFAULT_AUTH` | `offline` | Default auth mode: `offline` or `microsoft`. |
+| `MCP_DEFAULT_VERSION` | auto | Force a protocol version for the default account. |
+| `MCP_DEFAULT_AUTO_RECONNECT` | `true` | Auto-reconnect the default account on disconnect. |
+| `MCP_AUTO_CONNECT` | `true`† | Auto-connect the default on startup († when a default is configured). |
+| `MCP_PROFILES_FOLDER` | `<home>/profiles` | Microsoft auth token-cache directory. |
+| `AWESOME_MINEFLAYER_MCP_HOME` | `~/.awesome-mineflayer-mcp` | Config + token-cache directory. |
+| `MCP_READ_ONLY` | `false` | Observe-only mode: register only read-only tools (+ lifecycle). See [Safety](#safety--guardrails). |
+| `MCP_COMMAND_DENY` | _(admin verbs)_ | Slash commands `run_command` blocks. Setting it **replaces** the default; set empty to allow all. |
+| `MCP_COMMAND_ALLOW` | _(none)_ | If set, a strict allow-list: only these commands run (deny list ignored). |
+| `MCP_ALLOWED_HOSTS` | _(any)_ | Comma-separated allow-list of hosts the bot may connect to. |
+| `MCP_CHAT_MIN_INTERVAL_MS` | `0` | Minimum spacing between outbound chat/whisper/command sends (anti-spam). |
+| `MCP_ENABLE_RAW` | `false` | Enable the advanced/unsafe `raw` protocol tool group (direct packet send/subscribe). |
+| `MCP_SCREENSHOT_WIDTH` / `_HEIGHT` | `800` / `450` | Default `get_screenshot` image size (px). |
+| `MCP_SCREENSHOT_LOAD_MS` | `2500` | How long to let the world render before capturing a screenshot. |
+| `MCP_VIEW_DISTANCE` | `4` | Chunk render distance for screenshots. |
+| `MCP_SCREENSHOT_BROWSER_CHANNEL` | _(auto)_ | Browser channel for screenshots (`chrome`, `msedge`, `chromium`). |
+| `MCP_SCREENSHOT_EXECUTABLE_PATH` | _(none)_ | Explicit browser executable path for screenshots (overrides channel). |
 
 Example — disable rarely-used groups:
 
@@ -74,26 +155,30 @@ MCP_DISABLE_GROUPS=creative,villager,enchanting,settings
 
 ## Quick start (tool flow)
 
-1. **`connect_bot`** `{ host, username, auth }` — required first; resolves once the bot spawns.
+1. **`connect_bot`** `{ host, username, auth }` — connect (resolves once the bot spawns). *Skip this if you configured a [default account](#autonomous-operation-default-account) — the bot auto-connects on startup; just check `get_connection_status`.*
 2. Act: **`goto`**, **`dig`**, **`collect_block`**, **`craft_item`**, **`pvp_attack`**, **`chat`**, …
-3. Observe: poll **`get_events`** (pass the returned `nextSince` each time) and **`get_state`**; or subscribe to the `bot://*` resources.
+3. Observe: call **`get_observation`** for a one-shot snapshot (vitals, position, inventory, nearby entities, new events) — pass the returned `events.nextSince` back each tick. Or compose **`get_state`** / **`get_inventory`** / **`list_entities`** / **`get_events`**, or subscribe to the `bot://*` resources.
 4. **`disconnect_bot`** when done.
 
+New to the server? Use the **`getting_started`** prompt (see [Prompts](#prompts)) for an in-context walkthrough.
+
 Block / item / entity arguments accept **human names** (`"iron_ore"`, `"diamond_pickaxe"`, `"zombie"`); unknown names return fuzzy suggestions.
 
 ## Authentication
 
 - `auth: "offline"` (default) — offline-mode servers; `username` is the in-game name.
-- `auth: "microsoft"` — `username` is the account email. A device-code prompt is emitted as an `msa_code` event / log notification. Set **`profilesFolder`** to cache the token so subsequent runs skip the prompt, or pass a cached `accessToken`.
+- `auth: "microsoft"` — `username` is the account email. A device-code prompt is emitted as an `msa_code` event / log notification. Set **`profilesFolder`** to cache the token so subsequent runs skip the prompt, or pass a cached `accessToken`. **Tip:** run `npx awesome-mineflayer-mcp setup` once to do the device-code sign-in and cache the token, then the server connects autonomously (see [Autonomous operation](#autonomous-operation-default-account)).
 
 ---
 
-## Tool catalog (110 tools, 23 groups)
+## Tool catalog (123 tools, 26 groups)
+
+> Full generated reference (every tool, prompt, resource): [`docs/TOOLS.md`](docs/TOOLS.md).
 
 Group keys (for `MCP_DISABLE_GROUPS`) are shown in brackets.
 
-- **Lifecycle** `[lifecycle]` — `connect_bot`, `disconnect_bot`, `reconnect_bot`, `respawn`, `get_connection_status`
-- **State & inspection** `[state]` (read-only) — `get_state`, `get_inventory`, `list_players`, `list_entities`, `find_nearest_entity`, `get_entity_details`, `get_scoreboards`, `get_teams`, `get_boss_bars`, `get_control_states`, `get_chat_patterns`, `support_feature`, `pathfinder_status`, `get_settings`, `get_physics`, `get_loaded_plugins`
+- **Lifecycle** `[lifecycle]` — `connect_bot`, `connect_default`, `disconnect_bot`, `reconnect_bot`, `respawn`, `get_connection_status`, `get_default_account`
+- **State & inspection** `[state]` (read-only) — `get_observation` (one-call snapshot for an agent's observe loop), `get_state`, `get_inventory`, `list_players`, `list_entities`, `find_nearest_entity`, `get_entity_details`, `get_scoreboards`, `get_teams`, `get_boss_bars`, `get_control_states`, `get_chat_patterns`, `support_feature`, `pathfinder_status`, `get_settings`, `get_physics`, `get_loaded_plugins`
 - **World queries** `[world]` (read-only) — `get_block_at`, `find_blocks`, `get_cursor_target`, `get_blocks_in_region`, `wait_for_chunks_to_load`
 - **Movement & pathfinding** `[movement]` — `goto`, `set_goal`, `flee_from`, `follow_entity`, `stop_pathfinding`, `get_path_to`, `configure_movements`, `configure_pathfinder`, `set_control_state`, `clear_control_states`, `elytra_fly`, `wait_for_ticks`, `set_physics_enabled`
 - **Look** `[look]` — `look_at`, `look`, `look_at_entity`
@@ -114,10 +199,57 @@ Group keys (for `MCP_DISABLE_GROUPS`) are shown in brackets.
 - **Chat & communication** `[chat]` — `chat`, `whisper`, `run_command`, `tab_complete`, `register_chat_pattern`, `remove_chat_pattern`, `wait_for_message`
 - **Settings** `[settings]` — `set_settings`
 - **Creative mode** `[creative]` — `creative_set_inventory_slot`, `creative_clear_inventory`, `creative_fly`, `creative_fly_to`
+- **Vision** `[vision]` — `get_screenshot` (real first-person textured game render), `render_map` (dependency-free schematic map) — see [Vision](#vision--let-the-agent-see)
+- **Waypoints** `[waypoints]` — `set_waypoint`, `list_waypoints`, `delete_waypoint`, `goto_waypoint` (persisted across restarts)
+- **Build & dig macros** `[build]` — `clear_region`, `dig_tunnel`, `dig_staircase`, `fill_region` (cancellable, multi-block)
 - **Events & telemetry** `[events]` — `get_events`, `cancel_task`
+- **Raw protocol** `[raw]` — `send_packet`, `subscribe_packet`, `list_packet_subscriptions` (advanced/unsafe; **off unless `MCP_ENABLE_RAW=true`**)
 
 Long-running actions (`goto`, `dig`, `collect_block`, `pvp_attack`, `fish`, `smelt_item`, `craft_item`) are mutually exclusive and cancellable — start a new movement/combat action to supersede the prior one, or call `stop_pathfinding` / `pvp_stop` / `cancel_collect` / `cancel_fish` / `cancel_task`.
 
+## Prompts
+
+The server exposes **guided, parameterized workflows** as MCP prompts — clients surface them as slash-commands / templates. They teach an agent how to chain the right tools for a goal:
+
+- **`getting_started`** — orientation: connect → observe → act → recover.
+- **`gather_wood`** `{ count?, logType? }` — find trees and collect logs.
+- **`mine_to_diamonds`** `{ targetY? }` — descend safely and branch-mine.
+- **`build_shelter`** `{ material? }` — enclose a safe space before nightfall.
+- **`find_and_smelt`** `{ input, fuel? }` — mine/gather an input and smelt it.
+- **`follow_and_defend`** `{ player }` — follow a player and fight off hostiles.
+
+Block/item arguments offer name autocompletion drawn from the connected world.
+
+## Vision — let the agent *see*
+
+Two complementary tools return PNG images as MCP image content, so a vision-capable model (and a human) can look at the world instead of reconstructing it from JSON.
+
+### `get_screenshot` — a real game render
+
+Captures an **actual textured Minecraft render** of what the bot sees — first-person from its eyes (default) or a third-person orbit — exactly like an in-game screenshot. Under the hood, [`prismarine-viewer`](https://github.com/PrismarineJS/prismarine-viewer) renders the real world (client-side WebGL) and a headless browser screenshots it. Args: `width`, `height`, `firstPerson`, `waitMs`, `viewDistance`.
+
+**Setup (one-time).** The renderer deps ship as **optional** packages (installed by default with `npm install`). All you also need is a browser:
+
+- Already have **Google Chrome or Microsoft Edge**? Nothing to do — it's used automatically.
+- Otherwise run **`npx playwright install chromium`** once.
+- Headless servers: install Chrome/Chromium, or set `MCP_SCREENSHOT_EXECUTABLE_PATH` / `MCP_SCREENSHOT_BROWSER_CHANNEL`.
+
+If the deps/browser aren't available, `get_screenshot` returns a clear `UNSUPPORTED` error with these steps — the rest of the server is unaffected. The renderer packages are pure-JS (no native build), but if you want the leanest possible install and don't need screenshots, use `npm install --omit=optional`.
+
+### `render_map` — a dependency-free schematic
+
+A lightweight colored top-down map (or `mode:"slice"` cross-section) drawn from block data with a **built-in PNG encoder** (no extra deps at all). Good as a minimap/overview or when the screenshot extras aren't installed. North (−Z) is up; bot = white dot with a facing tick; players cyan, hostiles red, passives yellow, items grey; includes a block legend.
+
+## Safety & guardrails
+
+Sensible defaults that matter once an agent drives the bot autonomously (especially with a [default account](#autonomous-operation-default-account)):
+
+- **Command policy.** `run_command` blocks server-administration verbs by default (`op`, `deop`, `ban`, `kick`, `stop`, `whitelist`, and the `execute`/`function`/`schedule` wrappers, …). Ordinary gameplay commands (`/tp`, `/time`, `/give`, …) are allowed. Override with `MCP_COMMAND_DENY` (replaces the default; empty = allow all) or lock down with `MCP_COMMAND_ALLOW` (strict allow-list). This is **best-effort defense-in-depth**, not a hard boundary — it gates on the first command verb, and a bot with operator permissions could still find a way around it. For untrusted/autonomous deployments, prefer `MCP_COMMAND_ALLOW`, `MCP_READ_ONLY`, and not granting the bot's account operator rights. **Note:** incoming player chat is delivered to your agent as events — treat it as untrusted input.
+- **Host allow-list.** `MCP_ALLOWED_HOSTS` restricts which servers `connect_bot` / `reconnect_bot` may join, so an agent can't repoint the bot (and its cached token) at an arbitrary address.
+- **Read-only mode.** `MCP_READ_ONLY=true` registers only observation tools (plus connection management) — look-but-don't-touch.
+- **Rate limiting.** `MCP_CHAT_MIN_INTERVAL_MS` spaces outbound chat/commands to avoid spam-kicks.
+- **No secret leakage.** Passwords / access tokens are never stored on disk and are redacted from connection-error messages.
+
 ## Resources
 
 Subscribe-capable JSON resources for clients that support resource subscriptions:
@@ -127,6 +259,9 @@ Subscribe-capable JSON resources for clients that support resource subscriptions
 - `world://entities` — up to 50 nearest tracked entities
 - `world://players` — server roster
 - `bot://events` — tail of recent events
+- `bot://waypoints` — saved named waypoints
+
+Plus parameterized **resource templates** for on-demand lookups: `block://{x}/{y}/{z}` and `entity://{id}`.
 
 ## Events
 
@@ -153,25 +288,58 @@ Architecture and the full design rationale: [`docs/superpowers/specs/2026-06-28-
 
 ```
 src/
-  index.ts        entry (stdio transport, graceful shutdown)
-  server.ts       builds the McpServer, registers tool groups + resources
-  config.ts       env + constants
+  index.ts        entry (stdio transport, graceful shutdown, crash guards)
+  server.ts       builds the McpServer, registers tool groups + resources + prompts
+  config.ts       env + constants + safety policy (groups, read-only, command/host allow-lists)
   bot/            manager (lifecycle FSM), plugins, events, wire-events, state, windows, action-locks
   tools/          one module per tool group (+ registry.ts)
+  prompts/        guided multi-tool workflows
   resources/      MCP resources + push notifications
-  util/           errors, format, result, resolve (name→id + fuzzy), serialize
+  util/           errors, format, result, resolve (name→id + fuzzy), serialize, async, redact
   schemas/        shared Zod fragments
 ```
 
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for how to add a tool/group and run a local test server.
+
 ## Publishing (maintainers)
 
+Pushing a `v*` tag publishes to **npm**, **GitHub Container Registry** (Docker), the **MCP Registry**, and updates **Smithery** — all via [`.github/workflows/ci.yml`](.github/workflows/ci.yml). `npm version` keeps `package.json`, `src/config.ts`, and `server.json` in sync.
+
+```bash
+npm version minor        # bumps + syncs versions, commits, and tags
+git push --follow-tags   # triggers the release jobs
+```
+
+Full one-time setup and the step-by-step release checklist are in [`RELEASE.md`](RELEASE.md). The published npm package ships only `dist/`, `README.md`, `LICENSE`, and `NOTICE` (see the `files` field).
+
+## Troubleshooting
+
+Connection failures now return a **specific error code and suggestions** (not an opaque `INTERNAL`). Common cases:
+
+| Symptom / error | Likely cause | Fix |
+|---|---|---|
+| `CONNECT_REFUSED` (ECONNREFUSED) | Wrong host/port, or server not running | Check `host`/`port`; confirm the server has finished starting (default port 25565). |
+| `CONNECT_REFUSED` (ENOTFOUND) | Hostname doesn't resolve | Double-check the server address. |
+| `ONLINE_MODE` / "unverified username" | Server is online-mode; bot used offline auth | Use `auth: "microsoft"`, or set `online-mode=false` on the server. |
+| `VERSION_MISMATCH` / "outdated client/server" | Auto-detected version is wrong | Pass an explicit `version` (e.g. `"1.20.4"`). |
+| Chat rejected / "secure profile" | Server requires signed chat | Connect with `disableChatSigning: true`. |
+| `AUTH_FAILED` | Stale/invalid Microsoft token | Re-run `npx awesome-mineflayer-mcp setup`, or clear the `profilesFolder` cache and sign in again. |
+| `FORBIDDEN` on `run_command` | Command blocked by policy | See [Safety](#safety--guardrails) — adjust `MCP_COMMAND_DENY` / `MCP_COMMAND_ALLOW`. |
+| `FORBIDDEN` on `connect_bot` | Host not in allow-list | Add it to `MCP_ALLOWED_HOSTS` (or unset to allow any). |
+| `NO_PATH` | Pathfinder can't reach the goal | Move closer, clear obstacles, or relax `configure_movements`. |
+| Microsoft device-code prompt | First-time MSA sign-in | Visit the URL from the `msa_code` event; set `profilesFolder` to cache it. |
+
+First-run sign-in for Microsoft auth is interactive once — run `npx awesome-mineflayer-mcp setup` to do it and cache the token.
+
+## Docker
+
+A `Dockerfile` is included for headless/autonomous deployments (configure a default account via `MCP_DEFAULT_*`):
+
 ```bash
-npm version patch        # or minor / major — bumps package.json + tags
-npm publish              # the `prepare` script builds dist/ first; publishes to npm
-git push --follow-tags
+docker build -t awesome-mineflayer-mcp .
 ```
 
-The published package ships only `dist/`, `README.md`, and `LICENSE` (see the `files` field).
+Mount a volume at `/root/.awesome-mineflayer-mcp` to persist the config and Microsoft token cache. (The server speaks MCP over stdio, so a container is most useful for autonomous default-account runs rather than for a client to spawn.)
 
 ## Limitations
 

package/dist/account-config.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Persisted "default account" configuration for autonomous operation.
+ *
+ * Stored at ~/.awesome-mineflayer-mcp/config.json (override the directory with
+ * AWESOME_MINEFLAYER_MCP_HOME). NO secrets are stored: offline needs none, and
+ * Microsoft auth relies on the token cache under `profilesFolder` (managed by
+ * prismarine-auth), not a saved password. Environment variables override the
+ * file so MCP-client configs can set everything inline.
+ */
+import type { ConnectOptions } from "./bot/manager.js";
+export declare function configHome(): string;
+export declare function configPath(): string;
+export declare function defaultProfilesFolder(): string;
+export interface StoredAccount {
+    host: string;
+    port?: number;
+    username: string;
+    auth: "offline" | "microsoft";
+    version?: string;
+    autoReconnect?: boolean;
+    profilesFolder?: string;
+}
+export interface StoredConfig {
+    account?: StoredAccount;
+    autoConnect?: boolean;
+}
+export declare function loadConfig(): StoredConfig;
+export declare function saveConfig(cfg: StoredConfig): string;
+export interface ResolvedDefault {
+    /** ConnectOptions ready to pass to BotManager.connect, or null if unconfigured. */
+    opts: ConnectOptions | null;
+    /** Whether the server should auto-connect on startup. */
+    autoConnect: boolean;
+    /** Where the values came from. */
+    source: "env" | "file" | "none";
+    /** Sanitized account view for display (no secrets). */
+    account: StoredAccount | null;
+}
+/** Merge stored config with environment overrides into ConnectOptions. */
+export declare function resolveDefaultConnect(): ResolvedDefault;
+//# sourceMappingURL=account-config.d.ts.map

package/dist/account-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-config.d.ts","sourceRoot":"","sources":["../src/account-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,wBAAgB,UAAU,IAAI,MAAM,CAGnC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAEnC;AAED,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAgB,UAAU,IAAI,YAAY,CAQzC;AAED,wBAAgB,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,MAAM,CAKpD;AAUD,MAAM,WAAW,eAAe;IAC9B,mFAAmF;IACnF,IAAI,EAAE,cAAc,GAAG,IAAI,CAAC;IAC5B,yDAAyD;IACzD,WAAW,EAAE,OAAO,CAAC;IACrB,kCAAkC;IAClC,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IAChC,uDAAuD;IACvD,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;CAC/B;AAED,0EAA0E;AAC1E,wBAAgB,qBAAqB,IAAI,eAAe,CA2CvD"}

package/dist/account-config.js

@@ -0,0 +1,86 @@
+/**
+ * Persisted "default account" configuration for autonomous operation.
+ *
+ * Stored at ~/.awesome-mineflayer-mcp/config.json (override the directory with
+ * AWESOME_MINEFLAYER_MCP_HOME). NO secrets are stored: offline needs none, and
+ * Microsoft auth relies on the token cache under `profilesFolder` (managed by
+ * prismarine-auth), not a saved password. Environment variables override the
+ * file so MCP-client configs can set everything inline.
+ */
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs";
+export function configHome() {
+    const env = process.env.AWESOME_MINEFLAYER_MCP_HOME?.trim();
+    return env && env.length > 0 ? env : path.join(os.homedir(), ".awesome-mineflayer-mcp");
+}
+export function configPath() {
+    return path.join(configHome(), "config.json");
+}
+export function defaultProfilesFolder() {
+    return path.join(configHome(), "profiles");
+}
+export function loadConfig() {
+    try {
+        const raw = fs.readFileSync(configPath(), "utf8");
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function saveConfig(cfg) {
+    fs.mkdirSync(configHome(), { recursive: true });
+    const p = configPath();
+    fs.writeFileSync(p, `${JSON.stringify(cfg, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    return p;
+}
+function envBool(v) {
+    if (v === undefined)
+        return undefined;
+    const s = v.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(s))
+        return true;
+    if (["0", "false", "no", "off"].includes(s))
+        return false;
+    return undefined;
+}
+/** Merge stored config with environment overrides into ConnectOptions. */
+export function resolveDefaultConnect() {
+    const cfg = loadConfig();
+    const fileAcct = cfg.account ?? null;
+    const host = process.env.MCP_DEFAULT_HOST?.trim() || fileAcct?.host;
+    const username = process.env.MCP_DEFAULT_USERNAME?.trim() || fileAcct?.username;
+    const authEnv = process.env.MCP_DEFAULT_AUTH?.trim();
+    const auth = authEnv === "offline" || authEnv === "microsoft" ? authEnv : (fileAcct?.auth ?? "offline");
+    if (!host || !username) {
+        return { opts: null, autoConnect: false, source: "none", account: null };
+    }
+    const portEnv = process.env.MCP_DEFAULT_PORT;
+    const portParsed = portEnv ? Number.parseInt(portEnv, 10) : fileAcct?.port;
+    const port = portParsed && Number.isFinite(portParsed) ? portParsed : undefined;
+    const version = process.env.MCP_DEFAULT_VERSION?.trim() || fileAcct?.version || undefined;
+    const autoReconnect = envBool(process.env.MCP_DEFAULT_AUTO_RECONNECT) ?? fileAcct?.autoReconnect ?? true;
+    const profilesFolder = process.env.MCP_PROFILES_FOLDER?.trim() ||
+        fileAcct?.profilesFolder ||
+        (auth === "microsoft" ? defaultProfilesFolder() : undefined);
+    const opts = {
+        host,
+        username,
+        auth,
+        autoReconnect,
+        ...(port !== undefined ? { port } : {}),
+        ...(version ? { version } : {}),
+        ...(profilesFolder ? { profilesFolder } : {}),
+    };
+    const usedEnv = Boolean(process.env.MCP_DEFAULT_HOST?.trim() || process.env.MCP_DEFAULT_USERNAME?.trim());
+    const autoConnect = envBool(process.env.MCP_AUTO_CONNECT) ?? cfg.autoConnect ?? true;
+    return {
+        opts,
+        autoConnect,
+        source: usedEnv ? "env" : "file",
+        account: { host, port, username, auth, version, autoReconnect, profilesFolder },
+    };
+}
+//# sourceMappingURL=account-config.js.map

package/dist/account-config.js.map

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

package/dist/bot/events.d.ts

@@ -21,7 +21,12 @@ export interface DrainOptions {
     since?: number;
     /** Restrict to these event types. */
     types?: string[];
-    /** Return at most this many (most recent kept). */
+    /**
+     * Return at most this many events, OLDEST matching first. When more than
+     * `limit` are pending, the surplus is NOT dropped: `nextSince` is set to the
+     * last event actually returned so the remainder is delivered (in order,
+     * without loss) on the next call.
+     */
     limit?: number;
 }
 export interface DrainResult {

package/dist/bot/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/bot/events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,SAAoB;IAIxC,+DAA+D;IAC/D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAc,GAAG,SAAS;IAenD,0EAA0E;IAC1E,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW;IAgB3C,iEAAiE;IACjE,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE;IAI9B,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,iEAAiE;IACjE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAO/C,KAAK,IAAI,IAAI;CAGd"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/bot/events.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,SAAS;IACxB,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,mCAAmC;IACnC,EAAE,EAAE,MAAM,CAAC;IACX,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;CACf;AAED,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,iEAAiE;IACjE,SAAS,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,QAAQ,SAAoB;IAIxC,+DAA+D;IAC/D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,OAAc,GAAG,SAAS;IAenD,0EAA0E;IAC1E,KAAK,CAAC,IAAI,GAAE,YAAiB,GAAG,WAAW;IA0B3C,iEAAiE;IACjE,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE;IAI9B,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,iEAAiE;IACjE,MAAM,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,IAAI;IAO/C,KAAK,IAAI,IAAI;CAGd"}

package/dist/bot/events.js

@@ -41,10 +41,20 @@ export class EventBus {
             const set = new Set(types);
             out = out.filter((e) => set.has(e.type));
         }
+        // By default the caller has now seen everything up to the latest seq.
+        let nextSince = this.seqCounter;
         if (limit !== undefined && limit >= 0 && out.length > limit) {
-            out = out.slice(out.length - limit);
+            // Forward-paginate: hand back the OLDEST `limit` events and rewind the
+            // cursor to the last one returned, so the remainder is delivered on the
+            // next call instead of being silently skipped (which the previous
+            // "keep newest N, advance to seqCounter" behaviour did).
+            out = out.slice(0, limit);
+            // Advance the cursor only to the last event actually returned. When limit
+            // is 0 (out becomes empty), DON'T jump to seqCounter — that would skip all
+            // unread events; rewind to just before the oldest retained event instead.
+            nextSince = out.length > 0 ? out[out.length - 1].seq : (since ?? oldestSeq - 1);
         }
-        return { events: out, nextSince: this.seqCounter, dropped };
+        return { events: out, nextSince, dropped };
     }
     /** Most recent `n` events (used to seed the events resource). */
     recent(n) {

package/dist/bot/events.js.map

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

package/dist/bot/manager.d.ts

@@ -59,6 +59,11 @@ export declare class BotManager {
     reconnect(override?: Partial<ConnectOptions>): Promise<Record<string, unknown>>;
     /** Best-effort shutdown for process exit. */
     shutdown(): void;
+    private assertHostAllowed;
+    /** Strip any configured secrets from a reason string before it leaves the process. */
+    private redact;
+    /** Build a typed, actionable error from a raw connect/login failure reason. */
+    private connectError;
     private buildBotOptions;
     private spawnBot;
     /** Permanent end/kicked handling (active after a successful spawn). */

package/dist/bot/manager.d.ts.map

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