feat: add background parameter to new_page tool (#837)

## Summary

- Add `background` boolean parameter to the `new_page` tool
- When set to `true`, the new page opens in the background without
bringing it to the front
- Uses Puppeteer's existing `background` option for `browser.newPage()`

Fixes #826

---------

Co-authored-by: Alex Rudenko <OrKoN@users.noreply.github.com>
Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>

Author: domdomegg

docs/tool-reference.md

@@ -170,6 +170,7 @@
 **Parameters:**
 
 - **url** (string) **(required)**: URL to load in a new page.
+- **background** (boolean) _(optional)_: Whether to open the page in the background without bringing it to the front. Default is false (foreground).
 - **timeout** (integer) _(optional)_: Maximum wait time in milliseconds. If set to 0, the default timeout will be used.
 
 ---

src/McpContext.ts

@@ -265,8 +265,8 @@ export class McpContext implements Context {
     return this.#consoleCollector.getById(this.getSelectedPage(), id);
   }
 
-  async newPage(): Promise<Page> {
-    const page = await this.browser.newPage();
+  async newPage(background?: boolean): Promise<Page> {
+    const page = await this.browser.newPage({background});
     await this.createPagesSnapshot();
     this.selectPage(page);
     this.#networkCollector.addPage(page);

src/tools/ToolDefinition.ts

@@ -110,7 +110,7 @@ export type Context = Readonly<{
   getPageById(pageId: number): Page;
   getPageId(page: Page): number | undefined;
   isPageSelected(page: Page): boolean;
-  newPage(): Promise<Page>;
+  newPage(background?: boolean): Promise<Page>;
   closePage(pageId: number): Promise<void>;
   selectPage(page: Page): void;
   getElementByUid(uid: string): Promise<ElementHandle<Element>>;

src/tools/pages.ts

@@ -87,10 +87,16 @@ export const newPage = defineTool({
   },
   schema: {
     url: zod.string().describe('URL to load in a new page.'),
+    background: zod
+      .boolean()
+      .optional()
+      .describe(
+        'Whether to open the page in the background without bringing it to the front. Default is false (foreground).',
+      ),
     ...timeoutSchema,
   },
   handler: async (request, response, context) => {
-    const page = await context.newPage();
+    const page = await context.newPage(request.params.background);
 
     await context.waitForEventsAfterAction(async () => {
       await page.goto(request.params.url, {

tests/tools/pages.test.ts

@@ -43,6 +43,30 @@ describe('pages', () => {
         assert.ok(response.includePages);
       });
     });
+    it('create a page in the background', async () => {
+      await withMcpContext(async (response, context) => {
+        const originalPage = context.getPageById(1);
+        assert.strictEqual(originalPage, context.getSelectedPage());
+        // Ensure original page has focus
+        await originalPage.bringToFront();
+        assert.strictEqual(
+          await originalPage.evaluate(() => document.hasFocus()),
+          true,
+        );
+        await newPage.handler(
+          {params: {url: 'about:blank', background: true}},
+          response,
+          context,
+        );
+        // New page should be selected but original should retain focus
+        assert.strictEqual(context.getPageById(2), context.getSelectedPage());
+        assert.strictEqual(
+          await originalPage.evaluate(() => document.hasFocus()),
+          true,
+        );
+        assert.ok(response.includePages);
+      });
+    });
   });
   describe('close_page', () => {
     it('closes a page', async () => {