Metadata-Version: 2.4
Name: yooztech_mcp_taobao_search
Version: 0.0.1
Summary: MCP server for Taobao search and data scraping
Author: yooztech
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.2.0
Requires-Dist: playwright>=1.40.0
Dynamic: license-file

# yooztech_mcp_taobao_search —— 淘宝搜索采集 MCP 工具

基于 MCP (Model Context Protocol) 的淘宝搜索和商品数据采集工具，自动搜索关键词、提取商品信息并导出为 CSV。

## 功能概述

- `taobao_search(keyword, ...)`: 搜索淘宝关键词，采集商品数据并导出 CSV

## 在 Cursor 中配置

```json
{
  "mcpServers": {
    "yooztech_mcp_taobao_search": {
      "command": "yooztech_mcp_taobao_search",
      "args": []
    }
  }
}
```

或使用 `uvx` 方式：

```json
{
  "mcpServers": {
    "yooztech_mcp_taobao_search": {
      "command": "uvx",
      "args": ["yooztech_mcp_taobao_search"]
    }
  }
}
```

## 工具详解

### taobao_search - 淘宝搜索采集

根据关键词搜索淘宝商品，自动采集商品信息并导出为 CSV 文件。

**参数：**
- `keyword` (必填): 搜索关键词
- `max_items` (可选): 最大采集数量，默认 50，范围 1-200
- `slowly` (可选): 是否慢速操作（推荐），默认 true，避免操作过快
- `output_csv` (可选): CSV 输出路径，默认 `./tmp/taobao_<keyword>_<timestamp>.csv`
- `cdp_endpoint` (可选): Chrome CDP 端点（如 `ws://127.0.0.1:9222`），如果提供则连接到已运行的 Chrome，否则启动新浏览器

**返回：**
- `success`: 是否成功
- `csv_path`: CSV 文件路径
- `total_collected`: 采集到的商品数量
- `items`: 商品数据列表（前 10 条预览）
- `notes`: 提取说明（如有）

**CSV 列：**
- 排位: 商品排名（1-based）
- 标题: 商品标题
- 付款人数: 付款/收货人数
- 链接: 商品详情页链接
- 店铺名: 店铺名称

**使用示例：**

```json
{
  "tool": "taobao_search",
  "args": {
    "keyword": "iPhone 15",
    "max_items": 30,
    "slowly": true
  }
}
```

## 工作原理

1. **打开浏览器**: 使用 Playwright 通过 Chrome DevTools Protocol (CDP) 控制浏览器
   - 可以连接到已运行的 Chrome（通过 `cdp_endpoint` 参数）
   - 或启动新的 headed 浏览器（可见模式）
2. **检测登录**: 访问淘宝首页，检测是否已登录
3. **等待登录**: 如果未登录，提示用户手动登录，等待最多 5 分钟
4. **直接导航**: 构造并导航到搜索结果 URL `https://s.taobao.com/search?page=1&q=<keyword>&tab=all`（不操作搜索框）
5. **采集数据**: 滚动页面加载更多商品，使用 JavaScript 在页面内提取商品信息
6. **去重导出**: 根据商品链接去重，导出为 CSV（UTF-8 BOM，Excel 兼容）

## 注意事项

- **浏览器要求**: 需要 Chrome/Chromium 浏览器
- **首次使用**: 首次运行需要安装浏览器驱动：`playwright install chromium`
- **登录检测**: 工具会自动检测登录状态，未登录时会等待用户手动登录
- **CDP 连接**: 如果 OpenClaw 或其他工具已启动 Chrome，可通过 `cdp_endpoint` 参数连接（如 `ws://127.0.0.1:9222`）
- **页面结构**: 淘宝页面可能 A/B 测试或更新，如果解析失败，可能需要调整选择器
- **慢速模式**: 建议设置 `slowly=true` 避免操作过快被限制

## 依赖

- Python >= 3.10
- mcp >= 1.2.0
- playwright >= 1.40.0

## 安装

```bash
# 安装 Python 依赖
pip install -e .

# 安装浏览器驱动（首次使用必须）
playwright install chromium
```

## 许可证

MIT (见 LICENSE)
