pilot_file_upload

Instructions

Implementation Reference

• src/tools/interaction.ts:451-495 (handler)

  The full implementation of the 'pilot_file_upload' tool. Defined via server.tool(), it accepts a ref (element reference or CSS selector) and an array of file paths. It validates that files exist on disk, resolves the element via BrowserManager, uses Playwright's setInputFiles to upload, and returns a confirmation with file names and sizes. On error, it returns an isError response.

    server.tool(
      'pilot_file_upload',
      `Upload one or more files to a file input element on the page.
  Use when the user wants to attach files, upload images, or submit documents through a file input field.
  
  Parameters:
  - ref: The file input element reference from snapshot (e.g., "@e8") or a CSS selector pointing to an <input type="file">
  - paths: Array of absolute file paths to upload (e.g., ["/home/user/photo.png", "/home/user/doc.pdf"])
  
  Returns: Confirmation with file names and sizes uploaded.
  
  Errors:
  - "File not found": One or more paths do not exist on the filesystem. Verify the file paths.
  - "Element not found": The ref is stale or does not point to a file input. Run pilot_snapshot.
  - "Not a file input": The element is not an <input type="file">.`,
        {
        ref: z.string().describe('File input element ref or CSS selector'),
        paths: z.array(z.string()).describe('File paths to upload'),
      },
      async ({ ref, paths }) => {
        await bm.ensureBrowser();
        try {
          const resolvedPaths = paths.map(fp => {
            if (!fs.existsSync(fp)) throw new Error(`File not found: ${fp}`);
            return fs.realpathSync(fp);
          });
          const page = bm.getPage();
          const resolved = await bm.resolveRef(ref);
          if ('locator' in resolved) {
            await resolved.locator.setInputFiles(resolvedPaths);
          } else {
            await page.locator(resolved.selector).setInputFiles(resolvedPaths);
          }
          const fileInfo = resolvedPaths.map(fp => {
            const stat = fs.statSync(fp);
            return `${path.basename(fp)} (${stat.size}B)`;
          }).join(', ');
          bm.resetFailures();
          return { content: [{ type: 'text' as const, text: `Uploaded: ${fileInfo}` }] };
        } catch (err) {
          bm.incrementFailures();
          return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
        }
      }
    );

• src/tools/interaction.ts:466-469 (schema)

  Zod schema for pilot_file_upload inputs: 'ref' (string) and 'paths' (array of strings).

    {
    ref: z.string().describe('File input element ref or CSS selector'),
    paths: z.array(z.string()).describe('File paths to upload'),
  },

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

  registerAllTools in register.ts calls registerInteractionTools (which registers pilot_file_upload). Note that 'pilot_file_upload' is NOT in the core or standard tool sets, so it is only available in the 'full' profile.

  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);
  }