# airus-mcp

1688 / OZON 电商爬虫的 **MCP Server**。把选品爬虫暴露为标准 MCP 工具，供 Claude 桌面版、Cowork、Claude Code 等任何 MCP 宿主直接调用——**agent 当大脑，爬虫当手**。

由 [AIRus](https://github.com/Eureka-Zhang/AIRus) 项目的爬虫核心迁移而来，剥离了飞书机器人层与自建 WebSearch 层（宿主 agent 的原生联网能力已覆盖），并修复了迁移前的若干已知 bug。

## 架构

```
MCP 宿主（Claude Desktop / Cowork / Claude Code …）
    │  stdio
    ▼
mcp_server.py            ← MCP 工具入口（本仓库）
    │  HTTP :8765
    ▼
web_app.py               ← 任务队列 + 爬虫调度（单账号串行）
    │  subprocess
    ├── scrape_1688.py   ← 1688 关键词搜索 / 以图搜款 / 店铺联系方式（需登录态）
    └── crawl_ozon.py    ← OZON 关键词搜索（需俄罗斯 IP）
         ▲
         └── Chrome CDP :9222（真实 Chrome，登录态 / 过反爬的根基）
```

## MCP 工具（7 个）

| 工具 | 说明 |
|---|---|
| `crawler_browser_status` | 检查 Chrome CDP 与队列状态，是否需要人工登录/验证码 |
| `crawler_create_job` | 创建异步采集任务（1688 / ozon） |
| `crawler_image_search` | 1688 以图搜款：传本地图片路径，自动上传并建任务 |
| `crawler_wait_job` | **阻塞等待任务完成**（推荐，代替客户端轮询） |
| `crawler_get_job` | 查询任务状态与结果（含中文字段的 `bitable_rows`） |
| `crawler_list_jobs` | 列出近期任务 |
| `crawler_cancel_job` | 取消排队中的任务 |

## 快速开始

### 1. 启动爬虫 Worker（Mac 采集机）

```bash
./start_mac_worker.sh
```

脚本会自动创建 venv、装依赖、拉起 Chrome CDP (:9222) 和 web_app (:8765)。
首次使用请在弹出的 Chrome 窗口里手动登录 1688（登录态保存在 `~/.1688-tool-chrome`）。

### 2. 注册 MCP Server

Claude Desktop 的 `claude_desktop_config.json`（或任何 MCP 宿主的等价配置）：

```json
{
  "mcpServers": {
    "airus-crawler": {
      "command": "/path/to/airus-mcp/.venv/bin/python",
      "args": ["/path/to/airus-mcp/mcp_server.py"],
      "env": {
        "CRAWLER_BASE_URL": "http://127.0.0.1:8765"
      }
    }
  }
}
```

### 3. 对话示例

```text
帮我在 1688 搜「蓝牙耳机」前 2 页，采集供应商联系方式
帮我爬 OZON 上「механическая клавиатура」的第 1 页
用这张图在 1688 找同款：/Users/me/Desktop/product.jpg
```

## 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `CRAWLER_BASE_URL` | `http://127.0.0.1:8765` | web_app 地址（MCP 端） |
| `WEB_HOST` / `WEB_PORT` | `127.0.0.1` / `8765` | web_app 监听地址（Worker 端） |
| `RUB_CNY_RATE` | `0.078` | 卢布→人民币汇率（OZON 价格换算） |
| `CDP_PORT` | `9222` | Chrome CDP 端口 |
| `COMPANY_WORKER_URL` | — | 设置后 web_app 变为到远端 Worker 的反向代理 |
| `CRAWLER_WAIT_POLL_INTERVAL` | `10` | `crawler_wait_job` 轮询间隔（秒） |

## 注意事项

- **1688**：必须已登录（诚信通账号）；出现滑块/验证码时 `browser_status.needs_action` 会提示，请到采集机 Chrome 窗口人工完成。
- **OZON**：采集机必须是俄罗斯出口 IP；无需登录。
- 任务队列为单账号串行（物理上只有一个 Chrome），并发请求会自动排队。
- 队列当前为内存态，web_app 重启后任务与结果丢失（结果同时落盘在 `scrape_result/` 的 CSV/JSONL 里）。

## 相对原项目（AIRus）的变更

- 删除：飞书机器人层（Node/TS）、webfetch 自建搜索抓取、market_research 双市场调研、同步阻塞的 `crawler_search` 工具
- 新增：`crawler_wait_job`（阻塞等待）、`crawler_image_search`（本地图片以图搜款）
- 修复：联系方式按下标兜底导致串店、供应商电话列被覆盖丢失、`rating`/`review_count` 字段映射重复定义、汇率硬编码（改为 `RUB_CNY_RATE`）、多处乱码提示文案、登录误报 marker、删除 3 个遗留死函数