# DeepSyte

> Give your AI coding assistant browser truth. Inspect, test, and verify websites with screenshots, browser workflows, audits, and evidence-rich results via MCP tools.

DeepSyte is a Model Context Protocol (MCP) server with 47+ tools that gives AI coding assistants the ability to see, interact with, and verify websites. It supports remote browser workflows for public pages, managed local browser workflows for private or local environments, and evidence capture for proof-heavy debugging and QA. It works with Claude, Cursor, Windsurf, VS Code, and any MCP-compatible client.

## Agent Skill

Download the complete Agent Skill for all tools: https://deepsyte.com/.skills/deepsyte/SKILL.md

## Discovery Model

- Treat DeepSyte tools as atomic actions.
- Treat the DeepSyte skill as broad guidance for choosing the right path.
- Treat packaged workflows as targeted procedures for repeatable multi-step jobs.
- When the task is an audit, verification flow, or another repeatable multi-step procedure, check the available workflows before improvising.
- For any site audit, performance audit, SEO audit, UX audit, full audit, or another repeatable multi-page website review, read `workflows/sitewide-performance-audit/WORKFLOW.md` before opening browser sessions, running audit tools, or drafting findings.
- If the user gives you a site URL but no page list, infer a representative public page set and start instead of blocking on permission.
- Default authenticated pages to out of scope unless the user explicitly asks for login, dashboard, or another protected flow.
- Do not load every workflow up front. Read only the workflow that matches the task.
- If terminal access exists and repeated tool calls are likely, prefer the CLI when it is clearly faster than repeated MCP round-trips. If terminal access is not available, stay in MCP.
- For multi-page performance audits in MCP, avoid opening many new browser sessions in parallel. Measure sequentially unless there is a proven reason to increase concurrency.

Available workflow:
- `workflows/sitewide-performance-audit/WORKFLOW.md` — use when the user asks why a site is slow, wants the slowest pages identified, or wants a repeatable multi-page performance review.

## Quick Start

### Option A: CLI (fastest)

```bash
npx deepsyte setup --client cursor    # or: vscode, windsurf, claude, claude-code
```

The CLI now also installs or repairs the managed core DeepSyte skill in `~/.agents/skills/deepsyte`, including `workflows/sitewide-performance-audit/WORKFLOW.md`, during successful `login`, `install`, and `setup` flows.

If you prefer to do onboarding in two steps, run `npx deepsyte login` followed by `npx deepsyte install <client>`. For most clients that reaches the same result as `setup --client <client>`. The main nuances are that `install vscode` writes a workspace-local `.vscode/mcp.json`, while `install claude-code` prints the `claude mcp add ...` command for you to run manually.

Use remote workflows first for public sites. Escalate to the managed local browser when you need localhost access, intranet or VPN reachability, authenticated realism, or explicit user-approved local execution.

## Escalation Ladder for website auth

