Playwright本地调试服务

Local Playwright MCP

Small stdio-compatible MCP server for local Playwright troubleshooting and visual regression checks.

Installation

Create and activate a virtual environment:

cd PROJECT_FOLDER
python3 -m venv .venv
source .venv/bin/activate

Install dependencies and browsers:

pip install fastmcp playwright pillow numpy pydantic
playwright install

Freeze the requirements when dependencies change:

pip freeze > requirements.txt

Run the server:

python3 server.py

You should see:

Starting MCP server 'local-playwright-mcp' with transport 'stdio'

Configure OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-playwright": {
      "type": "local",
      "command": [
        "PATH_TO_YOUR_MCP_PROJECT/.venv/bin/python",
        "PATH_TO_YOUR_MCP_PROJECT/server.py"
      ],
      "enabled": true
    }
  }
}

Troubleshooting Tools

inspect_page

Use inspect_page for one-shot diagnostics of a rendered page with no interaction.

{
  "url": "http://localhost:5001/",
  "viewport": { "width": 1280, "height": 720 },
  "wait_ms": 1000,
  "capture": {
    "screenshot": true,
    "dom": true,
    "network": true,
    "console": true
  }
}

The result includes:

• final URL, title, and initial HTTP status when known
• page_errors from page.on("pageerror")
• console messages, including errors and warnings
• failed network requests and HTTP responses with status >= 400
• DOM summary with visible text, forms, fields, status text, and buttons
• screenshot artifact paths plus dimensions and captions
• text_report, a compact text summary for hosts that cannot inspect images

run_scenario

Use run_scenario when a bug requires interaction. New callers can pass url plus actions:

{
  "url": "http://localhost:5001/",
  "viewport": { "width": 1280, "height": 720 },
  "actions": [
    { "action": "fill", "selector": "#username", "value": "tester" },
    { "action": "fill", "selector": "#password", "value": "testpass123" },
    { "action": "click", "selector": "#register-btn" },
    { "action": "wait", "ms": 1000 }
  ],
  "capture": {
    "screenshot": true,
    "dom": true,
    "network": true,
    "console": true
  }
}

Existing callers can still pass steps and include a first goto step:

{
  "steps": [
    { "action": "goto", "url": "http://localhost:5001/" },
    { "action": "click", "selector": "#register-btn" },
    { "action": "screenshot", "name": "after-register" }
  ]
}

Supported action values are schema-constrained to:

goto, click, fill, press, select, submit, wait, wait_for_selector, expect_text, expect_selector, screenshot

Arbitrary evaluate actions are intentionally unsupported. Use inspect_page, expect_text, expect_selector, and the returned DOM summary instead.

Screenshot names are normalized to PNG paths. A screenshot action with "name": "after-register" writes a valid after-register.png artifact.

Secret Handling

Returned diagnostics redact obvious credentials in console text, request URLs, captions, and error messages. Password input values are not included in step results, and password fields are masked in screenshots.

Verification

Run syntax and unit checks:

python3 -m py_compile server.py
python3 -m unittest discover -s tests

The browser-backed test serves a demo page that throws Cannot access 'game' before initialization and verifies that inspect_page returns the runtime error in page_errors.