awesome-mineflayer-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryker Geesaman
+
+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

@@ -0,0 +1,185 @@
+# awesome-mineflayer-mcp
+
+[![npm version](https://img.shields.io/npm/v/awesome-mineflayer-mcp.svg)](https://www.npmjs.com/package/awesome-mineflayer-mcp)
+[![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.
+
+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`.
+
+---
+
+## Requirements
+
+- **Node.js ≥ 20** (developed on 22.16)
+- A Minecraft server to connect to (Java Edition). The bot auto-detects the server version.
+- For online-mode servers: a Microsoft account (`auth: "microsoft"`).
+
+## Installation
+
+Run it on demand with **npx** (no install needed):
+
+```bash
+npx awesome-mineflayer-mcp
+```
+
+…or install it globally:
+
+```bash
+npm install -g awesome-mineflayer-mcp
+awesome-mineflayer-mcp
+```
+
+The server speaks MCP over **stdio**, so it is normally launched by your MCP client rather than run by hand.
+
+## Use with an MCP client
+
+Add it to your client's MCP server configuration. The recommended form uses `npx` so you always get the latest published build:
+
+**Claude Desktop** (`claude_desktop_config.json`), **Claude Code**, **Cursor**, or any stdio MCP client:
+
+```json
+{
+  "mcpServers": {
+    "mineflayer": {
+      "command": "npx",
+      "args": ["-y", "awesome-mineflayer-mcp"],
+      "env": {
+        "MCP_DISABLE_GROUPS": ""
+      }
+    }
+  }
+}
+```
+
+If you installed it globally, use `"command": "awesome-mineflayer-mcp"` with `"args": []` instead.
+
+## 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_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. |
+
+Example — disable rarely-used groups:
+
+```
+MCP_DISABLE_GROUPS=creative,villager,enchanting,settings
+```
+
+## Quick start (tool flow)
+
+1. **`connect_bot`** `{ host, username, auth }` — required first; resolves once the bot spawns.
+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.
+4. **`disconnect_bot`** when done.
+
+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`.
+
+---
+
+## Tool catalog (110 tools, 23 groups)
+
+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`
+- **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`
+- **Digging & building** `[digging]` — `dig`, `place_block`, `activate_block`, `activate_entity`, `swing_arm`
+- **Combat** `[combat]` — `pvp_attack`, `attack_entity`, `pvp_stop`, `pvp_configure`
+- **Inventory & items** `[inventory]` — `equip_item`, `unequip_item`, `toss_item`, `set_quickbar_slot`, `consume`, `activate_item`, `click_window`, `move_slot_item`, `transfer_items`
+- **Containers** `[containers]` — `open_container`, `read_open_container`, `container_deposit`, `container_withdraw`, `close_window`
+- **Furnace / smelting** `[furnace]` — `open_furnace`, `furnace_action`, `furnace_status`, `smelt_item`
+- **Enchanting & anvil** `[enchanting]` — `enchant_item`, `anvil_combine`
+- **Villager trading** `[villager]` — `open_villager`, `trade_with_villager`
+- **Crafting** `[crafting]` — `list_recipes`, `craft_item`
+- **Block gathering** `[gathering]` — `collect_block`, `cancel_collect`, `set_collect_config`
+- **Tool auto-select** `[tool]` — `equip_tool_for_block`, `set_tool_chest_locations`, `get_best_tool`
+- **Survival automation** `[survival]` — `autoeat_set_enabled`, `autoeat_configure`, `autoeat_eat`, `autoeat_cancel`, `autoeat_preview`, `armor_equip_all`
+- **Beds & sleep** `[beds]` — `sleep`, `wake`
+- **Vehicles** `[vehicles]` — `mount_entity`, `dismount`, `steer_vehicle`
+- **Fishing, books & signs** `[fishing]` — `fish`, `cancel_fish`, `write_book`, `update_sign`
+- **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`
+- **Events & telemetry** `[events]` — `get_events`, `cancel_task`
+
+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`.
+
+## Resources
+
+Subscribe-capable JSON resources for clients that support resource subscriptions:
+
+- `bot://state` — live self snapshot (position, vitals, gamemode, time, weather, held item, control states)
+- `bot://inventory` — items, armor, off-hand, held slot
+- `world://entities` — up to 50 nearest tracked entities
+- `world://players` — server roster
+- `bot://events` — tail of recent events
+
+## Events
+
+Game events are delivered two ways:
+
+- **Pull:** `get_events({ since, types, limit })` drains a ring buffer; pass the returned `nextSince` to read only new events. `dropped: true` signals the buffer overflowed since your `since`.
+- **Push:** subscribed resources emit throttled `notifications/resources/updated`; notable lines (chat, death, kick, error, msa_code) are forwarded via `sendLoggingMessage`.
+
+High-frequency observations (movement, per-tick updates, block/entity updates, time) are intentionally **not** buffered — read them on demand via `get_state` and the read-only tools.
+
+## Development (from source)
+
+```bash
+git clone https://github.com/G0Osey99/awesome-mineflayer-mcp.git
+cd awesome-mineflayer-mcp
+npm install
+npm run build       # tsc -> dist/
+npm run typecheck   # tsc --noEmit
+npm test            # vitest (unit tests for the pure logic)
+npm run dev         # tsx src/index.ts (run from source, no build step)
+```
+
+Architecture and the full design rationale: [`docs/superpowers/specs/2026-06-28-mineflayer-mcp-server-design.md`](docs/superpowers/specs/2026-06-28-mineflayer-mcp-server-design.md).
+
+```
+src/
+  index.ts        entry (stdio transport, graceful shutdown)
+  server.ts       builds the McpServer, registers tool groups + resources
+  config.ts       env + constants
+  bot/            manager (lifecycle FSM), plugins, events, wire-events, state, windows, action-locks
+  tools/          one module per tool group (+ registry.ts)
+  resources/      MCP resources + push notifications
+  util/           errors, format, result, resolve (name→id + fuzzy), serialize
+  schemas/        shared Zod fragments
+```
+
+## Publishing (maintainers)
+
+```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
+```
+
+The published package ships only `dist/`, `README.md`, and `LICENSE` (see the `files` field).
+
+## Limitations
+
+- **One bot per server process** (single-session by design).
+- **Evaluations require a seeded world.** A live Minecraft world is not deterministic, so the evaluation set in `eval/` targets a documented seeded fixture (see `eval/fixture.md`); it cannot be verified against an arbitrary live server.
+- `cancel_fish` is best-effort (Mineflayer exposes no first-class fishing abort).
+- Microsoft auth's first run needs an interactive device code (surfaced as an `msa_code` event); use `profilesFolder` to cache it.
+
+## License
+
+MIT

package/dist/bot/action-locks.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Mutual exclusion + cancellation for long-running, conflicting bot actions
+ * (goto, dig, collect_block, pvp_attack, fish, smelt_item, craft_item).
+ *
+ * Starting a new exclusive action cancels the previous one cleanly: the prior
+ * action's `onCancel` runs (e.g. `bot.pathfinder.stop()`) and its AbortSignal
+ * fires so any in-flight `await` can bail out.
+ */
+export type CancelReason = "superseded" | "manual" | "shutdown";
+export declare class CancelledError extends Error {
+    readonly reason: CancelReason;
+    constructor(reason: CancelReason);
+}
+export interface ActionHandle {
+    /** Aborts when this action is superseded/cancelled. */
+    signal: AbortSignal;
+    /** Call when the action finishes (success or failure) to release the lock. */
+    release: () => void;
+}
+export declare class ActionLocks {
+    private active;
+    get current(): string | null;
+    isBusy(): boolean;
+    /**
+     * Acquire the exclusive action lock, cancelling any prior holder.
+     * @param name  Human label for diagnostics / errors.
+     * @param onCancel  Best-effort cleanup invoked if this action is cancelled.
+     */
+    begin(name: string, onCancel?: (reason: CancelReason) => void): ActionHandle;
+    /** Cancel the current exclusive action, if any. Returns true if one was cancelled. */
+    cancelAll(reason?: CancelReason): boolean;
+}
+//# sourceMappingURL=action-locks.d.ts.map

package/dist/bot/action-locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-locks.d.ts","sourceRoot":"","sources":["../../src/bot/action-locks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEhE,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;gBAClB,MAAM,EAAE,YAAY;CAKjC;AAOD,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,MAAM,EAAE,WAAW,CAAC;IACpB,8EAA8E;IAC9E,OAAO,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAA6B;IAE3C,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED,MAAM,IAAI,OAAO;IAIjB;;;;OAIG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,YAAY;IAsB5E,sFAAsF;IACtF,SAAS,CAAC,MAAM,GAAE,YAAuB,GAAG,OAAO;CAOpD"}

package/dist/bot/action-locks.js

@@ -0,0 +1,63 @@
+/**
+ * Mutual exclusion + cancellation for long-running, conflicting bot actions
+ * (goto, dig, collect_block, pvp_attack, fish, smelt_item, craft_item).
+ *
+ * Starting a new exclusive action cancels the previous one cleanly: the prior
+ * action's `onCancel` runs (e.g. `bot.pathfinder.stop()`) and its AbortSignal
+ * fires so any in-flight `await` can bail out.
+ */
+export class CancelledError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Action cancelled (${reason})`);
+        this.name = "CancelledError";
+        this.reason = reason;
+    }
+}
+export class ActionLocks {
+    active = null;
+    get current() {
+        return this.active?.name ?? null;
+    }
+    isBusy() {
+        return this.active !== null;
+    }
+    /**
+     * Acquire the exclusive action lock, cancelling any prior holder.
+     * @param name  Human label for diagnostics / errors.
+     * @param onCancel  Best-effort cleanup invoked if this action is cancelled.
+     */
+    begin(name, onCancel) {
+        this.cancelAll("superseded");
+        const controller = new AbortController();
+        const entry = {
+            name,
+            cancel: (reason) => {
+                try {
+                    onCancel?.(reason);
+                }
+                finally {
+                    controller.abort(new CancelledError(reason));
+                }
+            },
+        };
+        this.active = entry;
+        return {
+            signal: controller.signal,
+            release: () => {
+                if (this.active === entry)
+                    this.active = null;
+            },
+        };
+    }
+    /** Cancel the current exclusive action, if any. Returns true if one was cancelled. */
+    cancelAll(reason = "manual") {
+        const a = this.active;
+        if (!a)
+            return false;
+        this.active = null;
+        a.cancel(reason);
+        return true;
+    }
+}
+//# sourceMappingURL=action-locks.js.map

package/dist/bot/action-locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-locks.js","sourceRoot":"","sources":["../../src/bot/action-locks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,MAAM,CAAe;IAC9B,YAAY,MAAoB;QAC9B,KAAK,CAAC,qBAAqB,MAAM,GAAG,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF;AAcD,MAAM,OAAO,WAAW;IACd,MAAM,GAAwB,IAAI,CAAC;IAE3C,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,IAAI,CAAC;IACnC,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAY,EAAE,QAAyC;QAC3D,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;QAC7B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAiB;YAC1B,IAAI;YACJ,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE;gBACjB,IAAI,CAAC;oBACH,QAAQ,EAAE,CAAC,MAAM,CAAC,CAAC;gBACrB,CAAC;wBAAS,CAAC;oBACT,UAAU,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC;gBAC/C,CAAC;YACH,CAAC;SACF,CAAC;QACF,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC;QACpB,OAAO;YACL,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,OAAO,EAAE,GAAG,EAAE;gBACZ,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK;oBAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YAChD,CAAC;SACF,CAAC;IACJ,CAAC;IAED,sFAAsF;IACtF,SAAS,CAAC,SAAuB,QAAQ;QACvC,MAAM,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;QACtB,IAAI,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QACrB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;QACnB,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/bot/events.d.ts

@@ -0,0 +1,51 @@
+/**
+ * In-memory event ring buffer.
+ *
+ * Discrete, agent-actionable game events are pushed here and drained via the
+ * `get_events` tool. Push listeners (registered by the resource layer) fan each
+ * event out to MCP logging / resource-update notifications, throttled elsewhere.
+ */
+export interface GameEvent {
+    /** Monotonic sequence number (1-based). */
+    seq: number;
+    /** Unix epoch ms when captured. */
+    ts: number;
+    /** Event type, e.g. "chat", "death", "goal_reached". */
+    type: string;
+    /** Serialisable payload (already reduced to plain JSON). */
+    data: unknown;
+}
+export type EventPushListener = (event: GameEvent) => void;
+export interface DrainOptions {
+    /** Return only events with seq strictly greater than this. */
+    since?: number;
+    /** Restrict to these event types. */
+    types?: string[];
+    /** Return at most this many (most recent kept). */
+    limit?: number;
+}
+export interface DrainResult {
+    events: GameEvent[];
+    /** Pass as `since` on the next call to continue without gaps. */
+    nextSince: number;
+    /** True if `since` pointed before the oldest retained event (some were lost). */
+    dropped: boolean;
+}
+export declare class EventBus {
+    private buffer;
+    private seqCounter;
+    private readonly listeners;
+    private readonly capacity;
+    constructor(capacity?: number);
+    /** Append an event and notify push listeners. Never throws. */
+    push(type: string, data?: unknown): GameEvent;
+    /** Drain events after `since`, optionally filtered by type and capped. */
+    drain(opts?: DrainOptions): DrainResult;
+    /** Most recent `n` events (used to seed the events resource). */
+    recent(n: number): GameEvent[];
+    get lastSeq(): number;
+    /** Register a push listener; returns an unsubscribe function. */
+    onPush(listener: EventPushListener): () => void;
+    clear(): void;
+}
+//# sourceMappingURL=events.d.ts.map

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

@@ -0,0 +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"}

package/dist/bot/events.js

@@ -0,0 +1,67 @@
+/**
+ * In-memory event ring buffer.
+ *
+ * Discrete, agent-actionable game events are pushed here and drained via the
+ * `get_events` tool. Push listeners (registered by the resource layer) fan each
+ * event out to MCP logging / resource-update notifications, throttled elsewhere.
+ */
+import { EVENT_BUFFER_SIZE } from "../config.js";
+export class EventBus {
+    buffer = [];
+    seqCounter = 0;
+    listeners = new Set();
+    capacity;
+    constructor(capacity = EVENT_BUFFER_SIZE) {
+        this.capacity = Math.max(1, capacity);
+    }
+    /** Append an event and notify push listeners. Never throws. */
+    push(type, data = null) {
+        const event = { seq: ++this.seqCounter, ts: Date.now(), type, data };
+        this.buffer.push(event);
+        const overflow = this.buffer.length - this.capacity;
+        if (overflow > 0)
+            this.buffer.splice(0, overflow);
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A misbehaving listener must never break event capture.
+            }
+        }
+        return event;
+    }
+    /** Drain events after `since`, optionally filtered by type and capped. */
+    drain(opts = {}) {
+        const { since, types, limit } = opts;
+        const oldestSeq = this.buffer.length > 0 ? this.buffer[0].seq : this.seqCounter;
+        const dropped = since !== undefined && since + 1 < oldestSeq;
+        let out = since !== undefined ? this.buffer.filter((e) => e.seq > since) : this.buffer.slice();
+        if (types && types.length > 0) {
+            const set = new Set(types);
+            out = out.filter((e) => set.has(e.type));
+        }
+        if (limit !== undefined && limit >= 0 && out.length > limit) {
+            out = out.slice(out.length - limit);
+        }
+        return { events: out, nextSince: this.seqCounter, dropped };
+    }
+    /** Most recent `n` events (used to seed the events resource). */
+    recent(n) {
+        return this.buffer.slice(Math.max(0, this.buffer.length - n));
+    }
+    get lastSeq() {
+        return this.seqCounter;
+    }
+    /** Register a push listener; returns an unsubscribe function. */
+    onPush(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    clear() {
+        this.buffer = [];
+    }
+}
+//# sourceMappingURL=events.js.map

package/dist/bot/events.js.map

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

package/dist/bot/manager.d.ts

@@ -0,0 +1,72 @@
+/**
+ * BotManager — owns the single bot session and its lifecycle.
+ *
+ * Status FSM: disconnected → connecting → online → (reconnecting) → online | disconnected
+ * Lifecycle (connect/disconnect/reconnect) and end/kicked handling live here.
+ * Lifecycle + msa-code events are pushed to the EventBus so the resource/log
+ * layer can forward them to the MCP client.
+ */
+import { type Bot } from "mineflayer";
+import type { EventBus } from "./events.js";
+import type { WindowManager } from "./windows.js";
+import type { ActionLocks } from "./action-locks.js";
+export type ConnectionStatus = "disconnected" | "connecting" | "online" | "reconnecting";
+export interface ConnectOptions {
+    host: string;
+    port?: number;
+    username: string;
+    password?: string;
+    auth?: "offline" | "microsoft" | "mojang";
+    /** Omit / empty string => auto-detect from server. */
+    version?: string;
+    brand?: string;
+    respawn?: boolean;
+    physicsEnabled?: boolean;
+    viewDistance?: "far" | "normal" | "short" | "tiny";
+    chatLengthLimit?: number;
+    defaultChatPatterns?: boolean;
+    disableChatSigning?: boolean;
+    accessToken?: string;
+    clientToken?: string;
+    profilesFolder?: string;
+    keepAlive?: boolean;
+    checkTimeoutInterval?: number;
+    hideErrors?: boolean;
+    logErrors?: boolean;
+    autoReconnect?: boolean;
+    connectTimeoutMs?: number;
+}
+export declare class BotManager {
+    private readonly events;
+    private readonly windows;
+    private readonly locks;
+    private _bot;
+    private _status;
+    private lastOptions;
+    private lastEndReason;
+    private detachEvents;
+    private intentionalQuit;
+    private reconnectTimer;
+    private reconnectAttempt;
+    constructor(events: EventBus, windows: WindowManager, locks: ActionLocks);
+    get status(): ConnectionStatus;
+    /** The active, spawned bot, or throw NOT_CONNECTED. */
+    requireBot(): Bot;
+    botOrNull(): Bot | null;
+    statusReport(): Record<string, unknown>;
+    connect(opts: ConnectOptions): Promise<Record<string, unknown>>;
+    disconnect(reason?: string, force?: boolean): Promise<Record<string, unknown>>;
+    reconnect(override?: Partial<ConnectOptions>): Promise<Record<string, unknown>>;
+    /** Best-effort shutdown for process exit. */
+    shutdown(): void;
+    private buildBotOptions;
+    private spawnBot;
+    /** Permanent end/kicked handling (active after a successful spawn). */
+    private attachLifecycle;
+    private scheduleReconnect;
+    private cancelReconnectTimer;
+    private setStatus;
+    private detachAndClearBot;
+    private teardown;
+}
+//# sourceMappingURL=manager.d.ts.map

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

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