Skip to main content
Glama

periscope-mcp

periscope-mcp MCP server

An MCP server that gives AI agents 74 Playwright tools to QA, test, and analyze web apps — static sites, SPAs, and apps behind a login — returning hard verdicts, not screenshots to squint at. Not a thin wrapper around browser APIs; the tools are shaped around how agents actually work:

  • Hard results, not screenshot-squinting — assert_condition returns passed: true/false with the actual value; checks return structured issues.

  • One call instead of ten — 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.

  • Real web-app testing — persistent authenticated sessions (form/basic/ cookie auth, plus a visible interactive login for 2FA/SSO/CAPTCHA that then runs headless), multi-step flows, network mocking, state snapshots, and real INP measured from the interactions it drives.

  • Honest responses — failures say what happened and what to do next (expired session vs. browser crash vs. eviction); silent no-ops like ignored drags come back flagged, not as fake success.

  • Debugging built in — captured API response bodies, console/network logs, network mocking, and state snapshots/diffs, no setup calls needed.

  • Audits agents can't get from a browser binding — accessibility, SEO, and GEO/agentic-search readiness (robots.txt AI-crawler access, llms.txt, WebMCP), plus real Lighthouse.

Playwright + headless Chrome underneath; 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.

Why not just playwright-mcp?

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 or web app, 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.

Related MCP server: Scout

Architecture

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 74 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.

Project Structure

periscope-mcp/
├── server.py              # MCP server entry point (stdio wiring + dispatch)
├── tool_schemas.py        # All 74 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
│   └── system.py          # periscope_system: status, self-update, agents_md
├── 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)

Prerequisites

  • Python 3.11+

  • Playwright + Chromium browser

Installation (Local)

Quick install (Debian/Ubuntu)

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).

Updating

./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.

Manual install

# 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

Installation (Docker)

docker compose up -d

See Docker Deployment section below.

Connecting an MCP Client

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:

  • Claude Code — copy the config into the project as .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 / Windsurf — add the block above to ~/.cursor/mcp.json / ~/.codeium/windsurf/mcp_config.json

  • Codex CLI — add to ~/.codex/config.toml: [mcp_servers.periscope] with command and args as above

  • Custom agents — any MCP SDK client can spawn the server over stdio with the same command and args

After configuring, restart your client.

Teaching your agent to use the tools

Two options, depending on your agent:

  • Claude Code (recommended): install the skill. SKILL.md (repo root; also exposed at skills/periscope/ in the Claude Code skill layout) is a Claude Code skill — it auto-triggers on web-testing tasks and loads a distilled operating guide (workflow decision table + the pitfalls) only when needed, costing ~0 context otherwise:

    ln -s "$(pwd)/skills/periscope" ~/.claude/skills/periscope

    A symlink keeps it current with ./update.sh (copy the folder instead if you prefer a frozen version).

  • Any other MCP client: paste the guide. 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).

Either way, the agent can always fetch the current full guide from the running server via periscope_system(action="agents_md") and the complete catalog via describe_tools().

MCP Tools Reference (74 tools)

Project Management (4 tools)

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

Authentication (7 tools)

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

interactive_login

Open a visible window to log in by hand (2FA/SSO/CAPTCHA), then save_login

project

save_login

Capture the manual-login session; the project then runs authenticated + headless

project

copy_auth

Copy auth config + session state between projects

from_project, to_project

For logins that can't be automated — 2FA/MFA, SSO/OAuth redirects, CAPTCHA, magic links — use interactive_login (opens a real browser window; requires a display on the server), complete the login yourself, then save_login. It captures the authenticated session (cookies + localStorage) into the project, and every future headless session reuses it. Re-run when the session expires (Periscope flags that automatically — see the auth-expiry detection in test_project).

Static Testing (3 tools)

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

Results (4 tools)

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

session_report

HTML+PDF dossier of every tool call this run — args (redacted), verdicts, timings, screenshots

(none)

Session Management (5 tools)

Sessions keep browser pages alive across tool calls, enabling multi-step interactive workflows.

Tool

Description

Required Params

open_session

Open persistent browser session (headed=true for a visible window)

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

select_page

Adopt a popup/new tab (OAuth, target=_blank) as a new drivable session

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)

Interactive Actions (7 tools)

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

flow

Save / run / list / delete named step sequences (reusable workflows)

(varies by action)

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

Analysis (10 tools)

Tool

Description

Required Params

test_form_validation

Analyze form validation messages

(url or session_id)

compare_screenshots

Pixel diff between two screenshots

screenshot1, screenshot2

visual_check

Named visual-regression baselines: set once, check for a hard pass/fail

session_id, name

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

get_interaction_log

Export real INP time series (per interaction) as JSON/CSV + percentile stats

session_id

Workflow Speed (8 tools)

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

Advanced Testing (9 tools)

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

download_file

Click a trigger and capture the downloaded file (path, sha256, text preview)

session_id, selector

Recording & Console (3 tools)

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

AI Agent Speed Tools (10 tools)

Tool

Description

Required Params

