Server data from the Official MCP Registry
Website testing for AI agents: 63 Playwright tools, auth sessions, a11y/SEO/GEO + Lighthouse audits
Website testing for AI agents: 63 Playwright tools, auth sessions, a11y/SEO/GEO + Lighthouse audits
Periscope is a sophisticated Playwright-based testing MCP server with 63 tools for website auditing and interactive testing. While the codebase demonstrates strong architectural design and tool diversity, several security concerns emerge: credentials are stored in plaintext JSON, the server accepts and executes arbitrary JavaScript code, environment variables are accessible to tools, and there is minimal input validation on user-supplied selectors and URLs. The permissions granted (file I/O, network access, subprocess execution for Lighthouse) align with the server's purpose but create substantial attack surface when combined with weak credential handling. Supply chain analysis found 5 known vulnerabilities in dependencies (1 critical, 4 high severity).
3 files analyzed · 16 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: HEADLESS
Environment variable: STARTUP_PAUSE
Environment variable: TIMEOUT
Environment variable: VIEWPORT_WIDTH
Environment variable: VIEWPORT_HEIGHT
Environment variable: CHROMIUM_PATH
Environment variable: WAIT_UNTIL
Environment variable: MAX_PAGES
Environment variable: MAX_DEPTH
Environment variable: MAX_SESSIONS
Environment variable: SESSION_TIMEOUT
Environment variable: MAX_RESPONSE_BODY_SIZE
Environment variable: MAX_RESPONSE_BODIES
Environment variable: MAX_CONSOLE_LOG
Environment variable: MAX_NETWORK_LOG
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-segentic-lab-periscope-mcp": {
"env": {
"TIMEOUT": "your-timeout-here",
"HEADLESS": "your-headless-here",
"MAX_DEPTH": "your-max-depth-here",
"MAX_PAGES": "your-max-pages-here",
"WAIT_UNTIL": "your-wait-until-here",
"MAX_SESSIONS": "your-max-sessions-here",
"CHROMIUM_PATH": "your-chromium-path-here",
"STARTUP_PAUSE": "your-startup-pause-here",
"VIEWPORT_WIDTH": "your-viewport-width-here",
"MAX_CONSOLE_LOG": "your-max-console-log-here",
"MAX_NETWORK_LOG": "your-max-network-log-here",
"SESSION_TIMEOUT": "your-session-timeout-here",
"VIEWPORT_HEIGHT": "your-viewport-height-here",
"MAX_RESPONSE_BODIES": "your-max-response-bodies-here",
"MAX_RESPONSE_BODY_SIZE": "your-max-response-body-size-here"
},
"args": [
"-y",
"github:segentic-lab/periscope-mcp"
],
"command": "npx"
}
}
}From the project's GitHub README.
A website testing MCP server built for AI agents — not a thin wrapper around browser APIs. Its 63 Playwright-powered tools are shaped around how agents actually work:
assert_condition returns
passed: true/false with the actual value; checks return structured issues.auto_fill_form detects, infers, and fills a
whole form; interact_and_test batches 25 action types with checks;
test_project crawls and audits an entire site.Playwright + headless Chrome underneath; persistent authenticated sessions, site crawling, responsive testing, and screenshot diffing on top. Works with any MCP client — Claude Code, Codex, Cursor, Windsurf, Gemini CLI, custom agents, or anything else that speaks MCP over stdio.
playwright-mcp is excellent at what it is: general browser control over MCP, with tools that mirror Playwright's own API. If the job is "browse this site, click around, extract something," use it.
Periscope exists for a different job: testing and auditing a site, then reporting findings — and its tools encode the testing knowledge an agent would otherwise have to reinvent every session:
| Raw browser control | Periscope | |
|---|---|---|
| Verifying an outcome | Read a screenshot or DOM dump and judge | assert_condition → hard passed: true/false + actual value |
| Filling a form | One call per field, agent invents test data | auto_fill_form — detects fields, infers realistic data, reports per-field failures |
| Auth | Re-login by scripting clicks each session | Projects persist form/basic/cookie auth; sessions share the logged-in context |
| Site-wide audit | Loop pages manually | test_project — crawl + accessibility/SEO/GEO/visual/functionality checks + saved report |
| Diagnosing a broken page | Ask for logs, replay requests | Response bodies, console, and network are captured automatically; mock APIs with intercept_network |
| Silent failures | Drag "succeeds," nothing moved | Flagged in the result, with the recovery path spelled out |
| AI-readiness audits | — | robots.txt AI-crawler access, llms.txt, WebMCP annotations, JSON-LD, plus real Lighthouse scores |
The two aren't rivals — an agent can happily use playwright-mcp for browsing tasks and Periscope when it's wearing the QA hat. Periscope's design bets are simply about that hat: fewer, higher-level calls; structured verdicts instead of raw page state; and errors written to tell the agent what to do next.
MCP client (AI agent) --> MCP Server (stdio) --> Playwright (Headless Chrome)
| |
+-- Projects (JSON) +-- Persistent Sessions
+-- Screenshots (PNG) +-- Network Interception
+-- Reports (JSON) +-- Device Emulation
+-- Videos (WebM)
How it works: your MCP client connects to this server over stdio. The server exposes 63 tools the agent can call to create projects, configure authentication, crawl websites, run static checks, and interactively test web applications using persistent browser sessions. Results (JSON + screenshots + videos) are returned to the agent for analysis.
periscope-mcp/
├── server.py # MCP server entry point (stdio wiring + dispatch)
├── tool_schemas.py # All 63 MCP tool definitions (schemas)
├── runtime.py # Shared singletons (project store, sessions, browser)
├── coercion.py # Argument coercion for MCP clients with stale schemas
├── handlers/ # Tool handlers, grouped by category
│ ├── registry.py # @tool(name) decorator + HANDLERS registry
│ ├── projects.py # create/list/get/delete project
│ ├── auth.py # form login, basic auth, cookies, copy_auth
│ ├── static_testing.py # test_url, crawl, test_project, reports, responsive
│ ├── session_tools.py # open/close/list sessions, viewport, history
│ ├── interactive.py # click, fill, steps, element queries, dialogs
│ ├── analysis.py # forms, links, keyboard nav, tables, toasts, contrast
│ ├── advanced.py # network mocking, storage, iframes, emulation, recording
│ ├── agent_speed.py # assertions, smart find, auto-fill, snapshots
│ ├── web.py # web_search, web_fetch
│ └── discovery.py # describe_tools catalog
├── tester.py # Playwright browser control + test orchestration
├── crawler.py # Page discovery (BFS crawl, same-domain only)
├── projects.py # Project CRUD + auth config storage
├── auth.py # Authentication handlers (form, basic, cookies)
├── sessions.py # SessionManager + PageSession — persistent page lifecycle
├── interactions.py # Interaction primitives (click, fill, execute_steps)
├── utils.py # Screenshot comparison (Pillow pixel diff)
├── config.py # Global settings (timeouts, paths, session limits)
├── checks/
│ ├── visual.py # Broken images, favicon, overflow, small text
│ ├── accessibility.py # Alt text, labels, headings, lang, ARIA, keyboard nav
│ ├── functionality.py # Broken links, forms, SEO, performance, link checker
│ └── geo.py # GEO/agentic search: robots.txt AI crawlers, llms.txt, WebMCP, JSON-LD
├── tests/ # Unit tests (no browser) + tests/e2e/ (real browser + fixture pages)
├── data/ # Created at runtime (gitignored — contains credentials)
├── Dockerfile
├── docker-compose.yml
└── .mcp.json.example # MCP registration template (copy to .mcp.json)
One command — clone and install:
git clone https://github.com/segentic-lab/periscope-mcp.git && cd periscope-mcp && ./install.sh
Fully unattended (no confirmation prompts):
git clone https://github.com/segentic-lab/periscope-mcp.git && cd periscope-mcp && ./install.sh -y
Already cloned? Just run ./install.sh from the repo directory.
The script installs apt prerequisites, creates the venv, installs Python
dependencies and Playwright's Chromium, runs a headless self-test, and
generates mcp-config.json with the correct absolute paths for this install
(copy or merge it into your project's .mcp.json). Useful flags:
./install.sh --system-chromium — use an existing Chromium/Chrome (sets CHROMIUM_PATH) instead of downloading Playwright's build./install.sh --skip-deps — never touch apt / use sudo./install.sh -y — non-interactive (no confirmation prompts)On any other platform the script doesn't modify your system — it prints the
exact commands to run for your OS (./install.sh --manual macos|fedora|arch|suse|windows to pick explicitly).
./update.sh
Pulls the latest source from GitHub (git pull --ff-only) and refreshes the
install: Python dependencies, Playwright browser (kept on system Chromium if
that's what the install uses), the registry + headless-launch self-test, and a
regenerated mcp-config.json. Works on any platform with an existing install.
Your data/ directory (projects, credentials, screenshots, reports) is never
touched.
./update.sh --force — stash local modifications to tracked files first (recover with git stash pop)./update.sh --full — also re-check apt prerequisites on Debian/Ubuntu (uses sudo)If you have local modifications, the script refuses and lists them instead of overwriting.
# Clone the repo
cd periscope-mcp
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Install Chromium for Playwright
playwright install chromium
docker compose up -d
See Docker Deployment section below.
Periscope is a standard stdio MCP server: point any MCP client at
venv/bin/python server.py and you're done. ./install.sh generates
mcp-config.json with the correct absolute paths for your machine; most
clients accept that shape directly:
{
"mcpServers": {
"periscope": {
"command": "/path/to/periscope-mcp/venv/bin/python",
"args": ["/path/to/periscope-mcp/server.py"]
}
}
}
Client-specific examples:
.mcp.json
(cp .mcp.json.example .mcp.json and adjust paths), or run
claude mcp add periscope -- /path/to/venv/bin/python /path/to/server.py~/.cursor/mcp.json /
~/.codeium/windsurf/mcp_config.json~/.codex/config.toml:
[mcp_servers.periscope] with command and args as aboveAfter configuring, restart your client.
AGENTS.md contains a ready-made system-prompt block — workflows,
tool-selection guidance, and known pitfalls. Paste its contents into your
agent's system prompt (or custom instructions) so it drives the 63 tools
effectively instead of discovering the conventions by trial and error.
| Tool | Description | Required Params |
|---|---|---|
create_project | Create a new testing project | name, base_url |
list_projects | List all projects | (none) |
get_project | Get project details | name |
delete_project | Delete project + data | name |
| Tool | Description | Required Params |
|---|---|---|
set_form_login | Configure username/password form login | project, login_url, username, password |
set_basic_auth | Configure HTTP Basic Auth | project, username, password |
set_cookies | Inject session cookies | project, cookies (array) |
login_project | Execute login using configured auth | project |
copy_auth | Copy auth config + session cookies between projects | from_project, to_project |
| Tool | Description | Required Params |
|---|---|---|
test_url | Test a single URL (screenshot + checks) | url |
crawl_project | Discover all pages from base URL | project |
test_project | Full audit: crawl + test all pages | project |
| Tool | Description | Required Params |
|---|---|---|
get_screenshot | Get screenshot file path | project, url |
list_reports | List saved test reports | (optional: project) |
get_report | Read a report file | report_path |
Sessions keep browser pages alive across tool calls, enabling multi-step interactive workflows.
| Tool | Description | Required Params |
|---|---|---|
open_session | Open persistent browser session | url |
close_session | Close session and free resources | session_id |
list_sessions | List all active sessions | (none) |
set_viewport | Switch viewport size (8 device presets or custom w/h) | session_id |
set_viewport presets: mobile_sm (320x568), mobile (375x812), mobile_lg (428x926), tablet (768x1024), tablet_lg (1024x1366), laptop (1366x768), desktop (1920x1080), desktop_lg (2560x1440)
| Tool | Description | Required Params |
|---|---|---|
click_element | Click element (force=true bypasses overlays) | session_id, selector |
fill_form | Fill form fields, optionally submit | session_id, fields |
select_option | Native <select> or custom dropdown (Radix/shadcn) — auto-detects | session_id, selector |
interact_and_test | Multi-step workflow with 25 actions (see below) | steps |
get_page_elements | List matching elements with attributes | selector |
scroll_into_view | Scroll element into viewport without clicking | session_id, selector |
interact_and_test supports 25 step actions:
click, force_click, fill, force_fill, type, select, select_option, wait, wait_for, wait_for_text, screenshot, navigate, hover, press_key, check, uncheck, scroll_to, scroll_within, evaluate_js, drag, right_click, go_back, go_forward, upload_file, wait_for_network
| Tool | Description | Required Params |
|---|---|---|
test_form_validation | Analyze form validation messages | (url or session_id) |
compare_screenshots | Pixel diff between two screenshots | screenshot1, screenshot2 |
test_responsive | Test at mobile/tablet/desktop viewports | url |
check_links | Comprehensive link checker (internal + external) | (url or session_id) |
measure_interaction | Measure click-to-result timing | session_id, selector |
get_table_data | Parse HTML table into structured JSON (headers → cell values) | session_id |
get_toast_messages | Capture visible toast/notification messages | session_id |
run_lighthouse | Real Google Lighthouse audit: 0-100 scores, Core Web Vitals, failed audits (needs Node.js) | url |
| Tool | Description | Required Params |
|---|---|---|
screenshot_session | Quick screenshot of current page state | session_id |
run_checks_on_session | Run checks on active session (no new page) | session_id |
navigate_session | Browser history: back, forward, or reload | session_id, action |
handle_dialog | Accept/dismiss JS alert/confirm/prompt (call BEFORE trigger) | session_id, action |
upload_file | Set file(s) on <input type="file"> | session_id, selector, files |
wait_for_network | Wait for specific API URL pattern to complete | session_id, url_pattern |
wait_for_gone | Wait for element to disappear (modal close, spinner gone) | session_id, selector |
get_page_html | Raw outerHTML of elements, or full page HTML | session_id |
| Tool | Description | Required Params |
|---|---|---|
intercept_network | Mock API responses (test error/empty/loading states) | session_id, url_pattern |
clear_intercepts | Remove network mocks (all, or by pattern) | session_id |
get_local_storage | Read localStorage or sessionStorage | session_id |
set_local_storage | Write to localStorage or sessionStorage | session_id, entries |
select_iframe | Switch into iframe content (returns new session) | session_id, selector |
get_computed_style | Get actual rendered CSS values | session_id, selector, properties |
emulate_network | Throttle network: slow_3g, fast_3g, offline, reset | session_id, preset |
test_dark_mode | Toggle prefers-color-scheme dark/light | session_id, mode |
| Tool | Description | Required Params |
|---|---|---|
record_session | Record workflow as video | url, steps |
test_keyboard_navigation | Tab-order and focus indicator audit | (url or session_id) |
get_console_errors | Get all console errors/logs (passive monitoring) | session_id |
| Tool | Description | Required Params |
|---|---|---|
assert_condition | Programmatic pass/fail: text_contains, element_exists, url_contains, etc. | session_id, assertion |
find_element | Smart finder by text, tag, role, or proximity to another element | session_id |
auto_fill_form | Auto-detect fields, infer types, fill with test data. One call = many fills. | session_id |
get_network_log | All captured network requests (URL, status, method, type) | session_id |
get_response_body | Actual API response body text (diagnose 400/500 errors) | session_id, url_pattern |
page_state | Named checkpoints: snapshot / restore / diff page state | session_id, action, name |
get_cookies | Read all cookies from session | session_id |
check_color_contrast | WCAG AA/AAA contrast ratio checks on text elements | session_id |
| Tool | Description | Required Params |
|---|---|---|
web_search | Search DuckDuckGo: titles + URLs + snippets | query |
web_fetch | Fetch URL, extract readable text (or raw HTML); TLS verified by default | url |
describe_tools | Structured catalog of all tools with workflows and tips | (none) |
checks/visual.py)checks/accessibility.py)alt text (decorative images exempt: alt="", role="presentation"/"none", aria-hidden)aria-label, resolvable aria-labelledby, title, img[alt], svg <title>; aria-hidden elements exempt)label[for], wrapping label, aria-label/aria-labelledby, title)lang attribute on <html>id values (break label[for] and aria references)role values, aria-labelledby/describedby/controls/owns/activedescendant references to non-existent idstabindex > 0test_keyboard_navigation toolchecks/functionality.py)check_functionality)check_links tooltarget="_blank"checks/functionality.py -> check_seo)og:title/description/image/url), non-absolute og:image, missing twitter:cardnoindex via robots meta or X-Robots-Tag response headertest_project): duplicate titles / meta descriptions across pages, reported under site_issueschecks/geo.py -> check_geo)Generative Engine Optimization — is the site readable and usable by AI crawlers, answer engines, and in-browser agents:
llms.txt presence and format compliance (Markdown with at least one H1)<form toolname> annotations present and complete (tooldescription), form coverage ratio, and — when the browser exposes document.modelContext — registered tool enumeration with schema/name/description validationrobots.txt and llms.txt are fetched once per origin and cached for the server's lifetime.
checks/functionality.py -> get_performance_metrics)For scored, Lighthouse-official metrics use the run_lighthouse tool — it runs the real Lighthouse CLI (requires Node.js) and returns 0-100 category scores, official Core Web Vitals, and failed audits, saving the full JSON report to data/reports/.
Each test_url call returns:
{
"url": "https://example.com",
"status": "success",
"status_code": 200,
"title": "Page Title",
"screenshot_path": "/path/to/screenshot.png",
"load_time_ms": 1500,
"issues": [
{
"type": "accessibility",
"severity": "error",
"message": "3 images missing alt text",
"details": ["img1.png", "img2.png", "img3.png"]
}
],
"issue_count": 5,
"issues_by_severity": {"error": 1, "warning": 2, "info": 2},
"issues_by_type": {"accessibility": 2, "seo": 2, "visual": 1},
"performance": {
"dom_content_loaded_ms": 120,
"load_complete_ms": 1500,
"first_paint_ms": 140,
"first_contentful_paint_ms": 140,
"resource_count": 25,
"total_size_bytes": 512000,
"total_size_kb": 500
},
"console_errors": []
}
test_project returns an aggregated report with per-page results + summary.
User: "Test https://example.com for issues"
The agent calls:
1. create_project(name="example", base_url="https://example.com")
2. test_project(project="example")
3. Analyzes results and reports findings
User: "Test https://myapp.com, login is admin/password123"
The agent calls:
1. create_project(name="myapp", base_url="https://myapp.com")
2. set_form_login(project="myapp", login_url="https://myapp.com/login",
username="admin", password="password123")
3. login_project(project="myapp")
4. test_project(project="myapp")
User: "Test https://staging.example.com, it uses basic auth admin/secret"
The agent calls:
1. create_project(name="staging", base_url="https://staging.example.com")
2. set_basic_auth(project="staging", username="admin", password="secret")
3. login_project(project="staging")
4. test_project(project="staging")
User: "Test myapp using this session cookie: session=abc123"
The agent calls:
1. set_cookies(project="myapp", cookies=[
{"name": "session", "value": "abc123", "domain": "myapp.com"}
])
2. test_project(project="myapp")
User: "Go to myapp.com, click the login button, fill in the form, and check what happens"
The agent calls:
1. open_session(url="https://myapp.com") → session_id
2. get_page_elements(session_id=..., selector="button, a") → see clickable elements
3. click_element(session_id=..., selector="#login-btn") → screenshot after click
4. fill_form(session_id=..., fields=[
{"selector": "#email", "value": "user@test.com"},
{"selector": "#password", "value": "test123"}
], submit_selector="button[type='submit']")
5. Analyzes screenshot to see result
6. close_session(session_id=...)
User: "Test the checkout flow on myshop.com"
The agent calls:
1. interact_and_test(
url="https://myshop.com/products/1",
steps=[
{"action": "click", "selector": "#add-to-cart"},
{"action": "wait", "timeout": 1000},
{"action": "click", "selector": "#checkout-btn"},
{"action": "fill", "selector": "#email", "value": "test@test.com"},
{"action": "screenshot", "label": "checkout_form"},
{"action": "click", "selector": "#submit-order"}
],
run_checks=["visual", "accessibility"]
)
User: "Check how example.com looks on mobile, tablet, and desktop"
The agent calls:
1. test_responsive(url="https://example.com", run_checks=["visual"])
→ Returns screenshots at 375x812, 768x1024, and 1920x1080
User: "Show me how this page looks on mobile"
The agent calls:
1. set_viewport(session_id=..., device="mobile")
→ Returns screenshot at 375x812
User: "What happens when the API returns a 500 error?"
The agent calls:
1. intercept_network(session_id=..., url_pattern="/api/tasks", status=500,
body='{"error": "Internal server error"}')
2. navigate_session(session_id=..., action="reload")
3. screenshot_session(session_id=...)
→ Shows how the app handles the error state
User: "Does this site support dark mode?"
The agent calls:
1. open_session(url="https://example.com") → session_id
2. test_dark_mode(session_id=..., mode="dark")
→ Screenshot shows the page with prefers-color-scheme: dark
User: "Submit this form and wait for the success message"
The agent calls:
1. fill_form(session_id=..., fields=[...], submit_selector="#submit")
2. wait_for_network(session_id=..., url_pattern="/api/submit")
3. screenshot_session(session_id=...)
User: "How does this page load on a slow connection?"
The agent calls:
1. emulate_network(session_id=..., preset="slow_3g")
2. navigate_session(session_id=..., action="reload")
3. screenshot_session(session_id=...)
4. emulate_network(session_id=..., preset="reset")
Edit config.py to change defaults (env-overridable settings note the variable):
| Setting | Default | Description |
|---|---|---|
HEADLESS | True | Run Chrome in headless mode (env: HEADLESS=false) |
STARTUP_PAUSE | 10 | Seconds to wait after a non-headless browser opens (env: STARTUP_PAUSE) |
TIMEOUT | 30000 | Page load timeout (ms) |
VIEWPORT_WIDTH | 1920 | Browser viewport width |
VIEWPORT_HEIGHT | 1080 | Browser viewport height |
CHROMIUM_PATH | unset | Path to a system Chromium binary (env: CHROMIUM_PATH); unset = Playwright's bundled build |
WAIT_UNTIL | networkidle | Navigation wait strategy; never-idle pages (Turnstile, websockets) auto-downgrade to load per page, flagged as wait_downgraded (env: NAV_WAIT_UNTIL=load forces it globally) |
MAX_PAGES | 20 | Default max pages to crawl |
MAX_DEPTH | 3 | Default max crawl depth |
MAX_SESSIONS | 20 | Max concurrent interactive sessions (env: MAX_SESSIONS) |
SESSION_TIMEOUT | 300 | Auto-expire idle sessions after N seconds (env: SESSION_TIMEOUT) |
MAX_RESPONSE_BODY_SIZE | 512000 | Max bytes captured per response body |
MAX_RESPONSE_BODIES | 100 | Max captured response bodies kept per session |
MAX_CONSOLE_LOG | 500 | Max console entries kept per session |
MAX_NETWORK_LOG | 1000 | Max network log entries kept per session |
All data is stored in the data/ directory:
data/projects.json - Project configs (name, URL, auth, settings). Auth credentials are stored in plaintext - do not commit this file.data/screenshots/{project}/ - PNG screenshots per project. Filenames are {domain}_{path}_{hash}.png for static tests, interactive_{timestamp}_{label}.png for session screenshots.data/reports/{project}_{timestamp}.json - Full test reports with all findings.data/videos/{project}/ - Recorded session videos (WebM format from Playwright).data/diffs/ - Screenshot comparison diff images.docker compose up -d
Point your client's MCP config at the container instead of the venv:
{
"mcpServers": {
"periscope": {
"command": "docker",
"args": ["exec", "-i", "periscope", "python", "/app/server.py"]
}
}
}
The docker-compose.yml mounts ./data as a volume so screenshots, reports, and project configs survive container restarts.
Per-project browser contexts - Each project gets its own Playwright BrowserContext. This keeps sessions (cookies, auth) isolated between projects.
Lazy browser init - The Playwright browser is only launched on the first tool call, not at server startup. If the browser crashes or fails to launch, it re-creates on the next call.
BFS crawling - The crawler uses breadth-first search with depth tracking. It stays on the same domain and skips non-page resources (images, PDFs, etc.).
Check modularity - Each check category is a separate module in checks/. Add new checks by creating a function that takes a Playwright Page and returns list[dict].
JSON storage - Projects are stored in a single projects.json file. No database needed for the expected scale (dozens of projects, not thousands).
Persistent sessions - Interactive testing uses a SessionManager that keeps Playwright pages alive in a dict keyed by session ID. Sessions auto-expire after idle timeout and are capped at a configurable maximum to prevent resource leaks.
Ephemeral vs session mode - Tools like get_page_elements, interact_and_test, and check_links accept either a session_id (reuses an existing page) or a url (creates a temporary page that's closed after use). This makes them flexible for both interactive and one-shot use.
checks/*.py file:async def check_something(page: Page) -> list[dict]:
# Run your check
result = await page.evaluate("() => { ... }")
issues = []
if result:
issues.append({
"type": "your_category", # visual, accessibility, seo, etc.
"severity": "error", # error, warning, info
"message": "Description",
"details": [] # optional
})
return issues
tester.py inside test_url().<a href> for crawling)check_functionality link checking limited to 20 internal links (use check_links tool for up to 100 with external support)SESSION_TIMEOUT)MAX_SESSIONS)drag step (Playwright drag_to) is silently ignored by pointer-tracking DnD libraries (@hello-pangea/dnd and similar) — the step succeeds but nothing moves. Retry with method: "mouse" on the drag step (stepped manual drag that crosses the library's drag-start threshold), or drive the library's keyboard mode (focus the drag handle, Space to lift, arrows to move, Space to drop). Verify drags with diff_page_state or assert_condition.fill, force_fill, auto_fill_form)| Problem | Solution |
|---|---|
Executable doesn't exist | Run playwright install chromium |
'NoneType' has no attribute 'new_context' | Browser failed to launch. Check Chromium is installed. Server will auto-retry on next call. |
| Login not working | Try providing explicit CSS selectors via username_selector, password_selector, submit_selector |
| Timeout on page load | Increase TIMEOUT in config.py or check if site requires VPN/auth |
| Docker can't reach website | Ensure the container has network access. Use network_mode: host if testing localhost |
pip install -r requirements-dev.txt
pytest --ignore=tests/e2e # unit tests, no browser required
pytest tests/e2e # behavioral tests: real headless Chromium against
# fixture pages in tests/e2e/fixtures/ (~30s)
The e2e suite covers session lifecycle, network waits/intercepts, console
capture, dialogs, drag-and-drop (including the pointer-tracking DnD silent
no-op), the check modules against known-good/known-bad pages, Core Web Vitals,
and the agent-speed tools. CI runs both suites; e2e installs Playwright's
Chromium (python -m playwright install --with-deps chromium). Tests are
isolated from your real data/ via PERISCOPE_DATA_DIR.
Adding a new tool: define its schema in tool_schemas.py, then add a handler in the
matching handlers/<category>.py decorated with @tool("your_tool_name"). The
registry test (tests/test_registry.py) fails if schemas and handlers drift apart.
GNU AGPL-3.0 — see LICENSE.
Run it, modify it, use it anywhere — including commercially. If you distribute a modified version or offer one as a network service, you must make your modifications available under the same license.
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.