kill-switch-mcp 1.1.8 → 1.1.10

package/dist/server.js

@@ -7,7 +7,9 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 import { existsSync as existsSync3 } from "fs";
 import { readFile as readFile2 } from "fs/promises";
@@ -4109,19 +4111,16 @@ execute it by sending code to the game via execute_code.
 - bot.attackNpc("name" or /pattern/i) — attack an NPC
 - bot.walkTo(x, z) — pathfind and walk (complex, uses server pathfinding)
 
-### sdk methods (low-level, instant):
-- sdk.sendWalk(x, z) — click a tile to walk there (fast, no pathfinding)
-- sdk.getState() — full game state object
+### sdk methods (low-level):
+State (sync): sdk.getState(), sdk.getInventory(), sdk.getEquipment(), sdk.getNearbyPlayers(), sdk.getGroundItems()
+Search (sync): sdk.findInventoryItem(/pat/i), sdk.findGroundItem(/pat/i), sdk.findNearbyPlayer(/pat/i)
+Commands (async): sdk.sendWalk(x, z), sdk.sendPickup(x, z, itemId), sdk.sendInteractLoc(x, z, locId, option)
+Timing (async): await sdk.waitForTicks(n) — each tick ~0.6s
+
+Key state paths:
 - sdk.getState().player.worldX / .worldZ — your position
-- sdk.getState().player.hp — your current HP
-- sdk.getState().player.maxHp — your max HP
-- sdk.getInventory() — array of inventory items (each has .name)
-- sdk.getEquipment() — array of equipment items
-- sdk.findInventoryItem(/pattern/i) — find item in inventory
-- sdk.findGroundItem(/pattern/i) — find item on ground (returns { name, x, z, distance } — NOT .worldX!)
-- sdk.getGroundItems() — all nearby ground items (each has .name, .x, .z, .distance, .id, .count)
-- sdk.getNearbyPlayers() — nearby players (each has .name, .combatLevel, .distance, .x, .z)
-- sdk.waitForTicks(n) — wait n game ticks (~0.6s each)
+- sdk.getState().player.hp / .maxHp — your hitpoints
+- Ground items use .x / .z (NOT .worldX)
 
 ### actions (pre-built strategies, await each one):
 Actions are loaded from your bot's actions/ directory at login. Default actions:
@@ -4131,8 +4130,11 @@ Actions are loaded from your bot's actions/ directory at login. Default actions:
 
 ### IMPORTANT NOTES:
 - Blocking UI is auto-dismissed before every execute_code call — you do NOT need to call bot.dismissBlockingUI()
+- bot methods THROW on failure — use try/catch if you want to handle errors gracefully
 - bot.walkTo() uses server pathfinding (can be slow). For quick movement, use sdk.sendWalk(x, z) + sdk.waitForTicks(5)
-- State uses .player (NOT .localPlayer): sdk.getState().player.worldX (NOT state.localPlayer.x)
+- State path: sdk.getState().player.worldX / .worldZ / .hp / .maxHp (NOT .localPlayer, NOT .hitpoints)
+- Ground items use .x / .z (NOT .worldX / .worldZ): sdk.getGroundItems()[0].x
+- Players use .x / .z for nearby players, .worldX / .worldZ for your own player
 - Keep execute_code calls to 15-30 seconds, then check state and adapt
 
 ## Key Tips