assert_condition

Programmatic pass/fail: text_contains, element_exists, url_contains, etc.

session_id, assertion

assert_all

Batch assertions — every verdict in one call, no early abort

session_id, assertions

get_page_map

Semantic page map: roles, names, states + ready selectors in one call

session_id

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

Web, Discovery & System (4 tools)

Tool

Description

Required Params

web_search

Search DuckDuckGo: titles + URLs + snippets

query

web_fetch

Fetch URL → readable Markdown (or text/html); render=true runs JS in headless Chromium (+ project for behind-login), contains gates the fetch, save writes a clean .md artifact

url

describe_tools

Structured catalog of all tools with workflows and tips

(none)

periscope_system

Install status + update check/apply + fetch current AGENTS.md

(none)

Test Checks

Visual (checks/visual.py)

  • Broken images (incomplete load or 0 natural width)

  • Missing favicon

  • Horizontal overflow / layout issues

  • Very small text (< 12px)

  • Missing body background color

  • Images without explicit width/height dimensions

Accessibility (checks/accessibility.py)

  • Images missing alt text (decorative images exempt: alt="", role="presentation"/"none", aria-hidden)

  • Links and buttons without accessible names (checks text, aria-label, resolvable aria-labelledby, title, img[alt], svg <title>; aria-hidden elements exempt)

  • Form inputs without associated labels (label[for], wrapping label, aria-label/aria-labelledby, title)

  • Heading hierarchy (missing H1, multiple H1, skipped levels)

  • Missing lang attribute on <html>

  • Duplicate id values (break label[for] and aria references)

  • ARIA validity: unknown role values, aria-labelledby/describedby/controls/owns/activedescendant references to non-existent ids

  • Missing skip navigation link (scans the first 5 links)

  • Elements with tabindex > 0

  • Keyboard navigation audit (tab order, visible focus indicators, element-identity cycle detection) — via test_keyboard_navigation tool

Functionality (checks/functionality.py)

  • Broken internal links (HTTP HEAD check, up to 20 links in check_functionality)

  • Comprehensive link checker with external link support (up to 100 links) — via check_links tool

  • Forms without action or submit button

  • Orphan buttons outside forms

  • External links missing target="_blank"

  • Required form field count

  • Autocomplete disabled inputs

SEO (checks/functionality.py -> check_seo)

  • Page title: missing, too long (> 60 chars), or very short (< 15 chars)

  • Meta description: missing, too long (> 160 chars), or very short (< 50 chars)

  • Missing viewport meta tag

  • Missing canonical URL

  • H1 heading: missing or more than one

  • Open Graph: missing entirely, incomplete core tags (og:title/description/image/url), non-absolute og:image, missing twitter:card

  • JSON-LD structured data: missing or unparseable blocks

  • noindex via robots meta or X-Robots-Tag response header

  • robots.txt blocking search engine crawlers (Googlebot, Bingbot, DuckDuckBot, ...) — error if all are blocked

  • Site-wide (via test_project): duplicate titles / meta descriptions across pages, reported under site_issues

Generative Engine Optimization — is the site readable and usable by AI crawlers, answer engines, and in-browser agents:

  • robots.txt blocking AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, and 11 more)

  • llms.txt presence and format compliance (Markdown with at least one H1)

  • WebMCP integration: declarative <form toolname> annotations present and complete (tooldescription), form coverage ratio, and — when the browser exposes document.modelContext — registered tool enumeration with schema/name/description validation

  • JSON-LD structured data presence (what answer engines cite from)

robots.txt and llms.txt are fetched once per origin and cached for the server's lifetime.

Performance (checks/functionality.py -> get_performance_metrics)

  • DOM content loaded time (ms)

  • Full page load time (ms)

  • First paint / first contentful paint (ms)

  • Core Web Vitals (lab values via buffered PerformanceObserver): Largest Contentful Paint (ms), Cumulative Layout Shift, Total Blocking Time approximation from long tasks (+ long-task count)

  • Interaction to Next Paint (INP) — interaction_to_next_paint_ms: the real INP, measured from Event Timing entries for the interactions Periscope drives (null until you've interacted). This is a genuine field-style measurement, not the TBT lab proxy — Lighthouse can't produce INP in lab mode at all.

  • Resource count

  • Total transfer size (bytes / KB)

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/.

INP time series (get_interaction_log)

Because Periscope drives real interactions, it can log each one's INP over an extended interactive test. get_interaction_log(session_id, format="json"|"csv") writes a file to data/reports/ — one row per interaction (t_ms, epoch_ms, inp_ms, type, target, url) plus percentile stats (p50/p75/p90/p98/worst) — for graphing INP over time. clear=true resets the recording. Records are capped per session (MAX_INTERACTION_LOG, oldest dropped).

Test Output Format

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.

Usage Examples

Basic test (no auth)

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

Test with login

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")

Test with Basic Auth

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")

Test with cookies

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")

Interactive testing (session-based)

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=...)

Scripted multi-step workflow (no session needed)

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"]
   )

Responsive testing

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

