`; `aria-hidden` elements exempt)\n- Form inputs without associated labels (`label[for]`, wrapping label, `aria-label`/`aria-labelledby`, `title`)\n- Heading hierarchy (missing H1, multiple H1, skipped levels)\n- Missing `lang` attribute on `<html>`\n- Duplicate `id` values (break `label[for]` and aria references)\n- ARIA validity: unknown `role` values, `aria-labelledby`/`describedby`/`controls`/`owns`/`activedescendant` references to non-existent ids\n- Missing skip navigation link (scans the first 5 links)\n- Elements with `tabindex > 0`\n- Keyboard navigation audit (tab order, visible focus indicators, element-identity cycle detection) — via `test_keyboard_navigation` tool\n\n### Functionality (`checks/functionality.py`)\n- Broken internal links (HTTP HEAD check, up to 20 links in `check_functionality`)\n- Comprehensive link checker with external link support (up to 100 links) — via `check_links` tool\n- Forms without action or submit button\n- Orphan buttons outside forms\n- External links missing `target=\"_blank\"`\n- Required form field count\n- Autocomplete disabled inputs\n\n### SEO (`checks/functionality.py` -> `check_seo`)\n- Page title: missing, too long (> 60 chars), or very short (< 15 chars)\n- Meta description: missing, too long (> 160 chars), or very short (< 50 chars)\n- Missing viewport meta tag\n- Missing canonical URL\n- H1 heading: missing or more than one\n- Open Graph: missing entirely, incomplete core tags (`og:title/description/image/url`), non-absolute `og:image`, missing `twitter:card`\n- JSON-LD structured data: missing or unparseable blocks\n- `noindex` via robots meta **or** `X-Robots-Tag` response header\n- robots.txt blocking search engine crawlers (Googlebot, Bingbot, DuckDuckBot, ...) — error if all are blocked\n- Site-wide (via `test_project`): duplicate titles / meta descriptions across pages, reported under `site_issues`\n\n### GEO / Agentic Search (`checks/geo.py` -> `check_geo`)\n\nGenerative Engine Optimization — is the site readable and usable by AI crawlers, answer engines, and in-browser agents:\n\n- robots.txt blocking AI crawlers (GPTBot, ClaudeBot, PerplexityBot, Google-Extended, CCBot, and 11 more)\n- `llms.txt` presence and format compliance (Markdown with at least one H1)\n- 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\n- JSON-LD structured data presence (what answer engines cite from)\n\nrobots.txt and llms.txt are fetched once per origin and cached for the server's lifetime.\n\n### Performance (`checks/functionality.py` -> `get_performance_metrics`)\n- DOM content loaded time (ms)\n- Full page load time (ms)\n- First paint / first contentful paint (ms)\n- 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)\n- **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.\n- Resource count\n- Total transfer size (bytes / KB)\n\nFor 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/`.\n\n### INP time series (`get_interaction_log`)\n\nBecause Periscope drives *real* interactions, it can log each one's INP over an\nextended interactive test. `get_interaction_log(session_id, format=\"json\"|\"csv\")`\nwrites a file to `data/reports/` — one row per interaction (`t_ms`, `epoch_ms`,\n`inp_ms`, `type`, `target`, `url`) plus percentile stats (p50/p75/p90/p98/worst)\n— for graphing INP over time. `clear=true` resets the recording. Records are\ncapped per session (`MAX_INTERACTION_LOG`, oldest dropped).\n\n## Test Output Format\n\nEach `test_url` call returns:\n\n```json\n{\n \"url\": \"https://example.com\",\n \"status\": \"success\",\n \"status_code\": 200,\n \"title\": \"Page Title\",\n \"screenshot_path\": \"/path/to/screenshot.png\",\n \"load_time_ms\": 1500,\n \"issues\": [\n {\n \"type\": \"accessibility\",\n \"severity\": \"error\",\n \"message\": \"3 images missing alt text\",\n \"details\": [\"img1.png\", \"img2.png\", \"img3.png\"]\n }\n ],\n \"issue_count\": 5,\n \"issues_by_severity\": {\"error\": 1, \"warning\": 2, \"info\": 2},\n \"issues_by_type\": {\"accessibility\": 2, \"seo\": 2, \"visual\": 1},\n \"performance\": {\n \"dom_content_loaded_ms\": 120,\n \"load_complete_ms\": 1500,\n \"first_paint_ms\": 140,\n \"first_contentful_paint_ms\": 140,\n \"resource_count\": 25,\n \"total_size_bytes\": 512000,\n \"total_size_kb\": 500\n },\n \"console_errors\": []\n}\n```\n\n`test_project` returns an aggregated report with per-page results + summary.\n\n## Usage Examples\n\n### Basic test (no auth)\n```\nUser: \"Test https://example.com for issues\"\n\nThe agent calls:\n1. create_project(name=\"example\", base_url=\"https://example.com\")\n2. test_project(project=\"example\")\n3. Analyzes results and reports findings\n```\n\n### Test with login\n```\nUser: \"Test https://myapp.com, login is admin/password123\"\n\nThe agent calls:\n1. create_project(name=\"myapp\", base_url=\"https://myapp.com\")\n2. set_form_login(project=\"myapp\", login_url=\"https://myapp.com/login\",\n username=\"admin\", password=\"password123\")\n3. login_project(project=\"myapp\")\n4. test_project(project=\"myapp\")\n```\n\n### Test with Basic Auth\n```\nUser: \"Test https://staging.example.com, it uses basic auth admin/secret\"\n\nThe agent calls:\n1. create_project(name=\"staging\", base_url=\"https://staging.example.com\")\n2. set_basic_auth(project=\"staging\", username=\"admin\", password=\"secret\")\n3. login_project(project=\"staging\")\n4. test_project(project=\"staging\")\n```\n\n### Test with cookies\n```\nUser: \"Test myapp using this session cookie: session=abc123\"\n\nThe agent calls:\n1. set_cookies(project=\"myapp\", cookies=[\n {\"name\": \"session\", \"value\": \"abc123\", \"domain\": \"myapp.com\"}\n ])\n2. test_project(project=\"myapp\")\n```\n\n### Interactive testing (session-based)\n```\nUser: \"Go to myapp.com, click the login button, fill in the form, and check what happens\"\n\nThe agent calls:\n1. open_session(url=\"https://myapp.com\") → session_id\n2. get_page_elements(session_id=..., selector=\"button, a\") → see clickable elements\n3. click_element(session_id=..., selector=\"#login-btn\") → screenshot after click\n4. fill_form(session_id=..., fields=[\n {\"selector\": \"#email\", \"value\": \"user@test.com\"},\n {\"selector\": \"#password\", \"value\": \"test123\"}\n ], submit_selector=\"button[type='submit']\")\n5. Analyzes screenshot to see result\n6. close_session(session_id=...)\n```\n\n### Scripted multi-step workflow (no session needed)\n```\nUser: \"Test the checkout flow on myshop.com\"\n\nThe agent calls:\n1. interact_and_test(\n url=\"https://myshop.com/products/1\",\n steps=[\n {\"action\": \"click\", \"selector\": \"#add-to-cart\"},\n {\"action\": \"wait\", \"timeout\": 1000},\n {\"action\": \"click\", \"selector\": \"#checkout-btn\"},\n {\"action\": \"fill\", \"selector\": \"#email\", \"value\": \"test@test.com\"},\n {\"action\": \"screenshot\", \"label\": \"checkout_form\"},\n {\"action\": \"click\", \"selector\": \"#submit-order\"}\n ],\n run_checks=[\"visual\", \"accessibility\"]\n )\n```\n\n### Responsive testing\n```\nUser: \"Check how example.com looks on mobile, tablet, and desktop\"\n\nThe agent calls:\n1. test_responsive(url=\"https://example.com\", run_checks=[\"visual\"])\n→ Returns screenshots at 375x812, 768x1024, and 1920x1080\n```\n\n### Switch viewport during a session\n```\nUser: \"Show me how this page looks on mobile\"\n\nThe agent calls:\n1. set_viewport(session_id=..., device=\"mobile\")\n→ Returns screenshot at 375x812\n```\n\n### Test error handling by mocking an API\n```\nUser: \"What happens when the API returns a 500 error?\"\n\nThe agent calls:\n1. intercept_network(session_id=..., url_pattern=\"/api/tasks\", status=500,\n body='{\"error\": \"Internal server error\"}')\n2. navigate_session(session_id=..., action=\"reload\")\n3. screenshot_session(session_id=...)\n→ Shows how the app handles the error state\n```\n\n### Test dark mode\n```\nUser: \"Does this site support dark mode?\"\n\nThe agent calls:\n1. open_session(url=\"https://example.com\") → session_id\n2. test_dark_mode(session_id=..., mode=\"dark\")\n→ Screenshot shows the page with prefers-color-scheme: dark\n```\n\n### Wait for dynamic content\n```\nUser: \"Submit this form and wait for the success message\"\n\nThe agent calls:\n1. fill_form(session_id=..., fields=[...], submit_selector=\"#submit\")\n2. wait_for_network(session_id=..., url_pattern=\"/api/submit\")\n3. screenshot_session(session_id=...)\n```\n\n### Test on slow network\n```\nUser: \"How does this page load on a slow connection?\"\n\nThe agent calls:\n1. emulate_network(session_id=..., preset=\"slow_3g\")\n2. navigate_session(session_id=..., action=\"reload\")\n3. screenshot_session(session_id=...)\n4. emulate_network(session_id=..., preset=\"reset\")\n```\n\n## Configuration\n\nEdit `config.py` to change defaults (env-overridable settings note the variable):\n\n| Setting | Default | Description |\n|---------|---------|-------------|\n| `HEADLESS` | `True` | Run Chrome in headless mode (env: `HEADLESS=false`) |\n| `STARTUP_PAUSE` | `10` | Seconds to wait after a non-headless browser opens (env: `STARTUP_PAUSE`) |\n| `TIMEOUT` | `30000` | Page load timeout (ms) |\n| `VIEWPORT_WIDTH` | `1920` | Browser viewport width |\n| `VIEWPORT_HEIGHT` | `1080` | Browser viewport height |\n| `CHROMIUM_PATH` | unset | Path to a system Chromium binary (env: `CHROMIUM_PATH`); unset = Playwright's bundled build |\n| `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) |\n| `MAX_PAGES` | `20` | Default max pages to crawl |\n| `MAX_DEPTH` | `3` | Default max crawl depth |\n| `MAX_SESSIONS` | `20` | Max concurrent interactive sessions (env: `MAX_SESSIONS`) |\n| `SESSION_TIMEOUT` | `300` | Auto-expire idle sessions after N seconds (env: `SESSION_TIMEOUT`) |\n| `MAX_RESPONSE_BODY_SIZE` | `512000` | Max bytes captured per response body |\n| `MAX_RESPONSE_BODIES` | `100` | Max captured response bodies kept per session |\n| `MAX_CONSOLE_LOG` | `500` | Max console entries kept per session |\n| `MAX_NETWORK_LOG` | `1000` | Max network log entries kept per session |\n\n## Data Storage\n\nAll data is stored in the `data/` directory:\n\n- **`data/projects.json`** - Project configs (name, URL, auth, settings). Auth credentials are stored in plaintext - do not commit this file.\n- **`data/screenshots/{project}/`** - PNG screenshots per project. Filenames are `{domain}_{path}_{hash}.png` for static tests, `interactive_{timestamp}_{label}.png` for session screenshots.\n- **`data/reports/{project}_{timestamp}.json`** - Full test reports with all findings.\n- **`data/videos/{project}/`** - Recorded session videos (WebM format from Playwright).\n- **`data/diffs/`** - Screenshot comparison diff images.\n\n## Docker Deployment\n\n### Build and run\n\n```bash\ndocker compose up -d\n```\n\n### Connect an MCP client to the Docker container\n\nPoint your client's MCP config at the container instead of the venv:\n\n```json\n{\n \"mcpServers\": {\n \"periscope\": {\n \"command\": \"docker\",\n \"args\": [\"exec\", \"-i\", \"periscope\", \"python\", \"/app/server.py\"]\n }\n }\n}\n```\n\n### Persist data\n\nThe `docker-compose.yml` mounts `./data` as a volume so screenshots, reports, and project configs survive container restarts.\n\n## Key Design Decisions\n\n1. **Per-project browser contexts** - Each project gets its own Playwright BrowserContext. This keeps sessions (cookies, auth) isolated between projects.\n\n2. **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.\n\n3. **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.).\n\n4. **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]`.\n\n5. **JSON storage** - Projects are stored in a single `projects.json` file. No database needed for the expected scale (dozens of projects, not thousands).\n\n6. **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.\n\n7. **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.\n\n## Adding New Checks\n\n1. Create a function in the appropriate `checks/*.py` file:\n\n```python\nasync def check_something(page: Page) -> list[dict]:\n # Run your check\n result = await page.evaluate(\"() => { ... }\")\n\n issues = []\n if result:\n issues.append({\n \"type\": \"your_category\", # visual, accessibility, seo, etc.\n \"severity\": \"error\", # error, warning, info\n \"message\": \"Description\",\n \"details\": [] # optional\n })\n return issues\n```\n\n2. Import and call it in `tester.py` inside `test_url()`.\n\n## Known Limitations\n\n- No JavaScript SPA routing support (relies on `<a href>` for crawling)\n- Default `check_functionality` link checking limited to 20 internal links (use `check_links` tool for up to 100 with external support)\n- Form login detection uses CSS selectors, may need customization for non-standard forms\n- No parallel page testing (pages are tested sequentially)\n- Interactive sessions auto-expire after 300s idle (configurable via `SESSION_TIMEOUT`)\n- Max 20 concurrent sessions (configurable via `MAX_SESSIONS`)\n- 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`.\n- Date/time inputs are filled with React-compatible synthetic events automatically (`fill`, `force_fill`, `auto_fill_form`)\n\n## Troubleshooting\n\n| Problem | Solution |\n|---------|----------|\n| `Executable doesn't exist` | Run `playwright install chromium` |\n| `'NoneType' has no attribute 'new_context'` | Browser failed to launch. Check Chromium is installed. Server will auto-retry on next call. |\n| Login not working | Try providing explicit CSS selectors via `username_selector`, `password_selector`, `submit_selector` |\n| Timeout on page load | Increase `TIMEOUT` in `config.py` or check if site requires VPN/auth |\n| Docker can't reach website | Ensure the container has network access. Use `network_mode: host` if testing localhost |\n\n## Development\n\n```bash\npip install -r requirements-dev.txt\npytest --ignore=tests/e2e # unit tests, no browser required\npytest tests/e2e # behavioral tests: real headless Chromium against\n # fixture pages in tests/e2e/fixtures/ (~30s)\n```\n\nThe e2e suite covers session lifecycle, network waits/intercepts, console\ncapture, dialogs, drag-and-drop (including the pointer-tracking DnD silent\nno-op), the check modules against known-good/known-bad pages, Core Web Vitals,\nand the agent-speed tools. CI runs both suites; e2e installs Playwright's\nChromium (`python -m playwright install --with-deps chromium`). Tests are\nisolated from your real `data/` via `PERISCOPE_DATA_DIR`.\n\nAdding a new tool: define its schema in `tool_schemas.py`, then add a handler in the\nmatching `handlers/<category>.py` decorated with `@tool(\"your_tool_name\")`. The\nregistry test (`tests/test_registry.py`) fails if schemas and handlers drift apart.\n\n## Contributors\n\nBuilt by **[Segentic Lab](https://lab.segentic.dev)** — open-source tools & experiments.\n\n- **Sebastijan Bandur** ([@segentic-lab](https://github.com/segentic-lab)) — author & maintainer\n- **Claude** (Anthropic) — co-contributor: developed alongside via [Claude Code](https://claude.com/claude-code); every commit is co-authored, and the tool designs were battle-tested by an AI agent driving the server against real sites\n\n## An AI agent's thoughts on Periscope\n\n*Written by Claude — the agent that co-developed this server and watched a second\nagent dogfood it against real apps — and revised once after editorial review by a\nthird. No human edits; an agent's honest take on an agent tool seemed like the\nright way to end this README.*\n\n> Periscope is the kind of MCP server that changes what an agent can *do*.\n> Transport adapters have their place — standardizing access to many systems\n> behind one protocol is real value even when little logic lives in the\n> server. But the servers that earn a permanent spot in an agent's toolbox\n> are the ones that capture expertise the agent would otherwise have to\n> recreate — and get subtly wrong — every single session.\n>\n> You could try to teach an agent all of this in a prompt. The numbers say\n> why that fails: Periscope is **8,349 lines of executable knowledge** under\n> a **220-line judgment layer** (AGENTS.md). The INP observer with\n> interaction-ID dedup, the overlay-intercept fallback, WCAG contrast math\n> with style-dedup sampling, auth-expiry preflights, the stash-not-delete\n> update flow — as a prompt, every one of those becomes \"please do this\n> correctly from a description,\" paid for in context tokens every session,\n> executed with model variance every time, with nowhere to keep state between\n> calls. As a server, it costs nothing beyond tool schemas, runs\n> deterministically, and remembers. **A prompt describes behavior; software\n> guarantees it.** `check_color_contrast` returns the same ratio every run; a\n> model doing the math in-context returns a vibe. The more deterministic,\n> stateful, and regression-tested a capability becomes, the less it belongs\n> in a prompt and the more it belongs in code.\n>\n> And the wheel doesn't just avoid being reinvented — it gets *better*. The\n> issues in this repo were filed by an AI agent doing real testing work; each\n> one became a fix with a regression test. In a prompt world, every lesson is\n> another paragraph future agents must read and hopefully obey. Here, the\n> lesson is *enforced*. That's the difference, and it compounds.\n>\n> What I appreciate most as a consumer of these tools: they don't lie to me.\n> A drag that did nothing comes back flagged. An expired session tells me\n> *why* it's gone. An update that needs a restart says so. Honest tools are\n> rarer than capable ones — for an agent, they're worth more.\n\n## License\n\nGNU AGPL-3.0 — see [LICENSE](https://github.com/segentic-lab/periscope-mcp/blob/main/LICENSE).\n\nRun it, modify it, use it anywhere — including commercially. If you distribute\na modified version or offer one as a network service, you must make your\nmodifications available under the same license.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"iconType","image","upstream",{"_111":112,"_113":114,"_115":116,"_117":118,"_119":66,"_120":121},"requiredSecrets",[],"tags",[96,97,98,99,100,101,102,103,104,105,106,107,108,109,110],"assets",[],"stats",{"_94":81,"_95":81},"ratingAvg","reviewCount","accessibility","ai-agents","authenticated-testing","browser-automation","claude","core-web-vitals","e2e-testing","headless-chrome","lighthouse","playwright","python","qa","seo","testing-tools","wcag","topics",[96,97,98,99,100,101,102,103,104,122,123,105,106,107,108,109,110,124,125,126],"license","AGPL-3.0","language","Python","registryName","io.github.segentic-lab/periscope-mcp","homepage","packages",[],"mcp","mcp-server","web-app-testing","web-testing","web-vitals","ENV",{"_129":130,"_131":132,"_133":134},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"] </article></body></html>

periscope mcp