diff --git a/packages/playwright/src/mcp/browser/tools.ts b/packages/playwright/src/mcp/browser/tools.ts index d33da63e0d604..fe203bbdb6e74 100644 --- a/packages/playwright/src/mcp/browser/tools.ts +++ b/packages/playwright/src/mcp/browser/tools.ts @@ -20,6 +20,7 @@ import dialogs from './tools/dialogs'; import evaluate from './tools/evaluate'; import files from './tools/files'; import form from './tools/form'; +import geolocation from './tools/geolocation'; import install from './tools/install'; import keyboard from './tools/keyboard'; import mouse from './tools/mouse'; @@ -44,6 +45,7 @@ export const browserTools: Tool[] = [ ...evaluate, ...files, ...form, + ...geolocation, ...install, ...keyboard, ...navigate, diff --git a/packages/playwright/src/mcp/browser/tools/geolocation.ts b/packages/playwright/src/mcp/browser/tools/geolocation.ts new file mode 100644 index 0000000000000..1792665aa5e8c --- /dev/null +++ b/packages/playwright/src/mcp/browser/tools/geolocation.ts @@ -0,0 +1,77 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { z } from 'playwright-core/lib/mcpBundle'; +import { defineTool } from './tool'; + +const setGeolocation = defineTool({ + capability: 'geolocation', + + schema: { + name: 'browser_set_geolocation', + title: 'Set geolocation', + description: 'Set the browser geolocation to mock location-based features. This affects all pages in the browser context.', + inputSchema: z.object({ + latitude: z.number().min(-90).max(90).describe('Latitude between -90 and 90'), + longitude: z.number().min(-180).max(180).describe('Longitude between -180 and 180'), + accuracy: z.number().optional().describe('Optional accuracy in meters, defaults to 0'), + }), + type: 'action', + }, + + handle: async (context, params, response) => { + const browserContext = await context.ensureBrowserContext(); + + // Grant geolocation permission first + await browserContext.grantPermissions(['geolocation']); + + // Set the geolocation + await browserContext.setGeolocation({ + latitude: params.latitude, + longitude: params.longitude, + accuracy: params.accuracy ?? 0, + }); + + response.addCode(`await page.context().grantPermissions(['geolocation']);`); + response.addCode(`await page.context().setGeolocation({ latitude: ${params.latitude}, longitude: ${params.longitude}, accuracy: ${params.accuracy ?? 0} });`); + }, +}); + +const clearGeolocation = defineTool({ + capability: 'geolocation', + + schema: { + name: 'browser_clear_geolocation', + title: 'Clear geolocation', + description: 'Clear the mocked geolocation and restore default behavior', + inputSchema: z.object({}), + type: 'action', + }, + + handle: async (context, params, response) => { + const browserContext = await context.ensureBrowserContext(); + + // Clear the mocked geolocation while keeping the permission + await browserContext.setGeolocation(null); + + response.addCode(`await page.context().setGeolocation(null);`); + }, +}); + +export default [ + setGeolocation, + clearGeolocation, +]; diff --git a/packages/playwright/src/mcp/config.d.ts b/packages/playwright/src/mcp/config.d.ts index 98706d634c096..af32838640920 100644 --- a/packages/playwright/src/mcp/config.d.ts +++ b/packages/playwright/src/mcp/config.d.ts @@ -16,7 +16,7 @@ import type * as playwright from 'playwright-core'; -export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf' | 'testing' | 'tracing'; +export type ToolCapability = 'core' | 'core-tabs' | 'core-install' | 'vision' | 'pdf' | 'geolocation' | 'testing' | 'tracing'; export type Config = { /** @@ -104,6 +104,7 @@ export type Config = { * - 'core': Core browser automation features. * - 'pdf': PDF generation and manipulation. * - 'vision': Coordinate-based interactions. + * - 'geolocation': Browser geolocation mocking. */ capabilities?: ToolCapability[]; diff --git a/packages/playwright/src/mcp/program.ts b/packages/playwright/src/mcp/program.ts index 7495dd9af5d53..1e945cda47f97 100644 --- a/packages/playwright/src/mcp/program.ts +++ b/packages/playwright/src/mcp/program.ts @@ -32,88 +32,88 @@ import type { Command } from 'playwright-core/lib/utilsBundle'; export function decorateCommand(command: Command, version: string) { command - .option('--allowed-hosts ', 'comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass \'*\' to disable the host check.', commaSeparatedList) - .option('--allowed-origins ', 'semicolon-separated list of TRUSTED origins to allow the browser to request. Default is to allow all.\nImportant: *does not* serve as a security boundary and *does not* affect redirects. ', semicolonSeparatedList) - .option('--allow-unrestricted-file-access', 'allow access to files outside of the workspace roots. Also allows unrestricted access to file:// URLs. By default access to file system is restricted to workspace root directories (or cwd if no roots are configured) only, and navigation to file:// URLs is blocked.') - .option('--blocked-origins ', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.\nImportant: *does not* serve as a security boundary and *does not* affect redirects.', semicolonSeparatedList) - .option('--block-service-workers', 'block service workers') - .option('--browser ', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.') - .option('--caps ', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf.', commaSeparatedList) - .option('--cdp-endpoint ', 'CDP endpoint to connect to.') - .option('--cdp-header ', 'CDP headers to send with the connect request, multiple can be specified.', headerParser) - .option('--config ', 'path to the configuration file.') - .option('--console-level ', 'level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.', enumParser.bind(null, '--console-level', ['error', 'warning', 'info', 'debug'])) - .option('--device ', 'device to emulate, for example: "iPhone 15"') - .option('--executable-path ', 'path to the browser executable.') - .option('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.') - .option('--grant-permissions ', 'List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write".', commaSeparatedList) - .option('--headless', 'run browser in headless mode, headed by default') - .option('--host ', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.') - .option('--ignore-https-errors', 'ignore https errors') - .option('--init-page ', 'path to TypeScript file to evaluate on Playwright page object') - .option('--init-script ', 'path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page\'s scripts. Can be specified multiple times.') - .option('--isolated', 'keep the browser profile in memory, do not save it to disk.') - .option('--image-responses ', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".', enumParser.bind(null, '--image-responses', ['allow', 'omit'])) - .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.') - .option('--output-dir ', 'path to the directory for output files.') - .option('--port ', 'port to listen on for SSE transport.') - .option('--proxy-bypass ', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"') - .option('--proxy-server ', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"') - .option('--save-session', 'Whether to save the Playwright MCP session into the output directory.') - .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.') - .option('--save-video ', 'Whether to save the video of the session into the output directory. For example "--save-video=800x600"', resolutionParser.bind(null, '--save-video')) - .option('--secrets ', 'path to a file containing secrets in the dotenv format', dotenvFileLoader) - .option('--shared-browser-context', 'reuse the same browser context between all connected HTTP clients.') - .option('--snapshot-mode ', 'when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental.') - .option('--storage-state ', 'path to the storage state file for isolated sessions.') - .option('--test-id-attribute ', 'specify the attribute to use for test ids, defaults to "data-testid"') - .option('--timeout-action ', 'specify action timeout in milliseconds, defaults to 5000ms', numberParser) - .option('--timeout-navigation ', 'specify navigation timeout in milliseconds, defaults to 60000ms', numberParser) - .option('--user-agent ', 'specify user agent string') - .option('--user-data-dir ', 'path to the user data directory. If not specified, a temporary directory will be created.') - .option('--viewport-size ', 'specify browser viewport size in pixels, for example "1280x720"', resolutionParser.bind(null, '--viewport-size')) - .addOption(new ProgramOption('--vision', 'Legacy option, use --caps=vision instead').hideHelp()) - .action(async options => { - setupExitWatchdog(); + .option('--allowed-hosts ', 'comma-separated list of hosts this server is allowed to serve from. Defaults to the host the server is bound to. Pass \'*\' to disable the host check.', commaSeparatedList) + .option('--allowed-origins ', 'semicolon-separated list of TRUSTED origins to allow the browser to request. Default is to allow all.\nImportant: *does not* serve as a security boundary and *does not* affect redirects. ', semicolonSeparatedList) + .option('--allow-unrestricted-file-access', 'allow access to files outside of the workspace roots. Also allows unrestricted access to file:// URLs. By default access to file system is restricted to workspace root directories (or cwd if no roots are configured) only, and navigation to file:// URLs is blocked.') + .option('--blocked-origins ', 'semicolon-separated list of origins to block the browser from requesting. Blocklist is evaluated before allowlist. If used without the allowlist, requests not matching the blocklist are still allowed.\nImportant: *does not* serve as a security boundary and *does not* affect redirects.', semicolonSeparatedList) + .option('--block-service-workers', 'block service workers') + .option('--browser ', 'browser or chrome channel to use, possible values: chrome, firefox, webkit, msedge.') + .option('--caps ', 'comma-separated list of additional capabilities to enable, possible values: vision, pdf, geolocation.', commaSeparatedList) + .option('--cdp-endpoint ', 'CDP endpoint to connect to.') + .option('--cdp-header ', 'CDP headers to send with the connect request, multiple can be specified.', headerParser) + .option('--config ', 'path to the configuration file.') + .option('--console-level ', 'level of console messages to return: "error", "warning", "info", "debug". Each level includes the messages of more severe levels.', enumParser.bind(null, '--console-level', ['error', 'warning', 'info', 'debug'])) + .option('--device ', 'device to emulate, for example: "iPhone 15"') + .option('--executable-path ', 'path to the browser executable.') + .option('--extension', 'Connect to a running browser instance (Edge/Chrome only). Requires the "Playwright MCP Bridge" browser extension to be installed.') + .option('--grant-permissions ', 'List of permissions to grant to the browser context, for example "geolocation", "clipboard-read", "clipboard-write".', commaSeparatedList) + .option('--headless', 'run browser in headless mode, headed by default') + .option('--host ', 'host to bind server to. Default is localhost. Use 0.0.0.0 to bind to all interfaces.') + .option('--ignore-https-errors', 'ignore https errors') + .option('--init-page ', 'path to TypeScript file to evaluate on Playwright page object') + .option('--init-script ', 'path to JavaScript file to add as an initialization script. The script will be evaluated in every page before any of the page\'s scripts. Can be specified multiple times.') + .option('--isolated', 'keep the browser profile in memory, do not save it to disk.') + .option('--image-responses ', 'whether to send image responses to the client. Can be "allow" or "omit", Defaults to "allow".', enumParser.bind(null, '--image-responses', ['allow', 'omit'])) + .option('--no-sandbox', 'disable the sandbox for all process types that are normally sandboxed.') + .option('--output-dir ', 'path to the directory for output files.') + .option('--port ', 'port to listen on for SSE transport.') + .option('--proxy-bypass ', 'comma-separated domains to bypass proxy, for example ".com,chromium.org,.domain.com"') + .option('--proxy-server ', 'specify proxy server, for example "http://myproxy:3128" or "socks5://myproxy:8080"') + .option('--save-session', 'Whether to save the Playwright MCP session into the output directory.') + .option('--save-trace', 'Whether to save the Playwright Trace of the session into the output directory.') + .option('--save-video ', 'Whether to save the video of the session into the output directory. For example "--save-video=800x600"', resolutionParser.bind(null, '--save-video')) + .option('--secrets ', 'path to a file containing secrets in the dotenv format', dotenvFileLoader) + .option('--shared-browser-context', 'reuse the same browser context between all connected HTTP clients.') + .option('--snapshot-mode ', 'when taking snapshots for responses, specifies the mode to use. Can be "incremental", "full", or "none". Default is incremental.') + .option('--storage-state ', 'path to the storage state file for isolated sessions.') + .option('--test-id-attribute ', 'specify the attribute to use for test ids, defaults to "data-testid"') + .option('--timeout-action ', 'specify action timeout in milliseconds, defaults to 5000ms', numberParser) + .option('--timeout-navigation ', 'specify navigation timeout in milliseconds, defaults to 60000ms', numberParser) + .option('--user-agent ', 'specify user agent string') + .option('--user-data-dir ', 'path to the user data directory. If not specified, a temporary directory will be created.') + .option('--viewport-size ', 'specify browser viewport size in pixels, for example "1280x720"', resolutionParser.bind(null, '--viewport-size')) + .addOption(new ProgramOption('--vision', 'Legacy option, use --caps=vision instead').hideHelp()) + .action(async options => { + setupExitWatchdog(); - if (options.vision) { - console.error('The --vision option is deprecated, use --caps=vision instead'); - options.caps = 'vision'; - } + if (options.vision) { + console.error('The --vision option is deprecated, use --caps=vision instead'); + options.caps = 'vision'; + } - const config = await resolveCLIConfig(options); + const config = await resolveCLIConfig(options); - // Chromium browsers require ffmpeg to be installed to save video. - if (config.saveVideo && !checkFfmpeg()) { - console.error(colors.red(`\nError: ffmpeg required to save the video is not installed.`)); - console.error(`\nPlease run the command below. It will install a local copy of ffmpeg and will not change any system-wide settings.`); - console.error(`\n npx playwright install ffmpeg\n`); - // eslint-disable-next-line no-restricted-properties - process.exit(1); - } + // Chromium browsers require ffmpeg to be installed to save video. + if (config.saveVideo && !checkFfmpeg()) { + console.error(colors.red(`\nError: ffmpeg required to save the video is not installed.`)); + console.error(`\nPlease run the command below. It will install a local copy of ffmpeg and will not change any system-wide settings.`); + console.error(`\n npx playwright install ffmpeg\n`); + // eslint-disable-next-line no-restricted-properties + process.exit(1); + } - const browserContextFactory = contextFactory(config); - const extensionContextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir, config.browser.launchOptions.executablePath); + const browserContextFactory = contextFactory(config); + const extensionContextFactory = new ExtensionContextFactory(config.browser.launchOptions.channel || 'chrome', config.browser.userDataDir, config.browser.launchOptions.executablePath); - if (options.extension) { - const serverBackendFactory: mcpServer.ServerBackendFactory = { - name: 'Playwright w/ extension', - nameInConfig: 'playwright-extension', - version, - create: () => new BrowserServerBackend(config, extensionContextFactory) - }; - await mcpServer.start(serverBackendFactory, config.server); - return; - } - - const factory: mcpServer.ServerBackendFactory = { - name: 'Playwright', - nameInConfig: 'playwright', + if (options.extension) { + const serverBackendFactory: mcpServer.ServerBackendFactory = { + name: 'Playwright w/ extension', + nameInConfig: 'playwright-extension', version, - create: () => new BrowserServerBackend(config, browserContextFactory) + create: () => new BrowserServerBackend(config, extensionContextFactory) }; - await mcpServer.start(factory, config.server); - }); + await mcpServer.start(serverBackendFactory, config.server); + return; + } + + const factory: mcpServer.ServerBackendFactory = { + name: 'Playwright', + nameInConfig: 'playwright', + version, + create: () => new BrowserServerBackend(config, browserContextFactory) + }; + await mcpServer.start(factory, config.server); + }); } function checkFfmpeg(): boolean { diff --git a/tests/mcp/geolocation.spec.ts b/tests/mcp/geolocation.spec.ts new file mode 100644 index 0000000000000..5f2ed734a1953 --- /dev/null +++ b/tests/mcp/geolocation.spec.ts @@ -0,0 +1,95 @@ +/** + * Copyright (c) Microsoft Corporation. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +import { test, expect } from './fixtures'; + +test('test geolocation capability available with --caps=geolocation', async ({ startClient }) => { + const { client } = await startClient({ + args: ['--caps=geolocation'], + }); + const { tools } = await client.listTools(); + const toolNames = tools.map(t => t.name); + expect(toolNames).toContain('browser_set_geolocation'); + expect(toolNames).toContain('browser_clear_geolocation'); +}); + +test('browser_set_geolocation', async ({ startClient, server }) => { + server.setContent('/', ` + Geolocation Test +
Waiting...
+ + `, 'text/html'); + + const { client } = await startClient({ + args: ['--caps=geolocation'], + }); + + // Set geolocation to San Francisco coordinates + expect(await client.callTool({ + name: 'browser_set_geolocation', + arguments: { + latitude: 37.7749, + longitude: -122.4194, + accuracy: 100, + }, + })).toHaveResponse({ + code: expect.stringContaining(`await page.context().setGeolocation`), + }); + + // Navigate to page - geolocation will be fetched automatically + await client.callTool({ + name: 'browser_navigate', + arguments: { url: server.PREFIX }, + }); + + // Verify the mocked coordinates are returned + await expect.poll(() => client.callTool({ name: 'browser_snapshot' })).toHaveResponse({ + pageState: expect.stringContaining('Lat: 37.77'), + }); +}); + +test('browser_clear_geolocation', async ({ startClient }) => { + const { client } = await startClient({ + args: ['--caps=geolocation'], + }); + + // Set geolocation first + await client.callTool({ + name: 'browser_set_geolocation', + arguments: { + latitude: 37.7749, + longitude: -122.4194, + }, + }); + + // Clear geolocation + expect(await client.callTool({ + name: 'browser_clear_geolocation', + arguments: {}, + })).toHaveResponse({ + code: expect.stringContaining(`await page.context().setGeolocation(null)`), + }); +});