firefox-devtools-mcp

Instructions

Implementation Reference

• src/tools/input.ts:193-217 (handler)

  MCP tool handler: validates uid/value args, gets Firefox instance via getFirefox(), calls firefox.fillByUid(uid, value), returns success/error response with UID error handling.

  export async function handleFillByUid(args: unknown): Promise<McpToolResponse> {
    try {
      const { uid, value } = args as { uid: string; value: string };
  
      if (!uid || typeof uid !== 'string') {
        throw new Error('uid parameter is required and must be a string');
      }
  
      if (value === undefined || typeof value !== 'string') {
        throw new Error('value parameter is required and must be a string');
      }
  
      const { getFirefox } = await import('../index.js');
      const firefox = await getFirefox();
  
      try {
        await firefox.fillByUid(uid, value);
        return successResponse(`✅ fill ${uid}`);
      } catch (error) {
        throw handleUidError(error as Error, uid);
      }
    } catch (error) {
      return errorResponse(error as Error);
    }
  }

• src/tools/input.ts:62-79 (schema)

  Tool schema definition: specifies name 'fill_by_uid', description, and inputSchema requiring uid (string) and value (string).

  export const fillByUidTool = {
    name: 'fill_by_uid',
    description: 'Fill text input/textarea by UID.',
    inputSchema: {
      type: 'object',
      properties: {
        uid: {
          type: 'string',
          description: 'Input element UID from snapshot',
        },
        value: {
          type: 'string',
          description: 'Text to fill',
        },
      },
      required: ['uid', 'value'],
    },
  };

• src/index.ts:131-147 (registration)

  Registration of fill_by_uid handler in the central toolHandlers Map, mapping 'fill_by_uid' to tools.handleFillByUid.

    ['click_by_uid', tools.handleClickByUid],
    ['hover_by_uid', tools.handleHoverByUid],
    ['fill_by_uid', tools.handleFillByUid],
    ['drag_by_uid_to_uid', tools.handleDragByUidToUid],
    ['fill_form_by_uid', tools.handleFillFormByUid],
    ['upload_file_by_uid', tools.handleUploadFileByUid],
  
    // Screenshot
    ['screenshot_page', tools.handleScreenshotPage],
    ['screenshot_by_uid', tools.handleScreenshotByUid],
  
    // Utilities
    ['accept_dialog', tools.handleAcceptDialog],
    ['dismiss_dialog', tools.handleDismissDialog],
    ['navigate_history', tools.handleNavigateHistory],
    ['set_viewport_size', tools.handleSetViewportSize],
  ]);

• src/index.ts:175-180 (registration)

  Registration of fillByUidTool in the allTools array for listTools response.

  tools.clickByUidTool,
  tools.hoverByUidTool,
  tools.fillByUidTool,
  tools.dragByUidToUidTool,
  tools.fillFormByUidTool,
  tools.uploadFileByUidTool,

• src/firefox/dom.ts:166-183 (helper)

  Core implementation: Resolves UID to WebElement using snapshot resolveUid callback, clears the input field, sends the value via sendKeys, waits for events.

  async fillByUid(uid: string, value: string): Promise<void> {
    if (!this.resolveUid) {
      throw new Error('fillByUid: resolveUid callback not set. Ensure snapshot is initialized.');
    }
    const el = await this.resolveUid(uid);
  
    try {
      await el.clear();
    } catch {
      // Some inputs may not support clear(); fall back to select-all + delete
      await el.sendKeys(Key.chord(Key.CONTROL, 'a'), Key.DELETE);
    }
  
    await el.sendKeys(value);
  
    // Wait for events to propagate
    await this.waitForEventsAfterAction();
  }