Promas (скрапер изображений товаров)

Promas — это автоматический скрапер изображений товаров и сервер Model Context Protocol (MCP) для ИИ-агентов.

Вместо написания хрупких скраперов под каждый сайт, которые ломаются при изменении HTML-структур, Promas сочетает подключаемое поисковое обнаружение с универсальным конвейером семантического извлечения и расширяемым апскейлингом с учётом CDN. Он надёжно извлекает фотографии товаров в мастер-разрешении на любых сайтах брендов и розничных магазинов (Apple, Nike, Sony, Amazon, Target, B&H, Best Buy, eBay, магазины Shopify и произвольные URL товаров).

1. Быстрый старт

Вариант A: установка из PyPI (рекомендуется)

pip install promas
playwright install chromium

Запускайте мгновенно откуда угодно:

promas "iPhone 16 Pro"

Вариант B: запуск в Docker (без установки локальных 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. Архитектура и конвейер

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. Почему Promas? (Сравнение)

4. Поисковые бэкенды и конфигурация

Promas работает из коробки на 100% — без настройки и без API-ключей.

Как работает поисковое обнаружение:

1. Бесплатно / по умолчанию (без настройки): Promas использует встроенный браузерный движок Playwright Stealth, чтобы бесплатно обнаруживать e-commerce-кандидатов через Bing и DuckDuckGo.

2. Brave Search API (рекомендуется для продакшена): если задан BRAVE_API_KEY, Promas переключается на официальное API-обнаружение, соответствующее ToS и выполняющееся за доли секунды.

   • Получите бесплатный ключ (2 000 бесплатных запросов в месяц): Brave Search API

3. SerpAPI (альтернатива): если задан SERPAPI_API_KEY, Promas выполняет запросы к Google Search через SerpAPI.

   • Получите бесплатный ключ (100 бесплатных запросов в месяц): SerpAPI

Справочник переменных окружения:

5. Использование

A. Автономный CLI

Поиск по названию товара:

promas "iPhone 16 Pro"

Извлечение по прямому URL:

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

Фильтрация по конкретному домену и ограничение количества:

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

Обход кэша или отключение проверки:

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

B. Сервер FastMCP

Запустите автономный MCP-сервер:

promas-mcp

C. Интеграция с агентом (mcp_config.json)

Нативная установка Python:

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

Docker-контейнер (установка без зависимостей):

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

6. Многоинструментальный набор MCP

Promas предоставляет ИИ-агентам отдельные узкоспециализированные инструменты:

7. Рекомендации по системному промпту агента

Добавьте следующие инструкции в системный промпт вашего ИИ-агента:

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. Схема вывода

{
  "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. Участие в разработке

Участие в разработке приветствуется! Добавление поддержки мастер-апскейлинга для новой e-commerce-платформы или CDN занимает меньше 10 строк кода благодаря нашему реестру плагинов-декораторов.

👉 Пошаговые инструкции по добавлению нового правила CDN см. в CONTRIBUTING.md.

10. Тестирование и контроль качества

Promas включает модульные тесты для чистых функций парсинга, проверки типов и канареечные интеграционные тесты:

# 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. Правовое и этичное использование

• Только публичный доступ: Promas обращается исключительно к публично доступным веб-страницам; он не обходит аутентификацию, пейволлы или приватные логины.

• Условия использования (ToS): автоматический доступ может регулироваться условиями использования конкретного сайта. Всегда изучайте ToS целевых доменов и политики для роботов перед массовым скрапингом либо указывайте официальные поисковые API-ключи (BRAVE_API_KEY / SERPAPI_API_KEY) для обнаружения, соответствующего ToS.

• Авторские права на изображения и атрибуция: Promas находит и возвращает прямые URL изображений — он не хранит, не перехостит и не копирует медиафайлы. Дальнейший показ, хранение или коммерческое использование полученных изображений — ответственность пользователя.

12. Лицензия

Этот проект распространяется под лицензией MIT.