webscope-mcp 0.2.0__tar.gz

webscope_mcp-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 partprogramming09
+
+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.

webscope_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,249 @@
+Metadata-Version: 2.4
+Name: webscope-mcp
+Version: 0.2.0
+Summary: MCP server (stdio, standard library only) that gives a coding agent short answers about a project
+License: 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 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 |
+| `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 and searches that went through `leer` and `buscar` in sessions where Webscope was available, and the `Read`/`sed`/`grep` calls used instead | Claude Code |
+
+Project-specific settings go in the manifest's `proyecto` section:
+
+| Key | Used by | Meaning |
+| :--- | :--- | :--- |
+| `modulos` | `payload_check` | Backend modules folder (default `app/Modules`) |
+| `prefijo_rutas` | `e2e_chrome` | Prefix the app lives under, e.g. `/demo`, so routes work with or without it |
+| `contenedor` | `mapa_back` | Docker container where `php artisan route:list --json` runs; empty reads the route files |
+| `sql` | `payload_check`, `limpiar_zz` | Script that runs a read-only SQL query and prints TSV with a header |
+| `tinker` | `limpiar_zz` | Script that runs a PHP file against the database (`<script> <file.php> --commit`) |
+| `php_db` | `limpiar_zz` | PHP expression for the connection (default `DB::connection()`) |
+| `capturas` | MCP resources | Captures folder (the one given to `--servir`); its `.txt` files are listed as `webscope://capturas/<file>` next to the saved walks `webscope://recorridos/<file>` |
+
+The Vue index cache and `limpiar_zz` backups go to `~/.cache/webscope/`. The `e2e_chrome` receiver writes captures to the
+folder given to `--servir` (default `capturas`, relative to where it starts). `--servir` does not return: start it from a
+shell in the background (the example manifest lists it in `rechaza`, so `correr` refuses it).
+
+### Using the scripts from a subagent
+
+A subagent sees Webscope only if its definition lists the tools, for example in Claude Code's `.claude/agents/<name>.md`:
+
+```yaml
+tools: Read, Grep, Glob, Bash, mcp__webscope__buscar, mcp__webscope__leer, mcp__webscope__correr
+model: sonnet
+```
+
+Add `mcp__webscope__correr_escritura` only if the agent must run write arguments, plus the browser tools it needs.
+[`agents/recorrido.example.md`](agents/recorrido.example.md) is a ready-made agent that walks one frontend module in
+Chrome with `mapa`, `e2e_chrome` and `limpiar_zz` and returns a summary of at most 25 lines: copy it to
+`.claude/agents/recorrido.md` and replace `<webscope>` (the clone's folder; the receiver runs from the clone, not from
+`uvx`) and the captures folder.
+
+One measurement (a browser walk of one module, one project, one run per condition) found:
+
+- With the walk in the main session, Webscope did not change the cost (+7 % and −5 % in two runs). It changed accuracy:
+  the order of steps (`mapa --recorrido`), the fields that were not saved (`__f.verificar`) and the measured coverage.
+- The same walk in a sonnet subagent that returns a summary of at most 25 lines cost 1.05 USD instead of 6.40, with the
+  same coverage. About 2× came from isolating the context; the rest from the sonnet price.
+- Page reads and screenshots were about 80 % of the re-read context, so the agent reads state with `javascript_tool` and
+  takes screenshots only to understand an error.
+- Subagents that ran for more than about 40 turns grew their context like a main session. Give one module or one bounded
+  task per agent, and tell it to stop at about 40 tool calls and return what is done and what is pending.
+
+`costo_sesion.py --raiz <project>` and `uso_agentes.py --raiz <project>` measure the same in another project. The USD
+come from the price table at the top of `costo_sesion.py` (list prices, October 2026), which only lists models checked
+against the cost reported by `claude -p` (Opus 5.5, Sonnet 5.5, Fable 5.1: within 0.01 USD on three runs); any other
+model is shown as `sin precio` until it is added.
+
+## Hook: suggest Webscope
+
+Agents often keep using `Read`, `cat`, `sed -n` and `grep` even when Webscope is available. `hooks/sugerir_webscope.py`
+is a Claude Code `PostToolUse` hook that, after such a call, adds one line to the model's context with the equivalent
+Webscope call (for example `leer(archivo, lineas="120-180")`). It never blocks and speaks at most 3 times per session.
+Add it to the project's `.claude/settings.json` or `.claude/settings.local.json`:
+
+```json
+{"hooks": {"PostToolUse": [{"matcher": "Read|Bash", "hooks": [{"type": "command",
+  "command": "python3 -I /path/to/webscope/hooks/sugerir_webscope.py"}]}]}}
+```
+
+`uso_webscope.py` measures whether it works: the share of reads and searches that go through Webscope.
+
+## Browser UI check
+
+`webscope_adaptadores/web/chequeo-ui.js` is a standalone snippet for a browser automation tool (`page.evaluate` in Playwright, or a
+JavaScript tool in a browser extension). It returns only the problems on the current page: horizontal overflow, empty
+chips or badges, untranslated i18n keys, raw values (`undefined`, `NaN`…), overlapping text and unnamed buttons.
+
+```sh
+PLAYWRIGHT_DIR=<folder containing node_modules/playwright> node webscope_adaptadores/web/test_chequeo_ui.mjs
+PLAYWRIGHT_DIR=<folder containing node_modules/playwright> PW_CHANNEL=chrome node webscope_adaptadores/web/test_form.mjs
+```
+
+`PW_CHANNEL=chrome` uses the installed Chrome when Playwright's own browser is missing.
+
+## Tests
+
+```sh
+python3 -I test_webscope.py
+```
+
+## Out of scope
+
+Webscope does not replace a language server or a browser automation server, does not run code written by the agent, and
+is not a test framework.
+
+## License
+
+[MIT](LICENSE)

