looking-glass-mcp 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sahib Sawhney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,283 @@
+<p align="center">
+  <img src=".github/assets/looking-glass-logo.png" alt="Looking Glass" width="600" />
+</p>
+
+# Looking Glass
+
+**Give your AI agent real eyes.** Looking Glass is an MCP server that hands Claude Code a full Chromium browser — 63 tools for navigating, clicking, screenshotting, testing, auditing, and automating any web application.
+
+Built by Sahib Sawhney. [MIT License](LICENSE).
+
+---
+
+## Why Looking Glass?
+
+Claude Code is powerful, but it is blind. It cannot see your web app, click your buttons, or verify your login flow actually works. Looking Glass fixes that.
+
+```
+You:    "Does the checkout flow work on staging?"
+
+Claude: Opens a real browser. Navigates to staging. Fills the cart.
+        Enters payment details. Clicks submit. Screenshots every step.
+        Checks for console errors. Monitors API responses.
+        "Checkout completes successfully. One warning: the /api/payment
+        endpoint took 4.2s — see the performance audit below."
+```
+
+This is not a mock. Not a simulation. Claude controls a real browser, sees real screenshots, and reads real DOM trees.
+
+---
+
+## Get Running in 60 Seconds
+
+**Option A** — Add directly to Claude Code:
+
+```bash
+claude mcp add looking-glass -- npx looking-glass-mcp
+```
+
+**Option B** — Install globally:
+
+```bash
+npm install -g looking-glass-mcp
+```
+
+**Option C** — Configure `.mcp.json` manually:
+
+```json
+{
+  "mcpServers": {
+    "looking-glass": {
+      "command": "npx",
+      "args": ["looking-glass-mcp"],
+      "env": {
+        "BROWSER_HEADLESS": "false"
+      }
+    }
+  }
+}
+```
+
+Then just talk to Claude:
+
+```
+"Open localhost:3000 and tell me what you see"
+"Run an accessibility audit on the landing page"
+"Test the signup flow with an invalid email"
+"Explore the entire site and map all the pages"
+```
+
+---
+
+## The 63-Tool Arsenal
+
+Looking Glass ships with **63 MCP tools** organized across 7 categories. Every interaction and navigation tool automatically returns a **page state envelope** — URL, title, console errors, failed requests, and a screenshot — so the agent never needs follow-up calls to see what happened.
+
+### Core Browser Control
+
+| Tool | What it does |
+|------|-------------|
+| `browser_navigate` | Go to any URL |
+| `browser_click` | Click by CSS selector or plain text |
+| `browser_smart_click` | Click by natural language description ("the blue Submit button") |
+| `browser_type` | Fill input fields |
+| `browser_hover` | Hover over elements |
+| `browser_drag` | Drag and drop |
+| `browser_select_option` | Choose from dropdowns |
+| `browser_press_key` | Keyboard input (Enter, Tab, Escape, etc.) |
+| `browser_scroll` | Scroll page or scroll to a specific element |
+| `browser_go_back` / `browser_go_forward` | History navigation |
+| `browser_tab_new` / `browser_tab_list` / `browser_tab_select` / `browser_close` | Multi-tab management |
+
+### AI-Native Intelligence
+
+These tools exist because an AI is the operator — they would be useless to a human.
+
+| Tool | What it does |
+|------|-------------|
+| `browser_analyze_page` | Returns structured page analysis: type (login, dashboard, form, error), available actions, forms, navigation links, data elements, and page state |
+| `browser_resolve_element` | Finds elements by natural language ("the email input", "third navigation link") with confidence scores, **visibility, enabled state, bounding box, and viewport position** |
+| `browser_smart_click` | Click elements described in plain English instead of fragile CSS selectors. Returns page state envelope with screenshot. |
+| `browser_suggest_actions` | Examines the page and suggests what the agent should do next, with pre-filled tool parameters (returns structured JSON) |
+| `browser_explore` | Autonomously crawls the site within domain boundaries, classifies every page, and returns a complete site map (returns structured JSON) |
+| `browser_wait_until_stable` | Waits for true page readiness using multiple signals: network idle, DOM settled, spinners gone, images loaded |
+| `browser_login` | **Composite action**: navigates to login URL, auto-detects fields, fills credentials, submits, verifies redirect, reports cookies set — all in one call |
+| `browser_fill_and_submit` | **Composite action**: fills form fields by selector or label, submits, returns before/after state with screenshot |
+
+### Observation & Debugging
+
+| Tool | What it does |
+|------|-------------|
+| `browser_screenshot` | Capture viewport or full-page screenshot (returned inline) |
+| `browser_snapshot` | Get the full accessibility tree as structured text |
+| `browser_evaluate` | Execute arbitrary JavaScript in page context |
+| `browser_console_messages` | Read console logs, warnings, errors |
+| `browser_network_requests` | Monitor all HTTP requests and responses |
+| `browser_diagnose` | One-shot diagnostic bundle: console errors + failed requests + DOM context + screenshot |
+| `browser_error_report` | Catalog of all uncaught JS exceptions and failed resource loads |
+| `browser_snapshot_state` / `browser_diff_state` | Take a before/after snapshot and see exactly what changed on the page |
+| `browser_action_history` | Full journal of every action taken: tool, args, URL before/after, new errors, duration (returns structured JSON) |
+| `browser_clear_history` | Reset the action journal |
+
+### Storage & State Inspection
+
+| Tool | What it does |
+|------|-------------|
+| `browser_get_cookies` / `browser_set_cookie` | Read and write browser cookies |
+| `browser_get_localstorage` / `browser_set_localstorage` | Read and write localStorage entries |
+| `browser_clear_storage` | Clear cookies, localStorage, sessionStorage, or all at once |
+| `browser_clean_slate` | Nuclear option: wipe cookies, localStorage, sessionStorage, IndexedDB, and Cache API |
+
+### Test Automation
+
+| Tool | What it does |
+|------|-------------|
+| `test_scenario_run` | Execute multi-step test scenarios defined in JSON |
+| `test_scenario_status` | Check progress of a running scenario |
+| `test_assert` | Run a single assertion (12 types: exists, textContains, urlEquals, isVisible, etc.) |
+| `test_fill_form` | Auto-fill form fields by selector mapping |
+| `test_auth_flow` | Test complete login/signup flows end-to-end |
+| `test_watch_events` / `test_stop_watch` | Monitor DOM mutations, network requests, console errors, and dialogs |
+| `test_accessibility_audit` | WCAG 2.1 AA compliance audit with severity-ranked violations and fix suggestions |
+| `browser_performance_audit` | Core Web Vitals, page timing, resource analysis, and a performance score |
+| `test_generate_assertions` | Auto-detect what should be tested on the current page |
+| `test_chaos` / `test_chaos_clear` | Chaos testing: slow-3g, offline, block-api, random-delays, no-js, slow-cpu |
+
+### Session Recording & Visual Regression
+
+| Tool | What it does |
+|------|-------------|
+| `session_start` / `session_end` / `session_list` | Record browser sessions with action timelines |
+| `session_export_playwright` | Convert a recorded session into a standalone Playwright `.spec.ts` test file |
+| `visual_baseline` / `visual_compare` | Pixel-level visual regression testing with diff images |
+
+### Request Mocking
+
+| Tool | What it does |
+|------|-------------|
+| `browser_mock_route` | Intercept requests matching a URL pattern and return mock responses |
+| `browser_list_mocks` / `browser_clear_mocks` | Manage active mock routes |
+
+### Enterprise & Reliability
+
+| Tool | What it does |
+|------|-------------|
+| `browser_health_check` | Verify the browser is responsive |
+| `browser_recover` | Auto-recover from crashes by relaunching and restoring the last URL |
+
+---
+
+## Test Scenarios
+
+Define multi-step test flows in JSON and run them with `test_scenario_run`:
+
+```json
+{
+  "name": "Login Flow",
+  "steps": [
+    { "name": "Navigate", "action": "navigate", "url": "http://localhost:3000/login" },
+    { "name": "Enter email", "action": "type", "selector": "input[type='email']", "value": "user@test.com" },
+    { "name": "Enter password", "action": "type", "selector": "input[type='password']", "value": "secret" },
+    { "name": "Submit", "action": "click", "selector": "button[type='submit']" },
+    { "name": "Verify redirect", "action": "assert", "type": "urlContains", "expected": "/dashboard" },
+    { "name": "Capture result", "action": "screenshot", "screenshotName": "post-login" }
+  ]
+}
+```
+
+**14 step actions**: navigate, click, type, select, hover, scroll, press, waitForSelector, waitForText, waitForNavigation, waitForNetworkIdle, assert, screenshot, evaluate, sleep
+
+**12 assertion types**: exists, notExists, textContains, textEquals, hasAttribute, hasClass, isVisible, isEnabled, urlContains, urlEquals, countEquals, consoleNoErrors
+
+---
+
+## Configuration
+
+Everything is configured through environment variables.
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `BROWSER_HEADLESS` | `true` | Set `false` to watch the browser in real-time |
+| `BROWSER_ENGINE` | `chromium` | Browser engine: `chromium`, `firefox`, or `webkit` |
+| `BROWSER_VIEWPORT_WIDTH` | `1280` | Viewport width in pixels |
+| `BROWSER_VIEWPORT_HEIGHT` | `720` | Viewport height in pixels |
+| `BROWSER_TIMEOUT` | `30000` | Default operation timeout (ms) |
+| `BROWSER_SESSIONS_DIR` | `.browser-sessions` | Where screenshots, sessions, and audit logs are stored |
+| `BROWSER_SECURITY_PROFILE` | `local-dev` | Security profile (see below) |
+| `BROWSER_CHANNEL` | — | Specific browser channel (`chrome`, `msedge`) |
+| `BROWSER_PROXY_URL` | — | HTTP/HTTPS/SOCKS5 proxy for corporate environments |
+| `BROWSER_CA_CERT_PATH` | — | Path to custom CA certificate |
+
+### Security Profiles
+
+| Profile | URL Access | JS Execution | Tool Access | Rate Limit |
+|---------|-----------|--------------|-------------|------------|
+| `local-dev` | All HTTP/HTTPS | Allowed | All tools | 60/min |
+| `restricted` | localhost only | Blocked | Observation only | 30/min |
+| `open` | Everything | Allowed | All tools | 120/min |
+
+The `restricted` profile enforces **read-only access** — the agent can screenshot and inspect but cannot click, type, or modify anything. Ideal for production monitoring.
+
+---
+
+## Architecture
+
+```mermaid
+graph TD
+    A[Claude Code] -->|MCP stdio| B[Looking Glass]
+    B -->|Playwright API| C[Browser Engine]
+    C -->|Screenshots + DOM| B
+    B -->|Inline images + text| A
+
+    B --> D[Middleware Layer]
+    D --> E[Audit Logger]
+    D --> F[RBAC Policy]
+
+    B --> G[Session Recorder]
+    B --> H[Visual Comparator]
+```
+
+Looking Glass sits between Claude Code and a real browser. Every tool invocation passes through a middleware layer that handles audit logging and role-based access control. Sessions are recorded to disk. Visual baselines are stored for regression comparison.
+
+---
+
+## Claude Code Integration
+
+### Agent: `e2e-tester`
+
+A specialized testing agent that knows all 63 tools and follows a structured workflow. Invoke it for comprehensive testing:
+
+```
+"Use the e2e-tester agent to verify the entire checkout flow"
+```
+
+### Skill: `/looking-glass-test`
+
+Quick-fire E2E testing. Give it a URL and it handles the rest:
+
+```
+/looking-glass-test https://myapp.com
+```
+
+It will navigate, screenshot, discover pages, run assertions, check for JS errors, audit accessibility, and generate a pass/fail report.
+
+---
+
+## Development
+
+```bash
+git clone <your-repo-url>
+cd looking-glass
+npm install
+npx playwright install chromium
+npm run build
+npm start
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/bin/looking-glass-mcp.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../build/index.js';