feat(mcp): add snapshotOnNavigation config to reduce token usage

packages/playwright/src/mcp/browser/config.ts

@@ -58,6 +58,7 @@ export type CLIOptions = {
   saveVideo?: ViewportSize;
   secrets?: Record<string, string>;
   sharedBrowserContext?: boolean;
+  snapshotOnNavigation?: boolean;
   storageState?: string;
   testIdAttribute?: string;
   timeoutAction?: number;
@@ -85,6 +86,7 @@ export const defaultConfig: FullConfig = {
   },
   server: {},
   saveTrace: false,
+  snapshotOnNavigation: false,
   timeouts: {
     action: 5000,
     navigation: 60000,
@@ -101,6 +103,7 @@ export type FullConfig = Config & {
   },
   network: NonNullable<Config['network']>,
   saveTrace: boolean;
+  snapshotOnNavigation: boolean;
   server: NonNullable<Config['server']>,
   timeouts: {
     action: number;
@@ -235,6 +238,7 @@ export function configFromCLIOptions(cliOptions: CLIOptions): Config {
     saveVideo: cliOptions.saveVideo,
     secrets: cliOptions.secrets,
     sharedBrowserContext: cliOptions.sharedBrowserContext,
+    snapshotOnNavigation: cliOptions.snapshotOnNavigation,
     outputDir: cliOptions.outputDir,
     imageResponses: cliOptions.imageResponses,
     testIdAttribute: cliOptions.testIdAttribute,
@@ -278,6 +282,7 @@ function configFromEnv(): Config {
   options.saveTrace = envToBoolean(process.env.PLAYWRIGHT_MCP_SAVE_TRACE);
   options.saveVideo = resolutionParser('--save-video', process.env.PLAYWRIGHT_MCP_SAVE_VIDEO);
   options.secrets = dotenvFileLoader(process.env.PLAYWRIGHT_MCP_SECRETS_FILE);
+  options.snapshotOnNavigation = envToBoolean(process.env.PLAYWRIGHT_MCP_SNAPSHOT_ON_NAVIGATION);
   options.storageState = envToString(process.env.PLAYWRIGHT_MCP_STORAGE_STATE);
   options.testIdAttribute = envToString(process.env.PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE);
   options.timeoutAction = numberParser(process.env.PLAYWRIGHT_MCP_TIMEOUT_ACTION);

packages/playwright/src/mcp/browser/tools/navigate.ts

@@ -26,6 +26,7 @@ const navigate = defineTool({
     description: 'Navigate to a URL',
     inputSchema: z.object({
       url: z.string().describe('The URL to navigate to'),
+      snapshot: z.boolean().optional().describe('Whether to include a page snapshot (DOM structure, console messages, etc.) in the response. If not specified, uses the configured default (PLAYWRIGHT_MCP_SNAPSHOT_ON_NAVIGATION). Setting to true increases token usage but provides more context about the page state.'),
     }),
     type: 'action',
   },
@@ -34,7 +35,9 @@ const navigate = defineTool({
     const tab = await context.ensureTab();
     await tab.navigate(params.url);
 
-    response.setIncludeSnapshot();
+    const includeSnapshot = params.snapshot ?? context.config.snapshotOnNavigation ?? false;
+    if (includeSnapshot)
+      response.setIncludeSnapshot();
     response.addCode(`await page.goto('${params.url}');`);
   },
 });
@@ -45,13 +48,17 @@ const goBack = defineTabTool({
     name: 'browser_navigate_back',
     title: 'Go back',
     description: 'Go back to the previous page',
-    inputSchema: z.object({}),
+    inputSchema: z.object({
+      snapshot: z.boolean().optional().describe('Whether to include a page snapshot (DOM structure, console messages, etc.) in the response. If not specified, uses the configured default (PLAYWRIGHT_MCP_SNAPSHOT_ON_NAVIGATION). Setting to true increases token usage but provides more context about the page state.'),
+    }),
     type: 'action',
   },
 
   handle: async (tab, params, response) => {
     await tab.page.goBack();
-    response.setIncludeSnapshot();
+    const includeSnapshot = params.snapshot ?? tab.context.config.snapshotOnNavigation ?? false;
+    if (includeSnapshot)
+      response.setIncludeSnapshot();
     response.addCode(`await page.goBack();`);
   },
 });

packages/playwright/src/mcp/config.d.ts

@@ -170,5 +170,13 @@ export type Config = {
    * Whether to send image responses to the client. Can be "allow", "omit", or "auto". Defaults to "auto", which sends images if the client can display them.
    */
   imageResponses?: 'allow' | 'omit';
+
+  /**
+   * Whether to include page snapshots (DOM structure, console messages, etc.) after navigation actions.
+   * Disabling this reduces token usage significantly but provides less context about the page state.
+   * Defaults to false to minimize token consumption.
+   * Can be overridden per navigation action using the 'snapshot' parameter.
+   */
+  snapshotOnNavigation?: boolean;
 };