# Taobao MCP Bridge｜让 AI 逛淘宝

**v0.1.0 · 浏览预览版 · 中文教程 + 可运行源码 · MIT**

把电脑上的淘宝访问能力接到支持 Streamable HTTP 的 AI 客户端。AI 可以搜索候选、读详情、看商品图片，再和你一起选。手机里的 AI 也能用：执行发生在你的电脑，不是在手机里偷偷装一个淘宝机器人。

本项目是个人维护的第三方桥接，**不是淘宝、支付宝或 OpenCLI 官方产品，也不提供内测资格、账号或风控豁免**。

## 两条路线，不要混为一谈

| 路线 | 原理 | 本仓库提供 | 必要条件 |
| --- | --- | --- | --- |
| A：淘宝官方桌面能力 | AI → 鉴权中继 → 桌面淘宝本地 MCP | 官方 MCP 的网络转发及接入教程；官方 Skill 的使用说明 | 客户端确实开放 AI 权限、本地服务可用；工具以实时列表为准 |
| B：OpenCLI → MCP | AI → 本桥接 → OpenCLI → 浏览器扩展 → 已登录网页 | 3 个 MCP 工具、受限浏览工作流、原生商品图回传 | 电脑上的 Node、浏览器、OpenCLI 扩展、淘宝网页登录态 |

**推荐先看 [路线选择与避坑](docs/pitfalls.md)，再选 [A 官方路线](docs/official-route.md) 或 [B OpenCLI 路线](docs/opencli-route.md)。两种模式互斥，不自动降级切换。**

路线 B 不依赖淘宝桌面版的 MCP 或 AI 开关。它仍然需要正常的淘宝网页登录权限；不能用来绕过账号限制或验证。

## 这版能做什么

| 能力 | OpenCLI 公开版 |
| --- | --- |
| 搜索与选品 | 读取当前已加载候选，最多 10 条；由模型比较，非自动刷页 |
| 商品详情 | 标题、店铺、页面显示价格、规格；不保证每种页面都能解析 |
| 真实商品图 | 默认 1 张、最多 3 张原生 MCP 图片；跨域兜底通常只有当前主图 |
| 收藏／购物车 | **按关键词读取已有商品**，不新增、不删除 |
| 规格 | 支持可明确识别的单组规格与数量；复杂规格停止让人选择 |
| 加购／新增收藏 | **没有这两个写入工具** |
| 创建订单／付款／聊天 | **本公开版不提供**；付款实验的边界见 [说明](docs/payment-boundary.md) |

路线 A 为全量官方工具透传，**不受上表的浏览权限约束**。有连接 Token 的受信任客户端可调用上游实际开放的工具。启动必须显式加 `--allow-official-tools`；不要把它描述成只读沙箱。

## 从零开始：路线 B（Windows PowerShell）

准备 Python 3.10+、Node.js 20.18.1+、Git。源码与离线测试在 Windows/Python 3.14 验证；其他系统尚未做真实淘宝验收。安装依赖会下载第三方代码，请先审阅来源。

```powershell
git clone https://github.com/AZHi-xinxin/taobao-mcp-bridge.git
cd taobao-mcp-bridge
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
npm.cmd ci --prefix .\runtime --ignore-scripts
```

OpenCLI 固定为 **1.8.7**，npm 依赖树由 `runtime/package-lock.json` 锁定；第三方代码不在本仓库打包。安装时不执行 npm 生命周期脚本，仅使用其已发布的核心浏览器命令；不承诺自动安装其他站点适配器。浏览器扩展仍需单独安装、记录版本。

1. 按 [OpenCLI 项目指引](https://github.com/jackwener/opencli/tree/v1.8.7) 安装浏览器扩展，只在你要让 AI 使用的浏览器配置文件里启用。
2. 在该浏览器里人工登录淘宝。浏览器登录和桌面淘宝登录不是同一个环境。
3. 检查连接，再生成一个**不会打印到终端**的私有 Token：

```powershell
node .\runtime\node_modules\@jackwener\opencli\dist\src\main.js doctor
.\.venv\Scripts\python.exe .\create_token.py --path "$env:LOCALAPPDATA\TaobaoMCPBridge\access.token"
```

4. 启动（先不设置开机自启，便于看报错）：

```powershell
.\.venv\Scripts\python.exe .\taobao_mcp_relay.py --mode web --token-file "$env:LOCALAPPDATA\TaobaoMCPBridge\access.token"
```

5. AI 客户端添加 MCP：名称自定，如 `Taobao`；传输选 **Streamable HTTP**，不是旧式 SSE；地址 `http://127.0.0.1:18126/mcp`；请求头 `Authorization: Bearer <私密文件里的实际 Token>`。

不要把尖括号示例原样填入。用本机文本编辑器打开 Token 文件，仅复制到客户端的私密请求头，不发给模型、群聊、Issue 或 Git。**手机不能使用这个 127.0.0.1 地址**，见 [手机连接](docs/network.md)。

刷新工具后，路线 B 应出现：`taobao_shopping_guide`、`taobao_web`、`taobao_job`。无需新增很多 MCP 名称。

## 给 AI 的一句话测试

> 先读 taobao_shopping_guide。请搜索“指甲剪”，从当前结果里挑一件并读详情，再用 images 给我看一张商品图。每个动作完成后再做下一步；不加购、不收藏、不下单。遇登录或验证码就停止。

技术调用顺序和 JSON 示例在 [工具手册](docs/tools.md)。模型看图需要**客户端转交 MCP image 块 + 模型支持视觉**；有链接、看到“返回成功”不等于已经看过图片。

## 教程目录

- [A：淘宝官方 Skill / MCP 与中继](docs/official-route.md)
- [B：OpenCLI 安装、原理、升级边界](docs/opencli-route.md)
- [工具调用：job、详情、规格、图片](docs/tools.md)
- [手机、Tailscale、Token、持续运行](docs/network.md)
- [实测记录与避坑：掉登录、白名单、遮挡、多图](docs/pitfalls.md)
- [付款为什么没有随浏览版一起开放](docs/payment-boundary.md)
- [安全与隐私](SECURITY.md) · [测试与验收](TESTING.md) · [第三方说明](THIRD_PARTY_NOTICES.md)
- [给 AI 读的说明书](docs/ai-guide.md) · [可转发的小红书介绍](docs/xiaohongshu.md)

## 版本与维护

网页、官方客户端、扩展都会变化。本版是受限预览，不是“安装一次永久可用”。旧私有部署的成功记录≠这个公共入口已经在所有手机前端完成验收；详见 [测试与验收](TESTING.md)。

反馈时请附版本、模式、操作顺序和脱敏错误码，不要附登录 Cookie、Token、完整私人页面、地址、订单号或支付链接。MIT 仅覆盖本仓库自写代码；平台规则与第三方许可仍适用。