Add browser_new_page tool for opening URLs in new tabs

[pedramamini]

Add browser_new_page Tool

Overview

This PR adds the browser_new_page tool to Browser MCP, enabling AI applications to open URLs in new browser tabs. This feature enhances multi-tab workflows and allows AI assistants to manage multiple browser contexts simultaneously.

Note: This PR includes the MCP server changes. The Chrome extension will need corresponding updates (handler for browser_new_page message), which should be coordinated with the maintainers as the extension source is not publicly available.

Changes Made

1. Added newPage Tool Implementation

File: src/tools/common.ts (lines 123-148)

• Added NewPageSchema Zod validator for URL parameter
• Implemented newPage tool factory following existing pattern
• Sends browser_new_page WebSocket message to Chrome extension
• Optionally captures ARIA snapshot of the new page (when snapshot=true)
• Returns success message: "Opened {url} in a new tab"

2. Registered Tool in Server

File: src/index.ts (line 31)

• Added common.newPage(true) to snapshotTools array
• Positioned after navigate for logical grouping of navigation tools

3. Updated Documentation

File: CLAUDE.md

• Added newPage to the list of common tools
• Documented the browser_new_page feature implementation details
• Noted Chrome extension requirements for full functionality

File: extension-changes.patch (new)

• Documents required Chrome extension changes
• Provides schema definition, handler code, and integration points
• Includes testing instructions for the extension modifications

Implementation Details

Tool Schema

const NewPageSchema = z.object({
  url: z.string().describe("The URL to open in a new tab"),
});

Tool Factory

export const newPage: ToolFactory = (snapshot) => ({
  schema: {
    name: "browser_new_page",
    description: "Open a URL in a new browser tab",
    inputSchema: zodToJsonSchema(NewPageSchema),
  },
  handle: async (context, params) => {
    const { url } = NewPageSchema.parse(params);
    await context.sendSocketMessage("browser_new_page", { url });
    if (snapshot) {
      return captureAriaSnapshot(context);
    }
    return {
      content: [
        { type: "text", text: \`Opened \${url} in a new tab\` }
      ],
    };
  },
});

Message Flow

AI Client (Claude/VS Code)
    ↓ (MCP Protocol)
MCP Server (calls newPage tool)
    ↓ (WebSocket message: "browser_new_page" with {url})
Chrome Extension
    ↓ (chrome.tabs.create API)
New Browser Tab

Backward Compatibility

This change is backward compatible:

• Tool registration doesn't affect existing tools
• If Chrome extension doesn't support browser_new_page message, WebSocket call will fail gracefully
• No breaking changes to existing API or tool schemas
• Follows established patterns from navigate, goBack, goForward

Chrome Extension Requirement

Important: This MCP server change requires corresponding Chrome extension support to function.

The extension will need to:

1. Add handler for browser_new_page WebSocket message
2. Implement: chrome.tabs.create({url}) to open new tabs
3. Register the handler in the WebSocket message listener

Extension Implementation Note: The Chrome extension source is not publicly available. The required changes have been tested in a modified version of the extension and are documented in extension-changes.patch. The patch includes:

• Schema definition for browser_new_page tool (pq2 variable)
• Message handler: browser_new_page: async({url:t}) => { await chrome.tabs.create({url:t}) }
• Registration in the discriminated union and handler object

Testing

Manual Testing (with modified extension)

1. Start MCP server with these changes
2. Load modified Chrome extension with browser_new_page handler
3. Connect extension to a browser tab
4. Use AI client to call: browser_new_page with a URL
5. Verify: New tab opens with the specified URL
6. Verify: ARIA snapshot of new page is returned

Expected Behavior

Success case:

Input: browser_new_page("https://github.com")
Output: "Opened https://github.com in a new tab" + ARIA snapshot
Result: New tab opens with GitHub homepage

Error case (extension not modified):

Input: browser_new_page("https://github.com")
Output: WebSocket timeout or "Unknown message type" error
Result: No new tab opens

Files Changed

• src/tools/common.ts - Added newPage function (+27 lines, +1 import)
• src/index.ts - Registered tool (+1 line)
• CLAUDE.md - Updated documentation
• extension-changes.patch - Chrome extension modification guide (new file)

Dependencies

• No new npm dependencies
• Uses existing Zod for schema validation
• Uses existing WebSocket communication infrastructure
• Follows existing ToolFactory pattern

Migration Notes

For Users

Once merged, users will need:

1. Updated MCP server (via npx @browsermcp/mcp@latest)
2. Updated Chrome extension (when extension changes are applied)

Until the extension changes are applied, users can use a modified extension or the feature will gracefully fail.

For Developers

The implementation mirrors the pattern used by:

• navigate(snapshot) - URL navigation with optional snapshot
• goBack(snapshot) / goForward(snapshot) - Simple actions with optional snapshot

When adding similar tools, follow this same pattern.

Questions & Answers

Q: Why not use the existing navigate tool?
A: navigate changes the current tab. browser_new_page opens a new tab, allowing multi-tab workflows.

Q: What if the extension doesn't support browser_new_page?
A: The WebSocket message will timeout or error. The tool degrades gracefully.

Q: Should this use NewPageTool from @repo/types/mcp/tool?
A: Ideally yes, but since this is a new tool, the Zod schema is defined inline. Once merged, it can be moved to the types package in a follow-up PR.

Checklist

• Implementation follows existing tool patterns
• Code is properly typed with TypeScript
• Documentation updated (CLAUDE.md)
• Tool registered in index.ts
• WebSocket message matches extension expectations
• Backward compatible (no breaking changes)
• Manual testing completed with modified extension
• Extension changes coordinated with maintainers

Author Notes

This feature has been tested with a modified Chrome extension that includes the corresponding browser_new_page handler. The extension changes are documented in extension-changes.patch for the maintainers to apply. The modification is minimal and follows the existing pattern for WebSocket message handlers in the extension.

[pedramamini]

Needed browser_new_page functionality. Hacked it into my local NPM cache and Chrome extension. Works as needed, but my friend @stephanchenette insisted I PR back to origin :-)