SiteLens

SiteLens is real-browser verification and page intelligence for developers and AI agents.

Run structured QA and agent verification flows from .sitelens/flows, capture screenshots and artifacts, sync prompts and templates from the registry, and optionally use Page Intelligence and Cloud/API runs. Use SiteLens Local on your machine via this MCP package, Desktop, or QA Studio as needed.

This package (@sitelensapi/mcp) is the portable npm distribution: an MCP server for Cursor and other MCP hosts, plus a CLI for setup, registry sync, and diagnostics. Local runs use bundled Chromium on your machine—no Docker required.

Links: sitelensapi.com · MCP docs · QA Studio · Dashboard / MCP setup · npm @sitelensapi/mcp

Install

# One-shot bootstrap (recommended first run)
npx --yes @sitelensapi/mcp sitelens-mcp setup

# Or install globally
npm install -g @sitelensapi/mcp

Requires Node.js 20+.

Quick start

1. Wire Cursor (local QA — no API key)

Add to ~/.cursor/mcp.json or your project .cursor/mcp.json:

{
  "mcpServers": {
    "sitelens": {
      "command": "npx",
      "args": ["-y", "@sitelensapi/mcp"],
      "env": {
        "SITELENS_MODE": "local",
        "SITELENS_DEFAULT_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

For local/dev HTTPS targets with self-signed or private CA certificates (e.g. https://app.local), also allow the host and bypass Playwright TLS checks:

{
  "mcpServers": {
    "sitelens": {
      "command": "npx",
      "args": ["-y", "@sitelensapi/mcp"],
      "env": {
        "SITELENS_LOCAL_ALLOWED_HOSTS": "app.local",
        "SITELENS_LOCAL_IGNORE_HTTPS_ERRORS": "true"
      }
    }
  }
}

Restart Cursor after changing MCP env. Your normal browser may trust the cert; SiteLens local QA uses Playwright, which needs this flag for local/dev targets only.

Optional: on corporate machines where Chrome or Edge already trusts local certs, you may use the system browser instead of bundled Chromium:

{
  "mcpServers": {
    "sitelens": {
      "command": "npx",
      "args": ["-y", "@sitelensapi/mcp"],
      "env": {
        "SITELENS_LOCAL_ALLOWED_HOSTS": "app.local",
        "SITELENS_LOCAL_IGNORE_HTTPS_ERRORS": "true",
        "SITELENS_BROWSER_CHANNEL": "chrome"
      }
    }
  }
}

SITELENS_BROWSER_CHANNEL accepts chrome, msedge, or chromium (bundled default). When unset, SiteLens uses bundled Chromium. If you explicitly set chrome or msedge and that browser is missing, SiteLens reports a clear error — it does not silently fall back.

Restart Cursor, then ask: "Use SiteLens setup."

That runs the sitelens_setup MCP tool (bundled Chromium, writable dirs, API key presence only — never the key value).

2. Run local QA on your dev server

Ask Cursor:

"Run SiteLens local QA on http://localhost:3000 (desktop + mobile)."

That invokes sitelens_qa_run (alias sitelens_run_local_qa). Local QA does not require a SiteLens account or API key.

3. Check readiness from the terminal

npx --yes @sitelensapi/mcp sitelens-mcp -- --self-test
npx --yes @sitelensapi/mcp sitelens doctor
npx --yes @sitelensapi/mcp sitelens doctor --cursor

4. Scaffold and run a project flow from the terminal

Create a starter flow JSON in your project (edit steps and URL afterward):

npx --yes @sitelensapi/mcp sitelens flow init homepage-smoke
# or: npx --yes @sitelensapi/mcp sitelens flow init --flow-id homepage-smoke --template smoke

Then run it:

npx --yes @sitelensapi/mcp sitelens flow run \
  --flow-id homepage-smoke \
  --url http://127.0.0.1:3000/

Same engine as MCP sitelens_run_local_flow — useful for CI and shell scripts without Cursor.

Current status

Verified against package implementation and tests (May 2026). See MCP docs — project flows for flow schema and step reference.

Supported now

| Capability | How to use | |------------|------------| | Ad-hoc local QA | MCP sitelens_qa_run / sitelens_run_local_qa (≤ 8 steps, no API key) | | Project flows | JSON in .sitelens/flows/*.json + CLI sitelens flow run or MCP sitelens_run_local_flow (≤ 200 steps) | | Flow discovery | sitelens doctor, --self-test, MCP sitelens_setup list flows dir | | Local run artifacts | summary.json, report.md, screenshots/ under $TMPDIR/sitelens-mcp-local-qa | | Local run history / compare | MCP sitelens_list_local_runs, sitelens_compare_local_runs | | Saved auth profiles | ~/.sitelens/ + sitelens_auth_* tools | | Local MCP resources | sitelens-local://runs/{localRunId}/… | | CLI bootstrap / diagnostics | sitelens-mcp setup, --self-test, sitelens doctor | | CLI flow scaffold | sitelens flow init --flow-id <id> [--template smoke] | | CLI project flow runner | sitelens flow run --flow-id <id> --url <url> | | Scenario Runner | JSON in .sitelens/scenarios/*.json + CLI sitelens run scenario or MCP sitelens_run_local_scenario (chained flows, shared session) | | Remote content registry | sitelens registry sync — prompts, example flows, QA presets, scenario templates (optional) from sitelensapi.com/registry (no npm bump) | | Cloud QA (optional) | SITELENS_API_KEY + sitelens_run_qa, sitelens_run_flow (cloud UUID flows) |

Consumer-repo verification: release smoke (pnpm run pack:smoke) installs a publish-shaped tarball in a temp project with .sitelens/flows/smoke-flow.json, runs --self-test and sitelens doctor, and confirms flow discovery. Unit tests cover flow load, MCP registration, and GET /flows/local.

Experimental

| Capability | Notes | |------------|-------| | Strict pixel screenshot diff | MCP sitelens_compare_local_runs with includeScreenshotDiff: true — RGBA equality, not perceptual | | Local flow templates in ad-hoc QA | template presets on sitelens_qa_run (homepage-qa, basic-smoke, etc.) |

Internal only (not npm consumer surface)

| Capability | Notes | |------------|-------| | HTTP runtime sidecar | start:http-runtime — GET /flows/local, POST /flows/local/run, POST /runs/local for SiteLens Desktop | | Desktop capture packs | Desktop runs project flows via HTTP when a capture step references a flowId — not the primary npm onboarding path | | SITELENS_MCP_LOCAL_RUN_PLACEHOLDER | Dev/test flag — skips browser execution |

Planned / roadmap

| Capability | Notes | |------------|-------| | sitelens_local_doctor MCP tool | Targeted local connectivity diagnostics (hostname, allowlist, HTTPS ignore, browser channel, DNS/navigation) | | Desktop “Run flow” UI | Desktop Project flows page runs .sitelens/flows from the app | | QA Studio ↔ .sitelens/flows sync | Studio stores cloud UUID flows; repo JSON is separate | | Cloud sync of local artifacts | Local bundles stay on disk (supportsCloudUpload: false) | | Desktop visual compare viewer | MCP compare works; Desktop UI roadmap | | Advanced cloud history in Desktop | In progress |

Project flows

Project flows are JSON files stored in .sitelens/flows/*.json in your project — not hand-written browser test files (*.spec.ts), not QA Studio cloud records, and not files inside the npm package install path.

Intended convention

your-app-repo/
  .sitelens/
    flows/
      homepage-smoke.json      ← flowId "homepage-smoke"
      login-check.json         ← flowId "login-check"
    scenarios/
      login-then-smoke-scenario.json   ← scenarioId (see Scenario Runner)

Auth and browser profiles (when using profile or authProfile) are stored under ~/.sitelens/ on your machine — not in the repo:

~/.sitelens/
  auth/          ← Playwright storage-state JSON per profile name
  profiles/      ← persistent browser profile dirs (cookies, localStorage)

| Directory | Purpose | |-----------|---------| | .sitelens/flows/ | Single QA flows — one page or workflow step sequence each | | .sitelens/scenarios/ | Chained orchestration — runs multiple flows in order with one shared browser session | | ~/.sitelens/auth/ | Saved login state (storage-state auth mode) | | ~/.sitelens/profiles/ | Persistent browser profiles (persistent-profile auth mode; default for scenarios) |

| Rule | Detail | |------|--------| | Location | <workspace>/.sitelens/flows/{flowId}.json | | flowId | Lowercase slug: [a-z0-9][a-z0-9-]{0,63} (must match "id" inside the file) | | Workspace | Resolved from SITELENS_WORKSPACE_DIR → CURSOR_PROJECT_DIR → VSCODE_CWD → process.cwd() | | Schema | version: 1, required id, name, url, steps[] — validated by @sitelensapi/qa-smoke | | Steps | Same vocabulary as SiteLens cloud saved flows (click, assert*, network waits, expectEither, etc.) | | Step limits | File-backed: up to 200 steps. Ad-hoc sitelens_qa_run: 8 steps max |

Commit .sitelens/flows/ to git in your app repo so agents and CI can run the same smoke paths.

Starter flows (flow init)

Scaffold a valid flow file without hand-writing the full schema (via the sitelens bin from @sitelensapi/mcp):

npx --yes @sitelensapi/mcp sitelens flow init --flow-id homepage-smoke
npx --yes @sitelensapi/mcp sitelens flow init homepage-smoke --template smoke
npx --yes @sitelensapi/mcp sitelens flow init --flow-id screenshot-pack --template screenshots

After npm install -g @sitelensapi/mcp, you can use sitelens flow init … directly.

| Template | What you get | |----------|----------------| | smoke (default) | readySelector: body, document screenshot, minimal assertSelector, final-state screenshot step | | screenshot | Explicit waitForSelector on body, assertions, final-state screenshot step, exportArtifacts | | text-check | assertText placeholder plus final-state screenshot step — edit the expected string after init | | login | Login form fill, before-submit / after-submit / after-login screenshot checkpoints | | form-submit | Generic form fill/submit with before-submit / after-submit / final-state checkpoints |

Default URL in generated files is http://localhost:3000/ — change it in JSON or override at run time with --url. Existing files are not overwritten unless you pass --force.

Example flow file

{
  "version": 1,
  "id": "homepage-smoke",
  "name": "Homepage Smoke",
  "url": "http://127.0.0.1:3000/",
  "viewports": ["desktop", "mobile"],
  "screenshot": true,
  "readySelector": "body",
  "steps": [
    { "type": "assertSelector", "selector": "body", "state": "visible" },
    { "type": "assertText", "text": "Welcome" },
    { "type": "screenshot", "label": "final-state" }
  ]
}

Use screenshot steps for labeled checkpoints during a flow (saved under the run artifact screenshots/ directory and returned in actionLog[].screenshot):

{ "type": "screenshot", "label": "after-login" }

Common labels for investigations: before-submit, after-submit, after-login, final-state.

Legacy flow JSON may also use { "action": "screenshot", "label": "after-login" } — it normalizes to the same step.

Scaffold flows with checkpoints:

sitelens flow init login-smoke --template login
sitelens flow init checkout --template form-submit
sitelens flow init homepage-smoke --template smoke

Agent guidance: evidence collection

When debugging UI, auth, or workflow issues with MCP or CLI:

1. Call sitelens_status to confirm workspace and flow discovery.
2. Run flows/scenarios with exportArtifacts: true (default for repo flows).
3. Add { "type": "screenshot", "label": "…" } steps at key moments — before/after submit, after login, final state.
4. Read summary.actionLog[].screenshot.path and summary.screenshotPaths in the tool response; open PNGs under {artifactDir}/screenshots/.
5. For ad-hoc checks (≤8 steps), pass screenshot steps in sitelens_qa_run actions / scenario arrays.

Cursor prompt example: "Run sitelens_run_local_flow for auth-login-setup with export artifacts enabled. List every labeled screenshot path from actionLog."

Step reference: Project flows & local templates.

selectOption (native <select>)

Use selectOption when working with native HTML <select> dropdowns — especially when options are visually hidden or hard to click in headless mode. Playwright selects through the native element directly.

{
  "type": "selectOption",
  "selector": "select[name='status']",
  "value": "active"
}

Provide exactly one of value, label, or index. selector is required. Custom JavaScript dropdowns should still use click / press steps.

Tier 1 interactions

Target with exactly one of selector, testId, label, or role+name:

• check / uncheck — checkbox state via locator.check() / uncheck()
• setChecked — { "checked": true \| false } via locator.setChecked()
• clear — clear text inputs via locator.clear() (file inputs blocked)
• hover — reveal menus/tooltips via locator.hover()
• doubleClick — locator.dblclick() with the same allowSubmit guard as click

{ "type": "hover", "selector": "[data-testid='account-menu']" }
{ "type": "setChecked", "testId": "terms", "checked": true }

Tier 2 interactions

• uploadFile — locator.setInputFiles() on native input[type=file]; requires files (one or more paths)
• dragTo — locator.dragTo() with source and target endpoint objects (each uses one target ref style)
• focus / blur — locator.focus(); blur focuses first then locator.blur()
• scrollIntoView — locator.scrollIntoViewIfNeeded()

{ "type": "uploadFile", "label": "Attach CSV", "files": ["/tmp/report.csv"] }
{
  "type": "dragTo",
  "source": { "testId": "draggable-item" },
  "target": { "testId": "drop-zone" }
}

Browser storage

Safe localStorage / sessionStorage manipulation for authenticated or spoofed workflows — no arbitrary JavaScript. Mutations apply to the active page (no reload). Run results include actionLog[].storage with storage, operation, keysAffected, and pageUrl for each mutation step.

| Step | Behavior | |------|----------| | storage.set | Set a string value (setItem) | | storage.remove | Remove one key or many keys | | storage.clear | Clear all items in local or session storage | | storage.assert | Assert key exists / exists: false or exact value |

{ "type": "storage.remove", "storage": "session", "key": "environmentConfig" }
{ "type": "storage.set", "storage": "local", "key": "featureFlag", "value": "enabled" }
{ "type": "storage.assert", "storage": "session", "key": "environmentConfig", "exists": false }

Example smoke flow: .sitelens/flows/storage-smoke.json.

Project flows vs QA Studio vs cloud flows

These are three different storage/run paths that share step types:

| | Project flows (this package) | QA Studio / API | |--|---------------------------|-----------------| | Storage | .sitelens/flows/my-smoke.json in your repo | Postgres via sitelens-api | | ID | String slug (my-smoke) | UUID | | Run tool | CLI sitelens flow run or MCP sitelens_run_local_flow | MCP sitelens_run_flow or Studio UI | | API key | Not required | Required | | Browser | Your machine (bundled Chromium) | SiteLens cloud hosts | | History | Local disk (sitelens_list_local_runs) | Cloud (sitelens_list_runs) |

QA Studio does not read or write .sitelens/flows/*.json today. Export/import between Studio and repo JSON is not implemented.

Run a project flow (CLI or MCP)

Project flows can run from the terminal or Cursor MCP — same load → execute path (loadLocalFlowDocument → localFlowToToolInput → executeLocalRunQa).

CLI (shell / CI)

npx --yes @sitelensapi/mcp sitelens flow run --flow-id homepage-smoke --url http://127.0.0.1:3000/
npx --yes @sitelensapi/mcp sitelens flow run --flow-id login-flow --url http://localhost:3000 --viewport desktop --json

• --flow-id → .sitelens/flows/{flowId}.json in your workspace.
• --url is required (overrides or supplements the file’s url).
• Optional: --viewport, --output, --json, --auth-profile, --auth-mode, --browser.
• Prerequisites: dev server on url, sitelens-mcp setup completed, cwd (or SITELENS_WORKSPACE_DIR) pointing at the repo with .sitelens/flows/.

MCP (Cursor / IDE agents)

Tool: sitelens_run_local_flow (registered when local tools are enabled — always, including SITELENS_MODE=local)

{
  "flowId": "homepage-smoke",
  "url": "http://127.0.0.1:3000/"
}

• Same flags as CLI where applicable: authProfile, authMode, viewports, browser, exportArtifacts.
• Cursor prompt: "Run sitelens_run_local_flow with flowId auth-login-setup and url http://127.0.0.1:3000/login — list labeled screenshot paths from actionLog (before-submit, after-login, final-state)."

Flow discovery (CLI — list only)

These commands list flows; they do not run them:

npx --yes @sitelensapi/mcp sitelens doctor
npx --yes @sitelensapi/mcp sitelens-mcp -- --self-test

Both report the resolved workspace, flows directory, and discovered flow ids when present.

To run a flow from the terminal, use npx --yes @sitelensapi/mcp sitelens flow run (see above).

Screenshot & artifact output

When exportArtifacts is true (default for flow runs):

$SITELENS_LOCAL_ARTIFACT_DIR/runs/<localRunId>/
  summary.json                 # status, paths, localRunId, screenshotPaths, actionLog
  report.md                    # human-readable report
  raw.json                     # per-viewport capture (redacted)
  screenshot-inventory.json    # PNG metadata (size, WxH)
  screenshots/                 # PNG files — end-of-run and labeled checkpoint steps

Labeled checkpoint steps ({ "type": "screenshot", "label": "after-login" }) save {label}-{viewport}-step{N}.png during the flow. Each successful step adds actionLog[].screenshot with path, url, and label.

• Default base: $TMPDIR/sitelens-mcp-local-qa (override with SITELENS_LOCAL_ARTIFACT_DIR).
• Tool response includes summary.artifactDir, summary.reportPath, and sitelens-local:// resource URIs.
• Not uploaded to SiteLens cloud. Optional pixel diff only via sitelens_compare_local_runs.

SiteLens Desktop (architecture note)

Desktop bundles the MCP HTTP runtime (start:http-runtime) as a sidecar. That runtime exposes:

• GET /flows/local — catalog .sitelens/flows/*.json
• POST /flows/local/run — execute a flow (used by Desktop capture packs)

Desktop Project flows lists .sitelens/flows/*.json and runs them in-app. When Desktop detects supportsRepoLocalScenarios in MCP capabilities, it can surface Run Scenario using localScenarioRunner metadata (path pattern, param syntax, CLI command). npm consumers can use CLI or Cursor MCP without Desktop.

Scenario Runner

Flows and scenarios solve different problems:

| | Flow | Scenario | |--|------|----------| | What it is | A single QA flow targeting one page or workflow step sequence | Setup and orchestration of one or more flows using a shared browser session/profile | | Storage | .sitelens/flows/{flowId}.json | .sitelens/scenarios/{scenarioId}.json | | Browser session | New session per run | One session for all chained flows (cookies, localStorage, sessionStorage carry over) | | Run | sitelens flow run / sitelens_run_local_flow | sitelens run scenario / sitelens_run_local_scenario | | Params | Override url at run time | {{paramName}} interpolation + scenario/runtime params |

Supported use cases

• Login flows — authenticate once, then run smoke tests in the same session
• Session initialization — establish browser state before downstream flows
• Role elevation — dev or staging session setup that grants elevated permissions for admin flows
• Feature flag activation — toggle flags in an admin flow, verify in the app flow
• Test data selection — pick a record or fixture, then run workflow verification
• Environment setup — configure staging/local context before smoke validation
• Multi-step application workflows — paths spanning several pages with shared state
• Admin workflow verification — validate admin panels and privileged actions after setup
• End-to-end smoke validation — chained setup + assertion flows in one run

Scenarios stay inside the SiteLens flow step vocabulary (click, assert*, network waits, etc.) — they chain existing flow JSON files; they are not arbitrary Playwright scripts.

Example scenario JSON

{
  "version": 1,
  "id": "role-elevation-scenario",
  "name": "Role Elevation Scenario",
  "profile": "qa-user",
  "params": {
    "baseUrl": "http://localhost:3000",
    "userId": "12345"
  },
  "flows": [
    { "flow": "session-setup" },
    { "flow": "admin-workflow-smoke" }
  ]
}

Each flows[] entry references a flow id (.sitelens/flows/{id}.json) or a path to a flow file. Optional with overrides flow fields or supplies param values for that step.

Parameter interpolation

Use {{paramName}} placeholders in flow URL fields and string step fields (selectors, assert text, fill values, etc.).

Per-flow URL override with interpolation:

{
  "flow": "session-setup",
  "with": {
    "url": "{{baseUrl}}/dev/elevate-session?user={{userId}}"
  }
}

Example flow with interpolated fields:

{
  "id": "session-setup",
  "name": "Session Setup",
  "url": "{{baseUrl}}/dev/elevate-session?user={{userId}}",
  "steps": [
    { "type": "waitForSelector", "selector": "[data-testid='session-updated']" },
    { "type": "assertText", "text": "session updated" },
    { "type": "assertUrlContains", "text": "/dev/elevate-session" }
  ]
}

Precedence (later values win):

1. scenario.params — defaults in the scenario file
2. Runtime params — CLI --param key=value or MCP params object
3. Per-flow with — overrides and extra values for that flow entry

Validation (before browser launch):

• Missing {{param}} placeholders → clear error listing required param names
• Interpolated flow JSON → validated against the same schema as .sitelens/flows (invalid URLs or steps fail before execution)

Run a scenario (CLI)

npx --yes @sitelensapi/mcp sitelens run scenario role-elevation-scenario \
  --profile qa-user \
  --param baseUrl=http://localhost:3000 \
  --param userId=12345

| Flag | Description | |------|-------------| | --profile <name> | Auth profile for persistent browser session (overrides scenario.profile) | | --param key=value | Runtime param (repeatable); merges over scenario.params | | --viewport desktop\|mobile | Repeat for both viewports | | --output <dir> | Artifact base directory (SITELENS_LOCAL_ARTIFACT_DIR) | | --json | Machine-readable combined scenario result | | --auth-mode | none | storage-state | persistent-profile (default for scenarios: persistent-profile) | | --browser | chromium | chrome | msedge | firefox | webkit | | --no-screenshot | Disable screenshots for all flows in the scenario | | --no-artifacts | Disable artifact bundle export |

Help: sitelens run scenario --help

Each flow in the scenario gets its own artifact folder under the configured artifact base; the combined JSON output lists per-flow statuses, errors, labeled screenshot paths (actionLog[].screenshot), and artifactDir values.

Run a scenario (MCP)

Tool: sitelens_run_local_scenario

Input schema:

| Field | Type | Required | Description | |-------|------|----------|-------------| | scenarioId | string | yes | Scenario id (.sitelens/scenarios/{id}.json) or path to scenario JSON | | params | object (string values) | no | Runtime params merged over scenario.params | | profile | string | no | Auth profile override | | authMode | enum | no | none | storage-state | persistent-profile | | viewports | string[] | no | desktop, mobile | | browser | enum | no | Browser channel | | screenshot | boolean | no | Enable/disable screenshots | | exportArtifacts | boolean | no | Enable/disable artifact bundles |

Example request:

{
  "scenarioId": "role-elevation-scenario",
  "profile": "qa-user",
  "params": {
    "baseUrl": "http://localhost:3000",
    "userId": "12345"
  }
}

Example response (summary fields):

{
  "scenarioId": "role-elevation-scenario",
  "scenarioName": "Role Elevation Scenario",
  "status": "passed",
  "profile": "qa-user",
  "sharedSession": true,
  "startedAt": "2026-06-01T12:00:00.000Z",
  "finishedAt": "2026-06-01T12:01:30.000Z",
  "flowResults": [
    {
      "flowRef": "session-setup",
      "flowId": "session-setup",
      "flowName": "Session Setup",
      "index": 0,
      "status": "passed",
      "testedUrl": "http://localhost:3000/dev/elevate-session?user=12345",
      "localRunId": "local_abc123",
      "artifactDir": "/tmp/sitelens-mcp-local-qa/runs/local_abc123",
      "screenshotPaths": ["/tmp/.../screenshots/local-qa-....png"],
      "reportPath": "/tmp/.../report.md"
    },
    {
      "flowRef": "admin-workflow-smoke",
      "flowId": "admin-workflow-smoke",
      "flowName": "Admin Workflow Smoke Test",
      "index": 1,
      "status": "passed",
      "testedUrl": "http://localhost:3000/admin/dashboard",
      "localRunId": "local_def456",
      "screenshotPaths": [],
      "artifactDir": "/tmp/sitelens-mcp-local-qa/runs/local_def456"
    }
  ],
  "infrastructure": "local",
  "billingNotice": "Local SiteLens MCP runs are free."
}

If a flow fails, flowResults includes error on the failed entry and later flows are skipped. CLI human output and JSON include workspace paths, auth diagnostics (profile name, auth paths, whether saved state exists), and full artifact paths (artifactDir, summary.json, screenshots).

Working across multiple repositories

Each git repo can have its own SiteLens workspace. Flows and scenarios are repo-local; auth profiles are machine-local under ~/.sitelens/.

Recommended repo layout:

your-app-repo/
  .sitelens/
    flows/           ← flow JSON files
    scenarios/       ← scenario JSON files
    config.json      ← optional: browser channel, default profile name

Run artifacts (screenshots, summary.json, report.md) are written under the configured artifact base — default $TMPDIR/sitelens-mcp-local-qa/runs/<localRunId>/, or set SITELENS_LOCAL_ARTIFACT_DIR / CLI --output.

Workspace resolution order (first match wins):

1. SITELENS_WORKSPACE_DIR — explicit override (best for CI or monorepo subprojects)
2. CURSOR_PROJECT_DIR — Cursor’s open project root
3. VSCODE_CWD — VS Code / integrated terminal cwd hint
4. process.cwd() — shell working directory when you run the CLI

Per-run workspaceDir is not a CLI flag today; use SITELENS_WORKSPACE_DIR or cd into the repo. Scenario paths can also be passed as explicit file paths (relative to workspace or absolute).

There is no automatic walk for a nearest ancestor .sitelens/ directory. If you run from a subdirectory, set SITELENS_WORKSPACE_DIR to the repo root or pass a path to the scenario file.

Use distinct profile names per app (--profile my-app-qa) so cookies from one repo do not leak into another when reusing ~/.sitelens/profiles/.

Interactive login and saved profiles

Scenarios default to persistent-profile auth — one Chromium user-data directory per profile name under ~/.sitelens/profiles/<name>/.

| Step | Command / tool | |------|----------------| | Interactive login | sitelens auth start --profile qa-user → log in → sitelens auth save | | Check saved state | sitelens auth status --profile qa-user or MCP sitelens_auth_status | | Run with profile | sitelens run scenario … --profile qa-user |

At scenario start, CLI and MCP results include auth diagnostics (no secrets):

• Profile name and resolved paths (~/.sitelens/auth/<profile>.json, ~/.sitelens/profiles/<profile>/)
• Whether each path exists on disk before the run
• Auth mode (persistent-profile, storage-state, none)
• Whether a shared session is reused across chained flows

For login flows inside a scenario, prefer DOM and URL assertions over a single network URL check — see Troubleshooting login redirects.

Running scenarios

| Surface | Command / tool | |---------|----------------| | CLI | sitelens run scenario <scenario-id> [--profile …] [--param key=value …] | | MCP | sitelens_run_local_scenario with scenarioId, optional profile, params | | Help | sitelens run scenario --help |

Use --json for CI: combined status, per-flow artifactDir, summary.json paths, and auth block. Exit code 1 when scenario status is failed.

List scenario ids: ls .sitelens/scenarios/ or copy examples from docs/examples/scenarios/.

Troubleshooting login redirects

If a flow lands on /login instead of the expected page:

1. Read auth diagnostics in the scenario result — confirm profile name, paths, and found vs missing.
2. Run sitelens auth status --profile <name> — re-save if storage state or profile dir is empty.
3. Inspect the failed flow artifact — open summary.json and screenshots under the printed artifactDir.
4. Harden login flows — combine multiple success signals instead of relying on one API response URL:

{
  "type": "expectEither",
  "label": "login success",
  "oneOf": [
    { "type": "assertSelector", "selector": "[data-testid='user-menu']", "state": "visible" },
    { "type": "assertText", "text": "Welcome" },
    { "type": "assertUrlContains", "text": "/dashboard" }
  ]
}

After submit, use assertNotExists on the login form to catch silent failures. Avoid only waitForResponse on a login API path — pair it with assertText, waitForSelector, or assertUrlContains.

Scenario runs surface login-related interpretationNotes from the underlying QA runner when a redirect is detected.

Capabilities (Desktop discovery)

When the MCP HTTP runtime is enabled, GET /capabilities includes:

| Field | Meaning | |-------|---------| | supportsRepoLocalScenarios | true when sitelens_run_local_scenario is registered | | supportsScenarioParamInterpolation | true — {{paramName}} supported in flows | | localScenarioRunner | { tool, scenarioPathPattern, paramSyntax, cliCommand } for Desktop UI |

Desktop should call /capabilities (or read MCP tool list) and, when supportsRepoLocalScenarios is true, offer Run Scenario with runtime param inputs matching localScenarioRunner.paramSyntax ({{paramName}}).

Complete examples

Copyable bundles live in docs/examples/:

1. Login → smoke test — login-then-smoke-scenario.json + auth-login-setup, homepage-smoke flows
2. Session setup → admin smoke — role-elevation-scenario.json + session-setup, admin-workflow-smoke flows
3. Multi-flow workflow verification — workflow-verification-scenario.json — test data selection → feature toggle → admin panel verify

See docs/scenario-runner-release-notes.md for release notes and a pre-release verification checklist.

Migrating from helper scripts

Shell wrappers that call multiple flow runs in sequence:

./run-workflow.sh userId=12345
./run-smoke.sh userId=12345

become one scenario file plus a single command:

sitelens run scenario role-elevation-scenario \
  --param userId=12345

Scenarios replace custom orchestration scripts in many cases while keeping flows as reusable, reviewable JSON. You still author flows for individual pages; scenarios wire them together with shared session and params.

SiteLens ecosystem

| Surface | What it is | Local flows? | |---------|------------|--------------| | @sitelensapi/mcp (this package) | MCP server + CLI for Cursor/IDEs and shell/CI | Yes — .sitelens/flows + CLI + MCP tools | | SiteLens API | Hosted cloud QA, run history, artifacts | Cloud UUID flows via sitelens_run_flow | | QA Studio | Visual flow builder (web) | Cloud-stored flows — not the same as .sitelens/flows JSON | | SiteLens Desktop | Native app + local engine | Project flows page — list and run .sitelens/flows/*.json | | Dashboard / MCP onboarding | API keys, setup copy-paste | — |

Website: https://www.sitelensapi.com
MCP docs: https://www.sitelensapi.com/mcp/docs
npm: @sitelensapi/mcp · @sitelensapi/qa-smoke (shared step schema; usually a dependency)

Setup guides

• Use SiteLens MCP globally in Cursor
• WSL / Linux setup
• Login once and reuse auth
• Authenticated localhost QA
• Project flows & local templates
• Clear saved sessions

CLI commands

| Command | Purpose | |---------|---------| | sitelens-mcp | Start stdio MCP server (normal Cursor wiring) | | sitelens-mcp setup | Install bundled Chromium + verify dirs | | sitelens-mcp -- --self-test | Readiness probe (workspace, flows dir, browser) | | sitelens doctor | Portable diagnostics (lists .sitelens/flows ids) | | sitelens doctor --cursor | Cursor-focused hints + example mcp.json | | sitelens flow init | Scaffold .sitelens/flows/{flowId}.json (--flow-id or positional id; --template) | | sitelens flow run | Run .sitelens/flows/{flowId}.json (--flow-id, --url) | | sitelens run scenario | Run .sitelens/scenarios/{scenarioId}.json (chained flows, shared session) |

Example:

npx --yes @sitelensapi/mcp sitelens flow run \
  --flow-id homepage-smoke \
  --url https://example.com

npx --yes @sitelensapi/mcp sitelens run scenario login-then-smoke-scenario \
  --profile qa-user \
  --param baseUrl=http://localhost:3000

Cursor wiring: use npx -y @sitelensapi/mcp as the command — do not pass setup, doctor, flow run, or --self-test as MCP server args.

SiteLens Desktop uses a separate HTTP runtime process (start:http-runtime) — do not set SITELENS_MCP_HTTP=1 in Cursor unless you intentionally want a loopback health server.

MCP tools

Local (registered when SITELENS_MODE=local or always without cloud key)

| Tool | Description | |------|-------------| | sitelens_setup | First-run bootstrap | | sitelens_billing_status | Local-free vs cloud-paid boundary | | sitelens_auth_start / _save / _status / _clear | Login-once auth under ~/.sitelens/ | | sitelens_qa_run | Ad-hoc local QA (preferred name) | | sitelens_run_local_qa | Same as sitelens_qa_run (legacy alias) | | sitelens_run_local_flow | Run .sitelens/flows/{flowId}.json | | sitelens_run_local_scenario | Run .sitelens/scenarios/{scenarioId}.json (chained flows, shared session, {{param}} interpolation) | | sitelens_list_local_runs | Scan local artifact dirs | | sitelens_compare_local_runs | Diff two local run bundles |

Cloud (requires SITELENS_API_KEY + SITELENS_MODE=all or cloud)

| Tool | HTTP | |------|------| | sitelens_analyze_page | POST /analyze/page | | sitelens_run_qa | POST /analyze/qa | | sitelens_list_runs | GET /qa/runs | | sitelens_get_run | GET /qa/runs/:runId | | sitelens_run_flow | POST /qa/flows/:flowId/run |

Cloud run resources: sitelens://runs/{runId} (Markdown digest via MCP resources/read).

Cursor MCP config (cloud + local)

When you need cloud tools, add your API key:

{
  "mcpServers": {
    "sitelens": {
      "command": "npx",
      "args": ["--yes", "@sitelensapi/mcp", "sitelens-mcp"],
      "env": {
        "SITELENS_API_BASE_URL": "https://api.sitelensapi.com",
        "SITELENS_API_KEY": "sitelens_sk_…",
        "SITELENS_MODE": "all"
      }
    }
  }
}

Local-only tools work without an API key — omit the key or use SITELENS_MODE=local.

Page Intelligence: Use MCP tool sitelens_analyze_page (cloud API) to plan flows from page structure. See Page Intelligence overview and monorepo doc docs/sitelens-mcp-page-intelligence.md for the analyze → flow → verify workflow.

Environment variables

| Variable | Description | |----------|-------------| | SITELENS_MODE | local (default for Cursor) · all · cloud | | SITELENS_API_KEY | Required for cloud tools only | | SITELENS_API_BASE_URL | API origin (default http://127.0.0.1:3000; production https://api.sitelensapi.com) | | SITELENS_WORKSPACE_DIR | Override workspace root for .sitelens/flows and .sitelens/scenarios (see Working across multiple repositories) | | SITELENS_LOCAL_ARTIFACT_DIR | Base for runs/<localRunId>/ bundles | | SITELENS_LOCAL_BROWSER_CHANNEL | Omit → bundled Chromium; or chrome / msedge / firefox / webkit | | SITELENS_BROWSER_CHANNEL | Optional local MCP alias when SITELENS_LOCAL_BROWSER_CHANNEL unset — chrome, msedge, or chromium (bundled default). Explicit chrome/msedge never silently falls back to bundled Chromium | | SITELENS_LOCAL_BROWSER_ARGS | Advanced/dev-only: comma-separated Chromium launch flags (e.g. --ignore-certificate-errors) for local MCP runs | | SITELENS_LOCAL_ALLOWED_HOSTS | Extra hostnames for local QA (staging domains) | | SITELENS_LOCAL_IGNORE_HTTPS_ERRORS | Local/dev only: true, 1, or yes — Playwright ignores HTTPS certificate errors (self-signed / private CA) | | SITELENS_DEFAULT_URL | Default target for cloud sitelens_run_qa |

Never commit real API keys.

Example Cursor prompts

• "Use SiteLens setup."
• "Run SiteLens local QA on http://localhost:3000."
• "Run sitelens_run_local_flow with flowId homepage-smoke and url http://127.0.0.1:3000/."
• "Run sitelens_run_local_scenario for login-then-smoke-scenario with baseUrl http://127.0.0.1:3000/."
• "List my last 10 SiteLens local QA runs."
• "Compare these two local runs and include screenshot diff."
• "Open the SiteLens local report resource for the last run."

With cloud API key configured:

• "Use sitelens_analyze_page on https://www.sitelensapi.com/ and list primaryActions and workflowStages."
• "Use SiteLens to QA https://staging.example.com and call out blockers."
• "List my latest SiteLens QA runs."
• "Run saved flow <cloud-flow-uuid> against https://staging.example.com."

Remote registry (prompts, flows, templates)

Ship updated Cursor prompts, example flows, and local QA template presets without publishing a new @sitelensapi/mcp version.

npx --yes @sitelensapi/mcp sitelens registry sync
npx --yes @sitelensapi/mcp sitelens registry list --type prompts
npx --yes @sitelensapi/mcp sitelens registry show prompts teach-cursor
npx --yes @sitelensapi/mcp sitelens registry materialize flow homepage-smoke

Cache: ~/.sitelens/registry/ (override with SITELENS_REGISTRY_DIR). Catalog URL: SITELENS_REGISTRY_URL (default https://www.sitelensapi.com/registry/v1/).

Operators publish catalog JSON to https://www.sitelensapi.com/registry/v1/ (manifest + prompts/, flows/, scenarios/, qa-templates/). Scenario templates use the same flow-entry shape as local scenarios; remote sync is optional — local .sitelens/scenarios/ works without registry sync.

Monorepo development

cd packages/sitelens-mcp
pnpm install
pnpm run build
pnpm run setup
pnpm run doctor
pnpm run start        # stdio MCP server
pnpm run test
pnpm run pack:smoke   # release tarball smoke

Rebuild after src/ changes — MCP clients run compiled dist/.

Requirements & privacy

• Node.js 20+
• Local QA: bundled browser runtime (via sitelens-mcp setup); no Docker
• macOS: approve Cursor + browser automation in Privacy & Security when prompted
• Local artifacts stay on disk — not uploaded to SiteLens cloud by default
• SITELENS_API_KEY is required only for cloud HTTP tools and sitelens://runs/… resources

Troubleshooting: browser runtime (last resort)

Normal path: sitelens-mcp setup (or sitelens doctor) — installs dirs, probes the bundled Chromium, and reports what failed.

Only if setup cannot finish (offline CDN, strict proxies, corrupted cache) and you are developing this package from a git checkout:

cd packages/sitelens-mcp && pnpm exec playwright install chromium

Then rerun sitelens-mcp setup. Do not use the command above for routine installs — it bypasses SiteLens setup checks.

License

See repository root for license terms.