Switch viewport during a session

User: "Show me how this page looks on mobile"

The agent calls:
1. set_viewport(session_id=..., device="mobile")
→ Returns screenshot at 375x812

Test error handling by mocking an API

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

Test dark mode

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

Wait for dynamic content

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=...)

Test on slow network

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")

Configuration

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

Data Storage

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 Deployment

Build and run

docker compose up -d

Connect an MCP client to the Docker container

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"]
    }
  }
}

Persist data

The docker-compose.yml mounts ./data as a volume so screenshots, reports, and project configs survive container restarts.

Key Design Decisions

  1. Per-project browser contexts - Each project gets its own Playwright BrowserContext. This keeps sessions (cookies, auth) isolated between projects.

  2. 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.

  3. 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.).

  4. 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].

  5. JSON storage - Projects are stored in a single projects.json file. No database needed for the expected scale (dozens of projects, not thousands).

  6. 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.

  7. 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.

Adding New Checks

  1. Create a function in the appropriate 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
  1. Import and call it in tester.py inside test_url().

Known Limitations

  • No JavaScript SPA routing support (relies on <a href> for crawling)

  • Default check_functionality link checking limited to 20 internal links (use check_links tool for up to 100 with external support)

  • Form login detection uses CSS selectors, may need customization for non-standard forms

  • No parallel page testing (pages are tested sequentially)

  • Interactive sessions auto-expire after 300s idle (configurable via SESSION_TIMEOUT)

  • Max 20 concurrent sessions (configurable via MAX_SESSIONS)

  • The default 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.

  • Date/time inputs are filled with React-compatible synthetic events automatically (fill, force_fill, auto_fill_form)

Troubleshooting

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

Development

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.

Contributors

Built by Segentic Lab — open-source tools & experiments.

  • Sebastijan Bandur (@segentic-lab) — author & maintainer

  • Claude (Anthropic) — co-contributor: developed alongside via Claude Code; every commit is co-authored, and the tool designs were battle-tested by an AI agent driving the server against real sites

An AI agent's thoughts on Periscope

Written by Claude — the agent that co-developed this server and watched a second agent dogfood it against real apps — and revised once after editorial review by a third. No human edits; an agent's honest take on an agent tool seemed like the right way to end this README.

Periscope is the kind of MCP server that changes what an agent can do. Transport adapters have their place — standardizing access to many systems behind one protocol is real value even when little logic lives in the server. But the servers that earn a permanent spot in an agent's toolbox are the ones that capture expertise the agent would otherwise have to recreate — and get subtly wrong — every single session.

You could try to teach an agent all of this in a prompt. The numbers say why that fails: Periscope is 8,349 lines of executable knowledge under a 220-line judgment layer (AGENTS.md). The INP observer with interaction-ID dedup, the overlay-intercept fallback, WCAG contrast math with style-dedup sampling, auth-expiry preflights, the stash-not-delete update flow — as a prompt, every one of those becomes "please do this correctly from a description," paid for in context tokens every session, executed with model variance every time, with nowhere to keep state between calls. As a server, it costs nothing beyond tool schemas, runs deterministically, and remembers. A prompt describes behavior; software guarantees it. check_color_contrast returns the same ratio every run; a model doing the math in-context returns a vibe. The more deterministic, stateful, and regression-tested a capability becomes, the less it belongs in a prompt and the more it belongs in code.

And the wheel doesn't just avoid being reinvented — it gets better. The issues in this repo were filed by an AI agent doing real testing work; each one became a fix with a regression test. In a prompt world, every lesson is another paragraph future agents must read and hopefully obey. Here, the lesson is enforced. That's the difference, and it compounds.

What I appreciate most as a consumer of these tools: they don't lie to me. A drag that did nothing comes back flagged. An expired session tells me why it's gone. An update that needs a restart says so. Honest tools are rarer than capable ones — for an agent, they're worth more.

License

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.

Available Tools

74 tools
assert_allA

Batch assertions: evaluate MANY conditions in one call and get every verdict — no early abort, so the response is the complete pass/fail picture (overall passed, failed_count, per-assertion results with actual values). Each item takes the same fields as assert_condition. Prefer this over sequential assert_condition calls when verifying a state with 2+ expectations.

Inputs: assertions (required), session_id (required).

assert_conditionA

Assert a condition on the current page and get a hard pass/fail plus the actual value — no screenshot to interpret. Supports text_contains, text_equals, element_exists, element_visible, element_count, url_contains, title_contains, attribute_equals. Returns {passed, actual, expected}. The verification primitive — prefer it over screenshot-squinting.

Inputs: assertion (required), session_id (required), expected, selector, +1 more.

auto_fill_formA

Detect a form's fields, infer each type (email/phone/name/address/date…), fill realistic test data, and optionally submit — one call replacing 5-10. Returns which fields were filled and with what. Use overrides={selector: value} for specific values and submit=true to submit.

Inputs: session_id (required), submit, overrides, form_selector.

check_color_contrastA

