pilot_select_option

Instructions

Implementation Reference

• src/tools/interaction.ts:180-221 (handler)

  The main handler for the 'pilot_select_option' tool. Registered via server.tool() inside registerInteractionTools(). It takes a 'ref' (select element) and 'value' (option value/label/text), supports both extension and Playwright modes, resolves the ref, and calls selectOption(). On success returns a confirmation with snapshot; on failure returns an error message.

    server.tool(
      'pilot_select_option',
      `Select an option from a <select> dropdown element by value, label, or visible text.
  Use when the user wants to choose a dropdown option, select from a combobox, or pick from a list. Note: clicking an <option> in pilot_snapshot is auto-routed here.
  
  Parameters:
  - ref: The <select> element reference from snapshot (e.g., "@e5") or a CSS selector
  - value: The option's value attribute, label, or visible text to match
  
  Returns: Confirmation with the selected value and element ref.
  
  Errors:
  - "No option matched": The value does not match any option. Check the exact option text or value attribute via pilot_page_html.
  - "Element not found": The ref is stale or does not point to a <select> element. Run pilot_snapshot.`,
        {
        ref: z.string().describe('Select element ref (@e3) or CSS selector'),
        value: z.string().describe('Option value, label, or text to select'),
      },
      async ({ ref, value }) => {
        await bm.ensureBrowser();
        try {
          const ext = bm.getExtension();
          if (ext) {
            const res = await ext.send<{ selected: string; value: string }>('select_option', { ref, label: value });
            bm.resetFailures();
            return { content: [{ type: 'text' as const, text: `Selected "${res.selected}" in ${ref}` }] };
          }
          const resolved = await bm.resolveRef(ref);
          if ('locator' in resolved) {
            await resolved.locator.selectOption(value, { timeout: 5000 });
          } else {
            await bm.getPage().selectOption(resolved.selector, value, { timeout: 5000 });
          }
          bm.resetFailures();
          const snap = await postActionSnapshot(bm);
          return { content: [{ type: 'text' as const, text: `Selected "${value}" in ${ref}${snap}` }] };
        } catch (err) {
          bm.incrementFailures();
          return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
        }
      }
    );

• src/tools/interaction.ts:194-197 (schema)

  Zod input schema for pilot_select_option. Validates two parameters: 'ref' (string, element ref or CSS selector) and 'value' (string, option value/label/text to select).

    {
    ref: z.string().describe('Select element ref (@e3) or CSS selector'),
    value: z.string().describe('Option value, label, or text to select'),
  },

• src/tools/register.ts:73-87 (registration)

  Registration entry point: registerAllTools() calls registerInteractionTools() which registers the pilot_select_option tool. Also listed in the STANDARD_TOOLS set (line 41) for profile-based filtering.

  export function registerAllTools(server: McpServer, bm: BrowserManager, profile: ToolProfile = 'full'): void {
    const allowed = PROFILE_TOOLS[profile];
    const effectiveServer = allowed ? createFilteredServer(server, allowed) : server;
  
    registerNavigationTools(effectiveServer, bm);
    registerSnapshotTools(effectiveServer, bm);
    registerInteractionTools(effectiveServer, bm);
    registerPageTools(effectiveServer, bm);
    registerInspectionTools(effectiveServer, bm);
    registerVisualTools(effectiveServer, bm);
    registerTabTools(effectiveServer, bm);
    registerSettingsTools(effectiveServer, bm);
    registerIframeTools(effectiveServer, bm);
    registerAutomationTools(effectiveServer, bm);
  }

• src/tools/register.ts:41-41 (registration)

  'pilot_select_option' is listed in the STANDARD_TOOLS set (line 41), meaning it's included in the 'standard' tool profile but not in the 'core' profile.

  'pilot_hover', 'pilot_select_option', 'pilot_scroll', 'pilot_drag',

• src/tools/interaction.ts:9-17 (helper)

  The postActionSnapshot helper function used by pilot_select_option to capture a lightweight interactive snapshot after selecting an option.

  /** After an action, take a lightweight snapshot so the LLM doesn't need a separate call */
  async function postActionSnapshot(bm: BrowserManager): Promise<string> {
    try {
      const snap = await takeSnapshot(bm, { interactive: true, maxElements: 20, lean: true });
      return '\n--- page state (interactive, top 20) ---\n' + snap;
    } catch {
      return '';
    }
  }