Promas
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 --> Return3. 왜 Promas인가? (비교)
기능 | 원시 스크립트 ( | 유료 API ( | 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% 즉시 작동합니다.
검색 디스커버리 작동 방식:
무료 / 기본 (설정 불필요): Promas는 내장된 Playwright Stealth 브라우저 엔진을 사용하여 Bing 및 DuckDuckGo를 통해 전자상거래 후보를 무료로 발견합니다.
Brave Search API (프로덕션 권장):
BRAVE_API_KEY가 설정되면 Promas는 공식적이고 ToS를 준수하는 서브초 API 디스커버리로 전환합니다.무료 키 받기 (월 2,000회 무료 쿼리): Brave Search API
SerpAPI (대안):
SERPAPI_API_KEY가 설정되면 Promas는 SerpAPI를 통해 Google Search를 쿼리합니다.무료 키 받기 (월 100회 무료 쿼리): SerpAPI
환경 변수 참조:
변수 | 기본값 | 설명 |
| 없음 | Brave Search용 선택적 API 키 |
| 없음 | SerpAPI Google Search용 선택적 API 키 |
|
| 최대 동시 브라우저 컨텍스트 수 |
|
| 대상 스토어당 최대 동시 요청 수 |
|
| 동일 도메인에 대한 요청 간 정중한 지연 |
|
| 디스크 캐싱 토글 ( |
|
| 캐시 만료 시간 (초) |
|
| 비동기 HTTP MIME 및 픽셀 크기 확인 |
|
| pHash 근사 중복 크롭 제거 |
|
| 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-verifyB. FastMCP 서버
독립형 MCP 서버 실행:
promas-mcpC. 에이전트 통합 (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 에이전트에게 전용 세분화 도구를 제공합니다:
도구 | 목적 | 설명 |
| 전체 파이프라인 | 쿼리 문자열 또는 URL -> 자동 디스커버리 -> 병렬 스크래핑 -> HTTP 검증 -> pHash 중복 제거 -> 마스터 사진 링크. |
| 디스커버리 전용 | 쿼리 문자열 -> 전자상거래 제품 페이지 후보의 빠른 순위 (이미지 스크래핑 없이 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. ``) 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. 기여
기여는 언제나 환영합니다! 새로운 전자상거래 플랫폼 또는 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-integration11. 법적 및 윤리적 사용
공개 액세스 전용: Promas는 공개적으로 접근 가능한 웹 페이지만 액세스합니다. 인증, 페이월 또는 개인 로그인을 우회하지 않습니다.
서비스 약관: 자동 액세스는 개별 사이트의 서비스 약관의 적용을 받을 수 있습니다. 대규모 스크래핑 전에 항상 대상 도메인의 ToS 및 로봇 정책을 검토하거나, ToS를 준수하는 디스커버리를 위해 공식 검색 API 키 (
BRAVE_API_KEY/SERPAPI_API_KEY)를 제공하세요.이미지 저작권 및 출처 표시: Promas는 직접 이미지 URL을 해석하고 반환합니다. 미디어 파일을 저장, 재호스팅 또는 복사하지 않습니다. 검색된 이미지의 다운스트림 표시, 저장 또는 상업적 사용은 사용자의 책임입니다.
12. 라이선스
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.
Available Tools
4 toolsfetch_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:
fetch_product_images(query="Sony FX3 Cinema Camera", max_images=5)
fetch_product_images(query="Nike Air Jordan 1", site_filter="nike.com")
fetch_product_images(query="https://www.target.com/p/apple-iphone-16-pro/-/A-93597960")
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:
scrape_single_url(url="https://www.apple.com/iphone-16-pro/")
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
Scored across 4 tools
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.
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.
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.
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
Related MCP Connectors
Live product search for AI agents across Shopify merchants and major retailers.
The E-commerce Marketplace For Every AI Agent. A Governed Catalog Of 600M+ US Products, Plus Four Agent Ready Capabilities Search, Price Comparison, Product-Vs-Product, And Detailed Q&A.
AI-agent product catalog: search, lookup & purchase routing over verified merchant data.
Product discovery for AI agents: ranked products and bundles from the open merchant web.
Related MCP Servers
- AlicenseAqualityDmaintenanceKlarna-style product discovery for AI shopping agents. Makes product catalogs machine-readable so AI agents can search, compare, and purchase products programmatically.6MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to browse product catalogs, search products with filters, and initiate checkouts, generating order summaries and checkout URLs.-

Periskop MCP Serverofficial
AlicenseNot gradedqualityDmaintenanceEnables AI agents to perform product discovery from natural language shopping intents, returning ranked products with merchant links without completing checkout.MIT- AlicenseNot gradedqualityBmaintenanceEnables agents to perform structured shopping actions and retrieve targeted product images for visual comparison, matching, and aesthetic recommendations.MIT