@tontoko/fast-playwright-mcp 0.0.8 → 0.1.0

package/README.md

@@ -1,4 +1,7 @@
-## Playwright MCP
+## **Fast** Playwright MCP
+
+This MCP server is a fork of the Microsoft one.
+<https://github.com/microsoft/playwright-mcp>
 
 A Model Context Protocol (MCP) server that provides browser automation capabilities using [Playwright](https://playwright.dev). This server enables LLMs to interact with web pages through structured accessibility snapshots, bypassing the need for screenshots or visually-tuned models.
 
@@ -15,10 +18,6 @@ A Model Context Protocol (MCP) server that provides browser automation capabilit
   - `includeSnapshot: false` - Skip page snapshot for minimal responses (70-80% token reduction)
   - `includeConsole: false` - Exclude console messages
   - `includeTabs: false` - Hide tab information
-- **Ultra-Compact Tool Descriptions**. One-line tool descriptions with full parameter details:
-  - 70-80% reduction in tool description tokens
-  - All expectation parameters inline without formatting overhead
-  - Smart tips for efficient usage (e.g., "Use selector to focus on specific area")
 - **Image Compression**. Screenshot tool supports `imageOptions`:
   - `format: 'jpeg'` - Use JPEG instead of PNG
   - `quality: 1-100` - Compress images (e.g., 50 for 50% quality)
@@ -133,6 +132,29 @@ Go to `Advanced settings` -> `Extensions` -> `Add custom extension`. Name to you
 Go to `Program` in the right sidebar -> `Install` -> `Edit mcp.json`. Use the standard config above.
 </details>
 
+<details>
+<summary>opencode</summary>
+
+Follow the MCP Servers [documentation](https://opencode.ai/docs/mcp-servers/). For example in `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": [
+        "npx",
+        "@tontoko/fast-playwright-mcp"
+      ],
+      "enabled": true
+    }
+  }
+}
+
+```
+</details>
+
 <details>
 <summary>Qodo Gen</summary>
 
@@ -191,6 +213,9 @@ Playwright MCP server supports following arguments. They can be provided in the
   --config <path>              path to the configuration file.
   --device <device>            device to emulate, for example: "iPhone 15"
   --executable-path <path>     path to the browser executable.
+  --extension                  Connect to a running browser instance
+                               (Edge/Chrome only). Requires the "Playwright MCP
+                               Bridge" browser extension to be installed.
   --headless                   run browser in headless mode, headed by default
   --host <host>                host to bind server to. Default is localhost. Use
                                0.0.0.0 to bind to all interfaces.
@@ -224,7 +249,7 @@ Playwright MCP server supports following arguments. They can be provided in the
 
 ### User profile
 
-You can run Playwright MCP with persistent profile like a regular browser (default), or in the isolated contexts for the testing sessions.
+You can run Playwright MCP with persistent profile like a regular browser (default), in isolated contexts for testing sessions, or connect to your existing browser using the browser extension.
 
 **Persistent profile**
 
@@ -264,6 +289,10 @@ state [here](https://playwright.dev/docs/auth).
 }
 ```
 
+**Browser Extension**
+
+The Playwright MCP Chrome Extension allows you to connect to existing browser tabs and leverage your logged-in sessions and browser state. See [extension/README.md](extension/README.md) for installation and setup instructions.
+
 ### Configuration file
 
 The Playwright MCP server can be configured using a JSON configuration file. You can specify the configuration file
