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, to run it with uvx without cloning
• grep on PATH (used by buscar)

Installation

1. In your project's root, generate or create its manifest. You can autodetect the stack (Laravel, Vue/React/Frontend, Python or generic) and generate webscope.json in 1 second:

   # With webscope-mcp installed or via uvx
   webscope-mcp --init
   
   # Or using standard Python
   python3 webscope.py --init
   

   --init automatically inspects composer.json, package.json, pyproject.toml and directory structure to configure adapters and search paths (see Configuration and webscope.example.json). All adapters (db_check.php, agents, web/*.js) come packaged as internal package assets.

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

   # Claude Code con uvx (sin clonar, versión v0.2.3)
   claude mcp add --scope project webscope -- uvx --from git+https://github.com/partprogramming09/webscope@v0.2.3 webscope-mcp --manifest "$PWD/webscope.json"
   
   # Con pip
   pip install git+https://github.com/partprogramming09/webscope.git@v0.2.3
   claude mcp add --scope project webscope -- webscope-mcp --manifest "$PWD/webscope.json"
   
   # Con un clon local y Python estándar
   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.

Configuration in other MCP clients

You can configure Webscope in other MCP clients using uvx or standard Python:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "webscope": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/partprogramming09/webscope@v0.2.3",
        "webscope-mcp",
        "--manifest",
        "/absolute/path/to/your/project/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.2.3",
        "webscope-mcp",
        "--manifest",
        "${workspaceFolder}/webscope.json"
      ]
    }
  }
}

Zed (settings.json)

{
  "context_servers": {
    "webscope": {
      "command": {
        "path": "uvx",
        "args": [
          "--from",
          "git+https://github.com/partprogramming09/webscope@v0.2.3",
          "webscope-mcp",
          "--manifest",
          "/absolute/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.

Updating

If you previously installed or ran an earlier version of Webscope:

• uvx: uv caches git repositories and tools. Clear the cache or pass --refresh:

  # Clean cached tool package
  uv cache clean webscope-mcp
  
  # Or run uvx with --refresh
  claude mcp add --scope project webscope -- uvx --refresh --from git+https://github.com/partprogramming09/webscope@v0.2.3 webscope-mcp --manifest "$PWD/webscope.json"
  

• pip:

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

• Git clone:

  cd ~/webscope && git pull origin main
  

Docker

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

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.

{
  "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
    }
  }
}

Included scripts

The package ships ready-made scripts in webscope_adaptadores/. All adapters (db_check.php, agents, web/*.js) come packaged as internal package assets. A manifest names them with {adaptadores} in cmd (see webscope.example.json); copy the entries you need and adjust the folders.

Two prompts ship with the server: sesion (the browser session starts with estado_sesion, the test menu and the budget rules; shows the menu table as a question only when the user does not name a test type) and recorrido (one-module walk).

Project-specific settings go in the manifest's proyecto section:

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), and at each save merges the module index into .claude/webscope/mapa-modulos.json (module → routes → captures and walks that cover it), so start it with the project environment like the other scripts: WEBSCOPE_RAIZ (only needed if you want the project root) and WEBSCOPE_MANIFIESTO (path of webscope.json), which --cargar/--guardar need for the route prefix. --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:

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 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:

{"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.

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

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