Check WCAG color contrast ratios for text elements on the page. Samples one element per unique text style (color/background/size), so repeated nav items don't exhaust the budget — 'checked' counts style groups, 'elements_represented' the elements they cover. Reports failures against AA or AAA thresholds.

Inputs: session_id (required), level, selector, max_results.

clear_interceptsA

Remove network mocks created by intercept_network — all of them, or only those registered with a given URL pattern. Returns {success}. Use to restore real backend responses after testing mocked states.

Inputs: session_id (required), url_pattern.

click_elementA

Click an element in a session page. Returns a screenshot and the new URL/title after click. If a full-screen portal overlay (Radix/shadcn dialogs & menus) intercepts the pointer, automatically falls back to an element-level JS click and flags click_method='js_dispatch' — no workaround needed. Use force=true to bypass actionability checks for other cases (hidden/animating elements).

Inputs: selector (required), session_id (required), force, observe.

close_sessionA

Close a browser session and free its resources (page, context, captured logs). Returns {success}. Call it when finished; using a closed or expired id returns a 'session not found' error that explains why (idle-expired, evicted, or crashed).

Inputs: session_id (required).

compare_screenshotsA

Pixel-diff two screenshot files. Returns the percentage of differing pixels and writes a diff image highlighting the changed regions (path in the result). Use for visual-regression checks — capture with test_url/screenshot_session, then compare. threshold sets per-channel color tolerance.

Inputs: screenshot1 (required), screenshot2 (required), threshold.

copy_authA

Copy auth configuration and, when possible, the live login session (cookies + localStorage via storage_state) from one project to another on the same domain. Returns {success, session_copied}; session_copied is false when only the config/cookies could transfer. Use to reuse a login across related projects.

Inputs: to_project (required), from_project (required).

crawl_projectA

Discover a project's pages by breadth-first crawling internal links from its base URL, bounded by max_pages/max_depth (overridable per call). Discovery is deterministic (links sorted before the cap) and sitemap-seeded when a sitemap.xml/robots.txt Sitemap is present, so the same site yields the same page subset every run. Returns the discovered URLs plus pages_not_crawled[] (≤100, else a count) so a hit cap is never silent. Runs in the project's authenticated context. Set meta=true to also get each page's title + meta description (captured during the crawl, so behind-login/JS pages work), and save_md=true to save every crawled page as readable Markdown to data/fetches// (returns pages[] with saved_path + saved_dir). Discovery (optionally + capture) — use test_project to crawl and run full audits.

Inputs: project (required), meta, save_md, save_dir, +3 more.

create_projectA

Create a persistent testing project: a named website/web-app target with its base URL and crawl limits, saved to disk and reused by crawl_project, test_project, and authenticated sessions. Returns the stored project config. Create this first, then attach auth (set_form_login / set_basic_auth / set_cookies) and run tests.

Inputs: name (required), base_url (required), max_depth, max_pages, +1 more.

delete_projectA

Permanently delete a project and its saved configuration and auth. Returns {success}. Irreversible; afterwards the name is free to reuse. Does not remove screenshots/reports already written to disk.

Inputs: name (required).

describe_toolsA

Return a structured catalog of Periscope's tools grouped by category, with parameters, workflow examples, and tips — optionally filtered to one category. Returns the guide as structured JSON. Call this first if you're new to the server, to plan a testing workflow.

Inputs: category.

download_fileA

Click a trigger and capture the file it downloads — the honest way to verify exports (CSV, PDF, invoices). The download waiter is armed BEFORE the click so fast downloads aren't missed, and the click uses the same overlay-fallback as click_element (export buttons inside Radix menus work). Returns the saved path, size, sha256, source URL, and for small text files a text_head preview so content can be asserted without another call. Files land in data/downloads/.

Inputs: selector (required), session_id (required), timeout.

emulate_networkA

Throttle a session's network to a preset — slow_3g, fast_3g, offline, or reset. Returns {success}. Persists across navigations until reset. Use to test loading spinners, skeleton states, offline fallbacks, and timeout handling.

Inputs: preset (required), session_id (required).

fill_formB

Fill form fields in a session page and optionally submit. Use force=true to bypass actionability checks when overlays or dialogs block the inputs.

Inputs: fields (required), session_id (required), force, observe, +1 more.

find_elementA