@@ -4140,7 +4142,201 @@ Actions are loaded from your bot's actions/ directory at login. Default actions:
 - Grab a weapon first, then food, then armor
 - Risk vs reward: center has the best loot but everyone converges there
 - The human gives you strategy ("rush center", "play safe", "grab and run") — you turn it into code`;
-var server = new Server({ name: "kill-switch", version: "3.0.0" }, { capabilities: { tools: {} } });
+var server = new Server({ name: "kill-switch", version: "3.0.0" }, { capabilities: { tools: {}, resources: {} } });
+var SDK_REFERENCE = `# Kill Switch SDK Reference
+
+This is the DEFINITIVE API reference. Do NOT guess method names or property paths.
+If a method or property is not listed here, it does not exist.
+
+## Globals available in execute_code
+
+Three objects are available in every execute_code call:
+- \`bot\` — High-level game actions (all async, all throw on failure)
+- \`sdk\` — Low-level state access and direct commands
+- \`actions\` — Pre-built strategy functions loaded from your bot's actions/ directory
+
+---
+
+## bot methods
+
+All bot methods are async. They THROW an error if they fail — you do NOT need to check return values.
+Wrap in try/catch if you want to handle failures gracefully.
+
+### Movement
+- \`await bot.walkTo(x, z)\` — Pathfind and walk to coordinates. Uses server-side pathfinding. Can be slow and may fail if path is blocked by walls/doors.
+
+### Items
+- \`await bot.pickupItem(pattern)\` — Walk to and pick up a ground item matching the pattern. Example: \`await bot.pickupItem(/rune scimitar/i)\`
+- \`await bot.equipItem(pattern)\` — Equip an item from inventory. Example: \`await bot.equipItem(/rune scimitar/i)\`
+- \`await bot.eatFood(pattern)\` — Eat food from inventory. Example: \`await bot.eatFood(/lobster/i)\`
+
+### Combat
+- \`await bot.attackPlayer(nameOrPattern)\` — Attack a player. Example: \`await bot.attackPlayer("Arwen")\` or \`await bot.attackPlayer(/arwen/i)\`
+- \`await bot.attackNpc(nameOrPattern)\` — Attack an NPC.
+
+### NPCs & Objects
+- \`await bot.talkTo(nameOrPattern)\` — Talk to an NPC.
+- \`await bot.interactLoc(nameOrPattern, option)\` — Interact with a game object.
+- \`await bot.interactNpc(nameOrPattern, option)\` — Interact with an NPC.
+- \`await bot.openDoor(target)\` — Open a door. Pass a NearbyLoc object, string name, or RegExp. With no args, opens nearest door.
+
+### Dialog
+- \`await bot.navigateDialog(choices)\` — Navigate through NPC dialog.
+- \`await bot.waitForDialogClose()\` — Wait for dialog to close.
+
+### Other
+- \`await bot.dismissBlockingUI()\` — Dismiss modals/dialogs. NOTE: This is called automatically before every execute_code — you do NOT need to call it yourself.
+- \`await bot.waitForIdle()\` — Wait until the bot is idle (not moving/acting).
+
+---
+
+## sdk methods
+
+### State (instant, not async)
+- \`sdk.getState()\` — Returns the full game state object. See "State Object Shape" below.
+- \`sdk.getInventory()\` — Array of inventory items. Each has: \`.name\`, \`.id\`, \`.count\`, \`.slot\`
+- \`sdk.getEquipment()\` — Array of equipped items. Each has: \`.name\`, \`.id\`, \`.slot\`
+- \`sdk.getNearbyPlayers()\` — Array of nearby players. Each has: \`.index\`, \`.name\`, \`.combatLevel\`, \`.distance\`, \`.x\`, \`.z\`
+- \`sdk.getGroundItems()\` — Array of ground items. Each has: \`.name\`, \`.id\`, \`.count\`, \`.x\`, \`.z\`, \`.distance\`
+- \`sdk.getNearbyLocs()\` — Array of nearby game objects. Each has: \`.id\`, \`.name\`, \`.x\`, \`.z\`, \`.distance\`, \`.options\`
+- \`sdk.getNearbyNpcs()\` — Array of nearby NPCs. Each has: \`.index\`, \`.name\`, \`.combatLevel\`, \`.x\`, \`.z\`, \`.distance\`, \`.hp\`, \`.maxHp\`, \`.inCombat\`
+
+### Search (instant, not async)
+- \`sdk.findInventoryItem(pattern)\` — Find first matching inventory item. Returns item or null.
+- \`sdk.findGroundItem(pattern)\` — Find first matching ground item. Returns item or null.
+- \`sdk.findNearbyPlayer(pattern)\` — Find a nearby player. Returns player or null.
+- \`sdk.findNearbyNpc(pattern)\` — Find a nearby NPC. Returns NPC or null.
+- \`sdk.findNearbyLoc(pattern)\` — Find a nearby game object. Returns loc or null.
+
+### Direct Commands (async, send action to server)
+All send* methods are async and return Promise<ActionResult>. Use await or fire-and-forget.
+- \`sdk.sendWalk(x, z)\` — Click a tile to walk there. Fast, no pathfinding. Use for quick movement.
+- \`sdk.sendPickup(x, z, itemId)\` — Pick up a ground item. Args are (x, z, itemId) — NOT (itemId, x, z).
+- \`sdk.sendInteractPlayer(playerIndex, option)\` — Interact with a player. Use player.index from getNearbyPlayers().
+- \`sdk.sendInteractNpc(npcIndex, option)\` — Interact with an NPC. Use npc.index from getNearbyNpcs(). NOT npcId.
+- \`sdk.sendInteractLoc(x, z, locId, option)\` — Interact with a game object. Args are (x, z, locId, option) — NOT (locId, x, z).
+- \`sdk.sendUseItem(slot, option)\` — Use an inventory item. option defaults to 1 (first option, e.g. eat/wear).
+- \`sdk.sendSetCombatStyle(style)\` — Change combat style (0-3).
+- \`sdk.sendTogglePrayer(prayer)\` — Toggle a prayer. Accepts prayer name string (e.g. 'protect_from_melee') or prayer ID number.
+
+### Timing (async)
+- \`await sdk.waitForTicks(n)\` — Wait n game ticks. Each tick ≈ 0.6 seconds.
+- \`await sdk.waitForStateChange(timeoutMs)\` — Wait for any state update.
+- \`await sdk.waitForCondition(fn, timeoutMs)\` — Wait until fn(state) returns true.
+
+---
+
+## State Object Shape
+
+\`\`\`
+sdk.getState() returns:
+{
+  tick: number,              // Current game tick
+  player: {
+    name: string,
+    worldX: number,          // Your X coordinate
+    worldZ: number,          // Your Z coordinate
+    level: number,           // Floor level (0 = ground)
+    hp: number,              // Current hitpoints
+    maxHp: number,           // Max hitpoints
+    combatLevel: number,
+    animId: number,          // Current animation ID (-1 = idle)
+    combat: {                // Combat sub-state
+      inCombat: boolean,
+      targetIndex: number,
+    },
+  },
+  inGame: boolean,           // Whether connected to game
+  skills: [...],             // Array of skill objects
+  inventory: [...],          // Array of inventory slots
+  equipment: [...],          // Array of equipment slots
+  groundItems: [...],        // Nearby ground items (each has .name, .x, .z, .id, .count, .distance)
+  nearbyPlayers: [...],      // Nearby players (each has .index, .name, .x, .z, .distance, .combatLevel)
+  nearbyNpcs: [...],         // Nearby NPCs (each has .index, .name, .x, .z, .distance, .hp, .maxHp)
+  nearbyLocs: [...],         // Nearby game objects (each has .id, .name, .x, .z, .distance, .options)
+  dialog: { isOpen, ... },   // Dialog state
+  modalOpen: boolean,        // Whether a modal is open
+  gameMessages: [...],       // Recent game messages
+}
+\`\`\`
+
+IMPORTANT PROPERTY NAMES:
+- Player position: \`.player.worldX\`, \`.player.worldZ\` (NOT .localPlayer, NOT .x/.z)
+- Player HP: \`.player.hp\`, \`.player.maxHp\` (NOT .hitpoints, NOT .hitpointsBase)
+- Ground item position: \`.x\`, \`.z\` (NOT .worldX, NOT .worldZ)
+- Nearby player position: \`.x\`, \`.z\` (NOT .worldX, NOT .worldZ)
+
+---
+
+## Common Patterns
+
+### Quick loot (walk + pick up):
+\`\`\`
+// Option A: Use bot.pickupItem (walks to item automatically, throws on failure)
+try { await bot.pickupItem(/lobster/i); } catch(e) { console.log("Missed lobster"); }
+
+// Option B: Manual walk + raw pickup (more control)
+const item = sdk.findGroundItem(/lobster/i);
+if (item) {
+  sdk.sendWalk(item.x, item.z);              // Walk to item
+  await sdk.waitForTicks(5);                  // Wait to arrive
+  sdk.sendPickup(item.x, item.z, item.id);   // Pick up (args: x, z, itemId)
+  await sdk.waitForTicks(2);                  // Wait for server
+}
+
+// Equip from inventory
+await bot.equipItem(/scimitar/i);
+\`\`\`
+
+### Combat loop:
+\`\`\`
+const endTime = Date.now() + 15000;
+while (Date.now() < endTime) {
+  const state = sdk.getState();
+  if (state.player.hp < 30) {
+    try { await bot.eatFood(/lobster|swordfish|salmon/i); } catch(e) {}
+  }
+  const players = sdk.getNearbyPlayers();
+  if (players.length > 0) {
+    const target = players.sort((a, b) => a.distance - b.distance)[0];
+    try { await bot.attackPlayer(target.name); } catch(e) {}
+  }
+  await sdk.waitForTicks(2);
+}
+\`\`\`
+
+### Movement tip:
+For combat/arena play, use \`sdk.sendWalk(x, z)\` + \`await sdk.waitForTicks(n)\` instead of \`bot.walkTo()\`.
+\`bot.walkTo()\` uses server pathfinding which can be slow or fail on complex terrain.
+\`sdk.sendWalk()\` just clicks the tile directly — fast and reliable for short distances.
+`;
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+  return {
+    resources: [
+      {
+        uri: "killswitch://sdk-reference",
+        name: "Kill Switch SDK Reference",
+        description: "Complete API reference for bot, sdk, and actions objects used in execute_code. READ THIS FIRST before writing any game code.",
+        mimeType: "text/markdown"
+      }
+    ]
+  };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+  const { uri } = request.params;
+  if (uri === "killswitch://sdk-reference") {
+    return {
+      contents: [
+        {
+          uri: "killswitch://sdk-reference",
+          mimeType: "text/markdown",
+          text: SDK_REFERENCE
+        }
+      ]
+    };
+  }
+  throw new Error(`Unknown resource: ${uri}`);
+});
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return {
     tools: [
@@ -4165,16 +4361,17 @@ ${GAME_DESCRIPTION}`,
       },
       {
         name: "execute_code",
-        description: `Execute TypeScript code on your connected bot. The code runs in an async context with three globals:
-  - bot: High-level actions (await bot.pickupItem(/name/i), bot.equipItem(), bot.eatFood(), bot.attackPlayer(), bot.walkTo())
-  - sdk: Low-level state/commands (sdk.getState(), sdk.sendWalk(x,z), sdk.getNearbyPlayers(), sdk.getInventory(), sdk.findGroundItem())
-  - actions: Pre-built strategy functions from bot's actions/ directory (listed at login)
+        description: `Execute TypeScript code on your connected bot. Three globals available: bot, sdk, actions.
 
-State object: sdk.getState().player.worldX, .worldZ, .hp, .maxHp
-Movement: sdk.sendWalk(x, z) for quick moves, bot.walkTo(x, z) for pathfinding
-Timing: await sdk.waitForTicks(n) — each tick is ~0.6 seconds
+IMPORTANT: Read the "Kill Switch SDK Reference" resource (killswitch://sdk-reference) for the complete API.
+Do NOT guess method names or property paths — only use what is documented in the SDK reference.
 
-Blocking UI is auto-dismissed before your code runs — do NOT call bot.dismissBlockingUI().
+Quick reminders:
+- bot methods are async and THROW on failure
+- sdk.getState().player.worldX / .worldZ / .hp / .maxHp
+- Ground items use .x / .z (NOT .worldX)
+- sdk.sendWalk(x, z) for fast movement, bot.walkTo(x, z) for pathfinding
+- Blocking UI is auto-dismissed — do NOT call bot.dismissBlockingUI()
 
 You MUST call login before using this tool.`,
         inputSchema: {
@@ -4572,6 +4769,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             "",
             "After joining a game, call wait_for_game_start to wait for the game to begin."
           ];
+          parts.push("");
+          parts.push("── IMPORTANT: Read the SDK Reference ──");
+          parts.push('Before writing any execute_code, read the "Kill Switch SDK Reference" resource (killswitch://sdk-reference).');
+          parts.push("It contains the complete API for bot, sdk, and actions. Do NOT guess method names — use only what is documented.");
           if (activeActionDescriptions.length > 0) {
             parts.push("");
             parts.push("── Loaded Actions ──");
@@ -4654,14 +4855,23 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
               reject(new Error(typeof signal.reason === "string" ? signal.reason : "Code execution cancelled"));
             }, { once: true });
           });
