webscope-mcp 0.2.0__py3-none-any.whl

webscope.py

@@ -0,0 +1,695 @@
+#!/usr/bin/env python3
+"""Webscope: servidor MCP (stdio, JSON-RPC 2.0, solo biblioteca estándar) que expone los scripts de un proyecto con salidas cortas.
+
+Uso: python3 -I webscope.py --manifest <ruta/webscope.json>   (o WEBSCOPE_MANIFEST=<ruta/webscope.json>)
+Herramientas: buscar (archivo:línea con tope), leer (solo el símbolo de un archivo) y correr (scripts de solo lectura del
+manifiesto, descubiertos por niveles). Cada salida se recorta a cabeza y cola; lo que escribe archivos no se expone.
+También expone el prompt `recorrido`, los recorridos guardados y las capturas como recursos, y avisa del progreso de
+los scripts largos cuando el cliente manda `progressToken`.
+Los scripts reciben solo PATH, HOME, LANG, LC_ALL, TMPDIR y las variables que el manifiesto declara en `env_permitidas`.
+"""
+import fnmatch
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+INSTRUCCIONES = ("Antes de Bash, grep o Read en este proyecto usa estas herramientas: devuelven menos. "
+                 "Dónde se usa X: buscar (formato=conciso si solo quieres los archivos). "
+                 "Una función, clase, sección de un .md (por su título) o un log (contiene, cola): leer; no leas el archivo entero. "
+                 "Para lo que cubre un script del proyecto: correr(nombre, args) con uno de la lista de abajo, sin pedir «lista».")
+ENV_BASE = ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR")
+ADAPTADORES = Path(__file__).resolve().parent / "webscope_adaptadores"
+AVISO = 5  # segundos entre avisos de progreso de un script largo
+
+
+def cargar(ruta=None):
+    """Lee el manifiesto en `ruta` y devuelve su configuración con la raíz resuelta; sin `ruta`, raíz = carpeta actual y sin scripts."""
+    if ruta is None:
+        cfg = {"root": Path.cwd().resolve(), "manifiesto": ""}
+    else:
+        ruta = Path(ruta).resolve()
+        cfg = json.loads(ruta.read_text())
+        cfg["root"] = (ruta.parent / cfg.get("root", ".")).resolve()
+        cfg["manifiesto"] = str(ruta)
+    cfg.setdefault("recorte", {"cabeza": 12, "cola": 48})
+    cfg.setdefault("scripts", {})
+    cfg.setdefault("buscar", {})
+    cfg.setdefault("tope_tokens", 5000)
+    return cfg
+
+
+def run(cfg, argv, timeout=300, cabeza=None, cola=None):
+    """Corre `argv` desde la raíz del proyecto y devuelve `exit N` y la salida recortada a `cabeza` + `cola` líneas."""
+    cabeza = cfg["recorte"]["cabeza"] if cabeza is None else cabeza
+    cola = cfg["recorte"]["cola"] if cola is None else cola
+    permitidas = (*ENV_BASE, *cfg.get("env_permitidas", []))
+    env = {k: os.environ[k] for k in permitidas if k in os.environ}
+    proc = subprocess.Popen([str(a) for a in argv], cwd=cfg["root"], stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True,
+                            errors="replace", stdin=subprocess.DEVNULL,
+                            env={**env, "WEBSCOPE_RAIZ": str(cfg["root"]), "WEBSCOPE_MANIFIESTO": cfg.get("manifiesto", "")})
+    pasado = 0
+    while True:
+        try:
+            stdout, stderr = proc.communicate(timeout=min(AVISO, timeout - pasado))
+            break
+        except subprocess.TimeoutExpired:
+            pasado += AVISO
+            if pasado >= timeout:
+                proc.kill()
+                proc.communicate()
+                raise
+            if cfg.get("_avisar"):
+                cfg["_avisar"](pasado, f"sigue corriendo: {pasado} s")
+    lines = (stdout + stderr).strip().splitlines()
+    if len(lines) > cabeza + cola:
+        lines = lines[:cabeza] + [f"… {len(lines) - cabeza - cola} líneas omitidas …"] + lines[-cola:]
+    return "\n".join([f"exit {proc.returncode}"] + lines)
+
+
+SECRETOS = (".env", ".env.*", "*.pem", "*.key", "*.p12", "id_rsa*", "id_ed25519*", "auth.json", "credentials*")
+
+
+def secreto(nombre):
+    """True si el nombre de archivo suele guardar claves (`.env`, llaves, credenciales), salvo las plantillas `.example`."""
+    return not nombre.endswith(".example") and any(fnmatch.fnmatch(nombre, p) for p in SECRETOS)
+
+
+def dentro(cfg, ruta):
+    """Devuelve la ruta resuelta si cuelga de la raíz del proyecto y no es un archivo de claves; si no, None."""
+    resuelta = (cfg["root"] / ruta).resolve()
+    if secreto(resuelta.name):
+        return None
+    return resuelta if resuelta == cfg["root"] or cfg["root"] in resuelta.parents else None
+
+
+def formato_valido(formato):
+    """Devuelve True si `formato` es «conciso»; False si es «detallado»; si no, falla."""
+    if formato not in ("conciso", "detallado"):
+        raise ValueError("formato debe ser «conciso» o «detallado»")
+    return formato == "conciso"
+
+
+def _con_contexto(cfg, archivo, hits, contexto, todas):
+    """Filas de `hits` [(n, texto)] de `archivo` con `contexto` líneas alrededor: `n:` las coincidencias de `todas`, `n-` el resto."""
+    lineas = (cfg["root"] / archivo).read_text(errors="ignore").splitlines()
+    marcadas, filas, ultima = {int(n) for n, _ in todas}, [], 0
+    for n in sorted(int(n) for n, _ in hits):
+        desde, hasta = max(n - contexto, ultima + 1), min(n + contexto, len(lineas))
+        if filas and desde > ultima + 1:
+            filas.append("  --")
+        filas += [f"  {k}{':' if k in marcadas else '-'} {lineas[k - 1].strip()[:80]}".rstrip() for k in range(desde, hasta + 1)]
+        ultima = max(ultima, hasta)
+    return filas
+
+
+def tool_buscar(cfg, texto, donde="", tope=15, formato="detallado", contexto=0, regex=False):
+    """Líneas con `texto` agrupadas por archivo, primero los más referenciados, hasta `tope` líneas; `donde` = carpeta o archivo relativo a la raíz.
+
+    `formato` conciso = solo los 5 archivos con más coincidencias; `contexto` = líneas alrededor de cada una; `regex` = `texto` es una expresión regular extendida.
+    """
+    conciso = formato_valido(formato)
+    if not isinstance(contexto, int) or not 0 <= contexto <= 5:
+        raise ValueError("contexto debe ser un entero de 0 a 5")
+    if not isinstance(regex, bool):
+        raise ValueError("regex debe ser true o false")
+    base = dentro(cfg, donde) if donde else None
+    if donde and (base is None or not base.exists()):
+        raise ValueError(f"{donde} no es una carpeta ni un archivo del proyecto")
+    dirs = [base] if base else [cfg["root"] / d for d in cfg["buscar"].get("dirs", ["."])]
+    exts = [] if base else [f"*.{e}" for e in cfg["buscar"].get("extensiones", [])]
+    proc = subprocess.run(["grep", "-rnIiEH" if regex else "-rnIiFH", "--exclude-dir=node_modules", "--exclude-dir=vendor", "--exclude-dir=.git",
+                           *[f"--exclude={p}" for p in SECRETOS], *[f"--include={e}" for e in exts], "-e", texto, *map(str, dirs)],
+                          capture_output=True, text=True, errors="replace", stdin=subprocess.DEVNULL)
+    if proc.returncode > 1:
+        raise ValueError(f"grep: {proc.stderr.strip().splitlines()[-1] if proc.stderr.strip() else 'error'}")
+    grupos = {}
+    for fila in proc.stdout.splitlines():
+        if fila.count(":") >= 2:
+            f, n, t = fila.split(":", 2)
+            grupos.setdefault(str(Path(f).relative_to(cfg["root"])), []).append((n, t.strip()[:80]))
+    total, salida, mostradas, k = sum(map(len, grupos.values())), [], 0, 0
+    ranking = sorted(grupos.items(), key=lambda g: (-len(g[1]), g[0]))
+    if conciso:
+        resumen = [f"{a}:{h[0][0]} ({len(h)})" for a, h in ranking[:5]]
+        resto = len(ranking) - 5
+        return "\n".join([f"{total} coincidencias en {len(grupos)} archivos"] + resumen + ([f"… otros {resto} archivos"] if resto > 0 else []))
+    while k < len(ranking) and mostradas < tope:
+        archivo, hits = ranking[k]
+        hits = hits[:tope - mostradas]
+        mostradas += len(hits)
+        k += 1
+        if contexto:
+            salida += [f"{archivo} ({len(ranking[k - 1][1])})"] + _con_contexto(cfg, archivo, hits, contexto, ranking[k - 1][1])
+        elif len(ranking[k - 1][1]) == 1:
+            salida.append(f"{archivo}:{hits[0][0]}  {hits[0][1]}")
+        else:
+            salida += [f"{archivo} ({len(ranking[k - 1][1])})"] + [f"  {n}  {t}" for n, t in hits]
+    if k < len(ranking):
+        salida.append(f"… otros {len(ranking) - k} archivos: " + ", ".join(f"{a} ({len(h)})" for a, h in ranking[k:k + 8])
+                      + (", …" if len(ranking) - k > 8 else ""))
+    return "\n".join([f"{total} coincidencias en {len(grupos)} archivos" + (f", primeras {mostradas}" if total > mostradas else "")] + salida)
+
+
+LOGS = {".log", ".txt", ".out"}
+DEFINE = r"(\b(function|def|class|interface|enum|trait|type)\s+{0}\b|\b(const|let|var)\s+{0}\s*[=:])"
+METODO = r"^\s*(async\s+)?{0}\s*[(<]"
+ASIGNACION = re.compile(r"\s*(export\s+)?(declare\s+)?(const|let|var|type)\b")
+CONTINUA = (".", "?", ":", "&&", "||", "+", "-", "*", "/", "|", "&", "=")
+
+
+def _seccion(lineas, titulo):
+    """Rango (inicio, fin exclusivo) de la sección markdown cuyo encabezado es `titulo` (igual, empieza por o contiene), con sus subsecciones."""
+    cerca, encabezados = "", []
+    for n, linea in enumerate(lineas):
+        marca = re.match(r"\s*(`{3,}|~{3,})", linea)
+        if marca:
+            if not cerca:
+                cerca = marca[1]
+            elif marca[1][0] == cerca[0] and len(marca[1]) >= len(cerca) and linea.strip() == marca[1]:
+                cerca = ""
+        elif not cerca and (m := re.match(r"(#{1,6})\s+(.*?)(?:\s*\{#[^}]*\})?\s*$", linea)):
+            encabezados.append((n, len(m[1]), m[2].lower()))
+    q = titulo.lower().strip()
+    for coincide in (lambda t: t == q, lambda t: t.startswith(q), lambda t: q in t):
+        for k, (n, nivel, t) in enumerate(encabezados):
+            if coincide(t):
+                return n, next((m for m, nv, _ in encabezados[k + 1:] if nv <= nivel), len(lineas))
+    raise LookupError(f"no hay una sección «{titulo}»")
+
+
+def _de_log(lineas, rel, cola, contiene, max_lineas):
+    """Líneas de un log numeradas y a 200 caracteres: las que contienen `contiene` y/o las últimas `cola` (40 si no hay filtro)."""
+    filas = [(n + 1, l) for n, l in enumerate(lineas) if contiene.lower() in l.lower()]
+    total, tope = len(filas), min(cola or (max_lineas if contiene else 40), max_lineas)
+    filas = filas[-tope:]
+    if contiene:
+        cabeza = f"{rel}: {total} líneas con «{contiene}» de {len(lineas)}" + (f", últimas {len(filas)}" if total > len(filas) else "")
+    else:
+        cabeza = f"{rel}:{filas[0][0] if filas else 0}-{filas[-1][0] if filas else 0} de {len(lineas)}"
+    return "\n".join([cabeza] + [f"{n}: {l[:200]}" for n, l in filas])
+
+
+def _salta_cadena(texto, n, comilla):
+    """Desde `n` (tras la comilla de apertura) devuelve (índice tras el cierre, False) o (índice tras `${`, True) en una plantilla."""
+    while n < len(texto) and texto[n] != comilla:
+        if texto[n] == "\\":
+            n += 1
+        elif comilla == "`" and texto[n:n + 2] == "${":
+            return n + 2, True
+        n += 1
+    return n + 1, False
+
+
+def _fin_llaves(lineas, i, php):
+    """Índice (exclusivo) de la línea donde acaba la declaración de `lineas[i]`: cuenta (), [] y {} fuera de cadenas, comentarios y regex.
+
+    shortcut: sin heredoc con etiqueta entre comillas ni regex tras `)`; mejorar con un tokenizador real si un símbolo sale cortado.
+    """
+    texto = "\n".join(lineas[i:])
+    asignacion = bool(ASIGNACION.match(lineas[i]))
+    n, nivel, linea, previo, plantillas, abierto = 0, 0, i, "", [], False
+
+    def avanza(nuevo):
+        nonlocal linea
+        linea += texto.count("\n", n, nuevo)
+        return nuevo
+
+    while n < len(texto):
+        c, par = texto[n], texto[n:n + 2]
+        if c == "\n":
+            sigue = next((l.strip() for l in lineas[linea + 1:] if l.strip()), "")
+            if asignacion and nivel == 0 and previo and previo[-1] not in "=,(" and previo[-1] not in "+-*/&|?:" \
+                    and previo != "=>" and not sigue.startswith(CONTINUA):
+                return linea + 1
+            linea += 1
+        elif par == "//" or (php and c == "#" and par != "#["):
+            n = (texto.find("\n", n) if "\n" in texto[n:] else len(texto)) - 1
+        elif par == "/*":
+            n = avanza(texto.find("*/", n + 2) + 2 if "*/" in texto[n:] else len(texto)) - 1
+        elif php and par == "<<" and (m := re.match(r"<<<\s*['\"]?(\w+)['\"]?\s*\n", texto[n:])):
+            cierre = re.search(rf"\n\s*{m[1]}\b", texto[n + m.end() - 1:])
+            n = avanza(n + m.end() - 1 + (cierre.end() if cierre else len(texto))) - 1
+            previo = "'"
+        elif c in "'\"" or (c == "`" and not php):
+            nuevo, plantilla = _salta_cadena(texto, n + 1, c)
+            n = avanza(nuevo) - 1
+            if plantilla:
+                plantillas.append(nivel)
+                nivel += 1
+            previo = "'"
+        elif c == "/" and not php and previo[-1:] in ("", *"(,=:[!&|?{};") and par not in ("//", "/*"):
+            n += 1
+            clase = False
+            while n < len(texto) and (texto[n] != "/" or clase) and texto[n] != "\n":
+                clase = clase if texto[n] != "[" and texto[n] != "]" else texto[n] == "["
+                n += 2 if texto[n] == "\\" else 1
+            previo = "'"
+        elif c in "{([":
+            nivel, abierto, previo = nivel + 1, abierto or c == "{", c
+        elif c in ")]":
+            nivel, previo = nivel - 1, c
+        elif c == "}":
+            nivel, previo = nivel - 1, c
+            if plantillas and plantillas[-1] == nivel:
+                plantillas.pop()
+                nuevo, plantilla = _salta_cadena(texto, n + 1, "`")
+                n = avanza(nuevo) - 1
+                if plantilla:
+                    plantillas.append(nivel)
+                    nivel += 1
+            elif not asignacion and abierto and nivel == 0 and not texto[n + 1:].split("\n", 1)[0].lstrip().startswith("{"):
+                return linea + 1
+        elif c == ";" and nivel == 0:
+            return linea + 1
+        elif not c.isspace():
+            previo = (previo + c)[-2:]
+        n += 1
+    return len(lineas)
+
+
+def _inicio(lineas, simbolo):
+    """Índice de la línea que define `simbolo`: primero una declaración (function, class, const…), si no un método sin palabra clave."""
+    nombre = re.escape(simbolo)
+    for patron in (DEFINE.format(nombre), METODO.format(nombre)):
+        for i, linea in enumerate(lineas):
+            if not linea.lstrip().startswith(("//", "*", "/*", "#")) and re.search(patron, linea):
+                return i
+    raise LookupError(f"no hay {simbolo}")
+
+
+INDICE = re.compile(r"^\s*(?:export\s+(?:default\s+)?)?(?:(?:public|private|protected|static|abstract|final|readonly|async)\s+)*"
+                    r"(?:function\*?|def|class|interface|enum|trait|type)\s+([A-Za-z_$][\w$]*)"
+                    r"|^\s*(?:export\s+)?(?:const|let)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\(|function\b|[A-Za-z_$][\w$]*\s*=>)")
+
+
+VUE = re.compile(r"<(template|script|style)\b|(export\s+)?(const|let|function|async\s+function)\s")
+
+
+def _indice(lineas, rel, ruta, max_lineas):
+    """Índice de un archivo: títulos de un .md, bloques y declaraciones de primer nivel de un .vue o definiciones de código, con su línea.
+
+    Sin ninguno devuelve las primeras 30 líneas numeradas.
+    """
+    if ruta.suffix == ".md":
+        filas = [f"{n + 1}: {l.strip()}" for n, l in enumerate(lineas) if re.match(r"#{1,6}\s", l)]
+    elif ruta.suffix == ".vue":
+        filas = [f"{n + 1}: {l.strip()[:90]}" for n, l in enumerate(lineas) if VUE.match(l)]
+    else:
+        filas = [f"{n + 1}: {l.strip()[:90]}" for n, l in enumerate(lineas) if INDICE.match(l)]
+    if not filas:
+        tope = min(30, max_lineas, len(lineas))
+        return "\n".join([f"{rel}: {len(lineas)} líneas, SIN ÍNDICE (no hay símbolos); primeras {tope}, el resto con lineas=«a-b»"]
+                         + [f"{n + 1}: {lineas[n]}" for n in range(tope)])
+    extra = [f"… {len(filas) - max_lineas} más"] if len(filas) > max_lineas else []
+    return "\n".join([f"{rel}: {len(lineas)} líneas, índice"] + filas[:max_lineas] + extra)
+
+
+def _rango(lineas, rel, texto, max_lineas):
+    """Líneas numeradas del rango `texto` («120-180» o «120»), hasta `max_lineas`."""
+    m = re.fullmatch(r"\s*(\d+)\s*(?:-\s*(\d+))?\s*", str(texto))
+    if not m or int(m[1]) < 1:
+        raise ValueError("lineas debe ser «inicio-fin» o «inicio», p. ej. «120-180»")
+    i, fin = int(m[1]) - 1, min(int(m[2] or m[1]), len(lineas))
+    if i >= len(lineas) or fin <= i:
+        raise ValueError(f"{rel} tiene {len(lineas)} líneas; el rango {texto} queda fuera")
+    cuerpo = [f"{n + 1}: {lineas[n]}" for n in range(i, min(fin, i + max_lineas))]
+    if fin - i > max_lineas:
+        cuerpo.append(f"… {fin - i - max_lineas} líneas más (hasta {fin})")
+    return "\n".join([f"{rel}:{i + 1}-{fin} de {len(lineas)}"] + cuerpo)
+
+
+def tool_leer(cfg, archivo, simbolo="", max_lineas=120, cola=0, contiene="", formato="detallado", lineas=""):
+    """Solo un trozo de `archivo`: la función, método o clase `simbolo` (php, ts, vue, js, py), la sección `simbolo` de un .md por su título, o de un log/.txt las últimas `cola` líneas y/o las que tienen `contiene`.
+
+    `simbolo` puede ser una lista (un trozo por símbolo); `lineas` = rango «120-180»; sin `simbolo` ni `lineas`, el índice del archivo.
+    """
+    formato_valido(formato)
+    ruta = dentro(cfg, archivo)
+    if ruta is None or not ruta.is_file():
+        raise ValueError(f"{archivo} no es un archivo del proyecto")
+    texto = ruta.read_text(errors="ignore").splitlines()
+    rel = ruta.relative_to(cfg["root"])
+    if lineas:
+        return _rango(texto, rel, lineas, max_lineas)
+    if ruta.suffix in LOGS:
+        return _de_log(texto, rel, cola or (10 if formato == "conciso" else 0), contiene, max_lineas)
+    if not simbolo:
+        return _indice(texto, rel, ruta, max_lineas)
+    if isinstance(simbolo, list):
+        return "\n\n".join(_trozo(texto, rel, ruta, str(s), max_lineas, formato == "conciso") for s in simbolo)
+    return _trozo(texto, rel, ruta, simbolo, max_lineas, formato == "conciso")
+
+
+def _trozo(lineas, rel, ruta, simbolo, max_lineas, conciso):
+    """La función, método o clase `simbolo` de `lineas` numerada, o la sección `simbolo` si es un .md."""
+    numerar = ruta.suffix != ".md"
+    try:
+        if ruta.suffix == ".md":
+            i, fin = _seccion(lineas, simbolo)
+        else:
+            i = _inicio(lineas, simbolo)
+            if ruta.suffix == ".py":
+                sangria = len(lineas[i]) - len(lineas[i].lstrip())
+                fin = next((j for j in range(i + 1, len(lineas)) if lineas[j].strip() and len(lineas[j]) - len(lineas[j].lstrip()) <= sangria),
+                           len(lineas))
+            else:
+                fin = _fin_llaves(lineas, i, ruta.suffix == ".php")
+    except LookupError as error:
+        raise LookupError(f"{error} en {rel}") from None
+    while fin > i + 1 and not lineas[fin - 1].strip():
+        fin -= 1
+    if conciso and ruta.suffix == ".md":
+        titulos = [l for l in lineas[i:fin] if re.match(r"#{1,6}\s", l)]
+        return "\n".join([f"{rel}:{i + 1}-{fin}"] + titulos)
+    max_lineas = 1 if conciso else max_lineas
+    cuerpo = [f"{n + 1}: {lineas[n]}" if numerar else lineas[n] for n in range(i, min(fin, i + max_lineas))]
+    if fin - i > max_lineas:
+        cuerpo.append(f"… {fin - i - max_lineas} líneas más (hasta {fin})")
+    return "\n".join([f"{rel}:{i + 1}-{fin}"] + cuerpo)
+
+
+def tool_correr(cfg, nombre="lista", args=(), detalle="nombre", escritura=False):
+    """Corre un script de solo lectura del manifiesto con `args`; `nombre`="lista" los enumera con su uso; `detalle`="esquema" con un script da su ficha."""
+    scripts = cfg["scripts"]
+    if nombre == "lista":
+        if detalle == "nombre":
+            return "\n".join(f"{n} {s.get('uso', '').split(';')[0][:70]}".rstrip() for n, s in scripts.items())
+        return "\n".join(f"{n}: {s['descripcion']}" + (f"\n  uso: {s.get('uso', '')}" if detalle == "esquema" else "")
+                         for n, s in scripts.items())
+    if nombre not in scripts:
+        raise LookupError(f"no hay el script {nombre}; correr('lista') los enumera")
+    s = scripts[nombre]
+    rechaza = s.get("rechaza", [])
+    if detalle == "esquema":
+        return f"{nombre}: {s['descripcion']}\nuso: {s.get('uso', '')}\nno admite: {', '.join(rechaza) or '-'}"
+    if isinstance(args, str):
+        raise ValueError("args debe ser una lista, p. ej. [\"a\", \"b\"]")
+    args = [str(a) for a in args]
+    for a in args:
+        if any(a == f or a.startswith(f + "=") for f in rechaza):
+            raise ValueError(f"{nombre} no admite {a} (escribiría archivos)")
+        if a in s.get("escribe", []) and not escritura:
+            raise ValueError(f"{nombre} {a} escribe en la base: usa correr_escritura")
+        if a in s.get("escribe", []) and os.environ.get("WEBSCOPE_ESCRITURA") not in ("1", "sin-confirmar"):
+            raise ValueError(f"{nombre} {a} escribe en la base: el usuario debe activar WEBSCOPE_ESCRITURA=1 en la configuración del servidor")
+        if (a.startswith("/") and not s.get("acepta_barra")) or ".." in Path(a).parts:
+            raise ValueError(f"{a}: usa rutas relativas a la raíz del proyecto, sin ..")
+    cmd = [sys.executable if c == "python3" else c.replace("{adaptadores}", str(ADAPTADORES)) for c in s["cmd"]]
+    return run(cfg, [*cmd, *args], timeout=s.get("timeout", 300), cabeza=s.get("cabeza"), cola=s.get("cola"))
+
+
+def tool_correr_escritura(cfg, nombre, args):
+    """Corre un script del manifiesto con un argumento que escribe en la base (lo declara `escribe`); exige WEBSCOPE_ESCRITURA=1 y confirmación del usuario en cada llamada."""
+    return tool_correr(cfg, nombre, args, escritura=True)
+
+
+S, I = {"type": "string"}, {"type": "integer"}
+FORMATO = {**S, "enum": ["conciso", "detallado"], "default": "detallado", "description": "conciso = solo lo esencial"}
+ARGS = {"type": "array", "items": S, "description": "un argumento por elemento; rutas relativas, sin .."}
+TOOLS = {
+    "buscar": (tool_buscar, {"type": "object", "additionalProperties": False, "required": ["texto"], "properties": {
+        "texto": {**S, "minLength": 1, "description": "literal salvo regex=true"},
+        "donde": {**S, "description": "carpeta o archivo relativo a la raíz"},
+        "tope": {**I, "minimum": 1, "default": 15, "description": "máximo de líneas"}, "formato": FORMATO,
+        "contexto": {**I, "minimum": 0, "maximum": 5, "default": 0, "description": "líneas alrededor"},
+        "regex": {"type": "boolean", "default": False, "description": "texto es regex extendida"}}}),
+    "leer": (tool_leer, {"type": "object", "additionalProperties": False, "required": ["archivo"], "properties": {
+        "archivo": {**S, "description": "ruta relativa a la raíz"},
+        "simbolo": {"anyOf": [S, {"type": "array", "items": S}], "description": "función, clase o título; lista = varios"},
+        "lineas": {**S, "description": "rango «120-180»"},
+        "max_lineas": {**I, "minimum": 1, "default": 120},
+        "cola": {**I, "minimum": 0, "default": 0, "description": "logs: últimas N líneas"},
+        "contiene": {**S, "description": "logs: líneas con este texto"}, "formato": FORMATO}}),
+    "correr": (tool_correr, {"type": "object", "additionalProperties": False, "required": [], "properties": {
+        "nombre": {**S, "default": "lista", "description": "script o «lista»"}, "args": ARGS,
+        "detalle": {**S, "enum": ["nombre", "descripcion", "esquema"], "default": "nombre", "description": "esquema = ficha sin correrlo"}}}),
+    "correr_escritura": (tool_correr_escritura, {"type": "object", "additionalProperties": False, "required": ["nombre", "args"], "properties": {
+        "nombre": {**S, "description": "script que declara `escribe`"}, "args": {**ARGS, "minItems": 1}}}),
+}
+TITULOS = {"buscar": "Buscar en el proyecto", "leer": "Leer un trozo de archivo", "correr": "Correr un script de solo lectura",
+           "correr_escritura": "Correr un script que escribe"}
+DESCRIPCIONES = {
+    "buscar": "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...).",
+    "leer": "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.",
+    "correr": "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).",
+    "correr_escritura": "Destructiva: corre un script con un argumento que escribe datos (de su `escribe`, p. ej. --borrar); no "
+                        "se deshace. Exige WEBSCOPE_ESCRITURA=1 y confirmación del usuario en cada llamada. Úsala solo si el "
+                        "usuario pidió el cambio; antes revisa con correr sin ese argumento.",
+}
+
+
+def con_tope(cfg, texto):
+    """Recorta `texto` a `tope_tokens` del manifiesto (4 caracteres por token, aproximado) y avisa cómo pedir menos."""
+    limite = cfg["tope_tokens"] * 4
+    if len(texto) <= limite:
+        return texto
+    return texto[:limite] + f"\n… recortado a ~{cfg['tope_tokens']} tokens; usa formato=conciso o filtra más"
+
+
+def explica(nombre, args, texto):
+    """Antepone a `texto` una línea corta que dice qué es la respuesta de la herramienta `nombre` y qué sigue."""
+    simbolo, script = args.get("simbolo", ""), args.get("nombre", "lista")
+    if nombre == "buscar":
+        lead = f"Líneas del proyecto con «{str(args.get('texto', ''))[:30]}» (archivo, línea). Sigue: leer(archivo, símbolo) de la que interese."
+    elif Path(str(args.get("archivo", ""))).suffix in LOGS:
+        lead = "Líneas de un registro (log), numeradas. Sigue: afinar con contiene o cola."
+    elif nombre == "leer" and args.get("lineas"):
+        lead = "Rango de líneas numeradas. Sigue: leer(archivo, simbolo) si buscas una función entera."
+    elif nombre == "leer" and not simbolo:
+        lead = "Índice del archivo con su línea, o sus primeras líneas si no tiene símbolos. Sigue: leer(archivo, simbolo) o lineas=«a-b»."
+    elif nombre == "leer" and isinstance(simbolo, list):
+        lead = f"{len(simbolo)} trozos, uno por símbolo. Sigue: buscar el que quieras ver usado."
+    elif nombre == "leer" and Path(str(args.get("archivo", ""))).suffix == ".md":
+        lead = f"Sección «{simbolo}» del documento (hasta el siguiente título igual o mayor). Sigue: otra sección o buscar."
+    elif nombre == "leer":
+        lead = f"Código de «{simbolo}» (función o clase) con sus líneas. Sigue: buscar(\"{simbolo}\") para ver quién lo usa."
+    elif script == "lista":
+        lead = "Scripts de solo lectura del proyecto. Sigue: correr(nombre, args) directo; detalle=\"esquema\" solo si dudas de los args de uno."
+    elif args.get("detalle") == "esquema":
+        lead = f"Ficha del script «{script}». Sigue: correr(\"{script}\", args)."
+    else:
+        lead = f"Salida del script «{script}» (exit 0 = sin error). Sigue: leer o buscar lo que cite."
+    return f"{lead}\n{texto}"
+
+
+TIPOS = {"string": (str, "texto"), "integer": (int, "entero"), "boolean": (bool, "true o false"), "array": (list, "lista")}
+
+
+def invalido(esquema, valor, nombre):
+    """Motivo por el que `valor` no cumple `esquema` (tipos, enum, mínimos y máximos de los esquemas de TOOLS), o '' si lo cumple."""
+    if "anyOf" in esquema:
+        return "" if any(not invalido(s, valor, nombre) for s in esquema["anyOf"]) else f"{nombre} debe ser texto o lista de textos"
+    tipo, como = TIPOS.get(esquema.get("type"), (object, ""))
+    if not isinstance(valor, tipo) or (tipo is int and isinstance(valor, bool)):
+        return f"{nombre} debe ser {como}"
+    if "enum" in esquema and valor not in esquema["enum"]:
+        return f"{nombre} debe ser uno de {', '.join(esquema['enum'])}"
+    if "minimum" in esquema and valor < esquema["minimum"] or "maximum" in esquema and valor > esquema["maximum"]:
+        return f"{nombre} debe estar entre {esquema.get('minimum', '-∞')} y {esquema.get('maximum', '∞')}"
+    if len(valor) < esquema.get("minLength", esquema.get("minItems", 0)) if tipo in (str, list) else False:
+        return f"{nombre} no puede estar vacío"
+    if tipo is list and "items" in esquema:
+        return next((m for m in (invalido(esquema["items"], x, f"cada elemento de {nombre}") for x in valor) if m), "")
+    return ""
+
+
+def validar(esquema, args):
+    """Falla con un mensaje claro si `args` no cumple el esquema de entrada de la herramienta."""
+    if not isinstance(args, dict):
+        raise ValueError("arguments debe ser un objeto")
+    faltan = [p for p in esquema.get("required", []) if p not in args]
+    sobran = [p for p in args if p not in esquema["properties"]]
+    motivo = (f"falta {', '.join(faltan)}" if faltan else f"no existe {', '.join(sobran)}; hay {', '.join(esquema['properties'])}" if sobran
+              else next((m for m in (invalido(esquema["properties"][p], v, p) for p, v in args.items()) if m), ""))
+    if motivo:
+        raise ValueError(motivo)
+
+
+VERSIONES = ("2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05")
+SALIDA = {"type": "object", "properties": {"nota": S, "exit": {"type": ["integer", "null"]}, "salida": S}}
+
+
+def estructura(texto, nota):
+    """`structuredContent` de correr: la nota de qué sigue, el código de la primera línea «exit N» y el resto como salida."""
+    m = re.match(r"exit (-?\d+)\n?", texto)
+    return {"nota": nota, **({"exit": int(m.group(1)), "salida": texto[m.end():]} if m else {"exit": None, "salida": texto})}
+
+
+def anotaciones(nombre):
+    """Pistas de comportamiento de la herramienta: solo `correr_escritura` escribe; ninguna sale del proyecto."""
+    if nombre == "correr_escritura":
+        return {"readOnlyHint": False, "destructiveHint": True, "idempotentHint": False, "openWorldHint": False}
+    return {"readOnlyHint": True, "openWorldHint": False}
+
+
+def herramientas(cfg):
+    """Herramientas que expone el servidor: `correr_escritura` solo si algún script del manifiesto declara `escribe`."""
+    escribe = any(x.get("escribe") for x in cfg.get("scripts", {}).values())
+    return [(n, f, s) for n, (f, s) in TOOLS.items() if n != "correr_escritura" or escribe]
+
+
+RECORRIDO = Path(__file__).resolve().parent / "agents" / "recorrido.example.md"
+PROMPTS = [{"name": "recorrido", "title": "Recorrer un módulo en el navegador",
+            "description": "Recorre en vivo un módulo del frontend (listar, crear ZZ_E2E, editar, verificar, borrar, limpiar) con "
+                           "Chrome y los scripts de webscope, y resume solo lo que falla.",
+            "arguments": [{"name": "modulo", "description": "módulo del frontend, p. ej. sales/orders", "required": True},
+                          {"name": "url", "description": "URL base de la app, p. ej. http://localhost:5173"},
+                          {"name": "prefijo", "description": "prefijo de lo que se crea (por defecto ZZ_E2E)"}]}]
+
+
+def prompt_recorrido(argumentos):
+    """Mensaje del prompt `recorrido`: el método del agente de ejemplo (sin su cabecera) y el pedido con sus argumentos."""
+    if not argumentos.get("modulo"):
+        raise ValueError("falta el argumento modulo")
+    metodo = RECORRIDO.read_text().split("---", 2)[2].strip()
+    pedido = (f"Walk the module `{argumentos['modulo']}`"
+              + (f" of the app at {argumentos['url']}" if argumentos.get("url") else "")
+              + f". Prefix for everything you create: {argumentos.get('prefijo') or 'ZZ_E2E'}.")
+    return {"description": PROMPTS[0]["description"],
+            "messages": [{"role": "user", "content": {"type": "text", "text": f"{metodo}\n\n## Request\n{pedido}"}}]}
+
+
+def carpetas_recursos(cfg):
+    """Carpetas cuyos archivos se publican como recursos: {tipo: (carpeta, patrón, mimeType)}."""
+    carpetas = {"recorridos": (cfg["root"] / ".claude/webscope/recorridos", "*.json", "application/json")}
+    capturas = cfg.get("proyecto", {}).get("capturas")
+    if capturas and dentro(cfg, capturas):
+        carpetas["capturas"] = (dentro(cfg, capturas), "*.txt", "text/plain")
+    return carpetas
+
+
+def recursos(cfg):
+    """Recorridos guardados y capturas del proyecto como recursos MCP (`webscope://<tipo>/<archivo>`)."""
+    return [{"uri": f"webscope://{tipo}/{f.name}", "name": f"{tipo}/{f.name}", "mimeType": mime,
+             "description": "pasos que repite e2e_chrome --repetir" if tipo == "recorridos" else "captura de un recorrido (red, pasos, tiempos)"}
+            for tipo, (carpeta, patron, mime) in carpetas_recursos(cfg).items() if carpeta.is_dir()
+            for f in sorted(carpeta.glob(patron))]
+
+
+def leer_recurso(cfg, uri):
+    """Contenido de un recurso `webscope://<tipo>/<archivo>`, recortado al tope de tokens."""
+    m = re.fullmatch(r"webscope://(\w+)/([\w.-]+)", str(uri))
+    carpetas = carpetas_recursos(cfg)
+    if not m or m.group(1) not in carpetas:
+        raise LookupError(f"recurso desconocido {uri}")
+    carpeta, patron, mime = carpetas[m.group(1)]
+    ruta = carpeta / m.group(2)
+    if not fnmatch.fnmatch(ruta.name, patron) or not ruta.is_file():
+        raise LookupError(f"recurso desconocido {uri}")
+    return {"contents": [{"uri": uri, "mimeType": mime, "text": con_tope(cfg, ruta.read_text(errors="replace"))}]}
+
+
+def handle(cfg, message):
+    """Responde una petición JSON-RPC; devuelve None si es una notificación."""
+    method, mid, params = message.get("method"), message.get("id"), message.get("params") or {}
+    if mid is None:
+        return None
+    if not isinstance(params, dict):
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32602, "message": "params debe ser un objeto"}}
+    if method == "initialize":
+        pedida = params.get("protocolVersion")
+        result = {"protocolVersion": pedida if pedida in VERSIONES else VERSIONES[0],
+                  "capabilities": {"tools": {}, "resources": {}, **({"prompts": {}} if RECORRIDO.is_file() else {})},
+                  "serverInfo": {"name": "webscope", "version": "0.2.0"},
+                  "instructions": f"{INSTRUCCIONES}\nScripts (nombre y args):\n{tool_correr(cfg)}"}
+    elif method == "ping":
+        result = {}
+    elif method == "resources/list":
+        result = {"resources": recursos(cfg)}
+    elif method == "resources/templates/list":
+        result = {"resourceTemplates": []}
+    elif method == "resources/read":
+        try:
+            result = leer_recurso(cfg, params.get("uri"))
+        except LookupError as error:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32002, "message": str(error)}}
+    elif method == "prompts/list":
+        result = {"prompts": PROMPTS if RECORRIDO.is_file() else []}
+    elif method == "prompts/get":
+        if params.get("name") != "recorrido" or not RECORRIDO.is_file():
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32602, "message": f"prompt desconocido {params.get('name')}"}}
+        try:
+            result = prompt_recorrido(params.get("arguments") or {})
+        except ValueError as error:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32602, "message": str(error)}}
+    elif method == "tools/list":
+        result = {"tools": [{"name": n, "title": TITULOS[n], "description": DESCRIPCIONES[n], "inputSchema": s,
+                             **({"outputSchema": SALIDA} if n.startswith("correr") else {}),
+                             "annotations": anotaciones(n),
+                             # sin-confirmar quita la confirmación por llamada (corridas desatendidas como `claude -p`)
+                             "_meta": ({} if os.environ.get("WEBSCOPE_ESCRITURA") == "sin-confirmar" else {"anthropic/requiresUserInteraction": True})
+                             if n == "correr_escritura" else {"anthropic/alwaysLoad": True}}
+                            for n, f, s in herramientas(cfg)]}
+    elif method == "tools/call":
+        name, arguments = params.get("name"), params.get("arguments") or {}
+        if name not in {n for n, _, _ in herramientas(cfg)}:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32602, "message": f"herramienta desconocida {name}"}}
+        ficha = (params.get("_meta") or {}).get("progressToken")
+        if ficha is not None:
+            cfg = {**cfg, "_avisar": lambda n, texto: escribir({"jsonrpc": "2.0", "method": "notifications/progress",
+                                                                "params": {"progressToken": ficha, "progress": n, "message": texto}})}
+        try:
+            validar(TOOLS[name][1], arguments)
+            salida = TOOLS[name][0](cfg, **arguments)
+            result = {"content": [{"type": "text", "text": con_tope(cfg, explica(name, arguments, salida))}]}
+            if name.startswith("correr"):
+                result["structuredContent"] = estructura(con_tope(cfg, salida), explica(name, arguments, "").strip())
+        except Exception as error:  # una herramienta fallida se informa al cliente, no tumba el servidor
+            aviso = f"No se pudo: {str(error).splitlines()[0][:80] if str(error) else type(error).__name__}. Sigue: corrige el argumento o usa otra herramienta."
+            result = {"content": [{"type": "text", "text": f"{aviso}\n{type(error).__name__}: {error}"}], "isError": True}
+    else:
+        return {"jsonrpc": "2.0", "id": mid, "error": {"code": -32601, "message": f"método desconocido {method}"}}
+    return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+
+def escribir(mensaje):
+    """Escribe un mensaje JSON-RPC en la salida estándar, una línea por mensaje."""
+    sys.stdout.write(json.dumps(mensaje) + "\n")
+    sys.stdout.flush()
+
+
+def responder(cfg, linea):
+    """Respuesta JSON-RPC a una línea de la entrada, o None si es una notificación; un fallo inesperado vuelve como error, no tumba el servidor."""
+    try:
+        message = json.loads(linea)
+    except json.JSONDecodeError:
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "error de sintaxis"}}
+    if not isinstance(message, dict):
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "la petición debe ser un objeto JSON"}}
+    try:
+        return handle(cfg, message)
+    except Exception as error:
+        return {"jsonrpc": "2.0", "id": message.get("id"), "error": {"code": -32603, "message": f"error interno: {error}"}}
+
+
+def main(argv=None):
+    """Carga el manifiesto de `--manifest`, WEBSCOPE_MANIFEST o ./webscope.json (sin ninguno, la carpeta actual sin scripts) y atiende JSON-RPC por la entrada estándar."""
+    argv = sys.argv[1:] if argv is None else argv
+    if "--manifest" in argv and argv.index("--manifest") + 1 < len(argv):
+        manifiesto = argv[argv.index("--manifest") + 1]
+    else:
+        manifiesto = os.environ.get("WEBSCOPE_MANIFEST") or ("webscope.json" if Path("webscope.json").is_file() else None)
+    if not manifiesto:
+        print(f"webscope: sin manifiesto; raíz = {Path.cwd()}, sin scripts (usa --manifest <ruta/webscope.json>)", file=sys.stderr)
+    try:
+        cfg = cargar(manifiesto)
+    except (OSError, ValueError) as error:
+        sys.exit(f"webscope: no se pudo leer el manifiesto {manifiesto}: {error}")
+    for line in sys.stdin:
+        if not line.strip():
+            continue
+        reply = responder(cfg, line)
+        if reply is not None:
+            escribir(reply)
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])