Skip to main content
Glama

Promas(製品画像スクレイパー)

Promas は、AIエージェント向けの自動製品画像スクレイパー兼 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: Commerce 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なのか?(比較)

機能

生スクリプト(BeautifulSoup、Puppeteer)

有料API(Bright Data、ScrapingBee)

Promas

コスト

無料

$50〜$500+/月 継続課金

100%無料&オープンソース(MIT)

セットアップとメンテナンス

サイト別の脆弱なセレクタ。リニューアルで破損

汎用HTMLレスポンス。カスタムパーサーが必要

検索駆動 + セマンティックスキーマ + CDNアップスケーラー

アンチボットとレート制限

Cloudflare/Akamai ですぐにブロックされる

クラウドで処理

ドメイン別レートリミッター + ステルス + Tenacityリトライ

画像検証

なし。壊れたリンクや1x1ピクセルを返す

基本的なステータスチェック

非同期HTTP検証 + pHash知覚重複排除

検索バックエンド

ハードコードされたスクレイパー

カスタムAPIスクレイパー

プラグ可能(Brave API / SerpAPI / ブラウザフォールバック)

キャッシュ

なし

追加コスト

内蔵TTLディスクキャッシュ(サブ秒の繰り返しクエリ)

画像品質

通常、低解像度のUIサムネイルを取得

生のページ画像のみ

マスターCDNデキャップ(最大2500px以上)

AIエージェントネイティブ

手動ラッパーが必要

REST APIのみ

ネイティブFastMCPツールプロトコル + Dockerサポート


4. 検索バックエンドと設定

Promas は、設定やAPIキーを一切必要とせず、100%そのまま動作します。

検索ディスカバリーの仕組み:

  1. 無料 / デフォルト(設定不要): Promas は内蔵の Playwright Stealth ブラウザエンジンを使用して、Bing と DuckDuckGo 経由で eコマース候補を無料で発見します。

  2. Brave Search API(本番環境推奨): BRAVE_API_KEY が設定されている場合、Promas は公式で ToS 準拠のサブ秒 API ディスカバリーに切り替えます。

  3. SerpAPI(代替): SERPAPI_API_KEY が設定されている場合、Promas は SerpAPI 経由で Google 検索をクエリします。

    • 無料キーを取得(月100回の無料クエリ): SerpAPI

環境変数リファレンス:

変数

デフォルト

説明

BRAVE_API_KEY

なし

Brave Search 用のオプションAPIキー

SERPAPI_API_KEY

なし

SerpAPI Google Search 用のオプションAPIキー

PROMAS_GLOBAL_CONCURRENCY

3

同時ブラウザコンテキストの最大数

PROMAS_PER_DOMAIN_CONCURRENCY

1

対象ストアごとの同時リクエストの最大数

PROMAS_DOMAIN_DELAY_SECONDS

0.5

同じドメインへのリクエスト間の丁寧な遅延

PROMAS_CACHE_ENABLED

True

ディスクキャッシュの切り替え(True/False)

PROMAS_CACHE_TTL_SECONDS

86400 (24h)

キャッシュの有効期限(秒)

PROMAS_ENABLE_IMAGE_VERIFICATION

True

非同期HTTP MIME&ピクセル寸法チェック

PROMAS_ENABLE_PERCEPTUAL_DEDUP

True

pHashによるほぼ重複したクロップの除去

PROMAS_PHASH_HAMMING_THRESHOLD

4

pHash重複排除の感度しきい値


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 は、AIエージェント向けに専用の細粒度ツールを公開します:

ツール

目的

説明

fetch_product_images

フルパイプライン

クエリ文字列またはURL -> 自動ディスカバリー -> 並列スクレイピング -> HTTP検証 -> pHash重複排除 -> マスター写真リンク。

search_product_urls

ディスカバリーのみ

クエリ文字列 -> eコマース製品ページの候補を高速ランキング(画像をスクレイピングせずにURLを返す)。

scrape_single_url

抽出のみ

特定の直接URL -> そのページからタイトルとマスター画像アセットを厳密に抽出。


7. エージェントシステムプロンプトガイドライン

AIエージェントのシステムプロンプトに以下の指示を追加してください:

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コマースプラットフォームや 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)を提供してください。

  • 画像の著作権と帰属: Promas は直接画像 URL を解決して返します。メディアファイルを保存、再ホスト、コピーすることはありません。取得した画像の表示、保存、商用利用はユーザーの責任です。


12. ライセンス

このプロジェクトは MIT License の下でライセンスされています。

Available Tools

4 tools
fetch_product_imagesA

Universally extracts verified, high-resolution product photography and official sources across the web.

USE THIS TOOL WHEN:

  • You need product photos, packshots, visual references, or master CDN assets for any physical item.

  • You want Promas to automatically discover authoritative stores, scrape candidate pages, verify images via HTTP, and deduplicate near-identical photo crops.

EXAMPLE QUERIES:

RETURNS:

  • ProductImageResult containing:

    • status: 'success' or 'error'

    • title: Cleaned product title

    • sources_scraped: List of retail & brand URLs visited

    • images: List of verified master-resolution image URLs (up to 2500px+)

Inputs: query (required), no_cache, max_images, site_filter. Returns: Unified result model returned by Promas.

get_product_images_toolD

Backward-compatible alias for fetch_product_images.

Inputs: query (required), max_images, site_filter. Returns: Unified result model returned by Promas.

scrape_single_urlA

Extracts high-resolution product imagery from a single direct product URL (Extraction only).

USE THIS TOOL WHEN:

  • You already have an exact product URL (from search_product_urls or user input) and want to extract master photos strictly from that page.

  • Uses universal Schema.org JSON-LD, OpenGraph, dynamic JS datasets, DOM selectors, and CDN upscalers.

EXAMPLE CALL:

RETURNS:

  • ProductImageResult containing extracted images and metadata from the specified URL.

Inputs: url (required), no_cache, max_images. Returns: Unified result model returned by Promas.

search_product_urlsA

Discovers and ranks candidate e-commerce product pages for a given query (Discovery only).

USE THIS TOOL WHEN:

  • You want to find authoritative product detail pages (PDPs) across retailers without downloading or scraping images yet.

  • You want to preview which stores/URLs exist for a product before selecting one to scrape.

EXAMPLE CALL:

  • search_product_urls(query="Sony FX3 Cinema Camera", max_urls=3)

  • search_product_urls(query="MacBook Pro M3", site_filter="apple.com")

RETURNS:

  • A list of ranked, direct product destination URLs.

Inputs: query (required), max_urls, site_filter. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    The three primary tools have clearly distinct purposes: fetch_product_images performs full discovery and scraping, search_product_urls only finds URLs, and scrape_single_url extracts images from a provided URL. The fourth tool is explicitly marked as a backward-compatible alias, so no genuine ambiguity exists.

    Naming Consistency4/5

    The main tools follow a verb_noun pattern (fetch_product_images, search_product_urls, scrape_single_url), but the alias get_product_images_tool breaks the pattern by using 'get' and a '_tool' suffix. This is a minor deviation, as the alias is clearly labeled and does not detract from the overall predictability.

    Tool Count5/5

    With only 4 tools, the server is well-scoped. Each core tool serves a distinct stage in the product image retrieval workflow (discovery, extraction, combined pipeline), and the alias is a harmless addition. The count fits comfortably within the ideal range.

    Completeness5/5

    The tool surface completely covers the domain: it offers discovery-only (search_product_urls), extraction-only (scrape_single_url), and a comprehensive pipeline (fetch_product_images). There are no obvious dead ends or missing operations for the stated purpose of retrieving product images.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers