pilot_set_useragent

Instructions

Implementation Reference

• src/tools/settings.ts:187-213 (registration)

  Registration of the 'pilot_set_useragent' tool on the MCP server with description and Zod schema for useragent parameter.

    server.tool(
      'pilot_set_useragent',
      `Set a custom browser User-Agent string, which recreates the browser context to apply the change while preserving cookies and page state.
  Use when the user wants to simulate a different browser or device, bypass bot detection, test mobile user agents, or debug User-Agent-dependent behavior. Note: this recreates the browser context, which may briefly interrupt in-progress requests.
  
  Parameters:
  - useragent: The full User-Agent string (e.g., "Mozilla/5.0 (iPhone; CPU iPhone OS 16_0 like Mac OS X) AppleWebKit/605.1.15")
  
  Returns: Confirmation with the new User-Agent string.
  
  Errors:
  - Context recreation warnings: If cookies or state could not be fully preserved during context recreation, a warning is included.`,
        { useragent: z.string().describe('User agent string') },
      async ({ useragent }) => {
        await bm.ensureBrowser();
        try {
          bm.setUserAgent(useragent);
          const error = await bm.recreateContext();
          if (error) {
            return { content: [{ type: 'text' as const, text: `User agent set to "${useragent}" but: ${error}` }] };
          }
          return { content: [{ type: 'text' as const, text: `User agent set: ${useragent}` }] };
        } catch (err) {
          return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
        }
      }
    );

• src/tools/settings.ts:200-213 (handler)

  Handler function for pilot_set_useragent that calls bm.setUserAgent(useragent), then bm.recreateContext(), and returns confirmation or error.

    async ({ useragent }) => {
      await bm.ensureBrowser();
      try {
        bm.setUserAgent(useragent);
        const error = await bm.recreateContext();
        if (error) {
          return { content: [{ type: 'text' as const, text: `User agent set to "${useragent}" but: ${error}` }] };
        }
        return { content: [{ type: 'text' as const, text: `User agent set: ${useragent}` }] };
      } catch (err) {
        return { content: [{ type: 'text' as const, text: wrapError(err) }], isError: true };
      }
    }
  );

• src/tools/settings.ts:199-199 (schema)

  Zod schema defining useragent parameter as a required string.

  { useragent: z.string().describe('User agent string') },

• src/browser-manager.ts:415-417 (helper)

  BrowserManager.setUserAgent() stores the custom user agent string.

  setUserAgent(ua: string) {
    this.customUserAgent = ua;
  }

• src/browser-manager.ts:535-575 (helper)

  BrowserManager.recreateContext() saves state, closes old context, creates new context with customUserAgent, restores state.

  async recreateContext(): Promise<string | null> {
    if (!this.browser || !this.context) throw new Error('Browser not launched');
  
    try {
      const state = await this.saveState();
      for (const page of this.pages.values()) {
        await page.close().catch(() => {});
      }
      this.pages.clear();
      await this.context.close().catch(() => {});
  
      const contextOptions: BrowserContextOptions = {
        viewport: { width: 1280, height: 720 },
      };
      if (this.customUserAgent) {
        contextOptions.userAgent = this.customUserAgent;
      }
      this.context = await this.browser.newContext(contextOptions);
      if (Object.keys(this.extraHeaders).length > 0) {
        await this.context.setExtraHTTPHeaders(this.extraHeaders);
      }
      await this.restoreState(state);
      await this.applyRoutesFromConfig();
      return null;
    } catch (err: unknown) {
      try {
        this.pages.clear();
        if (this.context) await this.context.close().catch(() => {});
        const contextOptions: BrowserContextOptions = {
          viewport: { width: 1280, height: 720 },
        };
        if (this.customUserAgent) {
          contextOptions.userAgent = this.customUserAgent;
        }
        this.context = await this.browser!.newContext(contextOptions);
        await this.newTab();
        this.clearRefs();
      } catch {}
      return `Context recreation failed: ${err instanceof Error ? err.message : String(err)}. Browser reset to blank tab.`;
    }
  }