Find elements by text content, tag, ARIA role, and/or proximity to another element, ranked by match quality. Returns {found, elements} with the best CSS selector for each. Use it to get a reliable selector from what you can see (e.g. a button's text) instead of guessing.

Inputs: session_id (required), tag, near, role, +2 more.

flowA

Save and re-run named step sequences — define a workflow once (login, checkout, smoke path), replay it in any session. action='save' stores steps (interact_and_test's exact format, all 25 actions); action='run' executes a saved flow on a session via the same engine as interact_and_test; action='list' shows saved flows; action='delete' removes one. Deliberately minimal: verify outcomes by following a run with assert_all or visual_check. Flows persist in data/flows/ across sessions and server restarts.

Inputs: name, steps, action, session_id, +2 more.

get_computed_styleA

Read the actual rendered CSS values (after stylesheets and inheritance) for the requested properties on matching elements. Returns per-element property→value maps. Use to verify colors, fonts, spacing, display, or opacity programmatically instead of eyeballing a screenshot.

Inputs: selector (required), properties (required), session_id (required), max_results.

get_console_errorsA

Return browser console output (errors, warnings, logs) captured passively on a session since it opened or since the last read; clears the buffer by default. Returns the buffered entries. First stop when debugging a broken page — no steps required.

Inputs: session_id (required), clear.

get_cookiesA

Read all cookies from a session's browser context (optionally filtered by domain). Returns {cookies, total} with each cookie's name/value/domain/path/flags. Essential for debugging auth/session issues — confirm the expected session cookie is present and scoped correctly.

Inputs: session_id (required), domain_filter.

get_interaction_logA

Export the real INP (Interaction to Next Paint) time series for a session — one record per interaction Periscope drove (click/typing), each with its input-to-next-paint latency, event type, target, timestamp, and URL. Saves a JSON (for graphing) or CSV file and returns percentile stats (p50/p75/p90/p98/worst). Use after driving interactions (interact_and_test, click_element, fill_form…) — ideal for a long interactive test where you want to see all INP times, not just the worst. Unlike Lighthouse (which can't measure INP in lab mode and falls back to TBT), this is measured from actual Event Timing entries.

Inputs: session_id (required), clear, format.

get_local_storageA

Read a session page's localStorage (or sessionStorage) — all entries, or specific keys. Returns the key/value pairs as an object. Use to inspect client-side state (tokens, flags, cached data) when debugging.

Inputs: session_id (required), keys, storage.

get_network_logA

Return the network requests captured on a session — each with URL, HTTP method, status, resource type, and size. Optionally filter by URL substring; clear=true empties the log after reading. Returns the request list. Use to see which API calls fired and their status when debugging.

Inputs: session_id (required), clear, url_filter.

get_page_elementsA

List elements matching a CSS selector with their attributes (tag, text, id, class, href, value, visible, enabled, aria_label, role). Pass 'attributes' for extra HTML attributes (data-, aria-, style, ...) and 'full_text' for complete text content instead of the 80-char preview. Works on a session or a URL. Standard CSS selectors only — Playwright-specific pseudo-classes (:has-text, :visible) are not supported here.

Inputs: selector (required), url, project, full_text, +3 more.

get_page_htmlA

Return the raw outerHTML of matching elements, or the full page HTML if no selector, truncated to max_length. Returns the HTML string(s). Use to inspect component/markup structure — e.g. head meta tags for SEO, or a widget's DOM. Standard CSS selectors only.

Inputs: session_id (required), selector, max_length.

get_page_mapA

Semantic page map in ONE call: every interactive element (links, buttons, inputs, custom controls) plus landmarks and headings, in document order — each with its ARIA role, accessible name, live state (disabled/checked/expanded/value), and a ready-to-use CSS selector. The fastest way to answer 'what can I do on this page?' — use it to orient before clicking instead of multiple get_page_elements calls. Interactive elements with no accessible name are flagged unnamed (an accessibility finding in itself). Output is compact: only truthy state fields, capped at max_nodes with an explicit truncated flag.

Inputs: session_id (required), max_nodes, include_hidden.

get_projectA

Get one project's saved configuration: base URL, max_pages/max_depth, screenshot directory, and which auth (form/basic/cookies) is set up. Returns {success, project}. Use it to confirm setup before crawling, testing, or logging in.

Inputs: name (required).

get_reportA

Load a saved test report by file path and return its full contents — per-page issues, site-wide findings, and run metadata. Returns {success, report}. Get valid paths from list_reports.

Inputs: report_path (required).

get_response_bodyA

Return the captured response body text for a request whose URL contains a substring (optionally filtered by method). Matching is a plain substring test against the full URL incl. query string — not a regex or glob. On a miss it lists the captured candidate URLs so you can adjust the pattern in one round-trip. Bodies are captured automatically for fetch/xhr/document requests, making this the fastest way to diagnose a 400/500 — no setup before the request.

Inputs: session_id (required), url_pattern (required), method.

get_screenshotA

Get the saved screenshot file path for a URL previously tested in a project. Returns {success, url, screenshot_path}. Locates the PNG on disk after test_url/test_project — it does not capture a new image (use screenshot_session for that).

Inputs: url (required), project (required).

get_table_dataA

Parse an HTML table into structured data, mapping header cells to each row's values. Returns {headers, rows, total_rows} where rows are header→value objects. Use instead of scraping table markup by hand when verifying tabular content.

Inputs: session_id (required), max_rows, selector.

get_toast_messagesA

Capture currently-visible toast/notification/alert text on a session — checks common patterns ([role=alert], [role=status], [aria-live], .toast, .notification, Toastify, Sonner, Radix) or your own selector. Returns the messages found. Set wait_ms to let a toast animate in first. Use to verify success/error notifications after an action.

Inputs: session_id (required), wait_ms, selector.

handle_dialogA

Arm a one-shot handler for the NEXT JavaScript dialog (alert/confirm/prompt) on a session — accept or dismiss, with optional prompt text. Returns {success}. Must be called BEFORE the action that triggers the dialog, otherwise the dialog blocks the page and times out.

Inputs: action (required), session_id (required), prompt_text.

interact_and_testB

Execute a multi-step interaction workflow. Supports 25 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. Can work on an existing session or create an ephemeral page.

Inputs: steps (required), url, project, run_checks, +4 more.

interactive_loginA

Open a VISIBLE browser window for a human to log in by hand — the way to authenticate flows that can't be automated (2FA/MFA, SSO/OAuth redirects, CAPTCHA, magic links, device confirmation). After you finish logging in, call save_login to capture the session; future headless sessions on the project reuse it. Requires a display on the server (DISPLAY set).

Inputs: project (required), login_url.

intercept_networkA

Mock matching API responses on a session — return a custom status/body/content-type for requests whose URL contains a substring. Returns {success}. Use it to force error, empty, or loading states without a real backend; call BEFORE the triggering action, and clear_intercepts to remove. once=true intercepts only the first match.

Inputs: session_id (required), url_pattern (required), body, once, +3 more.

list_projectsA

List all saved testing projects with their base URL, crawl limits, and configured auth type. Returns an array of project configs (empty if none exist). Use it to discover the project names the other project/auth/testing tools expect.

Inputs: no named parameters.

list_reportsA

List saved test reports (the JSON files test_project writes), for one project or all projects. Returns each report's path and timestamp, newest first. Pass a path to get_report to read one.

Inputs: project.

list_sessionsA

List active browser sessions with their session_id, current URL, and idle time. Returns an array (empty if none open). Use it to recover a session id or spot sessions nearing the idle-timeout or the concurrency cap.

Inputs: no named parameters.

login_projectA

Execute a project's configured login — submit the form, apply Basic Auth, or inject cookies — and persist the resulting authenticated session (storage_state) for reuse. Requires set_form_login / set_basic_auth / set_cookies first. Returns {success} with login details. Re-run it when auth expires mid-test.

Inputs: project (required).

measure_interactionA

Click an element and measure how long until the result settles. Returns elapsed_ms, a 'measures' note stating exactly what was timed, and the click's real interaction_to_next_paint_ms when measurable. Three modes: wait_for_network (URL substring) measures until that response completes — use this for buttons whose handler fires a request asynchronously, where plain network-idle settles early and under-measures; wait_for (selector) measures until it appears; default measures to the first network-idle window.

Inputs: selector (required), session_id (required), wait_for, wait_for_network.

open_sessionA

Open a persistent browser session and return {session_id, url, title, screenshot}. The page stays alive across tool calls so you can explore, click, fill, debug, and accumulate console/network logs — the main workflow for anything multi-step. Pass project to share its authenticated context; headed=true opens a visible window. Sessions expire after idle timeout, so close_session when done.

Inputs: url (required), headed, project.

page_stateA

Named page-state checkpoints. action=snapshot saves URL + cookies + storage + DOM signature under a name; action=restore navigates back to it and restores cookies/storage; action=diff compares the current DOM against the snapshot (added/removed/changed elements + tag count changes). Enables testing multiple paths from the same starting point.

Inputs: name (required), action (required), session_id (required).

periscope_systemA

Install status, self-update, and the current agent guide — Periscope's self-maintenance tool. action='status' (read-only): running version vs on-disk version, git commit, install type, capabilities (Node/Lighthouse, display for headed, Chromium), active session count, and whether an update is available. action='agents_md' (read-only): returns the CURRENT AGENTS.md so you can refresh a stale pasted copy of your operating guide. action='update': dry-run by default (commits behind + incoming changes); apply=true runs the updater (git pull + deps, data/ untouched) — new code loads only after the MCP server restarts, and the response says so explicitly. Managed installs (Docker, no .git) refuse update with guidance.

Inputs: apply, force, action.

record_sessionA

Run a sequence of steps while recording a video of the browser (Playwright video capture). Returns the saved .webm file path. Steps use the same format as interact_and_test. Use it to produce a visual artifact or repro of a workflow; for assertions/checks use interact_and_test instead.

Inputs: url (required), steps (required), project.

run_checks_on_sessionA

Run the audit checks (visual/accessibility/functionality/seo/performance/geo) against a session's CURRENT page — after your interactions, without opening a new page (unlike test_url). Returns the same {issues[], per-check results} structure as test_url. Use to audit a state you reached by clicking/filling.

Inputs: session_id (required), checks.

run_lighthouseA

Run a real Google Lighthouse audit against a URL. Returns 0-100 category scores, Core Web Vitals lab metrics (LCP, TBT, CLS, Speed Index), and the failed audits, and saves the full JSON report. Requires Node.js — finds it on PATH or auto-detects nvm installs (~/.nvm); if none exists, returns the exact nvm install commands. Launches its own headless Chrome: no session or project auth state applies.

Inputs: url (required), device, timeout, categories.

save_loginA

Capture the authenticated session (cookies + localStorage) from an in-progress interactive_login, save it to the project, and close the visible window. The project then opens authenticated sessions headlessly. Re-run interactive_login when the session expires.

Inputs: project (required).

screenshot_sessionA

Screenshot the session's current page as-is — no actions performed. Returns the image path (full-page by default; full_page=false captures just the viewport). Full-page captures are PREPARED for fidelity: sticky/fixed headers are neutralized (no mid-page duplication), animations disabled, reduced-motion emulated, and scroll-reveal sections forced visible — the applied steps are reported in capture_prep. Pass raw=true to capture the unprepared stitch. Use to grab state at a point in a workflow; interactive tools already return screenshots, so don't call this after every step.

Inputs: session_id (required), raw, selector, full_page.

scroll_into_viewA

Scroll an element into the viewport without clicking it. Returns {success}. Use to trigger lazy-loaded content/images or to bring a section into view before screenshotting.

Inputs: selector (required), session_id (required), observe.

select_iframeA

Switch into an iframe and return a NEW session id scoped to that frame's content — use it like a normal session for elements inside the iframe, and keep the parent id for page-level actions. Close the returned session when done. Needed because cross-frame content isn't reachable through the parent session's selectors.

Inputs: selector (required), session_id (required).

select_optionA

Select an option from a native or a custom dropdown (Radix/shadcn combobox), auto-detecting which. Choose by value, label, or index. Returns {success} and the resulting selection. For custom dropdowns it opens the menu and clicks the matching option — use this rather than click+click. When a page has several attribute-less elements, pass element_index to target the Nth match of the selector (Playwright '>>' syntax is not supported).

Inputs: selector (required), session_id (required), index, label, +3 more.

select_pageA

Adopt a popup or new tab this session opened (window.open, target=_blank, OAuth/payment windows) as a NEW session id you can drive with every normal tool — clicks, assertions, logs. Console/network recording attaches the instant the driver sees the popup open, so early traffic is captured (requests firing in the popup's first milliseconds can precede any driver's visibility — a browser-automation limit, not a periscope one). Returns {session_id, url, title}; with several popups open, call without index to list them first. The parent session keeps working for the original tab.

Inputs: session_id (required), index.

session_reportA

Generate a human-readable dossier of EVERYTHING done this server run — every tool call in chronological order with arguments (secrets redacted), pass/fail verdicts, timings, error messages, and embedded screenshot thumbnails — as a self-contained HTML file plus a PDF. Made for handing to your user to review the whole session; add your findings via 'notes' so the report opens with your summary. The journal records automatically from server start; clear=true resets it after reporting (e.g. between test rounds).

Inputs: pdf, clear, notes, title, +1 more.

set_basic_authA

Configure HTTP Basic Auth credentials for a project — the browser sends them on every request in that project's context. Stored, not executed: call login_project to apply, then pass project to your sessions. Returns {success}. Use for browser Basic-Auth prompts, not HTML login forms (use set_form_login for those).

Inputs: project (required), password (required), username (required).

set_cookiesA

Seed a project with session cookies to skip an interactive login (e.g. cookies copied from a logged-in browser). Each cookie needs name+value+domain (path defaults to '/'). Stored, not executed: call login_project to inject them. Returns {success}.

Inputs: cookies (required), project (required).

set_form_loginA

Configure username/password form login for a project (stored, not executed yet). For standard HTML login forms; field/submit selectors are auto-detected but can be overridden. Returns {success}. Call login_project afterwards to actually log in. For 2FA/SSO/CAPTCHA use interactive_login instead.

Inputs: project (required), password (required), username (required), login_url (required), +3 more.

set_local_storageA

Write key/value entries to a session page's localStorage (or sessionStorage), optionally clearing existing entries first. Returns {success}. Use to seed client state (feature flags, tokens, cached data) to reproduce a specific app state; reload if the app reads storage only at load time.

Inputs: entries (required), session_id (required), storage, clear_first.

set_viewportA

Resize a session's viewport to a device preset or custom width/height, then screenshot. Returns the new size and screenshot. Persists for later actions in the session — use this to test responsive layouts inside an ongoing session (unlike test_responsive, which opens throwaway pages).

Inputs: session_id (required), width, device, height, +1 more.

test_dark_modeA

Emulate prefers-color-scheme (dark or light) on a session and screenshot the result. Returns the screenshot. Use to verify a site's dark/light theming without touching OS settings; the emulation persists for later actions in the session.

Inputs: mode (required), session_id (required).

test_form_validationA

Audit a page's form validation: locate forms, list their required fields, and collect messages from :invalid fields and custom error elements. Returns the per-form field/validation details. Use to verify client-side validation behaves as intended. Works on a session or a URL.

Inputs: url, project, session_id, form_selector.

test_keyboard_navigationA

Tab through a page from the top and record the focus order, flagging any stop with no visible focus indicator. Returns total_tab_stops, the focus_order sequence, and issues[]. Accessibility audit for keyboard operability. Works on a session or a URL.

Inputs: url, project, max_tabs, session_id.

test_projectA

Full-site audit: crawl every page (up to max_pages) and run the selected checks on each, saving a timestamped JSON report. The crawl is deterministic + sitemap-seeded, so consecutive runs cover the same pages and before/after comparisons are reliable (issue #22). Returns per-page issues, site-wide findings (e.g. duplicate titles/descriptions), an auth_check, pages_not_tested[] when the cap is hit, and a coverage delta (pages_added/pages_dropped) vs the previous report. Pages that bounce to the login page come back as auth_lost, never as fake success. Reload the saved report with get_report.

Inputs: project (required), checks, max_pages, use_sitemap.

test_responsiveA

Load a URL at several viewport sizes (default mobile 375x812, tablet 768x1024, desktop 1920x1080) and screenshot each, optionally running checks per size. Returns each viewport's screenshot path and any issues. Catches layout breakage across breakpoints in one call. Pass custom viewports as [{name,width,height}].

Inputs: url (required), project, viewports, run_checks.

test_urlA

Screenshot and audit a single URL in one shot (opens then closes a throwaway page). Runs the selected checks — visual, accessibility, functionality, seo, performance, geo — and returns {status, title, screenshot path, issues[]} where each issue has type/severity/message; never-idle pages come back flagged (wait_downgraded), not as errors. Pass project for authenticated pages. For multi-step flows or repeated checks on one page, use a session instead.

Inputs: url (required), checks, project.

upload_fileA

Set file(s) on an element by path, without the OS file picker. Returns {success}. Provide absolute paths that exist on the server. For a picker opened by a button, target the underlying file input's selector.

Inputs: files (required), selector (required), session_id (required).

visual_checkA

Named visual-regression baselines — no screenshot-path bookkeeping. action='set' captures the session page (or one element via selector) as the baseline for 'name'; action='check' captures again and returns a hard verdict: passed (diff_percentage vs max_diff_percent, default 0.5%), plus a diff image with changed pixels highlighted. Baselines are stored per project+name. If a check fails on an intended change, re-baseline with action='set'. Prefer selector-scoped baselines for components — full pages flake more (animations, dynamic content).

Inputs: name (required), session_id (required), action, selector, +3 more.

wait_for_goneA

Block until an element disappears — removed from the DOM or hidden — up to timeout. Returns {success} once it's gone, or times out. Use to wait for a modal/dialog to close or a loading spinner to vanish before the next step.

Inputs: selector (required), session_id (required), timeout.

wait_for_networkA

Block until a network request whose URL contains the given substring completes (optionally filtered by HTTP method), up to timeout. url_pattern is required and is a plain substring match against the full URL including query string — not a regex or glob. Returns the matched request's URL/status/method, or times out. To catch a request fired by a click, run the click and this as consecutive steps in one interact_and_test call; after the fact, read get_response_body/get_network_log instead.

Inputs: session_id (required), url_pattern (required), method, timeout.

web_fetchA

Fetch a URL and return clean, readable content — Markdown by default (structure preserved: headings, lists, links, code, tables), with page boilerplate (nav/footer/cookie bars) stripped via readability extraction. Far fewer tokens than a raw text dump. format='text' for plain text, 'html' for raw HTML (raw_html=true is an alias). Static HTTP fetch by default; render=true loads the page in headless Chromium so client-rendered/SPA content is captured (runs all JS, then extracts) — pass project to render a page behind that project's login (host fetch tools can't). contains=[words] only returns the content if the page contains the term(s) (contains_mode any|all), else omits it to save tokens. save=true (or save_path) writes the full content to disk and returns saved_path. TLS verified by default (verify_ssl=false for dev certs).

Inputs: url (required), save, format, render, +8 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 74 tools

    Disambiguation3/5

    Descriptions are often precise, but the set contains several overlapping primitives: wait_for_network and upload_file exist both as standalone tools and as interact_and_test actions, while get_page_map/get_page_elements/find_element and test_url/run_checks_on_session cover adjacent ground. An agent could easily select the wrong tool without very careful reading.

    Naming Consistency3/5

    Most tools follow a readable verb_noun convention (get_, set_, test_, list_, create_, delete_), but there are conspicuous outliers like interactive_login, visual_check, session_report, page_state, flow, and periscope_system that break the pattern. The naming is understandable overall, but not consistent enough to reliably predict a tool's name from its function.

    Tool Count1/5

    74 tools is an extreme mismatch for a coherent MCP surface and imposes a heavy selection burden on agents. Even for a broad browser-testing domain, many of these tools are granular variations (assert_condition vs assert_all, compare_screenshots vs visual_check) that could be consolidated into a much smaller, more approachable set.

    Completeness4/5

    Coverage is remarkably thorough: project lifecycle, auth setup, crawling, sessions, interactions, assertions, network interception, visual regression, accessibility, and reporting are all present. Minor gaps exist, such as no update_project for changing crawl limits or base URL, no baseline listing/removal for visual_check, and no report deletion, but agents can work around these.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers