Provides tools for analyzing and managing Laravel projects, including mapping frontend modules to backend endpoints, validating payloads against FormRequest rules, and cleaning test data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@webscope busca 'getUser' en src y dame los archivos con más coincidencias"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Python 3.9 or newer (no third-party packages)
Optional: uv, to run it with uvx without cloning
grep on PATH (used by buscar)
Related MCP server: MCPort
In your project's root, create its manifest and list the folders and scripts it may use
(see Configuration and webscope.example.json).
Register the server. With Claude Code, from the project's root, pick one:
# 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.
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:
{
"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 build -t webscope .
docker run -i --rm -v "$PWD:/project:ro" -e WEBSCOPE_MANIFEST=/project/webscope.json webscopeWithout WEBSCOPE_MANIFEST the image serves the bundled webscope.example.json.
Tool | What it does |
| Case-insensitive search, literal unless |
| Returns only one function, method or class (PHP, TS, JS, Vue, Python) — or several, if |
| Runs a script declared in the manifest and returns |
| Only listed when a script declares |
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).
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.
webscope.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 |
| Project root, relative to the manifest's folder. |
| Default head ( |
| Maximum size of any response, in approximate tokens. |
| Folders and file extensions searched by default. |
| Extra environment variables passed to scripts. |
| Fixed command as a list; |
| Shown by |
| Flags that would write files; always refused. |
| Arguments that write data; only via |
| Allow arguments starting with |
| Per-script overrides. |
The package ships ready-made scripts in webscope_adaptadores/. A manifest names them with {adaptadores} in cmd
(see webscope.example.json); copy the entries you need and adjust the folders.
Script | What it answers | Stack |
| Routes, views, API calls, composables and stores of a frontend module; | Vue 3 + TS |
| Endpoint, controller, service, model and table behind a frontend module or API path | Laravel |
| 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; | Astro |
| JavaScript for one | Any SPA with a router |
| Checks a capture against the FormRequest rules, the Resource and the table columns; flags keys without a rule, values outside | Laravel |
| Lists, and with | Laravel |
| 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 |
| Subagent usage: turns, context, models, agents over the turn limit | Claude Code |
| Share of file reads and searches that went through | Claude Code |
Project-specific settings go in the manifest's proyecto section:
Key | Used by | Meaning |
|
| Backend modules folder (default |
|
| Prefix the app lives under, e.g. |
|
| Docker container where |
|
| Script that runs a read-only SQL query and prints TSV with a header |
|
| Script that runs a PHP file against the database ( |
|
| PHP expression for the connection (default |
| MCP resources | Captures folder (the one given to |
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).
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: sonnetAdd 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.
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.
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.mjsPW_CHANNEL=chrome uses the installed Chrome when Playwright's own browser is missing.
python3 -I test_webscope.pyWebscope 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.
Dónde se define o usa un texto: líneas agrupadas por archivo, primero los más citados (conciso: 5 archivos). Sin distinguir mayúsculas. Úsala en vez de grep. Para ver el código usa leer. Solo lectura, dentro de la raíz; omite secretos (.env, *.key...).
| Name | Required | Description | Default |
|---|---|---|---|
| tope | No | máximo de líneas | |
| donde | No | carpeta o archivo relativo a la raíz | |
| regex | No | texto es regex extendida | |
| texto | Yes | literal salvo regex=true | |
| formato | No | conciso = solo lo esencial | detallado |
| contexto | No | líneas alrededor |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false, and the description reinforces this with 'Solo lectura'. Beyond annotations it adds real behavioral context: case-insensitive matching, grouping/ordering by most-cited files, and secret exclusion (.env, *.key). It does not cover pagination or result-size limits, but the safety and scoping profile is well conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely dense and front-loaded: purpose first, then the grep comparison, the sibling routing, and the security constraint. Every clause earns its place with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter read-only search tool with no output schema, the description covers behavior, scoping, security exclusions, and alternatives. Minor gaps remain around result limits or pagination, but nothing critical to correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters (baseline 3). The description adds meaning beyond the schema by clarifying that 'conciso' returns 5 files and that matching is case-insensitive, which enriches the formato and texto parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: it finds where a text is defined or used and returns lines grouped by file. It separates itself from siblings by directing the agent to 'leer' for viewing code. An agent can distinguish it from 'leer' and 'correr' without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Úsala en vez de grep' (use instead of grep) and names the alternative 'Para ver el código usa leer'. Both the when-to-use condition and the routing to a sibling tool are stated directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Corre un script de solo lectura del manifiesto: código de salida y salida recortada. Sin nombre los enumera. Úsala en vez de Bash para lo que cubre un script. Sin shell; rechaza rutas absolutas, .. y lo que escribe (va por correr_escritura).
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | un argumento por elemento; rutas relativas, sin .. | |
| nombre | No | script o «lista» | lista |
| detalle | No | esquema = ficha sin correrlo | nombre |
| Name | Required | Description |
|---|---|---|
| exit | No | |
| nota | No | |
| salida | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnlyHint/openWorldHint; the description adds substantial behavior: no shell is spawned, absolute paths and `..` are rejected, and anything that writes is refused. It also discloses the response shape (exit code + trimmed/truncated output), which matters for a code-execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, each carrying a distinct payload (what it returns, default discovery behavior, when to use it, and the safety envelope). The routing constraint is front-loaded immediately after the purpose, with zero filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value documentation is optional, yet the description still summarizes it. Combined with the sandbox restrictions, write-redirect, and default behavior, an agent has everything needed to invoke this safely without opening the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics beyond the schema: omitting `nombre` enumerates the available scripts, and it reinforces the path constraints (`..`, relative only) that the `args` schema only partially states. The `detalle` enum behavior is left to the schema, so it is not a full 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a concrete verb+resource: it runs read-only manifest scripts and returns exit code plus trimmed output. It also distinguishes itself from adjacent tooling by naming Bash and `correr_escritura`, so the agent knows exactly which capability this is and which it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit routing: 'Úsala en vez de Bash para lo que cubre un script' tells when to prefer this over the general-purpose alternative, and the mention that writes go through `correr_escritura` gives the negative case. The 'sin `nombre` los enumera' clause further tells the agent how to invoke it when it just wants discovery.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Solo un trozo de un archivo: la función o clase simbolo (PHP, TS, JS, Vue, Python; lista = varias en una llamada), la sección de un .md, un rango lineas, o de un log las últimas cola o las que tienen contiene; sin nada, el índice del archivo. Úsala en vez de Read, cat o sed. Solo lectura, dentro de la raíz; no lee secretos.
| Name | Required | Description | Default |
|---|---|---|---|
| cola | No | logs: últimas N líneas | |
| lineas | No | rango «120-180» | |
| archivo | Yes | ruta relativa a la raíz | |
| formato | No | conciso = solo lo esencial | detallado |
| simbolo | No | función, clase o título; lista = varios | |
| contiene | No | logs: líneas con este texto | |
| max_lineas | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and closed-world scope, but the description adds two meaningful constraints beyond them: reads are confined to the project root, and secrets are not read. The default behavior when no selector is supplied (returns the index) is also disclosed. It stops short of describing output shape or truncation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The main sentence is long but front-loads the selector modes and every clause carries information; the two trailing sentences (use instead of X; read-only, root-scoped, no secrets) are tight. Slightly run-on, but no wasted prose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description carries the burden of explaining behavior, and it covers all selector modes, the default case, and safety constraints for a 7-parameter tool. The gaps are minor: return format, truncation via `max_lineas`, and the `formato` enum's effect are unmentioned.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is already 86%, so the baseline is 3, but the description adds real value: `simbolo` works across PHP/TS/JS/Vue/Python and accepts a list to fetch several symbols in one call, and it clarifies the conditional nature of `cola`/`contiene` (logs only) and `lineas` (a range). `formato` and `max_lineas` are not explained in the description, keeping it from a 5.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (read a portion) and enumerates every selection mode: `simbolo` for functions/classes across five languages, `.md` sections, `lineas` ranges, log `cola`/`contiene`, and the no-argument index fallback. An agent immediately understands this is a targeted file-slice reader, not a whole-file read.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly routes the agent away from Read, cat, and sed, and the no-argument case is spelled out as returning the file index. It does not, however, clarify how it relates to the actual siblings `buscar` (search) and `correr` (run), so sibling disambiguation is left implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0buscarcorrerleerScored across 3 tools
Cada herramienta tiene un rol claramente distinto: buscar localiza texto, leer extrae fragmentos de archivo y correr ejecuta scripts de solo lectura. La descripción de buscar redirige explícitamente a leer para ver código, eliminando cualquier solapamiento práctico.
Los tres nombres son verbos en infinitivo en español (buscar, correr, leer), con una convención uniforme y predecible en todo el conjunto.
Tres herramientas cubren las operaciones esenciales de exploración de código de solo lectura (buscar, leer, ejecutar scripts) sin redundancia; el conjunto está bien acotado para su propósito.
El conjunto cubre búsqueda textual, lectura por fragmentos y ejecución de scripts de solo lectura, pero no ofrece una operación directa para listar archivos/directorios ni búsqueda por nombre o regex. Además, se menciona correr_escritura sin incluirla, aunque el diseño parece intencionalmente read-only; son lagunas menores que un agente podría sortear vía scripts del manifiesto o búsqueda textual.
Project memory, semantic code search, and grounded agent context.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Securely search and manage workspace context files for AI agents and teams.
Scoped agent execution. Server-side credentials, policy, budgets and verifiable receipts.