Metadata-Version: 2.5
Name: cn-shop-mcp
Version: 0.1.0
Summary: Compliant product search & price comparison MCP server for Taobao/JD/PDD
Author: wangkehao
License-Expression: MIT
License-File: LICENSE
Keywords: cps,jd,mcp,pinduoduo,price-comparison,shopping,taobao
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=2.3.0
Requires-Dist: python-dotenv>=1.2.4
Description-Content-Type: text/markdown

# cn-shop-mcp

合规的淘宝 / 京东 / 拼多多商品搜索与跨平台比价 MCP Server（本机 stdio，Python）。

- **合规**：只调用三家官方开放平台 API（淘宝联盟 / 京东联盟 / 多多进宝），不做页面抓取、不做 UI 自动化。
- **能力**：搜索、比价、转链（淘口令 / 拼多多短链 / 京东短链）、"好价合集"群发文案；下单/付款仍在各平台 App 完成。
- **工具**：共 11 个，见下方[工具一览](#工具一览)。

## 安装

### 方式一：uvx（推荐，无需克隆代码）

```bash
uvx cn-shop-mcp
```

MCP 客户端里配置（以 opencode 为例，完整示例见[客户端配置](#客户端配置)）：

```json
"cn-shop-mcp": {
  "type": "local",
  "command": ["uvx", "cn-shop-mcp"],
  "environment": { "CN_SHOP_MCP_ENV_FILE": "D:/path/to/你的/.env" }
}
```

> `.env` 查找顺序：① 环境变量 `CN_SHOP_MCP_ENV_FILE` 指定路径 → ② 当前工作目录（含上级）→ ③ 包目录相对（源码运行时自动生效）。

### 方式二：源码运行（开发用）

```bash
uv sync
copy .env.example .env    # Windows（macOS/Linux: cp .env.example .env）
# 编辑 .env，按下方指南填入三家凭证
```

验证：`uv run python scripts/live_smoke.py 电脑桌`（未配置任何平台时退出码为 2 并提示缺失项）。

## 凭证配置表

| 变量 | 平台 | 说明 |
|---|---|---|
| `TB_APP_KEY` / `TB_APP_SECRET` | 淘宝 | 淘宝客应用（open.taobao.com）的 AppKey / AppSecret |
| `TB_ADZONE_ID` | 淘宝 | 淘宝联盟推广位 ID（adzone_id，`mm_xxx_xxx_数字` 中的最后一段数字） |
| `JD_APP_KEY` / `JD_APP_SECRET` | 京东 | 京东联盟应用（jos.jd.com）的 AppKey / AppSecret |
| `JD_SEARCH_MODE` | 京东 | `jingfen`（频道精选，免权限、无关键词，默认）或 `keyword`（关键词搜索，需接口权限） |
| `PDD_CLIENT_ID` / `PDD_CLIENT_SECRET` | 拼多多 | 多多客应用（open.pinduoduo.com）凭证 |
| `PDD_PID` | 拼多多 | 多多进宝推广位 PID |
| `SHOP_MCP_QPS` | 全部 | 可选，每平台每秒请求上限，默认 1 |
| `CN_SHOP_MCP_ENV_FILE` | 全部 | 可选，显式指定 `.env` 文件路径（uvx 安装运行时推荐配置） |

任一家未配置：该平台工具返回 `degraded: not_configured` 与修复提示，其余平台不受影响。

## 三家账号注册与开通

### 淘宝联盟
1. 打开 <https://pub.alimama.com>（用淘宝账号登录），完成实名认证与媒体备案；
2. 创建推广位，得到推广位 ID（`adzone_id`）；
3. 打开 <https://open.taobao.com> 创建应用，申请"淘宝客【推广者】"权限（物料搜索接口 `taobao.tbk.dg.material.optional`），获得 AppKey / AppSecret；
4. 填入 `.env`：`TB_APP_KEY` / `TB_APP_SECRET` / `TB_ADZONE_ID`。

### 京东联盟
1. 打开 <https://union.jd.com>（用京东账号登录），完成实名认证；
2. 在 <https://jos.jd.com>（宙斯开发者中心）/ 联盟开放平台创建应用，获得 AppKey / AppSecret；
3. 关键词搜索接口（`jd.union.open.goods.query`）可能需要为应用申请权限；**未获批前**：
   在 `.env` 设 `JD_SEARCH_MODE=jingfen`（现为默认），用"京粉精选"频道先跑通（无关键词，返回频道精选商品）；
4. 填入 `.env`：`JD_APP_KEY` / `JD_APP_SECRET`。

### 多多进宝（拼多多）
1. 打开 <https://jinbao.pinduoduo.com>，手机号注册并实名；
2. 创建推广位，得到 PID；
3. 到 <https://open.pinduoduo.com> 创建（多多客角色）应用，获得 `client_id` / `client_secret`；
4. 按官方指引用 `pid` + `custom_parameters` 完成**搜索接口备案**（未备案会报 `60001`）；
5. 填入 `.env`：`PDD_CLIENT_ID` / `PDD_CLIENT_SECRET` / `PDD_PID`。

## 客户端配置

### opencode

写入 `~/.config/opencode/opencode.json`（或项目根 `opencode.json`）：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cn-shop-mcp": {
      "type": "local",
      "command": ["uvx", "cn-shop-mcp"],
      "environment": { "CN_SHOP_MCP_ENV_FILE": "D:/work/cn-shop-mcp/.env" },
      "enabled": true
    }
  }
}
```

> 源码方式运行的话，command 换成 `["uv", "--directory", "你的仓库路径", "run", "cn-shop-mcp"]` 即可。

验证：`opencode mcp list` 应出现 `cn-shop-mcp`。

### Claude Desktop / Cherry Studio（`mcpServers` 形状）

```json
{
  "mcpServers": {
    "cn-shop-mcp": {
      "command": "uvx",
      "args": ["cn-shop-mcp"],
      "env": { "CN_SHOP_MCP_ENV_FILE": "D:/path/to/你的/.env" }
    }
  }
}
```

## 工具一览

| 工具 | 参数 | 说明 |
|---|---|---|
| `search_taobao` | keyword, price_min, price_max, coupon_only, sort, page, page_size | 淘宝联盟物料搜索 |
| `search_jd` | 同上 | 京东联盟搜索（或 jingfen 频道） |
| `search_pdd` | 同上 | 多多进宝商品搜索 |
| `compare_prices` | keyword, price_min, price_max, top_n_per_platform | 三平台并行搜索 + 启发式同款分桶（含置信度与价差） |
| `platform_status` | 无 | 各家凭证与最近一次调用状态（不回显密钥） |
| `create_taobao_tpwd` | url, text? | 淘口令生成（手机复制打开淘宝领券下单） |
| `taobao_promotions` | kind（大额店铺券/天猫店铺券/券券补/有价券）, page | 联盟『权益物料精选』神券（含券面额、领券链接、推荐商品） |
| `create_jd_short_link` | url | 京东转链：商品链接 → 推广短链（导购媒体走 `byunionid`，需 .env 配 `JD_UNION_ID`；网站/APP 走 `common.get`，配 `JD_SITE_ID`）|
| `create_pdd_link` | goods_sign（即搜索结果的 item_id） | 拼多多转链：→ `p.pinduoduo.com` 短链 |
| `query_jd_orders` | hours?, order_type? | 查自己的京东联盟订单（自动按1小时窗口分段；1=下单 2=完成 3=结算）|
| `build_deals_digest` | keyword, platforms?, n_per_platform?, price_max? | 一键生成"好价合集"群发文案（自动配口令/短链）|

`sort`：`relevance`（默认）/ `sales_desc` / `price_asc` / `price_desc` / `commission_desc`。
价格筛选（`price_min` / `price_max`）按**券后价**（有券可用时）判断；`coupon_only` 仅保留有券商品。京东/拼多多为页内本地筛选。
示例对话："帮我搜一下 80cm 宽的电脑桌，对比淘宝京东拼多多的价格。"

## 排障

| 现象 | 处理 |
|---|---|
| `degraded: not_configured` | 按 `.env.example` 补全对应平台凭证 |
| `bad_response`（非 JSON） | 可能被风控拦截，稍后重试 |
| 淘宝 code 2 / 4 | 检查 `TB_ADZONE_ID` 是否正确、有效，AppKey 是否匹配 |
| 淘宝 code 1911 | 该 AppKey 无对应物料场景权限（本工具使用默认物料 2836） |
| 京东 403 | 为应用申请该接口权限，或设 `JD_SEARCH_MODE=jingfen` |
| 京东 15 / 88 | 接口未开通：到京东开放平台『控制中心→应用管理→接口管理』申请该接口权限 |
| 京东 2000 | 未实名或超出当日调用额度：到 union.jd.com 完成实名/申请提额 |
| 拼多多 60001 | 到多多进宝完成 pid 备案（pid + custom_parameters） |
| 排序不符预期 | 京东/拼多多为页内本地排序；淘宝价格排序为本地、销量/佣金为原生 |

## 局限（如实说明）

- 跨平台没有互通商品 ID：`compare_prices` 的同款分组是启发式线索（给出高/中/低置信度），**不保证同款**，请以人工确认为准。
- 搜索范围为联盟物料库：未参加联盟推广计划的商品不会出现在结果里。
- 拼多多进宝库不覆盖 3C 大件/核心配件（实测返回 0 条、非报错）：`手机`、`平板`、`固态硬盘`、`内存条`、`显卡`、`CPU`、`主板`、`显示器`、`键鼠`、`机箱`、`整机` 等；周边配件正常（移动硬盘/U盘/路由器/耳机/充电宝/散热器/数据线等）。此类商品请用淘宝搜索或各平台网页/APP 查价。
- 京东 `jingfen` 模式不支持关键词（返回频道精选），且会标注 degraded 提示。
- 只读：下单/付款请到各平台 App 完成。

## 开发

```bash
uv run pytest                      # 全量离线测试
uv run python scripts/live_smoke.py 关键词   # 手动冒烟（需真实凭证）
```