Some sites (Cloudflare Turnstile, WorkOS AuthKit, Clerk bot-detection, Akamai/PerimeterX-protected signups) silently reject requests from the Railway-hosted cloud browser. `solve_captcha` returns a valid token, but the fingerprint gets filtered by Siteverify — no amount of token injection fixes it. When a valid-looking submit silently does nothing (URL doesn't change, no error, form resets), escalate instead of retrying:

1. Start with MCP tools (`browser_navigate`, `smart_login`, `solve_captcha`).
2. If MCP stalls silently, switch to the CLI local browser: `npx deepsyte browser:start <url>`, then drive real Chrome one atomic command at a time with `browser:click`, `browser:fill`, `browser:paste` (React-compatible), `browser:wait-for`, `browser:inspect`, `browser:eval`. Real Chrome on the user's residential IP passes WorkOS/Turnstile trust checks silently, often without even showing a CAPTCHA checkbox.
3. Always call `deepsyte auth:plan <url>` before a fresh auth attempt and `deepsyte auth:record <url> <outcome>` after. Inbox, password, and per-site auth state persist in the DB so the next run resumes at the right stage.
4. Use `+alias` emails (e.g. `you+smithery@agentmail.to`) to reuse a single inbox for multiple signups — most providers treat each alias as a distinct identity.

The interactive rule: read the returned PNG after every `browser:*` command, confirm the state, then issue the next command. No preset scripts.

For repeatable public-page performance audits, use the CLI only when the command path is already available or can be approved up front. If command approval would stall the run and MCP is already available, begin with MCP and collect metrics sequentially.

Important: `deepsyte skills ...` only manages the local core DeepSyte skill. For community skill discovery or installation, use the `find-skills` workflow or `npx skills find ...` / `npx skills add ...` instead.

### Option B: Manual

1. Get an API key at https://deepsyte.com/dashboard/keys
2. Add to your MCP config:

```json
{
  "mcpServers": {
    "deepsyte": {
      "url": "https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY"
    }
  }
}
```

3. Ask your AI: "Take a screenshot of https://example.com"

## VS Code Extension Preview

A native DeepSyte VS Code extension is now being developed in the monorepo for a dedicated Activity Bar sidebar, automatic browser OAuth sign-in, automatic editor MCP setup, automatic managed core skill sync, API key fallback, native MCP registration, command palette actions, a live activity timeline panel, and browser workflow UX inside the editor.

Current preview commands include `DeepSyte: Sign In`, `DeepSyte: Check Status`, `DeepSyte: Take Screenshot`, `DeepSyte: Open Timeline`, `DeepSyte: Configure Editor Integration`, and `DeepSyte: Sync Core Skill`. The sidebar also exposes quick actions and recent activity directly in VS Code, and the extension opens browser OAuth, configures the editor automatically, and repairs the managed core skill when no credentials are stored.

Until the Marketplace release is ready, the recommended VS Code setup is to install the preview VSIX, sign in once, and use `DeepSyte: Configure Editor Integration` only if you need to repair the automatic MCP setup or `DeepSyte: Sync Core Skill` when you need to repair the managed local skill.

## Chrome Extension Preview

The monorepo also includes a Chrome extension preview under `packages/chrome-extension`.

- **Public pages** use the same DeepSyte Playwright-backed MCP path as the CLI for screenshot capture and page inspection when an API key is configured.
- **Localhost and private pages** stay local-first, so the extension can still capture and inspect pages that the cloud browser cannot reach.
- **Page tools** in the popup can read visible text and DOM HTML for the active tab.
- **Saved key validation** happens before the extension accepts a pasted API key, so revoked keys are rejected instead of being silently stored.
- **Viewer cloud actions** reuse existing cloud-backed captures when available and only upload local-only captures when needed.

Use the extension when you want a browser-native client for current-tab capture and inspection, while keeping parity with the DeepSyte platform for public URLs.

## CLI (for agents and humans)

DeepSyte has a CLI that exposes all tools as terminal commands. **AI agents can and should use the CLI directly via terminal/run_command** — it's often faster than MCP tool calls and returns structured text output.

Install: `npm install -g deepsyte`
npm: https://www.npmjs.com/package/deepsyte
Or use without installing: `npx deepsyte <command>`

### Auth
```
deepsyte login                    # OAuth (opens browser, saves key)
deepsyte login --key sk_live_...  # Direct API key
deepsyte whoami                   # Check auth status
deepsyte logout                   # Clear credentials
```

### Screenshots
```
deepsyte screenshot <url>                    # 1280×800 viewport
deepsyte screenshot <url> --width 1920 --height 1080 --full-page
deepsyte screenshot <url> --format jpeg --delay 2000
deepsyte fullpage <url>                      # Dedicated full-page capture
deepsyte responsive <url>                    # Desktop + tablet + mobile
deepsyte mobile <url>                        # iPhone 14 Pro (393×852)
deepsyte tablet <url>                        # iPad (820×1180)
deepsyte dark <url>                          # Dark mode emulated
deepsyte element <url> --selector "#hero"    # CSS element capture
deepsyte diff <urlA> <urlB>                  # Pixel-diff two URLs
deepsyte cross-browser <url>                 # Chromium + Firefox + WebKit
deepsyte batch <url1> <url2> <url3>          # Multiple URLs (max 10)
deepsyte pdf <url>                           # Export as PDF
deepsyte screenshots                         # List recent screenshot jobs
deepsyte screenshot:status <id>              # Check screenshot job status
```

### Browser Sessions
```
deepsyte browse <url>                                    # Start session → sessionId
deepsyte browse:click <sessionId> <selector>             # Click element
deepsyte browse:click-at <sessionId> 320 480             # Coordinate click
deepsyte browse:fill <sessionId> <selector> <value>      # Type into input
deepsyte browse:hover <sessionId> ".menu-trigger"       # Hover state
deepsyte browse:select <sessionId> "select[name=country]" "Australia"
deepsyte browse:wait-for <sessionId> ".results-loaded"  # Wait for selector
deepsyte browse:screenshot <sessionId>                   # Capture current state
deepsyte browse:text <sessionId>                         # Get visible text
deepsyte browse:html <sessionId>                         # Get page HTML
deepsyte browse:a11y <sessionId>                         # Accessibility tree
deepsyte browse:eval <sessionId> "document.title"       # Evaluate JavaScript
deepsyte browse:console <sessionId> --level error        # Console logs
deepsyte browse:network-errors <sessionId>               # Failed requests
deepsyte browse:network-requests <sessionId>             # Request waterfall
deepsyte browse:cookies <sessionId> get                  # Inspect cookies
deepsyte browse:storage <sessionId> getAll               # Inspect storage
deepsyte browse:back <sessionId>                         # Back in history
deepsyte browse:forward <sessionId>                      # Forward in history
deepsyte browse:viewport <sessionId> 393 852             # Resize existing session
deepsyte browse:seo <sessionId>                          # Session SEO audit
deepsyte browse:perf <sessionId>                         # Session performance metrics
deepsyte browse:captcha <sessionId>                      # Solve CAPTCHA in-session
deepsyte browse:scroll <sessionId> --y 500               # Scroll down
deepsyte browse:key <sessionId> Enter                    # Press key
deepsyte browse:goto <sessionId> <newUrl>                # Navigate
deepsyte browse:close <sessionId>                        # End session
```

### Reviews & Audits
```
deepsyte review <url>              # AI UX review (standalone, no Run created)
deepsyte seo <url>                 # SEO metadata, run-backed (shows verdict + summary in /dashboard/runs)
deepsyte perf <url>                # Core Web Vitals, run-backed against sitewide-performance-audit workflow
deepsyte a11y <url>                # Accessibility tree (standalone)
deepsyte ocr <imageUrl>            # Extract text from image via AI vision (OCR)
deepsyte ocr --session <id>        # OCR from browser session screenshot
deepsyte breakpoints <url>         # Responsive breakpoints (standalone)
```

`perf` and `seo` open a workflow-aware browser session so the run lands in the dashboard Runs UI with a structured outcome (verdict, summary, findings, proof coverage, next actions). `review`, `a11y`, and `breakpoints` stay standalone and do not create a Run.

### Disposable Email
```
deepsyte auth:test <url>           # Reuse auth memory + primary inbox
deepsyte auth:find-login <url>     # Discover likely login pages
deepsyte auth:smart-login <url> --username user@example.com --password secret
deepsyte auth:authorize-email      # Connect Gmail once for OTP reads
deepsyte auth:read-email           # Read latest Gmail OTP
deepsyte inbox:create              # Create or reuse the primary test inbox
deepsyte inbox:check <inboxId>     # Read messages, extract OTP codes
deepsyte inbox:send <inboxId> --to user@example.com --subject "Test" --text "Hello"
```

### Reusable Website Auth
- Start with `auth_test_assist` or `deepsyte auth:test <url>` for login, sign-up, or verification flows.
- Read the helper's recommended auth path, account-exists confidence, likely auth method, and expected follow-up before choosing sign-in or sign-up.
- Treat the helper's reusable strategy as the default cross-site guidance, and treat per-site hints as evidence rather than universal rules.
- Reuse the saved primary inbox and password unless you explicitly need a fresh registration.
- If sign-in fails because the account does not exist, switch to sign-up with the same saved credentials.
- If `smart_login` is uncertain on Clerk or other multi-step auth UIs, fall back to browser tools and inspect network or console evidence before concluding the login failed.
- Use `check_inbox` for verification codes or email links.
- After the attempt, call `auth_test_assist` again with `action: "record"` to save the outcome for future runs.

### Setup & Install
```
deepsyte setup                     # Interactive: login + choose IDE + auto-configure (recommended)
deepsyte setup --client cursor     # Non-interactive: for AI agents, skips prompt
deepsyte setup --client windsurf
deepsyte setup --client vscode
deepsyte setup --client claude
deepsyte setup --client claude-code
deepsyte browser open https://example.com  # Launch extension-free local browser with explicit approval
deepsyte browser open https://example.com --record-video  # Record the full managed local browser session to a local .webm file
deepsyte browser back                     # Navigate browser history backward
deepsyte browser forward                  # Navigate browser history forward
deepsyte browser status                   # Inspect the tracked managed local browser
deepsyte browser goto https://example.org # Navigate the managed local browser
deepsyte browser click-at 320 480         # Click viewport coordinates in the managed local browser
deepsyte browser hover ".menu-trigger"    # Trigger hover states in the managed local browser
deepsyte browser wait-for ".results-loaded" --timeout 8000
deepsyte browser select "select[name=country]" "Australia"
deepsyte browser viewport 393 852         # Resize the managed local browser viewport
deepsyte browser screenshot               # Save a local screenshot from the managed browser
deepsyte browser text                     # Read visible text from the managed browser
deepsyte browser console --level error    # Read captured console logs from the managed browser
deepsyte browser network-errors           # Read failed network requests from the managed browser
deepsyte browser network-requests --resource-type fetch --min-duration 200
deepsyte browser cookies get              # Inspect cookies in the managed browser
deepsyte browser storage getAll --type localStorage
deepsyte browser eval "document.title"   # Evaluate JavaScript in the managed browser
deepsyte browser a11y --max-depth 6       # Inspect the accessibility tree from the managed browser
deepsyte browser perf                     # Read performance metrics from the managed browser
deepsyte browser seo                      # Audit SEO metadata from the managed browser
deepsyte browser close                    # Close the tracked managed local browser
deepsyte skills list               # List installed skills under ~/.agents/skills
deepsyte skills sync               # Install, update, or repair the managed core skill
deepsyte skills update             # Alias for core skill sync
deepsyte install cursor            # Writes ~/.cursor/mcp.json
deepsyte install vscode            # Writes .vscode/mcp.json
deepsyte install windsurf          # Writes ~/.codeium/windsurf/mcp_config.json
deepsyte install claude            # Writes Claude Desktop config
deepsyte install claude-code       # Prints `claude mcp add` command
```

For community skills such as Anthropic's `frontend-design`, use `find-skills` or run `npx skills find frontend design` followed by `npx skills add anthropics/skills@frontend-design -g -y`.

### One-liner Install
```
# macOS/Linux
curl -fsSL https://deepsyte.com/install.sh | bash

# Windows PowerShell
irm https://deepsyte.com/install.ps1 | iex

# Or just use npx (no install needed)
npx deepsyte setup
```

### Agent Tips
- **AI agents: use `npx deepsyte setup --client <ide>` to install non-interactively.**
- **Use CLI when you have terminal access** — structured text output, no JSON-RPC overhead.
- **For auth testing, start with `npx deepsyte auth:test https://example.com`** so you reuse saved inbox credentials, remembered auth history, and the helper's site-specific confidence signals.
- Every screenshot command returns a public CDN URL.
- Browser sessions: start with `browse`, get sessionId, pass it to subsequent `browse:*` commands, and always `browse:close` when done.
- Use remote `browse:*` commands for public-site MCP-parity workflows. Use `deepsyte browser ...` only for the separate managed local browser used for localhost, VPN-only, or approval-gated work.
- Managed local browser commands under `deepsyte browser ...` now support continuous console/network capture while the browser stays open, plus history navigation, coordinate clicks, hover states, wait conditions, dropdown selection, viewport resizing, screenshots, text, HTML, cookies/storage inspection, script evaluation, accessibility trees, performance metrics, SEO audits, timestamped evidence bundle export via `browser evidence`, finalized video-inclusive export via `browser close --evidence`, and optional local `.webm` session recording against the tracked local browser.
- Prefer evidence-rich workflows when debugging: capture screenshots, logs, recordings, and bundle exports so the result is reviewable by both humans and agents.
- Credentials stored in `~/.config/deepsyte/config.json`. Once logged in, all commands are authenticated.
- Use `npx deepsyte` if unsure whether it's installed globally.

## Webhooks

Subscribe an HTTPS endpoint to receive HMAC-signed events:

```
POST   /v1/webhooks                  # create endpoint, secret returned once
GET    /v1/webhooks                  # list endpoints
PATCH  /v1/webhooks/:id              # update url, events, enabled flag
POST   /v1/webhooks/:id/rotate       # rotate signing secret
POST   /v1/webhooks/:id/test         # fire test.ping
GET    /v1/webhooks/:id/deliveries   # last 50 delivery attempts
DELETE /v1/webhooks/:id              # remove endpoint
```

Available events: `screenshot.completed`, `screenshot.failed`, `run.completed`, `run.failed`, `quota.warning`, `test.ping`. Default subscription is `["*"]` (forward-compatible).

Headers on every delivery: `Webhook-Id`, `Webhook-Timestamp`, `Webhook-Signature: t=<unix>,v1=<hex hmac sha256 of "${ts}.${body}">`. Verify within 5 minutes of `Webhook-Timestamp`.

Retries: 6 attempts at 1m / 5m / 30m / 2h / 12h. Exhausted deliveries are visible in `GET /v1/webhooks/:id/deliveries`.

Full reference: https://www.deepsyte.com/docs/api/webhooks

## Server URL

MCP endpoint: `https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY`
REST API base: `https://deepsyte-api-production.up.railway.app`
Transport: Streamable HTTP

## Authentication

Every request requires an API key. Keys start with `sk_live_`.

- MCP: API key is embedded in the server URL path
- REST API: Pass as `Authorization: Bearer sk_live_...` header

Rate limits by plan:
- Free: 100 screenshots/month
- Starter: 2,000 screenshots/month
- Pro: 10,000 screenshots/month

---

## Tools Reference (47+ tools)

### Screenshot Tools (no session needed)

#### take_screenshot
Capture a screenshot of any URL and return a public image URL.

Parameters:
- url (string, required): The URL to screenshot
- width (number, default: 1280): Viewport width in pixels (320–3840)
- height (number, default: 800): Viewport height in pixels (240–2160)
- fullPage (boolean, default: true): Capture full scrollable page
- maxHeight (number, optional): Cap extremely tall captures
- format (string, default: "png"): png, jpeg, or webp
- delay (number, default: 0): Wait ms after page load (0–10000)

#### screenshot_fullpage
Capture entire scrollable page.
Params: url, width, format, maxHeight

#### screenshot_mobile
iPhone 14 Pro (393×852).
Params: url, fullPage, format

#### screenshot_tablet
iPad (820×1180).
Params: url, fullPage, format

#### screenshot_responsive
Desktop + tablet + mobile in ONE call. Most efficient for responsive visual comparison. For detailed checks (overflow, touch targets, font sizes), follow up with responsive_audit in a browser session.
Params: url, fullPage, format

#### screenshot_dark
Dark mode emulated (prefers-color-scheme: dark).
Params: url, width, height, format

#### screenshot_element
Specific element by CSS selector. SPA-friendly with auto-wait.
Params: url, selector, format, delay

#### screenshot_pdf
Export as PDF (A4 with backgrounds).
Params: url

#### screenshot_batch
Capture multiple URLs in one call (max 10).
Params: urls[], width, height, format, fullPage

#### screenshot_cross_browser
Chromium + Firefox + WebKit simultaneously.
Params: url, width, height, fullPage

#### screenshot_diff
Pixel-diff two URLs. Returns diff image + percentage changed + match score. To capture multiple URLs for comparison, use screenshot_batch.
Params: urlA, urlB, width, height, threshold

#### find_breakpoints
Detect responsive breakpoints (scans 320px–1920px). Returns structured width table with overflow status (✅/❌), height, and scrollWidth at each width. For element-level issues (culprit elements, touch targets, font sizes), follow up with responsive_audit.
Params: url

#### responsive_audit
One-call responsive design audit in a browser session. Checks: horizontal overflow with culprit elements, touch target sizes (≥44×44px), text below 16px, viewport meta tag, input font sizes for iOS zoom prevention, and interactive element spacing. Returns structured pass/fail report.
Params: sessionId

#### list_recent_screenshots
View recent captures.
Params: limit (1–20)

#### get_screenshot_status
Check if a job is done.
Params: id

---

### Browser Session Tools

Start with `browser_navigate` → get sessionId → pass to all tools → `browser_close` when done. **Both tools return a `Run URL` pointing to the live dashboard for this run (timeline + captures + replay + console + network). Always surface the Run URL to the user at the end of the task so they can review the evidence. If a `Share URL` is also returned, include it for teammates who don't have an account.**

#### browser_navigate
Open URL, returns screenshot + sessionId + `Run URL` (dashboard deep-link for this run). Surface the Run URL to the user at the end of the task. Supports workflow-aware outcome context for run summaries.
Params: url, sessionId (optional), width, height, record_video, task_type, user_goal, workflow_name, workflow_required, auth_scope, tool_path, page_set, required_evidence

#### browser_click
Click by CSS selector or visible text.
Params: sessionId, selector

#### browser_click_at
Click at x,y coordinates — for CAPTCHAs, canvas, iframes.
Params: sessionId, x, y, clickCount, delay

#### browser_fill
Type into input field (clears first).
Params: sessionId, selector, value

#### browser_hover
Trigger hover states/tooltips/dropdowns.
Params: sessionId, selector

#### browser_select_option
Select from dropdown.
Params: sessionId, selector, value

#### browser_press_key
Keyboard: Enter, Tab, Escape, Control+a, etc.
Params: sessionId, key

#### browser_scroll
Scroll by pixel amount.
Params: sessionId, x, y

#### browser_wait_for
Wait for element to appear.
Params: sessionId, selector, timeout

#### browser_go_back / browser_go_forward
Browser history navigation.
Params: sessionId

#### browser_set_viewport
Resize viewport mid-session (e.g. desktop ↔ mobile).
Params: sessionId, width, height

#### browser_close
Free resources. Always call when done. Returns a `Run URL` pointing to the dashboard view of this run — you MUST include this Run URL in your final reply so the user can review the captured timeline, evidence, console, and network. Also returns a `Share URL` when one exists (public link for teammates).
Params: sessionId

#### browser_screenshot
Screenshot current page state.
Params: sessionId

#### browser_get_text
All visible text (or specific element). Returns fast "no matching element" error instead of hanging.
Params: sessionId, selector (optional), timeout (default 5000ms, 500–30000)

#### browser_get_html
DOM source. Returns fast "no matching element" error instead of hanging.
Params: sessionId, selector (optional), outer, timeout (default 5000ms, 500–30000)

#### browser_get_accessibility_tree
Full a11y tree — best for understanding page structure.
Params: sessionId, interestingOnly, maxDepth

#### accessibility_snapshot
A11y tree for any URL without a session.
Params: url, interestingOnly, maxDepth

#### accessibility_audit
Run a real WCAG 2.1 AA compliance audit on a URL. Checks landmarks, skip links, focus indicators, heading hierarchy, image alt text, aria-hidden on decorative SVGs, color contrast ratios, form labels, touch targets, and reduced-motion handling. Returns categorized PASS/FAIL results with WCAG criteria references. For element-level responsive checks (overflow culprits, touch target sizes, font sizes), use responsive_audit in a browser session.
Params: url, width, height

#### browser_evaluate
Run JavaScript, return result.
Params: sessionId, script

---

### Performance & SEO

#### browser_perf_metrics
Core Web Vitals: LCP, FCP, CLS, TTFB, DOM size, resource counts. For the full request waterfall with timing data, use browser_network_requests.
Good thresholds: TTFB < 800ms, FCP < 1.8s, LCP < 2.5s, CLS < 0.1
Params: sessionId

#### browser_network_requests
Full network waterfall with timing.
Params: sessionId, resourceType, minDuration, limit

#### browser_seo_audit
Meta, OG, Twitter cards, headings, JSON-LD, alt text, structured data.
Params: sessionId

#### seo_batch_compare
Compare SEO metadata across 2–10 URLs in one call. Returns a comparison table showing which meta fields are duplicated across pages — catches identical titles, descriptions, OG tags, and canonical issues that single-page tools miss. No browser session needed. For deeper single-page analysis, use browser_seo_audit in a browser session. For social card previews, use og_preview.
Params: urls (array of 2–10 URLs)

#### og_preview
Preview how a URL will look when shared on social media. Extracts all OG and Twitter Card meta tags from the rendered page, validates them, screenshots the og:image, and generates a social card mockup. Works with JS-rendered pages (SPAs). No browser session needed. For full SEO metadata (headings, structured data, robots), use browser_seo_audit. To compare OG tags across multiple pages, use seo_batch_compare.
Params: url (required), platform (twitter|facebook|linkedin|slack|all, default: all)

---

### Debugging

#### browser_console_logs
Console errors, warnings, logs, exceptions.
Params: sessionId, level, limit

#### browser_network_errors
Failed requests (4xx, 5xx).
Params: sessionId, limit

#### browser_cookies
Get/set/clear cookies.
Params: sessionId, action, cookies[]

#### browser_storage
Read/write localStorage and sessionStorage.
Params: sessionId, storageType, action, key, value

---

### Smart Login

#### auth_test_assist
Start here for website login, sign-up, and verification testing. Reuses the saved inbox/password, checks remembered auth state for the site's normalized origin, and returns reusable auth strategy plus site-specific signals such as recommended auth path, account-exists confidence, likely auth method, expected follow-up, and known-site history.
Params: url, action, intent, loginUrl, outcome, verification_required, username, display_name, force_new_inbox, notes

#### find_login_page
Discover login pages via sitemap.xml + common paths. After finding the login URL, use auth_test_assist to plan the auth flow, or smart_login to attempt sign-in directly.
Params: url

#### smart_login
Auto-detect form fields, fill credentials, submit with click, Enter, and form-submit fallbacks, then report result.
Params: loginUrl, username, password, usernameSelector, passwordSelector, submitSelector

Returns: screenshot + status (SUCCESS/FAILED/UNCERTAIN) + sessionId.

---

### CAPTCHA Solving

#### solve_captcha
Auto-detect and solve Cloudflare Turnstile, reCAPTCHA v2/v3, hCaptcha using AI (CapSolver).
For Clerk-powered sites, automatically calls sign-up/sign-in API with the solved token.
Params: sessionId, type (auto), sitekey (auto), pageUrl (auto), autoSubmit (default: true)

---

### Disposable Email (AgentMail)

Each user needs their own AgentMail API key (free at https://console.agentmail.to). Configure in Dashboard → Settings.

#### create_test_inbox
Standalone inbox helper. Create or reuse the saved primary inbox and return its email, password, inbox ID, and known-site history. For website auth work, start with auth_test_assist first so you also get reusable cross-site strategy and remembered per-site guidance.
Params: username (optional), display_name (optional), force_new (optional)

#### check_inbox
Read messages, auto-extracts OTP codes and verification links.
Params: inbox_id, limit

#### send_test_email
Send email from an inbox.
Params: inbox_id, to, subject, text

---

### Gmail Verification (OAuth)

#### authorize_email_access
One-time OAuth setup for Gmail.

#### read_verification_email
Read OTP codes from user's Gmail inbox.
Params: sender (optional), subject_keyword (optional), max_age_minutes

---

### AI-Powered Analysis

#### ux_review
AI-powered UX review using vision. Returns actionable feedback across Accessibility, SEO, Performance, Navigation, Content, and Mobile-friendliness. For deeper checks, follow up with accessibility_audit (WCAG compliance), responsive_audit (overflow, touch targets, font sizes), or browser_perf_metrics (Core Web Vitals).
Params: url, width, height

#### extract_text_from_image
Extract text from an image using AI vision (OCR). Works on screenshots, photos of text, infographics, social cards, Canva graphics, and any image with embedded text. If you need a screenshot URL first, use take_screenshot or browser_screenshot.
Params: image_url (optional — public URL of image), sessionId (optional — screenshot current page), selector (optional — OCR a specific element), prompt (optional — custom extraction prompt)
Requires either image_url or sessionId. Use when page text is embedded in images rather than DOM.

---

## Common Workflows

### Responsive Testing
→ `find_breakpoints` to scan all widths for overflow and layout shifts
→ `browser_navigate` (mobile viewport) → `responsive_audit` for element-level checks
→ `browser_set_viewport` (tablet) → `responsive_audit` again
→ `screenshot_responsive` for visual comparison across viewports

### Full Site Audit
→ First read `workflows/sitewide-performance-audit/WORKFLOW.md` before any browser or audit tool use
→ State that you read it, the page set, whether authenticated pages are in scope, and whether you will use MCP or CLI first
→ If the user gave the site URL but not the page list, infer the representative public pages and begin
→ `browser_navigate` → `browser_get_accessibility_tree` → `browser_perf_metrics` → `browser_seo_audit` → `og_preview` → `browser_console_logs` → `browser_network_errors`

### Sign-Up Testing with Disposable Email
1. `auth_test_assist` → decide whether sign-in or sign-up should be attempted first
2. `find_login_page` if needed
3. Reuse the saved primary inbox and password from the helper unless you explicitly need a fresh registration
4. `smart_login` for the first auth attempt or `browser_fill` / `browser_click` for manual multi-step flows
5. `check_inbox` → extract OTP or verification link
6. Record the outcome with `auth_test_assist`
7. Report reusable auth-system heuristics first, then the site-specific evidence that supported them

### Before/After Comparison
→ `screenshot_diff` with urlA and urlB → pixel diff + match score

### Cross-Browser Testing
→ `screenshot_cross_browser` for Chromium + Firefox + WebKit

---

## REST API

Base URL: https://deepsyte-api-production.up.railway.app

### POST /v1/screenshot
Enqueue a screenshot job.
Headers: Authorization: Bearer sk_live_...
Body: { url, width, height, fullPage, format, delay }
Response: { id, status: "pending" }

### GET /v1/screenshot/:id
Poll for status.
Response: { id, status, url, error, createdAt }

---

## Installation by Client

### Cursor
~/.cursor/mcp.json:
```json
{ "mcpServers": { "deepsyte": { "url": "https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### Windsurf
```json
{ "mcpServers": { "deepsyte": { "serverUrl": "https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### Claude Desktop / Claude Code
```json
{ "mcpServers": { "deepsyte": { "url": "https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### VS Code (Copilot)
.vscode/mcp.json:
```json
{ "mcpServers": { "deepsyte": { "url": "https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

### Gemini CLI / OpenCode / Roo Code / Other MCP clients
```json
{ "mcpServers": { "deepsyte": { "url": "https://deepsyte-api-production.up.railway.app/mcp/YOUR_API_KEY" } } }
```

---

## Documentation

Full docs: https://deepsyte.com/docs
Agent Skill: https://deepsyte.com/.skills/deepsyte/SKILL.md