Promas (Rascador de imágenes de producto)

Promas es un rascador automatizado de imágenes de producto y un servidor de Model Context Protocol (MCP) para agentes de IA.

En lugar de escribir rascadores frágiles específicos para cada sitio que se rompen cuando cambian las estructuras HTML, Promas combina Descubrimiento enchufable basado en búsqueda con un canal universal de extracción semántica y ampliación extensible compatible con CDN. Extrae de forma fiable fotografía de producto en resolución maestra en cualquier sitio de marcas o minoristas (Apple, Nike, Sony, Amazon, Target, B&H, Best Buy, eBay, tiendas Shopify y URLs de producto arbitrarias).

1. Inicio rápido

Opción A: Instalar desde PyPI (Recomendado)

pip install promas
playwright install chromium

Ejecútalo al instante desde cualquier lugar:

promas "iPhone 16 Pro"

Opción B: Ejecutar con Docker (Sin configuración local de Python / Playwright)

# Build the Docker image
docker build -t promas .

# Run the FastMCP Server for your AI Agent
docker run -i --rm promas

# Or run the standalone CLI scraper
docker run --rm promas promas "Sony FX3"

Related MCP server: Universal Shopping Agent MCP Server

2. Arquitectura y pipeline

graph TD
    User([AI Agent / CLI Request]) --> Cache{TTL Disk Cache}
    Cache -- "Cache Hit (<0.1s)" --> Return([Return Verified Master Assets])
    Cache -- "Cache Miss" --> SearchRouter{Pluggable Discovery}
    SearchRouter -->|BRAVE_API_KEY| BraveAPI[Brave Search API]
    SearchRouter -->|SERPAPI_API_KEY| SerpAPI[SerpAPI Google]
    SearchRouter -->|Default: Free / Zero Keys| BrowserSearch[Stealth Browser Discovery]
    BraveAPI --> Scorer[E-Commerce Candidate Scorer]
    SerpAPI --> Scorer
    BrowserSearch --> Scorer
    Scorer --> ParallelScraper[Parallel Multi-Page Scraper]
    subgraph Scraping Pipeline
        ParallelScraper --> RateLimiter[Domain Rate Limiter]
        RateLimiter --> Parser[Universal Extractor: Schema.org, OG, Microdata, DOM]
        Parser --> CDNUpscaler[CDN Master Upscalers: Scene7, Nike, Shopify, Amazon...]
    end
    CDNUpscaler --> Verifier[Async HTTP Verification & pHash Dedup]
    Verifier --> CacheStore[(Save to Disk Cache)]
    CacheStore --> Return

3. ¿Por qué Promas? (Comparativa)

4. Motores de búsqueda y configuración

Promas funciona 100 % listo para usar sin necesidad de configuración ni claves de API.

Cómo funciona el descubrimiento de búsqueda:

1. Gratis / predeterminado (sin configuración): Promas utiliza su motor de navegador Playwright Stealth integrado para descubrir candidatos de comercio electrónico mediante Bing y DuckDuckGo de forma gratuita.

2. Brave Search API (recomendado para producción): si se establece BRAVE_API_KEY, Promas cambia al descubrimiento oficial por API, conforme a los Términos de servicio y en menos de un segundo.

   • Obtén una clave gratuita (2,000 consultas gratuitas/mes): Brave Search API

3. SerpAPI (alternativa): si se establece SERPAPI_API_KEY, Promas consulta Google Search a través de SerpAPI.

   • Obtén una clave gratuita (100 consultas gratuitas/mes): SerpAPI

Referencia de variables de entorno:

5. Uso

A. CLI independiente

Buscar por nombre de producto:

promas "iPhone 16 Pro"

Extraer desde una URL directa:

promas "https://www.apple.com/iphone-16-pro/"

Filtrar por dominio específico y limitar el número de resultados:

promas "Sony FX3" --max-images 5 --site bhphotovideo.com

Omitir la caché o desactivar la verificación:

promas "Nike Air Jordan 1" --no-cache --no-verify

B. Servidor FastMCP

Ejecuta el servidor MCP independiente:

promas-mcp

C. Integración con agentes (mcp_config.json)

Instalación nativa de Python:

{
  "mcpServers": {
    "promas": {
      "command": "promas-mcp",
      "env": {
        "BRAVE_API_KEY": "optional-key-here"
      }
    }
  }
}

Contenedor Docker (configuración sin dependencias):

{
  "mcpServers": {
    "promas": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "promas"]
    }
  }
}

6. Suite MCP de múltiples herramientas

Promas expone herramientas granulares y dedicadas a los agentes de IA:

7. Directrices para el prompt del sistema del agente

Añade las siguientes instrucciones al prompt del sistema de tu agente de IA:

You have access to the `fetch_product_images` tool (Promas), which universally retrieves high-resolution product imagery and official product links from across the web.

GUIDELINES FOR USING PROMAS:
1. When asked for product images, photos, or visual references, call `fetch_product_images(query=<specific product name or direct URL>)`.
2. Do not invent or hallucinate image URLs; strictly return the verified URLs returned by Promas.
3. Render primary high-res images as markdown (e.g. `![Product Photo](url)`) and provide source product links for reference.
4. If a specific store is desired by the user, you can supply `site_filter` (e.g. `site_filter="apple.com"`).

8. Esquema de salida

{
  "status": "success",
  "query": "iPhone 16 Pro",
  "title": "Apple iPhone 16 Pro",
  "sources_scraped": [
    "https://www.target.com/p/apple-iphone-16-pro/-/A-93597960",
    "https://www.amazon.com/Apple-iPhone-Version-256GB-Titanium/dp/B0DHJDPYYR",
    "https://www.apple.com/shop/buy-iphone/iphone-16"
  ],
  "images": [
    "https://target.scene7.com/is/image/Target/GUEST_7c0750b4-ee18-41d4-9309-d08e41619229",
    "https://target.scene7.com/is/image/Target/GUEST_4e1ce623-313f-4193-93a4-61dc0fc9da14"
  ],
  "error_message": null
}

9. Contribuciones

¡Las contribuciones son muy bienvenidas! Añadir soporte de ampliación maestra para una nueva plataforma de comercio electrónico o CDN requiere menos de 10 líneas de código con nuestro registro de complementos por decorador.

👉 Consulta CONTRIBUTING.md para obtener instrucciones paso a paso sobre cómo añadir una nueva regla de CDN.

10. Pruebas y aseguramiento de la calidad

Promas incluye pruebas unitarias para funciones de análisis puro, comprobaciones de tipos y pruebas de integración canary:

# Run unit tests
pytest -v

# Run linting
ruff check .

# Run type checker
mypy promas/ tests/

# Run live golden canary integration tests (hits live sites)
pytest -v --run-integration

11. Uso legal y ético

• Solo acceso público: Promas accede exclusivamente a páginas web disponibles públicamente; no elude la autenticación, los muros de pago ni los inicios de sesión privados.

• Términos de servicio: El acceso automatizado puede estar sujeto a los Términos de servicio de cada sitio. Revisa siempre los ToS y las políticas de robots de los dominios objetivo antes de hacer scraping a gran escala, o proporciona claves oficiales de API de búsqueda (BRAVE_API_KEY / SERPAPI_API_KEY) para un descubrimiento conforme a los términos.

• Derechos de autor y atribución de las imágenes: Promas resuelve y devuelve URLs directas de imágenes; no almacena, realoja ni copia archivos multimedia. La visualización, el almacenamiento o el uso comercial posterior de las imágenes obtenidas son responsabilidad del usuario.

12. Licencia

Este proyecto está licenciado bajo la Licencia MIT.