kill-switch-mcp 1.1.7 → 1.1.9

package/defaults/actions/fight-loop.ts

@@ -35,7 +35,7 @@ export default async function fightLoop(bot: any, sdk: any, opts: any = {}) {
         const state = sdk.getState();
         if (!state) { await sdk.waitForTicks(1); continue; }
 
-        const hp = state.player.hitpoints;
+        const hp = state.player.hp;
         const players = sdk.getNearbyPlayers();
 
         // Bail signal: low food + outnumbered
@@ -43,7 +43,7 @@ export default async function fightLoop(bot: any, sdk: any, opts: any = {}) {
         if (foodCount <= fleeAt && players.length > 1) {
             return {
                 hp,
-                maxHp: state.player.hitpointsBase ?? 0,
+                maxHp: state.player.maxHp ?? 0,
                 foodLeft: foodCount,
                 target: lastTarget,
                 nearbyPlayers: players,
@@ -92,8 +92,8 @@ export default async function fightLoop(bot: any, sdk: any, opts: any = {}) {
     // Return status
     const finalState = sdk.getState();
     return {
-        hp: finalState?.player?.hitpoints ?? 0,
-        maxHp: finalState?.player?.hitpointsBase ?? 0,
+        hp: finalState?.player?.hp ?? 0,
+        maxHp: finalState?.player?.maxHp ?? 0,
         foodLeft: countFood(sdk),
         target: lastTarget,
         nearbyPlayers: sdk.getNearbyPlayers(),

package/defaults/actions/kite.ts

@@ -27,7 +27,7 @@ export default async function kite(bot: any, sdk: any, opts: any = {}) {
         const state = sdk.getState();
         if (!state) { await sdk.waitForTicks(1); continue; }
 
-        const hp = state.player.hitpoints;
+        const hp = state.player.hp;
 
         // Check if we've healed enough
         if (hp >= safeHp) {
@@ -82,7 +82,7 @@ export default async function kite(bot: any, sdk: any, opts: any = {}) {
         await sdk.waitForTicks(2);
     }
 
-    const finalHp = sdk.getState()?.player?.hitpoints ?? 0;
+    const finalHp = sdk.getState()?.player?.hp ?? 0;
     return { hp: finalHp, foodLeft: countFood(sdk), escaped: finalHp >= safeHp };
 }
 

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";
@@ -4113,12 +4115,13 @@ execute it by sending code to the game via execute_code.
 - sdk.sendWalk(x, z) — click a tile to walk there (fast, no pathfinding)
 - sdk.getState() — full game state object
 - sdk.getState().player.worldX / .worldZ — your position
-- sdk.getState().player.hitpoints — your current HP
-- sdk.getState().player.hitpointsBase — your max HP
+- 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 nearby
+- 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)
 
@@ -4130,8 +4133,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
@@ -4139,7 +4145,183 @@ 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(x, z)\` — Open a door at coordinates.
+
+### 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: \`.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.
+- \`sdk.getNearbyNpcs()\` — Array of nearby NPCs.
+
+### 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 (instant, fire-and-forget)
+- \`sdk.sendWalk(x, z)\` — Click a tile to walk there. Fast, no pathfinding. Use for quick movement during combat.
+- \`sdk.sendPickup(itemId, x, z)\` — Send raw pickup command.
+- \`sdk.sendInteractPlayer(playerIndex, option)\` — Interact with a player directly.
+- \`sdk.sendInteractNpc(npcId, option)\` — Interact with an NPC directly.
+- \`sdk.sendInteractLoc(locId, x, z, option)\` — Interact with a game object directly.
+- \`sdk.sendUseItem(slot)\` — Use an inventory item (e.g., eat food).
+- \`sdk.sendSetCombatStyle(style)\` — Change combat style (0-3).
+- \`sdk.sendTogglePrayer(prayerId)\` — Toggle a prayer on/off.
+
+### 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,
+    animation: number,       // Current animation ID (-1 = idle)
+  },
+  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)
+  nearbyPlayers: [...],      // Nearby players
+  nearbyNpcs: [...],         // Nearby NPCs
+  dialog: { isOpen, ... },   // Dialog state
+  modalOpen: boolean,        // Whether a modal is open
+}
+\`\`\`
+
+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):
+\`\`\`
+sdk.sendWalk(3106, 3353);           // Click tile to walk there
+await sdk.waitForTicks(5);          // Wait to arrive
+await bot.pickupItem(/lobster/i);   // Pick up item at feet
+await bot.equipItem(/scimitar/i);   // Equip from inventory
+\`\`\`
+
+### 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: [
@@ -4164,16 +4346,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, .hitpoints, .hitpointsBase
-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: {
@@ -4571,6 +4754,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 ──");
@@ -4653,14 +4840,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;
@@ -4669,7 +4865,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)
@@ -4733,7 +4929,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
                 "",
                 `You've been teleported to Draynor Manor. The fight is ON!`,
                 `Position: ${state.player.worldX}, ${state.player.worldZ}`,
-                `HP: ${state.player.hitpoints}/${state.player.hitpointsBase}`,
+                `HP: ${state.player.hp}/${state.player.maxHp}`,
                 "",
                 `Nearby players: ${players.length > 0 ? players.map((p) => `${p.name} (CB ${p.combatLevel}, dist ${p.distance})`).join(", ") : "scanning..."}`,
                 "",
@@ -4748,7 +4944,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
                 "",
                 "API REMINDERS:",
                 "- sdk.sendWalk(x, z) for quick movement (NOT bot.walkTo for combat)",
-                "- sdk.getState().player.worldX / .worldZ / .hitpoints",
+                "- sdk.getState().player.worldX / .worldZ / .hp",
                 "- Blocking UI is auto-dismissed — do NOT call bot.dismissBlockingUI()"
               ];
               if (activeActionDescriptions.length > 0) {

package/package.json

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