fill_form

Instructions

Implementation Reference

• src/tools/input.ts:212-224 (handler)

  The handler function for the fill_form tool, which fills multiple form elements by calling fillFormElement for each.

  handler: async (request, response, context) => {
    for (const element of request.params.elements) {
      await context.waitForEventsAfterAction(async () => {
        await fillFormElement(
          element.uid,
          element.value,
          context as McpContext,
        );
      });
    }
    response.appendResponseLine(`Successfully filled out the form`);
    response.setIncludeSnapshot(true);
  },

• src/tools/input.ts:202-211 (schema)

  Zod schema defining the input parameters for fill_form: an array of {uid, value} objects.

  schema: {
    elements: z
      .array(
        z.object({
          uid: z.string().describe('The uid of the element to fill out'),
          value: z.string().describe('Value for the element'),
        }),
      )
      .describe('Elements from snapshot to fill out.'),
  },

• src/tools/input.ts:195-225 (registration)

  Registration of the fill_form tool using defineTool, including name, description, annotations, schema, and handler.

  export const fillForm = defineTool({
    name: 'fill_form',
    description: `Fill out multiple form elements at once`,
    annotations: {
      category: ToolCategories.INPUT_AUTOMATION,
      readOnlyHint: false,
    },
    schema: {
      elements: z
        .array(
          z.object({
            uid: z.string().describe('The uid of the element to fill out'),
            value: z.string().describe('Value for the element'),
          }),
        )
        .describe('Elements from snapshot to fill out.'),
    },
    handler: async (request, response, context) => {
      for (const element of request.params.elements) {
        await context.waitForEventsAfterAction(async () => {
          await fillFormElement(
            element.uid,
            element.value,
            context as McpContext,
          );
        });
      }
      response.appendResponseLine(`Successfully filled out the form`);
      response.setIncludeSnapshot(true);
    },
  });

• src/tools/input.ts:120-136 (helper)

  Helper function that fills a single form element, handling comboboxes specially by selecting options.

  async function fillFormElement(
    uid: string,
    value: string,
    context: McpContext,
  ) {
    const handle = await context.getElementByUid(uid);
    try {
      const aXNode = context.getAXNodeByUid(uid);
      if (aXNode && aXNode.role === 'combobox') {
        await selectOption(handle, aXNode, value);
      } else {
        await handle.asLocator().fill(value);
      }
    } finally {
      void handle.dispose();
    }
  }

• src/tools/input.ts:87-118 (helper)

  Helper function to select an option in a combobox by matching text and using the real value.

  async function selectOption(
    handle: ElementHandle,
    aXNode: TextSnapshotNode,
    value: string,
  ) {
    let optionFound = false;
    for (const child of aXNode.children) {
      if (child.role === 'option' && child.name === value && child.value) {
        optionFound = true;
        const childHandle = await child.elementHandle();
        if (childHandle) {
          try {
            const childValueHandle = await childHandle.getProperty('value');
            try {
              const childValue = await childValueHandle.jsonValue();
              if (childValue) {
                await handle.asLocator().fill(childValue.toString());
              }
            } finally {
              void childValueHandle.dispose();
            }
            break;
          } finally {
            void childHandle.dispose();
          }
        }
      }
    }
    if (!optionFound) {
      throw new Error(`Could not find option with text "${value}"`);
    }
  }