firefox-devtools-mcp

Instructions

Implementation Reference

• src/tools/pages.ts:122-139 (handler)

  Main handler function for the 'new_page' MCP tool. Parses arguments, validates URL input, initializes Firefox instance if needed, calls firefox.createNewPage(url), and returns a formatted success response or error.

  export async function handleNewPage(args: unknown): Promise<McpToolResponse> {
    try {
      const { url } = args as { url: string };
  
      if (!url || typeof url !== 'string') {
        throw new Error('url parameter is required and must be a string');
      }
  
      const { getFirefox } = await import('../index.js');
      const firefox = await getFirefox();
  
      const newIdx = await firefox.createNewPage(url);
  
      return successResponse(`✅ new page [${newIdx}] → ${url}`);
    } catch (error) {
      return errorResponse(error as Error);
    }
  }

• src/tools/pages.ts:18-31 (schema)

  Tool schema definition for 'new_page', including name, description, and inputSchema requiring a 'url' string parameter.

  export const newPageTool = {
    name: 'new_page',
    description: 'Open new tab at URL. Returns tab index.',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'Target URL',
        },
      },
      required: ['url'],
    },
  };

• src/index.ts:107-112 (registration)

  Registration of 'new_page' handler in the central toolHandlers Map used by the MCP server to dispatch tool calls.

  // Pages
  ['list_pages', tools.handleListPages],
  ['new_page', tools.handleNewPage],
  ['navigate_page', tools.handleNavigatePage],
  ['select_page', tools.handleSelectPage],
  ['close_page', tools.handleClosePage],

• src/index.ts:152-156 (registration)

  Registration of 'new_page' schema in the allTools array returned by listTools MCP request.

  tools.listPagesTool,
  tools.newPageTool,
  tools.navigatePageTool,
  tools.selectPageTool,
  tools.closePageTool,

• src/firefox/pages.ts:156-164 (helper)

  Core implementation of createNewPage using WebDriver BiDi: opens new tab, switches to it, navigates to URL, updates cache, returns new tab index. Called by the tool handler via FirefoxDevTools facade.

  async createNewPage(url: string): Promise<number> {
    await this.driver.switchTo().newWindow('tab');
    const handles = await this.driver.getAllWindowHandles();
    const newIdx = handles.length - 1;
    this.setCurrentContextId(handles[newIdx]!);
    this.cachedSelectedIdx = newIdx;
    await this.driver.get(url);
    return newIdx;
  }