@@ -581,8 +610,14 @@ http.createServer(async (req, res) => {
 
 - **browser_network_requests**
   - Title: List network requests
-  - Description: Returns all network requests since loading the page
-  - Parameters: None
+  - Description: Returns network requests since loading the page with optional filtering. urlPatterns:["api/users"] to filter by URL patterns. excludeUrlPatterns:["analytics"] to exclude specific patterns. statusRanges:[{min:200,max:299}] for success codes only. methods:["GET","POST"] to filter by HTTP method. maxRequests:10 to limit results. newestFirst:false for chronological order. Supports regex patterns for advanced filtering.
+  - Parameters:
+    - `urlPatterns` (array, optional): URL patterns to include (supports regex)
+    - `excludeUrlPatterns` (array, optional): URL patterns to exclude (supports regex)
+    - `statusRanges` (array, optional): Status code ranges to include
+    - `methods` (array, optional): HTTP methods to filter by
+    - `maxRequests` (number, optional): Maximum number of results to return (default: 20)
+    - `newestFirst` (boolean, optional): Sort order - true for newest first (default: true)
   - Read-only: **true**
 
 <!-- NOTE: This has been generated via update-readme.js -->
@@ -792,19 +827,27 @@ All browser tools support an optional `expectation` parameter that controls what
 
 #### Basic Usage
 
-```javascript
+```json
 // Standard call - includes all information (snapshot, console, tabs, etc.)
-await browser_navigate({ url: 'https://example.com' });
+{
+  "name": "browser_navigate",
+  "arguments": {
+    "url": "https://example.com"
+  }
+}
 
 // Optimized call - only includes essential information
-await browser_navigate({ 
-  url: 'https://example.com',
-  expectation: {
-    includeSnapshot: false,  // Skip page snapshot
-    includeConsole: false,   // Skip console messages
-    includeTabs: false       // Skip tab information
+{
+  "name": "browser_navigate",
+  "arguments": {
+    "url": "https://example.com",
+    "expectation": {
+      "includeSnapshot": false,
+      "includeConsole": false,
+      "includeTabs": false
+    }
   }
-});
+}
 ```
 
 #### Expectation Options
@@ -817,36 +860,42 @@ await browser_navigate({
 
 #### Advanced Snapshot Options
 
-```javascript
-await browser_click({
-  element: 'Login button',
-  ref: '#login-btn',
-  expectation: {
-    includeSnapshot: true,
-    snapshotOptions: {
-      selector: '.dashboard',  // Only capture dashboard area
-      maxLength: 1000,         // Limit snapshot length
-      format: 'text'           // Use text format instead of aria
+```json
+{
+  "name": "browser_click",
+  "arguments": {
+    "element": "Login button",
+    "ref": "#login-btn",
+    "expectation": {
+      "includeSnapshot": true,
+      "snapshotOptions": {
+        "selector": ".dashboard",
+        "maxLength": 1000,
+        "format": "text"
+      }
     }
   }
-});
+}
 ```
 
 #### Console Filtering Options
 
-```javascript
-await browser_navigate({
-  url: 'https://example.com',
-  expectation: {
-    includeConsole: true,
-    consoleOptions: {
-      levels: ['error', 'warn'],     // Only errors and warnings
-      maxMessages: 5,                // Limit to 5 messages
-      patterns: ['^Error:'],         // Filter by regex patterns
-      removeDuplicates: true         // Remove duplicate messages
+```json
+{
+  "name": "browser_navigate",
+  "arguments": {
+    "url": "https://example.com",
+    "expectation": {
+      "includeConsole": true,
+      "consoleOptions": {
+        "levels": ["error", "warn"],
+        "maxMessages": 5,
+        "patterns": ["^Error:"],
+        "removeDuplicates": true
+      }
     }
   }
-});
+}
 ```
 
 ### Batch Execution
@@ -855,63 +904,69 @@ Execute multiple browser actions in a single request with optimized response han
 
 #### Basic Batch Execution
 
-```javascript
-await browser_batch_execute({
-  steps: [
-    {
-      tool: 'browser_navigate',
-      arguments: { url: 'https://example.com/login' }
-    },
-    {
-      tool: 'browser_type',
-      arguments: { 
-        element: 'username field', 
-        ref: '#username', 
-        text: 'testuser' 
-      }
-    },
-    {
-      tool: 'browser_type',
-      arguments: { 
-        element: 'password field', 
-        ref: '#password', 
-        text: 'password' 
+```json
+{
+  "name": "browser_batch_execute",
+  "arguments": {
+    "steps": [
+      {
+        "tool": "browser_navigate",
+        "arguments": { "url": "https://example.com/login" }
+      },
+      {
+        "tool": "browser_type",
+        "arguments": { 
+          "element": "username field", 
+          "ref": "#username", 
+          "text": "testuser" 
+        }
+      },
+      {
+        "tool": "browser_type",
+        "arguments": { 
+          "element": "password field", 
+          "ref": "#password", 
+          "text": "password" 
+        }
+      },
+      {
+        "tool": "browser_click",
+        "arguments": { "element": "login button", "ref": "#login-btn" }
       }
-    },
-    {
-      tool: 'browser_click',
-      arguments: { element: 'login button', ref: '#login-btn' }
-    }
-  ]
-});
+    ]
+  }
+}
 ```
 
 #### Advanced Batch Configuration
 
-```javascript
-await browser_batch_execute({
-  steps: [
-    {
-      tool: 'browser_navigate',
-      arguments: { url: 'https://example.com' },
-      expectation: { includeSnapshot: false },  // Step-specific optimization
-      continueOnError: true                     // Continue if this step fails
-    },
-    {
-      tool: 'browser_click',
-      arguments: { element: 'button', ref: '#submit' },
-      expectation: { 
-        includeSnapshot: true,
-        snapshotOptions: { selector: '.result-area' }
+```json
+{
+  "name": "browser_batch_execute",
+  "arguments": {
+    "steps": [
+      {
+        "tool": "browser_navigate",
+        "arguments": { "url": "https://example.com" },
+        "expectation": { "includeSnapshot": false },
+        "continueOnError": true
+      },
+      {
+        "tool": "browser_click",
+        "arguments": { "element": "button", "ref": "#submit" },
+        "expectation": { 
+          "includeSnapshot": true,
+          "snapshotOptions": { "selector": ".result-area" }
+        }
       }
+    ],
+    "stopOnFirstError": false,
+    "globalExpectation": {
+      "includeConsole": false,
+      "includeTabs": false
     }
-  ],
-  stopOnFirstError: false,           // Continue executing remaining steps
-  globalExpectation: {               // Default for all steps
-    includeConsole: false,
-    includeTabs: false
   }
-});
+}
 ```
 
 #### Error Handling Options
@@ -941,22 +996,24 @@ Each tool has optimized defaults based on typical usage patterns:
 
 The Fast Server includes automatic diff detection to efficiently track changes between consecutive tool executions:
 
-```javascript
-// Enable diff detection for any tool
-await browser_click({
-  element: 'Load more button',
-  ref: '#load-more',
-  expectation: {
-    includeSnapshot: true,
-    diffOptions: {
-      enabled: true,
-      threshold: 0.1,         // Show diff if >10% changed
-      format: 'unified',      // or 'split', 'minimal'
-      maxDiffLines: 50,       // Limit diff output size
-      context: 3              // Lines of context around changes
+```json
+{
+  "name": "browser_click",
+  "arguments": {
+    "element": "Load more button",
+    "ref": "#load-more",
+    "expectation": {
+      "includeSnapshot": true,
+      "diffOptions": {
+        "enabled": true,
+        "threshold": 0.1,
+        "format": "unified",
+        "maxDiffLines": 50,
+        "context": 3
+      }
     }
   }
-});
+}
 ```
 
 #### Diff Detection Benefits
@@ -973,23 +1030,25 @@ await browser_click({
 3. **Form interactions**: Track changes as users fill forms
 4. **Selective monitoring**: Use with CSS selectors to track specific areas
 
-```javascript
-// Example: Track only search results changes
-await browser_type({
-  element: 'Search input',
-  ref: '#search',
-  text: 'playwright',
-  expectation: {
-    includeSnapshot: true,
-    snapshotOptions: {
-      selector: '#search-results'  // Only monitor results area
-    },
-    diffOptions: {
-      enabled: true,
-      format: 'minimal'  // Just show what changed
+```json
+{
+  "name": "browser_type",
+  "arguments": {
+    "element": "Search input",
+    "ref": "#search",
+    "text": "playwright",
+    "expectation": {
+      "includeSnapshot": true,
+      "snapshotOptions": {
+        "selector": "#search-results"
+      },
+      "diffOptions": {
+        "enabled": true,
+        "format": "minimal"
+      }
     }
   }
-});
+}
 ```
 
 ### Best Practices
@@ -1037,6 +1096,107 @@ All tools automatically provide enhanced error messages with:
 - Context-aware troubleshooting tips
 - Performance insights
 
+### Network Request Filtering
+
+The `browser_network_requests` tool provides advanced filtering capabilities to reduce token usage by up to 80-95% when working with network logs.
+
+#### Basic Usage Examples
+
+```json
+// Filter API requests only
+{
+  "name": "browser_network_requests",
+  "arguments": {
+    "urlPatterns": ["api/", "/graphql"]
+  }
+}
+
+// Exclude analytics and tracking
+{
+  "name": "browser_network_requests", 
+  "arguments": {
+    "excludeUrlPatterns": ["analytics", "tracking", "ads"]
+  }
+}
+
+// Success responses only
+{
+  "name": "browser_network_requests",
+  "arguments": {
+    "statusRanges": [{ "min": 200, "max": 299 }]
+  }
+}
+
+// Recent errors only
+{
+  "name": "browser_network_requests",
+  "arguments": {
+    "statusRanges": [{ "min": 400, "max": 599 }],
+    "maxRequests": 5,
+    "newestFirst": true
+  }
+}
+```
+
+#### Advanced Filtering
+
+```json
+// Complex filtering for API debugging
+{
+  "name": "browser_network_requests",
+  "arguments": {
+    "urlPatterns": ["/api/users", "/api/posts"],
+    "excludeUrlPatterns": ["/api/health"],
+    "methods": ["GET", "POST"],
+    "statusRanges": [
+      { "min": 200, "max": 299 },
+      { "min": 400, "max": 499 }
+    ],
+    "maxRequests": 10,
+    "newestFirst": true
+  }
+}
+
+// Monitor only failed requests
+{
+  "name": "browser_network_requests", 
+  "arguments": {
+    "statusRanges": [
+      { "min": 400, "max": 499 },
+      { "min": 500, "max": 599 }
+    ],
+    "maxRequests": 3
+  }
+}
+```
+
+#### Regex Pattern Support
+
+```json
+{
+  "name": "browser_network_requests",
+  "arguments": {
+    "urlPatterns": ["^/api/v[0-9]+/users$"],
+    "excludeUrlPatterns": ["\\.(css|js|png)$"]
+  }
+}
+```
+
+#### Token Optimization Benefits
+
+- **Massive reduction**: 80-95% fewer tokens for large applications
+- **Focused debugging**: See only relevant network activity
+- **Performance monitoring**: Track specific endpoints or error patterns
+- **Cost savings**: Lower API costs due to reduced token usage
+
+#### When to Use Network Filtering
+
+1. **API debugging**: Focus on specific endpoints and methods
+2. **Error monitoring**: Track only failed requests
+3. **Performance analysis**: Monitor slow or problematic endpoints  
+4. **Large applications**: Reduce overwhelming network logs
+5. **Token management**: Stay within LLM context limits
+
 ### Migration Guide
 
 Existing code continues to work without changes. To optimize:

package/lib/batch/batch-executor.js

@@ -19,11 +19,10 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/batch/batch-executor.ts
 import { randomBytes } from "node:crypto";
-import debug from "debug";
 import { Response } from "../response.js";
 import { mergeExpectations } from "../schemas/expectation.js";
 import { getErrorMessage } from "../utils/common-formatters.js";
-var batchDebug = debug("pw:mcp:batch");
+import { batchExecutorDebug } from "../utils/log.js";
 
 class BatchExecutor {
   toolRegistry;
@@ -66,7 +65,7 @@ class BatchExecutor {
       batchId: this.generateBatchId(),
       startTime
     };
-    batchDebug(`Starting batch execution ${this.currentBatchContext.batchId} with ${options.steps.length} steps`);
+    batchExecutorDebug(`Starting batch execution ${this.currentBatchContext.batchId} with ${options.steps.length} steps`);
     this.validateAllSteps(options.steps);
     const executeSequentially = async (index) => {
       if (index >= options.steps.length) {
@@ -132,10 +131,10 @@ class BatchExecutor {
     this.context.batchContext = batchContext;
     try {
       const response = new Response(this.context, step.tool, argsWithExpectation, mergedExpectation);
-      batchDebug(`Executing batch step: ${step.tool}`);
+      batchExecutorDebug(`Executing batch step: ${step.tool}`);
       await tool.handle(this.context, argsWithExpectation, response);
       await response.finish();
-      batchDebug(`Batch step ${step.tool} completed`);
+      batchExecutorDebug(`Batch step ${step.tool} completed`);
       return response.serialize();
     } finally {
       this.context.batchContext = previousBatchContext;

package/lib/browser-context-factory.js

@@ -21,7 +21,6 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 import { promises as fsPromises } from "node:fs";
 import { createServer } from "node:net";
 import { join as pathJoin } from "node:path";
-import debug from "debug";
 import {
   chromium,
   firefox,
@@ -29,9 +28,8 @@ import {
 } from "playwright";
 import { registryDirectory } from "playwright-core/lib/server/registry/index";
 import { outputFile } from "./config.js";
-import { logUnhandledError, testDebug } from "./log.js";
-import { createHash } from "./utils.js";
-var browserDebug = debug("pw:mcp:browser");
+import { createHash } from "./utils/guid.js";
+import { browserDebug, logUnhandledError, testDebug } from "./utils/log.js";
 function getBrowserType(browserName) {
   switch (browserName) {
     case "chromium":

package/lib/browser-server-backend.js

@@ -19,16 +19,14 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/browser-server-backend.ts
 import { fileURLToPath } from "node:url";
-import debug from "debug";
 import { z } from "zod";
 import { Context } from "./context.js";
-import { logUnhandledError } from "./log.js";
-import { packageJSON } from "./package.js";
 import { Response } from "./response.js";
 import { SessionLog } from "./session-log.js";
 import { defineTool } from "./tools/tool.js";
 import { filteredTools } from "./tools.js";
-var backendDebug = debug("pw:mcp:backend");
+import { browserServerBackendDebug, logUnhandledError } from "./utils/log.js";
+import { packageJSON } from "./utils/package.js";
 
 class BrowserServerBackend {
   name = "Playwright";
@@ -79,14 +77,14 @@ class BrowserServerBackend {
       throw new Error(`Tool not found: ${schema.name}`);
     }
     context.setRunningTool(true);
-    backendDebug(`Executing tool: ${schema.name}`);
+    browserServerBackendDebug(`Executing tool: ${schema.name}`);
     try {
       await matchedTool.handle(context, parsedArguments, response);
       await response.finish();
       this._sessionLog?.logResponse(response);
-      backendDebug(`Tool ${schema.name} completed successfully`);
+      browserServerBackendDebug(`Tool ${schema.name} completed successfully`);
     } catch (error) {
-      backendDebug(`Error executing tool ${schema.name}:`, error);
+      browserServerBackendDebug(`Error executing tool ${schema.name}:`, error);
       response.addError(String(error));
     } finally {
       context.setRunningTool(false);

package/lib/config.js

@@ -22,7 +22,7 @@ import { promises as fsPromises } from "node:fs";
 import { platform, tmpdir } from "node:os";
 import { join as pathJoin } from "node:path";
 import { devices } from "playwright";
-import { sanitizeForFilePath } from "./utils.js";
+import { sanitizeForFilePath } from "./utils/guid.js";
 var defaultConfig = {
   browser: {
     browserName: "chromium",

package/lib/context.js

@@ -18,13 +18,10 @@ var __toESM = (mod, isNodeMode, target) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/context.ts
-import debug from "debug";
 import { BatchExecutor } from "./batch/batch-executor.js";
 import { outputFile } from "./config.js";
-import { logUnhandledError } from "./log.js";
 import { Tab } from "./tab.js";
-var testDebug = debug("pw:mcp:test");
-var contextDebug = debug("pw:mcp:context");
+import { contextDebug, logUnhandledError, testDebug } from "./utils/log.js";
 
 class Context {
   tools;

package/lib/diagnostics/common/error-enrichment-utils.js

@@ -19,6 +19,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/diagnostics/common/error-enrichment-utils.ts
 import { deduplicateAndLimit } from "../../utils/array-utils.js";
+import { errorEnrichmentDebug } from "../../utils/log.js";
 var errorPatterns = new Map([
   [
     /timeout/i,
@@ -101,11 +102,11 @@ function generateSuggestions(error, context) {
   }
   return deduplicateAndLimit(suggestions, 5);
 }
-async function safeDispose(resource, _resourceType, _operation) {
+async function safeDispose(resource, resourceType, operation) {
   try {
     await resource.dispose();
   } catch (error) {
-    console.warn(`Failed to dispose ${_resourceType} during ${_operation}:`, error);
+    errorEnrichmentDebug(`Failed to dispose ${resourceType} during ${operation}:`, error);
   }
 }
 async function safeDisposeAll(resources, resourceType, operation) {