fill_form_by_uid

Instructions

Implementation Reference

• src/tools/input.ts:100-127 (schema)

  Tool schema definition including inputSchema for validating the 'elements' array of {uid, value} pairs.

  export const fillFormByUidTool = {
    name: 'fill_form_by_uid',
    description: 'Fill multiple form fields at once.',
    inputSchema: {
      type: 'object',
      properties: {
        elements: {
          type: 'array',
          description: 'Array of {uid, value} pairs',
          items: {
            type: 'object',
            properties: {
              uid: {
                type: 'string',
                description: 'Field UID',
              },
              value: {
                type: 'string',
                description: 'Field value',
              },
            },
            required: ['uid', 'value'],
          },
        },
      },
      required: ['elements'],
    },
  };

• src/tools/input.ts:250-284 (handler)

  Primary MCP handler: validates input, retrieves Firefox instance, executes fillFormByUid on Firefox facade, handles UID staleness errors.

  export async function handleFillFormByUid(args: unknown): Promise<McpToolResponse> {
    try {
      const { elements } = args as { elements: Array<{ uid: string; value: string }> };
  
      if (!elements || !Array.isArray(elements) || elements.length === 0) {
        throw new Error('elements parameter is required and must be a non-empty array');
      }
  
      // Validate all elements
      for (const el of elements) {
        if (!el.uid || typeof el.uid !== 'string') {
          throw new Error(`Invalid element: uid is required and must be a string`);
        }
        if (el.value === undefined || typeof el.value !== 'string') {
          throw new Error(`Invalid element for uid "${el.uid}": value must be a string`);
        }
      }
  
      const { getFirefox } = await import('../index.js');
      const firefox = await getFirefox();
  
      try {
        await firefox.fillFormByUid(elements);
        return successResponse(`✅ filled ${elements.length} fields`);
      } catch (error) {
        const errorMsg = (error as Error).message;
        if (errorMsg.includes('stale') || errorMsg.includes('Snapshot') || errorMsg.includes('UID')) {
          throw new Error(`UIDs stale/invalid. Call take_snapshot first.`);
        }
        throw error;
      }
    } catch (error) {
      return errorResponse(error as Error);
    }
  }

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

  Registration of the fill_form_by_uid handler in the central toolHandlers Map used by the MCP server.

    ['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-181 (registration)

  Registration of fillFormByUidTool (with schema) in the allTools array returned by listTools.

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

• src/firefox/dom.ts:234-244 (helper)

  Core implementation: Iterates over elements array, resolves each UID to WebElement, calls fillByUid (clear + sendKeys) on each.

  async fillFormByUid(elements: Array<{ uid: string; value: string }>): Promise<void> {
    if (!this.resolveUid) {
      throw new Error(
        'fillFormByUid: resolveUid callback not set. Ensure snapshot is initialized.'
      );
    }
  
    for (const { uid, value } of elements) {
      await this.fillByUid(uid, value);
    }
  }