Pilot

Instructions

Implementation Reference

• src/tools/snapshot-tools.ts:21-39 (handler)

  Handler function for the 'pilot_snapshot' tool.

  async ({ selector, interactive_only, compact, depth, include_cursor_interactive, max_elements, structure_only }) => {
    await bm.ensureBrowser();
    try {
      const result = await takeSnapshot(bm, {
        selector,
        interactive: interactive_only,
        compact,
        depth,
        cursorInteractive: include_cursor_interactive,
        maxElements: max_elements,
        structureOnly: structure_only,
      });
      bm.resetFailures();
      return { content: [{ type: 'text' as const, text: result }] };
    } catch (err) {
      bm.incrementFailures();
      return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
    }
  }

• src/tools/snapshot-tools.ts:9-40 (registration)

  Registration of the 'pilot_snapshot' tool.

  server.tool(
    'pilot_snapshot',
    'Get accessibility tree snapshot with @eN refs for element selection. Use refs in click/fill/hover/etc. Use include_cursor_interactive to find non-ARIA clickable elements (@cN refs).',
    {
      selector: z.string().optional().describe('CSS selector to scope the snapshot'),
      interactive_only: z.boolean().optional().describe('Only show interactive elements (buttons, links, inputs)'),
      compact: z.boolean().optional().describe('Remove empty structural nodes'),
      depth: z.number().optional().describe('Limit tree depth (0 = root only)'),
      include_cursor_interactive: z.boolean().optional().describe('Scan for cursor:pointer/onclick/tabindex elements not in ARIA tree'),
      max_elements: z.number().optional().describe('Max elements to include before truncating (saves tokens on large pages)'),
      structure_only: z.boolean().optional().describe('Show tree structure without text content — saves tokens'),
    },
    async ({ selector, interactive_only, compact, depth, include_cursor_interactive, max_elements, structure_only }) => {
      await bm.ensureBrowser();
      try {
        const result = await takeSnapshot(bm, {
          selector,
          interactive: interactive_only,
          compact,
          depth,
          cursorInteractive: include_cursor_interactive,
          maxElements: max_elements,
          structureOnly: structure_only,
        });
        bm.resetFailures();
        return { content: [{ type: 'text' as const, text: result }] };
      } catch (err) {
        bm.incrementFailures();
        return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
      }
    }
  );