kill-switch-mcp 1.0.1 → 1.1.2

package/bin/kill-switch-mcp.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+// Node 22+ has native TypeScript support (--experimental-strip-types).
+// tsx's register() conflicts with Node 24's native .ts loader, causing
+// ERR_REQUIRE_CYCLE_MODULE on dynamic import() of .ts action files.
+// Only register tsx for older Node versions that lack native TS support.
+const major = parseInt(process.versions.node.split('.')[0]);
+if (major < 22) {
+  const { register } = await import('tsx/esm/api');
+  register();
+}
+
+await import('../src/server.ts');

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "kill-switch-mcp",
-  "version": "1.0.1",
+  "version": "1.1.2",
   "description": "Kill Switch MCP Server — AI battle royale powered by Claude Code",
   "type": "module",
   "bin": {
-    "kill-switch-mcp": "dist/server.js"
+    "kill-switch-mcp": "./bin/kill-switch-mcp.js"
   },
   "files": [
-    "dist/",
+    "bin/",
+    "src/",
     "defaults/"
   ],
   "scripts": {
-    "build": "bun build src/server.ts --outdir dist --target node --format esm --splitting",
-    "dev": "bun run src/server.ts"
+    "dev": "node bin/kill-switch-mcp.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.0.4"
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "tsx": "^4.19.0",
+    "viem": "^2.47.6"
   },
   "keywords": [
     "mcp",

package/src/api/index.ts

@@ -0,0 +1,188 @@
+// Bot connection manager
+// Supports multiple simultaneous bot connections
+
+import { BotSDK, deriveGatewayUrl } from '../sdk/index';
+import { BotActions } from '../sdk/actions';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+export interface BotConnection {
+  sdk: BotSDK;
+  bot: BotActions;
+  username: string;
+  connected: boolean;
+  unsubscribeConnectionState?: () => void;
+}
+
+class BotManager {
+  private connections: Map<string, BotConnection> = new Map();
+  private defaultGatewayUrl = 'ws://localhost:7780';
+
+  /**
+   * Connect to a bot by name.
+   * If password is not provided, loads credentials from bots/{name}/bot.env
+   */
+  async connect(name: string, password?: string, gatewayUrl?: string): Promise<BotConnection> {
+    // Check if already connected
+    if (this.connections.has(name)) {
+      const existing = this.connections.get(name)!;
+      if (existing.connected) {
+        return existing;
+      }
+      // Reconnect if disconnected
+      await this.connectWithTimeout(existing.sdk, 30000);
+      existing.connected = true;
+      return existing;
+    }
+
+    let username = name;
+    let pwd = password;
+    let gateway = gatewayUrl || this.defaultGatewayUrl;
+    let showChat = false;
+
+    // Load credentials from bot.env if no password provided
+    if (!password) {
+      const envPath = join(process.cwd(), 'bots', name, 'bot.env');
+
+      if (!existsSync(envPath)) {
+        throw new Error(`Bot "${name}" not found. No bots/${name}/bot.env file exists. Call login with an agent_name to create one.`);
+      }
+
+      const envContent = await readFile(envPath, 'utf-8');
+      const env = this.parseEnv(envContent);
+
+      username = env.BOT_USERNAME || name;
+      pwd = env.PASSWORD;
+
+      if (env.SERVER) {
+        gateway = deriveGatewayUrl(env.SERVER);
+      }
+
+      // Check if chat should be shown (default: false for safety)
+      if (env.SHOW_CHAT?.toLowerCase() === 'true') {
+        showChat = true;
+      }
+    }
+
+    if (!pwd) {
+      throw new Error(`No password provided for bot "${name}"`);
+    }
+
+    console.error(`[MCP] Connecting bot "${name}":`);
+    console.error(`[MCP]   username: ${username}`);
+    console.error(`[MCP]   gateway: ${gateway}`);
+    console.error(`[MCP]   password: ${pwd ? pwd.substring(0, 3) + '...' : 'MISSING'}`);
+
+    const sdk = new BotSDK({
+      botUsername: username,
+      password: pwd,
+      gatewayUrl: gateway,
+      connectionMode: 'control',
+      autoReconnect: true,       // Enable auto-reconnect for connection stability
+      autoLaunchBrowser: 'auto', // Auto-launch browser if session is dead
+      showChat,                  // Show other players' chat (default: false for safety)
+    });
+
+    const bot = new BotActions(sdk);
+
+    // Connect with 30s timeout to avoid blocking forever
+    console.error(`[MCP] Starting connection...`);
+    await this.connectWithTimeout(sdk, 30000);
+    console.error(`[MCP] Bot "${name}" connected!`);
+
+    const connection: BotConnection = {
+      sdk,
+      bot,
+      username,
+      connected: true
+    };
+
+    // Track connection state changes
+    connection.unsubscribeConnectionState = sdk.onConnectionStateChange((state) => {
+      const wasConnected = connection.connected;
+      connection.connected = state === 'connected';
+      if (wasConnected && !connection.connected) {
+        console.error(`[MCP] Bot "${name}" connection lost (${state}), will auto-reconnect...`);
+      } else if (!wasConnected && connection.connected) {
+        console.error(`[MCP] Bot "${name}" reconnected!`);
+      }
+    });
+
+    this.connections.set(name, connection);
+    return connection;
+  }
+
+  private async connectWithTimeout(sdk: BotSDK, timeoutMs: number): Promise<void> {
+    let timeoutId: ReturnType<typeof setTimeout>;
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      timeoutId = setTimeout(() => reject(new Error(`Connection timed out after ${timeoutMs / 1000}s`)), timeoutMs);
+    });
+
+    try {
+      await Promise.race([sdk.connect(), timeoutPromise]);
+    } finally {
+      clearTimeout(timeoutId!);
+    }
+  }
+
+  /**
+   * Disconnect a bot by name
+   */
+  async disconnect(name: string): Promise<void> {
+    const connection = this.connections.get(name);
+    if (!connection) {
+      throw new Error(`Bot "${name}" is not connected`);
+    }
+
+    console.error(`[MCP] Disconnecting bot "${name}"...`);
+    if (connection.unsubscribeConnectionState) {
+      connection.unsubscribeConnectionState();
+    }
+    connection.sdk.disconnect();
+    connection.connected = false;
+    this.connections.delete(name);
+    console.error(`[MCP] Bot "${name}" disconnected`);
+  }
+
+  /**
+   * Get a bot connection by name
+   */
+  get(name: string): BotConnection | undefined {
+    return this.connections.get(name);
+  }
+
+  /**
+   * List all connected bots
+   */
+  list(): Array<{ name: string; username: string; connected: boolean }> {
+    return Array.from(this.connections.entries()).map(([name, conn]) => ({
+      name,
+      username: conn.username,
+      connected: conn.connected
+    }));
+  }
+
+  /**
+   * Check if a bot is connected
+   */
+  has(name: string): boolean {
+    return this.connections.has(name);
+  }
+
+  private parseEnv(content: string): Record<string, string> {
+    const result: Record<string, string> = {};
+    for (const line of content.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const [key, ...valueParts] = trimmed.split('=');
+      if (key && valueParts.length > 0) {
+        result[key.trim()] = valueParts.join('=').trim();
+      }
+    }
+    return result;
+  }
+}
+
+// Export singleton instance
+export const botManager = new BotManager();

