Promas (Product Image Scraper)

Promas ist ein automatisierter Produktbild-Scraper und Model Context Protocol (MCP)-Server für KI-Agenten.

Anstatt fragiler, seiten-spezifischer Scraper, die bei jeder Änderung der HTML-Struktur brechen, kombiniert Promas pluggable, suchgesteuerte Erkennung mit einer universellen semantischen Extraktions-Pipeline und erweiterbarem, CDN-bewusstem Upscaling. Es extrahiert zuverlässig Produktfotografie in Master-Auflösung von beliebigen Marken- oder Einzelhandelsseiten (Apple, Nike, Sony, Amazon, Target, B&H, Best Buy, eBay, Shopify-Shops und beliebigen Produkt-URLs).

1. Schnellstart

Option A: Installation von PyPI (Empfohlen)

pip install promas
playwright install chromium

Sofort von überall ausführbar:

promas "iPhone 16 Pro"

Option B: Mit Docker ausführen (Keine lokale Python-/Playwright-Einrichtung)

# 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. Architektur & 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. Warum Promas? (Vergleich)

4. Such-Backends & Konfiguration

Promas funktioniert zu 100 % sofort einsatzbereit, ohne Konfiguration oder API-Schlüssel.

So funktioniert die Such-Erkennung:

1. Kostenlos / Standard (keine Einrichtung): Promas nutzt die integrierte Playwright-Stealth-Browser-Engine, um E-Commerce-Kandidaten kostenlos über Bing und DuckDuckGo zu finden.

2. Brave Search API (für Produktion empfohlen): Wenn BRAVE_API_KEY gesetzt ist, wechselt Promas zur offiziellen, ToS-konformen API-Erkennung im Sub-Sekunden-Bereich.

   • Kostenlosen Schlüssel erhalten (2.000 kostenlose Abfragen/Monat): Brave Search API

3. SerpAPI (Alternative): Wenn SERPAPI_API_KEY gesetzt ist, fragt Promas die Google-Suche über SerpAPI ab.

   • Kostenlosen Schlüssel erhalten (100 kostenlose Abfragen/Monat): SerpAPI

Referenz der Umgebungsvariablen:

5. Verwendung

A. Eigenständige CLI

Nach Produktname suchen:

promas "iPhone 16 Pro"

Von einer direkten URL extrahieren:

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

Nach bestimmter Domain filtern & Anzahl begrenzen:

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

Cache umgehen oder Verifizierung deaktivieren:

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

B. FastMCP-Server

Den eigenständigen MCP-Server ausführen:

promas-mcp

C. Agenten-Integration (mcp_config.json)

Native Python-Installation:

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

Docker-Container (Einrichtung ohne Abhängigkeiten):

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

6. Multi-Tool-MCP-Suite

Promas stellt KI-Agenten dedizierte, granulare Tools zur Verfügung:

7. Richtlinien für Agenten-Systemprompts

Fügen Sie Ihrem KI-Agenten-Systemprompt die folgenden Anweisungen hinzu:

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. Ausgabe-Schema

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

Beiträge sind herzlich willkommen! Die Unterstützung für Master-Upscaling einer neuen E-Commerce-Plattform oder eines CDN erfordert mit unserem Decorator-Plugin-Registry weniger als 10 Zeilen Code.

👉 Siehe CONTRIBUTING.md für Schritt-für-Schritt-Anleitungen zum Hinzufügen einer neuen CDN-Regel.

10. Tests & Qualitätssicherung

Promas enthält Unit-Tests für reine Parsing-Funktionen, Typprüfungen und Canary-Integrationstests:

# 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. Rechtliche & ethische Nutzung

• Nur öffentlicher Zugriff: Promas greift ausschließlich auf öffentlich zugängliche Webseiten zu; es umgeht keine Authentifizierung, Bezahlschranken oder private Logins.

• Nutzungsbedingungen: Automatisierter Zugriff kann den Nutzungsbedingungen einzelner Websites unterliegen. Überprüfen Sie vor dem Scraping in großem Umfang immer die ToS- und Robot-Richtlinien der Ziel-Domains oder stellen Sie offizielle Such-API-Schlüssel (BRAVE_API_KEY / SERPAPI_API_KEY) für ToS-konforme Erkennung bereit.

• Bildurheberrecht & Namensnennung: Promas löst direkte Bild-URLs auf und gibt sie zurück – es speichert, rehostet oder kopiert keine Mediendateien. Die weitere Anzeige, Speicherung oder kommerzielle Nutzung abgerufener Bilder liegt in der Verantwortung des Nutzers.

12. Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.