# pinduoduo-mcp

**Windows 本地拼多多 MCP · 0.2.0 只读推荐预览版**

**面向非商业学习、技术研究与交流，禁止商用，非官方 API。** 许可为 [PolyForm Noncommercial 1.0.0](LICENSE)，详见 [中文许可说明](LICENSING.md)。

让支持 MCP 的 AI 客户端根据自然语言需求，在真实页面上搜索商品、核对完整规格及参考价，再给出有依据的选择。例如：“200元以内，安卓通勤用的入耳式耳机，续航优先、兼顾音质。”

MCP 提供网页事实和确定性筛选，需求理解与推荐由 Codex 等客户端完成。服务端不需要额外的模型 API Key；客户端本身需具备模型能力。

## 功能

| 能力 | 行为 |
|---|---|
| 搜索 | 读取正常搜索卡片，按显示价和标题条件筛选，说明未知价格、排除原因及截断 |
| 商品详情 | 读取商品身份、标题、价格条件、属性；可选返回已加载商品主图 |
| 完整规格 | 核对实际规格组、当前选择、唯一 SKU 关联及稳定可见价格 |
| 参考价 | 区分常规、拼单及优惠条件；运费和资格不明时保留未知 |
| 推荐流程 | 提供通用、猫粮、耳机三个模板，供客户端分步比较 |
| 状态与恢复 | 区分当前任务和历史记录；重启后重新搜索建立来源 |

提供10个工具和3个推荐模板，主要支持搜索、商品读取与推荐比较。完整清单及兼容范围见 [CAPABILITIES.md](CAPABILITIES.md)。

## 快速安装

首发环境为 Windows、本机 Chrome 或 Edge、Node.js 22及以上。安装器不安装 Node 或浏览器。

可以克隆本仓库，也可以下载 GitHub 提供的源码 ZIP 并解压。首次安装，在源码目录执行：

```powershell
git clone https://github.com/LUNA70612/pinduoduo-mcp.git
Set-Location '.\pinduoduo-mcp' # 下载 ZIP 时，改为实际解压目录
.\Install.ps1
npm run browser
```

在项目隔离浏览器窗口中人工扫码登录，再合并生成配置：

- Codex：outputs/codex-mcp.generated.toml。
- 使用 mcpServers JSON 的客户端：outputs/mcp-config.generated.json。

保留客户端原有配置和其他 MCP 服务；每次工具调用预留240秒。PowerShell脚本受限时，可执行 npm run setup，再运行 doctor、check、smoke。详细步骤见 [AI-INSTALL.md](AI-INSTALL.md)。

**已有登录浏览器时直接复用。** 新安装默认端口为9222，可配置；已有9335等本机CDP绑定时沿用原端口和profile，按安装说明重新绑定即可。不要为新对话清登录数据、切换 UA、换端口或另建登录环境。

## 在新对话中使用

完成客户端配置并加载MCP服务后，保持项目浏览器打开，新建对话直接说明需求：

> 用拼多多 MCP，找200元以内、安卓通勤用的入耳式耳机。续航优先，兼顾音质，给我2～3个有差异的选择，写明具体规格、参考价、价格条件和未知项。排除明确多人团，不加购、不联系客服、不下单。

客户端应先检查连接，再重新搜索。旧对话的候选及搜索上下文不会自动带入新连接。商品必须从同连接的正常搜索卡片进入，不直接打开旧商品链接。

更多需求示例、结果格式和故障处理见 [USAGE.md](USAGE.md)。不支持 prompts 界面的客户端也能通过 initialize.instructions 和工具说明执行流程。

搜索优先使用“商品类型或明确型号＋必要限定”的短核心词，预算通过price_max筛选；“续航好、音质好”等偏好用于后续比较。pdd_status返回login_status=not_checked，浏览器连接正常不等于已经检查登录。

## 使用边界

- 固定 OpenCLI 2.0.2，默认90秒串行间隔；完整比较可能需要较长时间。
- 最多3组搜索、每组10条、6个不同商品详情和3个商品规格核验；不无限滚动或并发抓取。
- 排除明确多人团，普通拼单保留条件；卡片未声明人数时不能保证没有人数门槛。
- 仅已核验完整规格的价格可作为规格参考价。搜索显示价不代表任意规格或含运费到手价。
- 页面缺少独立音质、续航实测或营养资料时返回未知，不以标题、销量或广告证明质量。
- 缺安全入口、选项禁用、身份或价格不一致时明确停止。仅使用已识别且只展开规格的入口，停在“确定”前。
- 登录、验证码由本人处理；遇验证、繁忙或连接异常停止，不绕过平台限制。
- 默认写权限关闭；不加购、不发送客服消息、不下单、不结算、不支付。

## 兼容性

已在 Windows + Chrome 环境验证搜索、详情、规格、参考价及 Codex 接入流程。兼容范围见 [CAPABILITIES.md](CAPABILITIES.md)，测试方法见 [TESTING.md](TESTING.md)。

## 开发与反馈

```powershell
npm test
npm run check
npm run smoke
```

- [开发说明](DEV.md)：架构、协议、页面读取和验证要求。
- [贡献规范](CONTRIBUTING.md)：修改流程、代码风格及问题反馈。
- [测试说明](TESTING.md)：验证层级和发布门禁。
- [变更记录](CHANGELOG.md)：版本和交付范围。

反馈请提供版本、输入摘要、状态及脱敏证据，不提交Cookie、浏览器profile、个人配置、账号资料或完整聊天记录。

## 许可

本项目采用 [PolyForm Noncommercial 1.0.0](LICENSE)，用于非商业学习、研究和技术交流，不授予商业使用许可。分发时请保留许可和第三方声明，详见 [中文许可说明](LICENSING.md) 与 [第三方声明](THIRD-PARTY-NOTICES.md)。