package/src/sdk/actions-helpers.ts

@@ -0,0 +1,450 @@
+// Bot SDK - Action Helpers
+// Private helper methods extracted from BotActions for reusability
+
+import { BotSDK } from './index';
+import type {
+    NearbyLoc,
+    NearbyNpc,
+    NearbyPlayer,
+    InventoryItem,
+    GroundItem,
+    ShopItem,
+} from './types';
+
+export class ActionHelpers {
+    constructor(private sdk: BotSDK) {}
+
+    // ============ Door Retry Wrapper ============
+
+    /**
+     * Wraps an action with automatic door-opening retry logic.
+     * If the action fails due to "can't reach", tries to open a nearby door and retries.
+     *
+     * @param action - Function that performs the action and returns a result
+     * @param shouldRetry - Function that checks if the result indicates a "can't reach" failure
+     * @param maxRetries - Maximum number of door-open retries (default 2)
+     * @returns The action result (either successful or final failure)
+     *
+     * @example
+     * ```ts
+     * return this.helpers.withDoorRetry(
+     *   () => this._pickupItemOnce(target),
+     *   (r) => r.reason === 'cant_reach'
+     * );
+     * ```
+     */
+    async withDoorRetry<T extends { success: boolean }>(
+        action: () => Promise<T>,
+        shouldRetry: (result: T) => boolean,
+        maxRetries: number = 2
+    ): Promise<T> {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const result = await action();
+
+            // Success or non-retryable failure
+            if (result.success || !shouldRetry(result)) {
+                return result;
+            }
+
+            // Try opening a door before retrying
+            if (attempt < maxRetries) {
+                const doorOpened = await this.tryOpenBlockingDoor();
+                if (doorOpened) {
+                    await this.sdk.waitForTicks(1);
+                    continue;
+                }
+            }
+
+            // No door to open or max retries reached
+            return result;
+        }
+
+        // TypeScript needs this, but it's unreachable
+        return action();
+    }
+
+    // ============ Door Handling ============
+
+    /**
+     * Try to find and open a nearby blocking door/gate/fence.
+     * Walks to the door using raw sendWalk (not walkTo) to avoid recursion.
+     * @param maxDistance - Maximum distance to search for openable objects (default 15 tiles)
+     * @returns true if something was successfully opened
+     */
+    async tryOpenBlockingDoor(maxDistance: number = 15): Promise<boolean> {
+        // Look for any loc with an "Open" option - covers doors, gates, fences, pens, etc.
+        const openables = this.sdk.getNearbyLocs()
+            .filter(l => l.optionsWithIndex.some(o => /^open$/i.test(o.text)))
+            .filter(l => l.distance <= maxDistance)
+            .sort((a, b) => a.distance - b.distance);
+
+        if (openables.length === 0) {
+            return false;
+        }
+
+        const door = openables[0]!;
+        const doorX = door.x;
+        const doorZ = door.z;
+        const doorId = door.id;
+
+        const openOpt = door.optionsWithIndex.find(o => /^open$/i.test(o.text));
+        if (!openOpt) {
+            return true; // Already open (has Close option instead)
+        }
+
+        // Walk to an adjacent tile first — sendInteractLoc uses server-side
+        // pathfinding which enforces closed door collision, so it can't route
+        // through the very door we're trying to open.
+        await this.walkAdjacentTo(door.x, door.z);
+
+        const startTick = this.sdk.getState()?.tick || 0;
+        await this.sdk.sendInteractLoc(door.x, door.z, door.id, openOpt.opIndex);
+
+        // Wait for door to open (with longer timeout to allow for walking)
+        try {
+            await this.sdk.waitForCondition(state => {
+                // Check for failure messages - locked doors, can't reach, etc.
+                for (const msg of state.gameMessages) {
+                    if (msg.tick > startTick) {
+                        const text = msg.text.toLowerCase();
+                        if (text.includes("can't reach") || text.includes("cannot reach") || text.includes("locked")) {
+                            return true; // Exit early — door can't be opened
+                        }
+                    }
+                }
+
+                const doorNow = state.nearbyLocs.find(l =>
+                    l.x === doorX && l.z === doorZ && l.id === doorId
+                );
+                if (!doorNow) return true; // Door gone = opened
+                return !doorNow.optionsWithIndex.some(o => /^open$/i.test(o.text)); // No "Open" option = opened
+            }, 8000); // Longer timeout to allow walking + opening
+
+            // Check if we got a "can't reach" message
+            const finalState = this.sdk.getState();
+            for (const msg of finalState?.gameMessages ?? []) {
+                if (msg.tick > startTick) {
+                    const text = msg.text.toLowerCase();
+                    if (text.includes("can't reach") || text.includes("cannot reach")) {
+                        return false;
+                    }
+                }
+            }
+
+            // Verify door actually opened
+            const doorAfter = finalState?.nearbyLocs.find(l =>
+                l.x === doorX && l.z === doorZ && l.id === doorId
+            );
+            if (!doorAfter || !doorAfter.optionsWithIndex.some(o => /^open$/i.test(o.text))) {
+                return true;
+            }
+
+            return false;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * Check recent game messages for "can't reach" indicators.
+     * @param startTick - Only check messages after this tick
+     */
+    checkCantReachMessage(startTick: number): boolean {
+        const state = this.sdk.getState();
+        if (!state) return false;
+
+        for (const msg of state.gameMessages) {
+            if (msg.tick > startTick) {
+                const text = msg.text.toLowerCase();
+                if (text.includes("can't reach") || text.includes("cannot reach") || text.includes("i can't reach")) {
+                    return true;
+                }
+            }
+        }
+        return false;
+    }
+
+    // ============ Walk Adjacent ============
+
+    /**
+     * Walk to a tile adjacent to the given coordinates using raw sendWalk.
+     * Picks the closest cardinal-adjacent tile to the player.
+     * Used before interacting with doors/gates to avoid server-side pathfinding
+     * through the very door we're trying to open.
+     * @returns true if already adjacent or successfully walked adjacent
+     */
+    private async walkAdjacentTo(targetX: number, targetZ: number): Promise<boolean> {
+        const playerState = this.sdk.getState()?.player;
+        if (!playerState) return false;
+
+        const px = playerState.worldX;
+        const pz = playerState.worldZ;
+        const dx = Math.abs(px - targetX);
+        const dz = Math.abs(pz - targetZ);
+        const isAdjacent = (dx <= 1 && dz <= 1) && (dx + dz > 0);
+
+        if (isAdjacent) return true;
+
+        const candidates = [
+            { x: targetX, z: targetZ - 1 },
+            { x: targetX, z: targetZ + 1 },
+            { x: targetX - 1, z: targetZ },
+            { x: targetX + 1, z: targetZ },
+        ].sort((a, b) => {
+            const da = Math.abs(a.x - px) + Math.abs(a.z - pz);
+            const db = Math.abs(b.x - px) + Math.abs(b.z - pz);
+            return da - db;
+        });
+
+        const target = candidates[0]!;
+        await this.sdk.sendWalk(target.x, target.z, true);
+        await this.waitForMovementComplete(target.x, target.z, 1);
+        return true;
+    }
+
+    // ============ Movement Helpers ============
+
+    async waitForMovementComplete(
+        targetX: number,
+        targetZ: number,
+        tolerance: number = 3
+    ): Promise<{ arrived: boolean; stoppedMoving: boolean; x: number; z: number }> {
+        // All logic is tick-based so it scales with any server tick rate.
+        // Running = 2 tiles/tick. Walking = 1 tile/tick.
+        const TILES_PER_TICK = 2;
+        const STUCK_TICKS = 2;       // 2 ticks of no movement = stuck
+        const MIN_TICKS = 3;         // minimum ticks to wait
+        const SAFETY_MS = 15_000;    // hard ms failsafe if state updates stop entirely
+
+        const startState = this.sdk.getState();
+        if (!startState?.player) {
+            return { arrived: false, stoppedMoving: true, x: 0, z: 0 };
+        }
+
+        const startX = startState.player.worldX;
+        const startZ = startState.player.worldZ;
+        const startTick = startState.tick;
+
+        const distance = Math.sqrt(
+            Math.pow(targetX - startX, 2) + Math.pow(targetZ - startZ, 2)
+        );
+        const expectedTicks = Math.ceil(distance / TILES_PER_TICK);
+        const maxTicks = Math.max(MIN_TICKS, Math.ceil(expectedTicks * 1.5));
+
+        let lastX = startX;
+        let lastZ = startZ;
+        let lastMoveTick = startTick;
+
+        return new Promise((resolve) => {
+            let resolved = false;
+            const done = (result: { arrived: boolean; stoppedMoving: boolean; x: number; z: number }) => {
+                if (resolved) return;
+                resolved = true;
+                clearTimeout(safetyTimer);
+                unsub();
+                resolve(result);
+            };
+
+            // Hard ms failsafe in case state updates stop arriving
+            const safetyTimer = setTimeout(() => {
+                const s = this.sdk.getState()?.player;
+                const fx = s?.worldX ?? lastX;
+                const fz = s?.worldZ ?? lastZ;
+                const fd = Math.sqrt(Math.pow(targetX - fx, 2) + Math.pow(targetZ - fz, 2));
+                done({ arrived: fd <= tolerance, stoppedMoving: true, x: fx, z: fz });
+            }, SAFETY_MS);
+
+            const unsub = this.sdk.onStateUpdate((state) => {
+                if (!state?.player) return;
+
+                const currentX = state.player.worldX;
+                const currentZ = state.player.worldZ;
+                const currentTick = state.tick;
+
+                // Check arrival
+                const distToTarget = Math.sqrt(
+                    Math.pow(targetX - currentX, 2) + Math.pow(targetZ - currentZ, 2)
+                );
+                if (distToTarget <= tolerance) {
+                    done({ arrived: true, stoppedMoving: false, x: currentX, z: currentZ });
+                    return;
+                }
+
+                // Track movement by tick
+                if (currentX !== lastX || currentZ !== lastZ) {
+                    lastMoveTick = currentTick;
+                    lastX = currentX;
+                    lastZ = currentZ;
+                }
+
+                // Stuck: no movement for STUCK_TICKS
+                if (currentTick - lastMoveTick >= STUCK_TICKS) {
+                    done({ arrived: false, stoppedMoving: true, x: currentX, z: currentZ });
+                    return;
+                }
+
+                // Tick budget exceeded
+                if (currentTick - startTick >= maxTicks) {
+                    done({ arrived: distToTarget <= tolerance, stoppedMoving: true, x: currentX, z: currentZ });
+                }
+            });
+        });
+    }
+
+    // ============ Walk Step Helper ============
+
+    /**
+     * Take a single walk step toward a target and report the result.
+     * Used by walkTo to avoid duplicating walk-and-check logic.
+     */
+    async walkStepToward(
+        targetX: number,
+        targetZ: number,
+        tolerance: number,
+        lastPos: { x: number; z: number }
+    ): Promise<{ status: 'arrived' | 'progress' | 'stuck'; pos: { x: number; z: number } }> {
+        await this.sdk.sendWalk(targetX, targetZ, true);
+        const moveResult = await this.waitForMovementComplete(targetX, targetZ, tolerance);
+
+        const pos = this.sdk.getState()?.player;
+        if (!pos) {
+            return { status: 'stuck', pos: lastPos };
+        }
+
+        const currentPos = { x: pos.worldX, z: pos.worldZ };
+
+        // Check if arrived
+        const distToTarget = Math.sqrt(
+            Math.pow(targetX - currentPos.x, 2) + Math.pow(targetZ - currentPos.z, 2)
+        );
+        if (distToTarget <= tolerance) {
+            return { status: 'arrived', pos: currentPos };
+        }
+
+        // Check if stuck (didn't move much and stopped)
+        const moved = Math.sqrt(
+            Math.pow(currentPos.x - lastPos.x, 2) + Math.pow(currentPos.z - lastPos.z, 2)
+        );
+        if (moved < 2 && moveResult.stoppedMoving) {
+            return { status: 'stuck', pos: currentPos };
+        }
+
+        return { status: 'progress', pos: currentPos };
+    }
+
+    /**
+     * Calculate distance between two points.
+     */
+    distance(x1: number, z1: number, x2: number, z2: number): number {
+        return Math.sqrt(Math.pow(x2 - x1, 2) + Math.pow(z2 - z1, 2));
+    }
+
+    // ============ Specific Door Opening ============
+
+    /**
+     * Open a specific door at exact coordinates.
+     * Used by proactive door-opening when the pathfinder identifies doors along the route.
+     * @returns true if the door was opened (or was already open)
+     */
+    async openDoorAt(doorX: number, doorZ: number): Promise<boolean> {
+        const locs = this.sdk.getNearbyLocs();
+        const door = locs.find(l => l.x === doorX && l.z === doorZ);
+        if (!door) return false;
+
+        const openOpt = door.optionsWithIndex.find(o => /^open$/i.test(o.text));
+        if (!openOpt) return true; // Already open (has Close option instead)
+
+        // Walk to an adjacent tile using raw sendWalk to avoid recursion
+        await this.walkAdjacentTo(doorX, doorZ);
+
+        const startTick = this.sdk.getState()?.tick || 0;
+        await this.sdk.sendInteractLoc(doorX, doorZ, door.id, openOpt.opIndex);
+
+        try {
+            await this.sdk.waitForCondition(state => {
+                // Check for failure messages (locked, can't reach, etc.)
+                for (const msg of state.gameMessages) {
+                    if (msg.tick > startTick) {
+                        const text = msg.text.toLowerCase();
+                        if (text.includes("locked") || text.includes("can't reach") || text.includes("cannot reach")) {
+                            return true; // Exit early — door can't be opened
+                        }
+                    }
+                }
+                const doorNow = state.nearbyLocs.find(l =>
+                    l.x === doorX && l.z === doorZ && l.id === door.id
+                );
+                if (!doorNow) return true; // Door gone = opened
+                return !doorNow.optionsWithIndex.some(o => /^open$/i.test(o.text));
+            }, 8000);
+
+            // Verify door actually opened
+            const doorAfter = this.sdk.getState()?.nearbyLocs.find(l =>
+                l.x === doorX && l.z === doorZ && l.id === door.id
+            );
+            return !doorAfter || !doorAfter.optionsWithIndex.some(o => /^open$/i.test(o.text));
+        } catch {
+            return false;
+        }
+    }
+
+    // ============ Resolution Helpers ============
+
+    resolveLocation(
+        target: NearbyLoc | string | RegExp | undefined,
+        defaultPattern: RegExp
+    ): NearbyLoc | null {
+        if (!target) {
+            return this.sdk.findNearbyLoc(defaultPattern);
+        }
+        if (typeof target === 'object' && 'x' in target) {
+            return target;
+        }
+        return this.sdk.findNearbyLoc(target);
+    }
+
+    resolveInventoryItem(
+        target: InventoryItem | string | RegExp | undefined,
+        defaultPattern: RegExp
+    ): InventoryItem | null {
+        if (!target) {
+            return this.sdk.findInventoryItem(defaultPattern);
+        }
+        if (typeof target === 'object' && 'slot' in target) {
+            return target;
+        }
+        return this.sdk.findInventoryItem(target);
+    }
+
+    resolveGroundItem(target: GroundItem | string | RegExp): GroundItem | null {
+        if (typeof target === 'object' && 'x' in target) {
+            return target;
+        }
+        return this.sdk.findGroundItem(target);
+    }
+
+    resolveNpc(target: NearbyNpc | string | RegExp): NearbyNpc | null {
+        if (typeof target === 'object' && 'index' in target) {
+            return target;
+        }
+        return this.sdk.findNearbyNpc(target);
+    }
+
+    resolvePlayer(target: NearbyPlayer | string | RegExp): NearbyPlayer | null {
+        if (typeof target === 'object' && 'index' in target) {
+            return target;
+        }
+        return this.sdk.findNearbyPlayer(target);
+    }
+
+    resolveShopItem(
+        target: ShopItem | InventoryItem | string | RegExp,
+        items: ShopItem[]
+    ): ShopItem | null {
+        if (typeof target === 'object' && 'id' in target && 'name' in target) {
+            return items.find(i => i.id === target.id) ?? null;
+        }
+        const regex = typeof target === 'string' ? new RegExp(target, 'i') : target;
+        return items.find(i => regex.test(i.name)) ?? null;
+    }
+}