webscope_mcp-0.2.0/README.md

@@ -0,0 +1,238 @@
+# 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 |
+| `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 and searches that went through `leer` and `buscar` in sessions where Webscope was available, and the `Read`/`sed`/`grep` calls used instead | Claude Code |
+
+Project-specific settings go in the manifest's `proyecto` section:
+
+| Key | Used by | Meaning |
+| :--- | :--- | :--- |
+| `modulos` | `payload_check` | Backend modules folder (default `app/Modules`) |
+| `prefijo_rutas` | `e2e_chrome` | Prefix the app lives under, e.g. `/demo`, so routes work with or without it |
+| `contenedor` | `mapa_back` | Docker container where `php artisan route:list --json` runs; empty reads the route files |
+| `sql` | `payload_check`, `limpiar_zz` | Script that runs a read-only SQL query and prints TSV with a header |
+| `tinker` | `limpiar_zz` | Script that runs a PHP file against the database (`<script> <file.php> --commit`) |
+| `php_db` | `limpiar_zz` | PHP expression for the connection (default `DB::connection()`) |
+| `capturas` | MCP resources | Captures folder (the one given to `--servir`); its `.txt` files are listed as `webscope://capturas/<file>` next to the saved walks `webscope://recorridos/<file>` |
+
+The Vue index cache and `limpiar_zz` backups go to `~/.cache/webscope/`. The `e2e_chrome` receiver writes captures to the
+folder given to `--servir` (default `capturas`, relative to where it starts). `--servir` does not return: start it from a
+shell in the background (the example manifest lists it in `rechaza`, so `correr` refuses it).
+
+### Using the scripts from a subagent
+
+A subagent sees Webscope only if its definition lists the tools, for example in Claude Code's `.claude/agents/<name>.md`:
+
+```yaml
+tools: Read, Grep, Glob, Bash, mcp__webscope__buscar, mcp__webscope__leer, mcp__webscope__correr
+model: sonnet
+```
+
+Add `mcp__webscope__correr_escritura` only if the agent must run write arguments, plus the browser tools it needs.
+[`agents/recorrido.example.md`](agents/recorrido.example.md) is a ready-made agent that walks one frontend module in
+Chrome with `mapa`, `e2e_chrome` and `limpiar_zz` and returns a summary of at most 25 lines: copy it to
+`.claude/agents/recorrido.md` and replace `<webscope>` (the clone's folder; the receiver runs from the clone, not from
+`uvx`) and the captures folder.
+
+One measurement (a browser walk of one module, one project, one run per condition) found:
+
+- With the walk in the main session, Webscope did not change the cost (+7 % and −5 % in two runs). It changed accuracy:
+  the order of steps (`mapa --recorrido`), the fields that were not saved (`__f.verificar`) and the measured coverage.
+- The same walk in a sonnet subagent that returns a summary of at most 25 lines cost 1.05 USD instead of 6.40, with the
+  same coverage. About 2× came from isolating the context; the rest from the sonnet price.
+- Page reads and screenshots were about 80 % of the re-read context, so the agent reads state with `javascript_tool` and
+  takes screenshots only to understand an error.
+- Subagents that ran for more than about 40 turns grew their context like a main session. Give one module or one bounded
+  task per agent, and tell it to stop at about 40 tool calls and return what is done and what is pending.
+
+`costo_sesion.py --raiz <project>` and `uso_agentes.py --raiz <project>` measure the same in another project. The USD
+come from the price table at the top of `costo_sesion.py` (list prices, October 2026), which only lists models checked
+against the cost reported by `claude -p` (Opus 5.5, Sonnet 5.5, Fable 5.1: within 0.01 USD on three runs); any other
+model is shown as `sin precio` until it is added.
+
+## Hook: suggest Webscope
+
+Agents often keep using `Read`, `cat`, `sed -n` and `grep` even when Webscope is available. `hooks/sugerir_webscope.py`
+is a Claude Code `PostToolUse` hook that, after such a call, adds one line to the model's context with the equivalent
+Webscope call (for example `leer(archivo, lineas="120-180")`). It never blocks and speaks at most 3 times per session.
+Add it to the project's `.claude/settings.json` or `.claude/settings.local.json`:
+
+```json
+{"hooks": {"PostToolUse": [{"matcher": "Read|Bash", "hooks": [{"type": "command",
+  "command": "python3 -I /path/to/webscope/hooks/sugerir_webscope.py"}]}]}}
+```
+
+`uso_webscope.py` measures whether it works: the share of reads and searches that go through Webscope.
+
+## Browser UI check
+
+`webscope_adaptadores/web/chequeo-ui.js` is a standalone snippet for a browser automation tool (`page.evaluate` in Playwright, or a
+JavaScript tool in a browser extension). It returns only the problems on the current page: horizontal overflow, empty
+chips or badges, untranslated i18n keys, raw values (`undefined`, `NaN`…), overlapping text and unnamed buttons.
+
+```sh
+PLAYWRIGHT_DIR=<folder containing node_modules/playwright> node webscope_adaptadores/web/test_chequeo_ui.mjs
+PLAYWRIGHT_DIR=<folder containing node_modules/playwright> PW_CHANNEL=chrome node webscope_adaptadores/web/test_form.mjs
+```
+
+`PW_CHANNEL=chrome` uses the installed Chrome when Playwright's own browser is missing.
+
+## Tests
+
+```sh
+python3 -I test_webscope.py
+```
+
+## Out of scope
+
+Webscope does not replace a language server or a browser automation server, does not run code written by the agent, and
+is not a test framework.
+
+## License
+
+[MIT](LICENSE)

webscope_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "webscope-mcp"
+version = "0.2.0"
+description = "MCP server (stdio, standard library only) that gives a coding agent short answers about a project"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.9"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/partprogramming09/webscope"
+
+[project.scripts]
+webscope-mcp = "webscope:main"
+
+[tool.setuptools]
+py-modules = ["webscope"]
+packages = ["webscope_adaptadores"]
+
+[tool.setuptools.package-data]
+webscope_adaptadores = ["web/*.js"]

webscope_mcp-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+