-          const cancellable = (target) => new Proxy(target, {
+          const cancellable = (target, throwOnFailure = false) => new Proxy(target, {
             get(obj, prop, receiver) {
               const value = Reflect.get(obj, prop, receiver);
               if (typeof value === "function") {
                 return (...args2) => {
                   if (signal.aborted)
                     throw new Error("Execution cancelled");
-                  return value.apply(obj, args2);
+                  const ret = value.apply(obj, args2);
+                  if (throwOnFailure && ret && typeof ret.then === "function") {
+                    return ret.then((result2) => {
+                      if (result2 && typeof result2 === "object" && result2.success === false) {
+                        throw new Error(result2.message || `${String(prop)} failed`);
+                      }
+                      return result2;
+                    });
+                  }
+                  return ret;
                 };
               }
               return value;
@@ -4670,7 +4880,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
           await connection.bot.dismissBlockingUI();
           let result;
           try {
-            result = await Promise.race([fn(cancellable(connection.bot), cancellable(connection.sdk), activeActions), timeoutPromise, cancelPromise]);
+            result = await Promise.race([fn(cancellable(connection.bot, true), cancellable(connection.sdk), activeActions), timeoutPromise, cancelPromise]);
           } finally {
             clearTimeout(timeoutId);
             if (!signal.aborted)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kill-switch-mcp",
-  "version": "1.1.8",
+  "version": "1.1.10",
   "description": "Kill Switch MCP Server — AI battle royale powered by Claude Code",
   "type": "module",
   "bin": {