# smart-crawler

> Agent 时代电商情报采集引擎。覆盖 62 个跨境电商站点：Walmart / Target / AliExpress / eBay / Etsy / Vidaxl / Songmics / Costway / Homary / Idealo / Otto / BOL / CDiscount / IKEA / Crate&Barrel / WestElm / Wayfair / Allegro / Article / Flexispot / VonHaus / Yaheetech / BCP / Overstock / Woltu —— 持续采集结构化竞品商品 / 价格 / 促销、消费者口碑(VOC)评论 + NLP 情感分析、Google Shopping 竞争格局、Reddit 社媒讨论。

smart-crawler 把"网页采集"做成 AI Agent 可直接调用的数据服务：自适应抓取、
抗封锁、可回溯。Agent 不需要自己写爬虫，直接调用结构化的竞品情报能力。

## Agent 接入（推荐 MCP）

- [MCP 服务器](https://smartcrawler.io/mcp): streamable-http 传输，17 个工具
- [发现清单](https://smartcrawler.io/.well-known/mcp.json): MCP 服务器元数据
- [能力总览](https://smartcrawler.io/agents.json): 工具 + REST 端点 + 接入方式

鉴权: MCP 与 REST 都用 API Key —— 请求头 `Authorization: Bearer sck_...`
（MCP）或 `X-API-Key: sck_...`（REST）。密钥在控制台「API 接入」生成。

## REST API（备选）

- [OpenAPI 规格](https://smartcrawler.io/openapi.json): OpenAPI 3.1
- [交互式文档](https://smartcrawler.io/docs): Swagger UI
- 主要端点: `/api/v1/products` `/api/v1/promotions` `/api/v1/site/{site}`

## MCP 工具

- list_data_sources: 列出全部数据源：46 个竞品站 + 评论平台 + Google Shopping
- search_competitor_products: 按品牌/国家/关键词/品类/价格/促销搜索竞品商品
- get_product_detail: 取单个商品完整信息 + 历史价格曲线
- list_promotions: 列出竞品当前促销活动及折扣率
- get_voc_reviews: 取消费者口碑评论 + NLP 情感/分类标注
- voc_summary: 口碑分析汇总：情感分布 + 痛点分类占比
- competitor_landscape: Google Shopping 某关键词下各商家出现占有率
- amazon_voc_report: 按 Amazon ASIN 取评论 + AI 口碑分析（情感/痛点/卖点/Listing 建议）
- fetch_amazon_reviews: 按 Amazon ASIN 取原始评论数组（不分析）
- scrape_url: Agent 推荐：抓单页 → markdown + 结构化，warehouse-first，未命中再 live
- map_site: 列出某已配置站点在仓库中的已知商品 URL
- crawl_site: 验证或触发一个已配置站点的异步整站采集（默认 dry_run）
- extract_structured_data: 把抓取结果按给定 JSON schema 投影为结构化数据
- query_warehouse: 实时抓取前先查仓库已有覆盖，避免重复消耗 credits
- fetch_listing_voc: 按 URL 抓 listing + VOC 原文（美客多 / Lazada / Shopee）
- crawl_custom_source: 通用数据采集：任意 URL → 带 provenance 入指定 dataset，warehouse-first 复用
- query_dataset: 查通用数据集（extracted_records），默认只返 main 质量层

## 覆盖范围

- 品牌: SONGMICS / VASAGLE / FEANDREA / Costway / Homary / Vidaxl / Flexispot / VonHaus
- 站点: 62 个跨境电商站点（独立站 + 主流平台 Walmart/Target/AliExpress/eBay/Etsy），覆盖 US/UK/DE/FR/IT/ES/CA/NL/PL/IE/PT/RO 等 12 国
- 口碑: Trustpilot / Reviews.io / Google Maps 共 21 个评论渠道
- 社媒: Reddit 子系统支持 subreddit 数据抓取 + LLM playbook 生成