Webscope

A lightweight, token-efficient MCP server (stdio, JSON-RPC 2.0, Python standard library only). It provides coding agents with short, surgical answers: grouped search hits, isolated symbols instead of whole files, native in-browser testing on the user's open Chrome, and bounded project scripts.

Tool names, parameters, and messages are in Spanish.

Quick Start

1. Initialize your project

Run in your project root to auto-detect your stack (Laravel, Vue/React, Astro, Python, or generic) and generate webscope.json:

# Via uvx (no install needed)
uvx webscope-mcp --init

# Or locally with Python
python3 webscope.py --init

2. Register with your MCP client

# Claude Code (recommended, writes project .mcp.json)
claude mcp add --scope project webscope -- uvx --from git+https://github.com/partprogramming09/webscope@v0.3.0 webscope-mcp --manifest "$PWD/webscope.json"

# With pip
pip install git+https://github.com/partprogramming09/webscope.git@v0.3.0
claude mcp add --scope project webscope -- webscope-mcp --manifest "$PWD/webscope.json"

Start claude and verify with /mcp: webscope will be connected with search, read, and run.

Tools

Every response starts with a one-line actionable guide and is capped at token_limit (~4 characters per token).

In-Browser Testing & Chrome Connector (e2e_chrome.py)

Webscope includes an in-browser automation engine that replaces heavy screenshot-based tools with lightweight DOM extraction:

Native Chrome Connector (--evaluate)

Operates directly on the developer's open Google Chrome window without opening clean/incognito profiles, preserving your active cookies, logins, and 2FA:

# Inspect current screen on active tab
python3 webscope_adapters/e2e_chrome.py --evaluate "window.__f.state()"

# Run on a tab matching a specific URL
python3 webscope_adapters/e2e_chrome.py --evaluate "window.__f.state()" "localhost:5173"

# Run a complete JS test flow
python3 webscope_adapters/e2e_chrome.py --evaluate test_flow.js "localhost:5173"

Key Capabilities

• Screen & Form Helpers (__f): Finds inputs by visible label, fills values, coordinates clicks with active settle wait (calma()), and verifies persistence.
• Network Capture (__e2e): Intercepts /api/ calls, latency (ms), and console errors without screenshots.
• Self-Healing Across Reloads: Injected helpers tolerate full page reloads (window.location.reload()) with automatic re-initialization.
• Zero-Token Replay (--replay <name>): Replays recorded user flows in one call with 0 AI tokens.
• Playwright Export (--export <capture> <url>): Converts recorded steps into clean .spec.js Playwright tests.

The Essential Testing Contract: Full Lifecycle (CRUD + Sub-modules)

A module is never considered tested by merely reading a view or clicking a button. Webscope enforces a strict full-lifecycle standard:

1. Create (C): Fill mandatory and conditional fields, submit, verify HTTP 200/201, and capture the generated record ID.
2. Edit (U): Reopen the record, mutate fields, and verify data persistence in both UI and database.
3. Exercise Sub-modules & Lifecycle: Navigate sub-routes (:id), exercise child panels/tabs (e.g. characteristics, tariffs, pre-settlements, notes, print), and trigger state transitions (e.g. approve, reopen, duplicate).
4. Delete & Clean (D): Delete the test record, confirm UI removal, and verify database clean state (ZZ_E2E).

Configuration (webscope.json)

All behavior is project-contained. See webscope.example.json.

{
  "root": ".",
  "trim": { "head": 10, "tail": 70 },
  "token_limit": 5000,
  "storage": ".agents/webscope",
  "test_prefix": "ZZ_E2E",
  "search": { "dirs": ["src"], "extensions": ["ts", "vue", "php", "py"] },
  "allowed_env": ["DATABASE_URL"],
  "scripts": {
    "report": {
      "cmd": ["python3", "-I", "scripts/report.py"],
      "description": "Summarises a database table",
      "usage": "<table>",
      "rejects": ["--out"],
      "writes": ["--fix"],
      "timeout": 120
    }
  }
}

The project section

Read by the included adapters; every key is optional and has a neutral default.

Database adapters run inside a transaction that is rolled back; only cleanup_test_rows --delete --confirm and tinker --commit (both behind run_write) commit.

Included Adapters ({adapters})

Ready-made scripts shipped in the package. Use {adapters} in cmd:

Subagents Integration

Webscope keeps subagents fast and lightweight (~9.3k tokens initial load vs 28.8k).

Exporting the walkthrough Agent

Export the ready-made walk agent without overwriting existing agents:

# Autodetects .agents/ or .claude/agents/
webscope-mcp --agent

# Or targeting a specific folder
webscope-mcp --agent [directory]

• Non-destructive: Never overwrites existing agent files unless --force is passed.
• Isolation: Leaves all other user-defined agents untouched.

Declaring Tools in Agents

In your .agents/<name>.md or .claude/agents/<name>.md:

---
name: navegador
tools: Read, Grep, Glob, mcp__webscope__search, mcp__webscope__read, mcp__webscope__run
model: sonnet
effort: high
---

Configuration in Other Clients

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "webscope": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/partprogramming09/webscope@v0.3.0", "webscope-mcp", "--manifest", "/absolute/path/to/webscope.json"]
    }
  }
}

Cursor / VS Code / Cline (.cursor/mcp.json or .vscode/mcp.json)

{
  "mcpServers": {
    "webscope": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/partprogramming09/webscope@v0.3.0", "webscope-mcp", "--manifest", "${workspaceFolder}/webscope.json"]
    }
  }
}

Zed (settings.json)

{
  "context_servers": {
    "webscope": {
      "command": {
        "path": "uvx",
        "args": ["--from", "git+https://github.com/partprogramming09/webscope@v0.3.0", "webscope-mcp", "--manifest", "/absolute/path/to/webscope.json"]
      }
    }
  }
}

Updating

# uvx: refresh package cache
uv cache clean webscope-mcp

# pip: force reinstall
pip install --upgrade --force-reinstall git+https://github.com/partprogramming09/webscope.git@v0.3.0

Security Model

• Root Sandbox: search and read resolve strictly within root and reject outside paths.
• Invisible Secrets: Automatically hides .env*, *.pem, *.key, *.p12, id_rsa*, id_ed25519*, auth.json, and credentials.
• No Shell Injection: Scripts execute as fixed argument lists without intermediate shell.
• Read-Only Default: Destructive arguments (writes) require run_write, WEBSCOPE_WRITE=1, and explicit approval.

Recommended .gitignore

# Temporary Webscope artifacts
captures/
.webscope/captures/

Commit webscope.json, .claude/webscope/walkthroughs/ (or .agents/webscope/), and module-map.json.

Tests

python3 -I test_webscope.py

License

MIT