Metadata-Version: 2.4
Name: webscope-mcp
Version: 0.3.0
Summary: MCP server (stdio, standard library only) that gives a coding agent short answers about a project
License-Expression: MIT
Project-URL: Repository, https://github.com/partprogramming09/webscope
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Webscope

<!-- mcp-name: io.github.partprogramming09/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`:

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

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

### 2. Register with your MCP client

```sh
# 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 `buscar`, `leer`, and `correr`.

---

## Tools

| Tool | Description |
| :--- | :--- |
| `buscar(texto, donde?, tope?, formato?, contexto?, regex?)` | Case-insensitive search grouped by file with relevance ranking. `formato="conciso"` returns top 5 files. Skips secrets (`.env`, `*.key`). |
| `leer(archivo, simbolo?, lineas?, max_lineas?, cola?, contiene?, formato?)` | Surgical read: extracts a single function, method, class (PHP, TS, JS, Vue, Python), Markdown section, line range, or log tail (`cola`). |
| `correr(nombre?, args?, detalle?)` | Runs a declared read-only script from the manifest. Output trimmed to head and tail limits. |
| `correr_escritura(nombre, args)` | Runs scripts declared in `escribe`. Requires `WEBSCOPE_ESCRITURA=1` and interactive user confirmation. |

Every response starts with a one-line actionable guide and is capped at `tope_tokens` (~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 (`--evaluar`)
Operates directly on the developer's open Google Chrome window without opening clean/incognito profiles, preserving your active cookies, logins, and 2FA:

```sh
# Inspect current screen on active tab
python3 webscope_adaptadores/e2e_chrome.py --evaluar "window.__f.estado()"

# Run on a tab matching a specific URL
python3 webscope_adaptadores/e2e_chrome.py --evaluar "window.__f.estado()" "localhost:5173"

# Run a complete JS test flow
python3 webscope_adaptadores/e2e_chrome.py --evaluar 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 (`--repetir <nombre>`)**: Replays recorded user flows in one call with 0 AI tokens.
- **Playwright Export (`--exportar <captura> <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`](webscope.example.json).

```json
{
  "root": ".",
  "recorte": { "cabeza": 10, "cola": 70 },
  "tope_tokens": 5000,
  "almacenamiento": ".agents/webscope",
  "prefijo_prueba": "ZZ_E2E",
  "buscar": { "dirs": ["src"], "extensiones": ["ts", "vue", "php", "py"] },
  "env_permitidas": ["DATABASE_URL"],
  "scripts": {
    "report": {
      "cmd": ["python3", "-I", "scripts/report.py"],
      "descripcion": "Summarises a database table",
      "uso": "<table>",
      "rechaza": ["--out"],
      "escribe": ["--fix"],
      "timeout": 120
    }
  }
}
```

| Key | Description |
| :--- | :--- |
| `root` | Project root relative to manifest directory. |
| `raices_extra` | Folders outside `root`, relative to the manifest directory, that `buscar` and `leer` may also read (for example a logs folder). Secret files stay blocked. |
| `tope_tokens` | Hard limit on response size in approximate tokens. |
| `recorte` | Default head (`cabeza`) and tail (`cola`) lines kept from script outputs. |
| `almacenamiento` | Internal storage for `mapa-modulos.json`, `flujos/`, `recorridos/`. Autodetects `.agents/webscope/`, `.claude/webscope/`, or `.webscope/`. |
| `prefijo_prueba` | Prefix for test entities (default `ZZ_E2E`). |
| `buscar.dirs`, `extensiones` | Folders and extensions searched by default. |
| `env_permitidas` | Environment variables passed to child scripts. |
| `scripts.<name>` | Fixed command list (`cmd`), `rechaza` (blocked flags), `escribe` (write flags). |

---

## Included Adapters (`{adaptadores}`)

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

| Script | Purpose | Stack |
| :--- | :--- | :--- |
| `e2e_chrome.py` | Browser walk, form automation (`__f`), replay, and open Chrome connector (`--evaluar`). | Any SPA |
| `vue_ts.py` (`mapa`) | Module mapping: routes, subroutes, clickable actions, API calls, and E2E coverage. | Vue 3 + TS |
| `laravel.py` (`mapa_back`) | Resolves endpoint → controller → service → model → database table. | Laravel |
| `astro.py` (`mapa_web`) | File-based routes, components, form fields, and client scripts. | Astro |
| `db_check.php` | SELECT-only database integrity checks by prefix marker from `.env`. | MySQL / Postgres |
| `payload_check.py` | Compares captures against FormRequest rules, Resources, and columns. | Laravel |
| `limpiar_zz.py` | Lists and safely cleans test rows matching the test prefix. | Laravel |
| `costo_sesion.py` | Token and USD cost auditor per model for Claude Code sessions. | Claude Code |

---

## Subagents Integration

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

### Exporting the `recorrido` Agent
Export the ready-made walk agent without overwriting existing agents:

```sh
# Autodetects .agents/ or .claude/agents/
webscope-mcp --agente

# Or targeting a specific folder
webscope-mcp --agente [directorio]
```

- **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`:
```yaml
---
name: navegador
tools: Read, Grep, Glob, mcp__webscope__buscar, mcp__webscope__leer, mcp__webscope__correr
model: sonnet
effort: high
---
```

---

## Configuration in Other Clients

### Claude Desktop (`claude_desktop_config.json`)
```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`)
```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`)
```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

```sh
# 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**: `buscar` and `leer` 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 (`escribe`) require `correr_escritura`, `WEBSCOPE_ESCRITURA=1`, and explicit approval.

### Recommended `.gitignore`
```gitignore
# Temporary Webscope artifacts
capturas/
.webscope/capturas/
```

Commit `webscope.json`, `.claude/webscope/recorridos/` (or `.agents/webscope/`), and `mapa-modulos.json`.

---

## Tests

```sh
python3 -I test_webscope.py
```

## License

[MIT](LICENSE)
