Scavenge — evidencia web determinista para humanos y agentes de codificación

Scavenge inspecciona un campo en una página web e informa cada lugar donde aparece ese campo, qué dice cada representación y exactamente de dónde proviene cada valor.

Recopila observaciones de campo con procedencia exacta. No determina qué observación es semánticamente correcta. Ese juicio necesita saber qué significa la página, y el motor es deliberadamente incapaz de hacerlo — consulte Por qué se detiene ahí.

Qué hace

$ scavenge inspect https://example.com/product/123 --field price

FIELD: price
  RAW_DOM          99.00 USD   [raw_dom:0]
                     raw:    '$99.00'
                     source: div.product-price
  STRUCTURED_DATA  99.00 USD   [structured_data:0]
                     raw:    '99.00'
                     source: script[0]/offers/price
  EMBEDDED_STATE   not observed
  RENDERED_DOM     79.00 USD   [rendered_dom:0]
                     raw:    '$79.00'
                     source: div.product-price
  NETWORK_JSON     79.00 USD   [network_json:0]
                     raw:    '79.00'
                     source: GET https://example.com/api/products/123 /price

ACQUISITION
  HTTP    200  48213 bytes  0.31s
  RENDER  OK
  JSON responses observed: 12

El HTML sin procesar dice 99.00, la página renderizada dice 79.00, y una llamada API explica por qué. Puede verlo en dos segundos; el motor no lo afirma.

Related MCP server: mcp-ux-vision

Por qué existe

Una página declara el mismo hecho en varios lugares — HTML visible, JSON-LD, un blob de hidratación, el DOM renderizado, una respuesta XHR — y discrepan más a menudo de lo que le gustaría. Determinar cuáles contienen su campo es un trabajo de DevTools, hecho a mano, una vez por objetivo, para siempre. Un agente también puede hacerlo, pero no de forma reproducible ni con procedencia exacta.

Por qué se detiene ahí

El objetivo original era más ambicioso: decidir de forma determinista si los valores encontrados en diferentes representaciones se referían a la misma cosa del mundo real, e informar dónde coincidían o discrepaban.

Las tiendas reales rompieron esa suposición. Los valores que parecían comparables pertenecían a carruseles de recomendaciones, carritos, tablas de financiación, localizadores de tiendas, variantes de producto y segundos bloques Product en la misma página. Una ejecución de validación en 12 tiendas encontró que cada discrepancia que el motor informaba era de ese tipo — los valores y la procedencia eran correctos, la comparación era incorrecta.

Arreglarlo correctamente se convierte en resolución de entidades. Así que Scavenge se detiene un paso antes: recopilar la evidencia de forma determinista y dejar que un humano o un agente la interprete. El relato completo, incluidos los resultados que mataron el diseño anterior, está en docs/research/.

Campos compatibles

price y availability. Dos, no "arbitrarios".

Canales compatibles

RAW_DOM · STRUCTURED_DATA · EMBEDDED_STATE · RENDERED_DOM · NETWORK_JSON

No están igualmente validados. En una validación de 23 páginas en 12 tiendas, STRUCTURED_DATA produjo valores en 28 de 46 ejecuciones y EMBEDDED_STATE solo en 6.

MCP

Una herramienta, inspect_web_field(url, field), que devuelve evidencia estructurada — no prosa.

{
  "mcpServers": {
    "scavenge": { "command": "python", "args": ["-m", "scavenge.mcp"] }
  }
}

El servidor no razona sobre nada, no genera código de scraping y no llama a ningún modelo.

Salida estructurada

{
  "schema_version": 3,
  "target": "https://example.com/product/123",
  "field": "price",
  "observations": [
    {
      "id": "raw_dom:0",
      "channel": "RAW_DOM",
      "normalized_value": {"kind": "money", "amount": "99.00", "currency": "USD"},
      "raw": "$99.00",
      "provenance": {"selector": "div.product-price"},
      "subject": {"scope": "PAGE", "key": "", "reason": ""},
      "status": "OK",
      "note": ""
    }
  ],
  "acquisition": {
    "http_status": 200, "http_bytes": 48213, "http_challenge": "",
    "render_status": "OK", "json_responses": 12
  },
  "warnings": []
}

Arquitectura

  MCP ─┐
       ├─→ evidence engine ─→ HTTP · raw DOM · structured data
  CLI ─┘                      embedded state · rendered DOM · network JSON

Un motor. Ambas interfaces lo llaman; una prueba afirma que el JSON de la CLI es el JSON del motor.

Instalación

pip install git+https://github.com/aarohim24/Scavenge.git
python -m playwright install chromium     # required for rendered DOM and network channels
scavenge inspect https://example.com/p/1 --field price

Aún no está en PyPI — deliberadamente, hasta que la API haya superado una ronda de comentarios externos.

--no-render omite el navegador e informa solo los canales HTTP.

Límites de seguridad

Solo http/https. file://, localhost, loopback, rangos link-local y privados son rechazados antes de cualquier solicitud — lo cual importa más bajo MCP, donde un agente proporciona URLs sin que un humano las vea. Cuerpos limitados a 512 KB, respuestas JSON limitadas a 40, esperas acotadas, recuperación de robots acotada. Se respeta robots.txt, y un timeout o robots.txt inalcanzable nunca se trata como permiso. Ninguna solicitud capturada se reproduce, ninguna solicitud autenticada se reemite, nada de una página se ejecuta.

Lo que explícitamente no hace

• Decidir qué observación es correcta. v0.1 no publica ninguna comparación.

• Resolución de entidades. No puede distinguir de forma fiable el producto de la página de un segundo bloque Product, un mosaico de venta adicional, un total del carrito o una fila de localizador de tiendas.

• Rastrear, programar o seguir enlaces.

• Derrotar sistemas anti-bot. Detecta un desafío obvio y lo indica; nunca lo evade.

• Llamar a un LLM, en ningún modo.

Limitaciones conocidas

1. Sin comparación en v0.1. Una versión anterior publicaba relaciones EQUAL/DIFFERENT. La validación en el mundo real encontró que cada DIFFERENT que producía en tiendas reales comparaba dos entidades diferentes, por lo que la función se eliminó en lugar de parchearse. El resultado completo está en docs/research/OSS-FINAL-CORRECTNESS.md.

2. La moneda suele ser null. $ nombra una docena de monedas; sin evidencia declarada se conserva el importe y se rechaza la moneda. Desconocido es común; incorrecto debería estar ausente.

3. Las unidades menores no están modeladas — un 2950 de Shopify y un 29.50 mostrado son dos observaciones diferentes.

4. El determinismo es de la generación del informe, no de la web. Mismos bytes de entrada, mismo informe de salida. La misma URL no siempre dará los mismos bytes.

5. Un renderizado bloqueado se detecta solo a partir de señales nombradas; un shell delgado sin nombre no.

6. El acceso respetuoso con robots excluye a muchos grandes minoristas por completo.

Licencia

Apache-2.0.

Estado

Experimental v0.1. Publicado para comentarios técnicos, no para producción. La API puede cambiar. Ha sido validado en 23 páginas de 12 tiendas, más un conjunto de pruebas deterministas; es una muestra pequeña y no es un punto de referencia.

El registro de investigación — incluidos los resultados que mataron versiones anteriores de esta idea — está en docs/research/.