内容
# 拼多多商家后台 MCP
面向 Agent 的本地、只读 MCP Server。它通过专用的可见 Chrome Profile 保存拼多多商家后台登录态，并提供订单与售后查询工具。
> 本项目不是拼多多官方产品。仅用于店铺主体授权的低频只读操作。验证码、短信、扫码、身份核验和风控必须由用户手工完成；项目不会绕过安全措施，也不会调用商家后台未公开接口。
## v1 边界
- 仅支持 Windows 10/11、Node.js 24、Google Chrome 和国内 `mms.pinduoduo.com`。
- 每位成员在自己的电脑运行；一次只连接一个 Agent 客户端。
- 支持多个店铺，但每个店铺使用完全独立的浏览器 Profile，同一时间只激活一个店铺。
- 只读取页面已显示的信息，不点击“解密、查看完整手机号”等额外披露按钮。
- 不提供发货、退款、改价、上下架、聊天、任意点击、脚本执行、Cookie 导出或文件下载。
## 安装
```powershell
pnpm install
pnpm build
node dist/cli.js doctor
```
默认状态目录为 `%LOCALAPPDATA%\pdd-mcp`。可在 MCP 客户端配置中通过 `PDD_MCP_HOME` 覆盖；该目录包含可用于登录店铺的浏览器状态，不要提交到 Git、云盘或共享目录。
通用 stdio 配置示例：
```json
{
"mcpServers": {
"pdd-merchant": {
"command": "node",
"args": [
"C:\\absolute\\path\\to\\pdd-merchant-mcp\\dist\\cli.js",
"serve"
],
"env": {
"PDD_MCP_HOME": "C:\\Users\\you\\AppData\\Local\\pdd-mcp"
}
}
}
}
```
stdout 专用于 MCP JSON-RPC；运行日志只写 stderr，而且不会记录工具输入、订单结果、Cookie、Token、验证码或页面截图。
## 首次使用
推荐让 Agent 按以下顺序调用：
1. `pdd.profiles.create` 创建店铺 Profile。
2. `pdd.profile.use` 激活 Profile 并打开专用 Chrome。
3. `pdd.session.login_open` 打开官方登录页。
4. 用户在 Chrome 中手工完成扫码、短信或验证。
5. `pdd.session.status` 确认状态为 `authenticated`，并确认返回的 Profile 包含可信的稳定 `shopId`。
6. 调用订单或售后查询工具。
活动 Profile 不跨 MCP 进程保存；MCP 重启后需要再次调用 `pdd.profile.use`，但只要拼多多没有使会话过期，就不需要重新登录。
订单和售后查询必须绑定可信的稳定 `shopId`。服务只从已校准的店铺身份区域读取该标识，不会从买家留言、订单正文等普通页面文本猜测店铺身份；首次绑定后，后续激活只校验而不会自动覆盖。如果旧 Profile 尚未绑定 `shopId`，请重新调用 `pdd.profile.use`。可信区域仍无法提供稳定标识时，服务会以 `SHOP_MISMATCH` 安全停止，不会继续查询。
删除 Profile 只允许通过本地 CLI，并且必须明确确认：
```powershell
node dist/cli.js profile remove <profileId> --confirm
```
## MCP 工具
| 工具 | 用途 |
| --- | --- |
| `pdd.profiles.create` | 创建隔离的本地浏览器 Profile |
| `pdd.profiles.list` | 列出 Profile 和最后已知状态 |
| `pdd.profile.use` | 切换活动店铺 |
| `pdd.session.status` | 实时检查登录、验证和风控状态 |
| `pdd.session.login_open` | 打开官方登录页供用户手工登录 |
| `pdd.orders.list` | 按日期、状态、订单号分页查询订单 |
| `pdd.orders.get` | 获取页面当前已显示的订单详情 |
| `pdd.after_sales.list` | 分页查询售后记录 |
| `pdd.after_sales.get` | 获取页面当前已显示的售后详情 |
订单与售后详情可能包含页面当前可见的姓名、电话和地址，并以 `containsSensitiveData: true` 标记。使用云端 Agent 前，应确认组织的数据处理与隐私政策允许发送这些字段。
### 列表分页与截断
`pdd.orders.list` 和 `pdd.after_sales.list` 返回的 `pagination.nextCursor` 是不透明的 v2 游标。推荐把它原样用于下一次调用，不要解析或修改：
```json
{
"cursor": "<上一页返回的 pagination.nextCursor>"
}
```
- 只传 `cursor` 即可继续同一次查询；日期、状态、订单号和 `limit` 会从游标恢复。
- 如同时显式传入筛选条件，这些条件必须与原查询完全一致，否则返回 `VALIDATION_FAILED`。
- 游标绑定具体工具、查询条件、活动 Profile 和稳定 `shopId`，不能跨订单/售后或跨店铺使用。
- 游标由当前 MCP 进程签发并校验；MCP 重启后旧游标失效，需要从首次查询重新开始。
- `limit` 表示本次最多返回的记录数（默认 20，最大 50），不会强制修改拼多多网页自身的每页条数。即使同一网页还有未返回记录，也会通过下一游标从正确行继续，不会跳过。
- 正常达到 `limit` 或网页翻页不代表数据被裁剪，`truncated` 不会因此设为 `true`。只有字段超过 16 KiB 或响应接近 512 KiB 安全预算而发生裁剪时，才会返回 `truncated: true`；若仍有未消费记录，会尽可能同时返回续页游标。
## 错误与人工接管
以下情况会停止自动化，不会自动重试：
- 登录过期或尚未登录：`AUTH_REQUIRED`
- 短信、滑块、扫码或身份核验：`USER_VERIFICATION_REQUIRED`
- 403、429 或风险提示：`PDD_RISK_CONTROL`
- 页面结构不再符合已验证地标：`PAGE_CHANGED`
- 登录店铺与 Profile 绑定身份不同：`SHOP_MISMATCH`
- 另一个客户端占用同一 Profile：`PROFILE_IN_USE`
- 单次浏览器操作超过 45 秒：`TIMEOUT`，并返回 `actionRequired.type: "reopen_browser"`
遇到 `reopen_browser` 时，超时的 Chrome context 已被关闭以终止卡住的页面操作。请重新调用 `pdd.profile.use` 打开当前 Profile，再重试原查询；不要重复提交仍在等待的旧调用。
## 开发与验证
```powershell
pnpm typecheck
pnpm test
pnpm build
```
普通测试只使用合成页面和临时 Profile，不连接真实拼多多。真实只读冒烟测试必须人工启用：
```powershell
$env:PDD_MCP_LIVE_TEST = "1"
$env:PDD_MCP_LIVE_PROFILE = "已手工登录的_profile_id"
pnpm test:live
```
首次用于真实店铺前，必须按 [MMS 页面适配校准](docs/selector-calibration.md) 在最小权限测试店铺完成一次只读校准。页面路由、地标和状态映射集中在 MMS 适配层；拼多多页面更新后，应重新校准并补充合成 fixture，不得通过模糊坐标点击来掩盖 `PAGE_CHANGED`。
## 后续官方 API 适配
拼多多开放平台提供面向商家自研系统的官方能力。v1 只实现浏览器 `OrderSource` / `AfterSaleSource`，但保留统一接口和 `source: "browser"` 字段，以便后续取得 OAuth 授权后增加 API 优先实现。
