MCP-IDB

Implementation Reference

• src/index.ts:65-79 (handler)

  Handler function that takes command and options, executes the 'idb' CLI command via execFileAsync, and returns the output as text content or error message.
  async ({ command, options }) => { const args = options ? [command, ...options] : [command]; debugLog(`Executing: idb ${args.join(' ')}`); try { const { stdout, stderr } = await execFileAsync('idb', args); // Prefer STDOUT; if empty and STDERR has content, use that const output = stdout.trim() || stderr.trim(); return { content: [{ type: 'text', text: output }] }; } catch (err: any) { debugLog(`Error executing idb ${command}: ${err.message || err}`); return { content: [{ type: 'text', text: `Error: ${err.message || err}` }], }; } },
• src/index.ts:61-64 (schema)

  Input schema for the 'idb' tool using Zod, defining required 'command' string (with detailed description) and optional 'options' array.
  { command: z.string().describe(idbCommandDescription), options: z.array(z.string()).optional().describe('Optional arguments for the IDB command'), },
• src/index.ts:59-80 (registration)

  Registration of the 'idb' tool on the McpServer instance using server.tool(), specifying name, input schema, and handler function.
  server.tool( 'idb', { command: z.string().describe(idbCommandDescription), options: z.array(z.string()).optional().describe('Optional arguments for the IDB command'), }, async ({ command, options }) => { const args = options ? [command, ...options] : [command]; debugLog(`Executing: idb ${args.join(' ')}`); try { const { stdout, stderr } = await execFileAsync('idb', args); // Prefer STDOUT; if empty and STDERR has content, use that const output = stdout.trim() || stderr.trim(); return { content: [{ type: 'text', text: output }] }; } catch (err: any) { debugLog(`Error executing idb ${command}: ${err.message || err}`); return { content: [{ type: 'text', text: `Error: ${err.message || err}` }], }; } }, );
• src/index.ts:21-56 (helper)

  Detailed multi-line description string for the 'command' parameter in the schema, providing usage instructions for IDB commands.
  const idbCommandDescription = `The IDB command to execute (e.g., list-apps, screenshot, etc.). - For a full list of commands, run 'idb help'. - For help with a specific command, run 'idb <command> --help'. To interact with the device (simulator): IMPORTANT: Always try using the 'idb ui describe-all' command to identify buttons before dispatching UI actions. If that doesn't work, try using the following commands: - **Tap** - **Command:** 'idb ui tap X Y [--duration DURATION]' - **Description:** Simulates a tap at the given screen coordinates. Optionally, you can set the tap's duration. - **Swipe** - **Command:** 'idb ui swipe X_START Y_START X_END Y_END [--delta STEP_SIZE]' - **Description:** Simulates a swipe gesture from the start point to the end point. By default, the swipe moves in steps of 10 points; use '--delta' to change the step size. - **Press a Button** - **Command:** 'idb ui button {APPLE_PAY, HOME, LOCK, SIDE_BUTTON, SIRI} [--duration DURATION]' - **Description:** Simulates pressing a specified hardware button. The press duration can be adjusted with the '--duration' flag. - **Inputting Text** - **Command:** 'idb ui text "some text"' - **Description:** Types the provided text string into the target device. - **Key Events** - **Single Key:** 'idb ui key KEYCODE [--duration DURATION]' - **Key Sequence:** 'idb ui key-sequence KEYCODE1 KEYCODE2 ...' - **Description:** Simulates key press events. Use the single key command for one key press (with an optional duration) or the key sequence command for multiple sequential key events. **Frame and Coordinates in idb ui describe-all:** The output from 'idb ui describe-all' provides detailed layout information for each UI element. Each element includes a 'frame' object with: - **x and y:** The coordinates of the element's top-left corner relative to the device screen. - **width and height:** The dimensions of the element. Additionally, an 'AXFrame' string presents this data in a human-readable format like '{{x, y}, {width, height}}'. These values allow you to determine an element's position—commonly by calculating its center (x + width/2, y + height/2) for precise interactions. For instance, in the sample output, the "More, tab, 4 of 4" button has a frame starting at x=330, y=876.33 with a width of 110 and height of 45.67. A tap command such as 'idb ui tap 375 880' (which targets near the element's center) successfully triggers the button. `;
• src/index.ts:16-19 (helper)

  Debug logging utility used in the handler for logging executed commands and errors.
  function debugLog(message: string) { // Toggle debug logging as needed console.debug(`[MCP-IDB] ${message}`); }