webscope

# Webscope

<!-- mcp-name: io.github.partprogramming09/webscope -->

A small MCP server (stdio, JSON-RPC 2.0, Python standard library only) that gives a coding agent short answers about a
project: grouped search hits, one symbol instead of a whole file, and the output of the project's own read-only scripts,
trimmed to head and tail. The goal is fewer tokens per question.

Tool names, parameters and messages are in Spanish.

## Requirements

- Python 3.9 or newer (no third-party packages)
- Optional: [uv](https://docs.astral.sh/uv/), to run it with `uvx` without cloning
- `grep` on `PATH` (used by `buscar`)

## Installation

1. In your project's root, create its manifest and list the folders and scripts it may use
   (see [Configuration](#configuration-webscopejson) and [`webscope.example.json`](webscope.example.json)).

2. Register the server. With Claude Code, from the project's root, pick one:

   ```sh
   # with uv, no clone needed (like npx)
   claude mcp add --scope project webscope -- uvx --from git+https://github.com/partprogramming09/webscope webscope-mcp --manifest "$PWD/webscope.json"

   # with a clone and plain Python
   git clone https://github.com/partprogramming09/webscope.git ~/webscope
   claude mcp add --scope project webscope -- python3 -I ~/webscope/webscope.py --manifest "$PWD/webscope.json"
   ```

   `--scope project` writes `.mcp.json` so the whole team gets it; use `--scope user` for all your projects. Add
   `-e WEBSCOPE_ESCRITURA=1` before `--` only if a script declares `escribe` and you want to allow it.

3. Start `claude` in the project, approve the server, and check it with `/mcp`: `webscope` should show as connected
   with the tools `buscar`, `leer` and `correr`.

Other MCP clients: add the same command to their configuration, for example a `.mcp.json`:

```json
{
  "mcpServers": {
    "webscope": {
      "command": "python3",
      "args": ["-I", "/path/to/webscope/webscope.py", "--manifest", "/path/to/your/project/webscope.json"]
    }
  }
}
```

Instead of `--manifest` you can set the environment variable `WEBSCOPE_MANIFEST`. Without either, the server uses
`./webscope.json` if it exists; otherwise it serves the current folder with `buscar` and `leer` and no scripts.

### Docker

```sh
docker build -t webscope .
docker run -i --rm -v "$PWD:/project:ro" -e WEBSCOPE_MANIFEST=/project/webscope.json webscope
```

Without `WEBSCOPE_MANIFEST` the image serves the bundled `webscope.example.json`.

## Tools

| Tool | What it does |
| :--- | :--- |
| `buscar(texto, donde?, tope?, formato?, contexto?, regex?)` | Case-insensitive search, literal unless `regex=true` (extended regex). Hits grouped by file, most-referenced files first, capped at `tope` lines. `donde` limits it to a folder or file; `contexto` (0-5) adds lines around each hit. `formato="conciso"` returns only the top 5 files with counts. |
| `leer(archivo, simbolo?, lineas?, max_lineas?, cola?, contiene?, formato?)` | Returns only one function, method or class (PHP, TS, JS, Vue, Python) — or several, if `simbolo` is a list —, one Markdown section by heading, a line range (`lineas="120-180"`), or for `.log`/`.txt`/`.out` files the last `cola` lines and/or the lines containing `contiene`. Without `simbolo` or `lineas` it returns the file's index: headings or definitions with their line numbers. |
| `correr(nombre?, args?, detalle?)` | Runs a script declared in the manifest and returns `exit N` plus trimmed output. Without `nombre` it lists the scripts; `detalle="esquema"` shows one script's usage. Read-only. |
| `correr_escritura(nombre, args)` | Only listed when a script declares `escribe`. Runs a write argument; requires `WEBSCOPE_ESCRITURA=1` in the server environment and is marked `destructiveHint` and `anthropic/requiresUserInteraction`. |

Every answer starts with one short line saying what it is and what to do next, and is capped at `tope_tokens`
(about 4 characters per token).

A malformed request, a non-UTF-8 script output or an unexpected error comes back as an error message; the server keeps
running. `buscar` skips files that are not valid UTF-8 when the locale is UTF-8 (grep treats them as binary).

## Security model

- **Project root only.** `buscar` and `leer` resolve paths against the manifest's `root` and reject anything outside it.
- **Secret files are invisible.** `buscar` and `leer` skip `.env`, `.env.*`, `*.pem`, `*.key`, `*.p12`, `id_rsa*`,
  `id_ed25519*`, `auth.json` and `credentials*` (templates ending in `.example` stay visible).
- **Fixed commands, no shell.** Scripts run as a fixed argument list from the manifest. Arguments that are absolute paths
  or contain `..` are rejected (unless the script sets `acepta_barra`, which allows URL-like `/a/b` but still not `..`).
  Flags listed in `rechaza` are rejected.
- **Read-only by default.** `correr` refuses any argument listed in a script's `escribe`. Those go through
  `correr_escritura`, which only exists when declared and only runs when the user sets `WEBSCOPE_ESCRITURA=1`.
- **Minimal environment.** Scripts do not inherit the server's environment. They receive only `PATH`, `HOME`, `LANG`,
  `LC_ALL`, `TMPDIR`, the variables named in the manifest's `env_permitidas`, plus `WEBSCOPE_RAIZ` (project root) and
  `WEBSCOPE_MANIFIESTO` (manifest path).
- **Bounded output.** Script output is trimmed to head and tail lines, and each response to `tope_tokens`.

The scripts themselves are trusted code: Webscope limits how they are called, not what they do. Only list scripts you
would run yourself.

## Configuration (`webscope.json`)

See [`webscope.example.json`](webscope.example.json).

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

| Key | Meaning |
| :--- | :--- |
| `root` | Project root, relative to the manifest's folder. |
| `recorte` | Default head (`cabeza`) and tail (`cola`) lines kept from script output. |
| `tope_tokens` | Maximum size of any response, in approximate tokens. |
| `buscar.dirs`, `buscar.extensiones` | Folders and file extensions searched by default. |
| `env_permitidas` | Extra environment variables passed to scripts. |
| `scripts.<name>.cmd` | Fixed command as a list; `python3` is replaced by the server's interpreter. |
| `descripcion`, `uso` | Shown by `correr()` listings. |
| `rechaza` | Flags that would write files; always refused. |
| `escribe` | Arguments that write data; only via `correr_escritura` with `WEBSCOPE_ESCRITURA=1`. |
| `acepta_barra` | Allow arguments starting with `/` (URL paths). |
| `timeout`, `cabeza`, `cola` | Per-script overrides. |

## Included scripts

The package ships ready-made scripts in `webscope_adaptadores/`. A manifest names them with `{adaptadores}` in `cmd`
(see [`webscope.example.json`](webscope.example.json)); copy the entries you need and adjust the folders.

| Script | What it answers | Stack |
| :--- | :--- | :--- |
| `vue_ts.py` (`mapa`) | Routes, views, API calls, composables and stores of a frontend module; `--recorrido` lists what can be clicked (actions with their `v-if` and permission, links, tabs with their API, form fields); `--cobertura` says which calls an e2e capture exercised | Vue 3 + TS |
| `laravel.py` (`mapa_back`) | Endpoint, controller, service, model and table behind a frontend module or API path | Laravel |
| `astro.py` (`mapa_web`) | File-based routes and endpoints with what they call; for one page, its components, data, client scripts, API calls and form fields with their visible (translated) label; `--cobertura <capture>` counts the page's `/api/` calls a capture exercised | Astro |
| `e2e_chrome.py` | JavaScript for **one** `javascript_tool` call of Claude in Chrome: walks routes and returns per route time, rows, failed requests, console errors and UI problems, without screenshots. `--llamar` reuses the walk already installed in the page; `--captura`/`--detalle` record what the page sends and receives; `--form` installs `__f` to fill a form by label, press Save and read it back, plus screen helpers that replace screenshots and coordinate clicks: `estado()` (the screen as short text), `clic(text)` (click by visible text, then wait until the page settles), `esperar`, `ir(route)` (router navigation without reload) and `pasos([...])` (several steps in one call). With a local receiver: `--servir [port folder]` starts it, `--cargar [port]` installs capture and `__f` from it, `--guardar <name> [port]` sends the whole capture to `<folder>/<name>.txt` (with one `ms <ms> <method> <status> <path>` line per API call; the receiver answers with the 5 slowest) and the steps `__f` recorded to `.claude/webscope/recorridos/<name>.json`, and `--repetir <name>` replays those steps in one call (with a fresh stamp on `ZZ_E2E` values) while the frontend does not change; `--exportar <capture> <url>` writes a Playwright test with the same steps | Any SPA with a router |
| `payload_check.py` | Checks a capture against the FormRequest rules, the Resource and the table columns; flags keys without a rule, values outside `in:`, `''` sent to a nullable column | Laravel |
| `limpiar_zz.py` | Lists, and with `--borrar` deletes after a backup, test rows whose code starts with `ZZ_` | Laravel |
| `costo_sesion.py` | Cost of the latest (or a given) Claude Code session in the project: USD per model at list prices (subagents and advisor included), calls and re-read context per tool, large outputs, repeated calls, and which tool loops would have been cheaper in a subagent | Claude Code |
| `uso_agentes.py` | Subagent usage: turns, context, models, agents over the turn limit | Claude Code |
| `uso_webscope.py` | Share of file reads