# PDD Shopping MCP

MCP server for Claude Code that enables searching, normalizing, and signal-analyzing products on Pinduoduo (拼多多).

## What it does

Write in Claude Code:
> "Find Ray-Ban Meta smart glasses on Pinduoduo. Compare options and warn me about fake risk."

Claude uses these MCP tools to fetch structured product data with pre-computed fraud signals, then does its own reasoning and recommendations.

## Data Sources

| Provider | Status | Notes |
|---|---|---|
| `mock` | ✅ Always works | Dev/testing. Three Ray-Ban Meta scenarios (replica, suspicious, potentially genuine). |
| `h5` | ⚠️ Requires login cookies | Playwright scraping of mobile.yangkeduo.com. Requires `PDD_H5_COOKIES_JSON`. |
| `official` | 🔲 Skeleton | PDD Open Platform / DDK API. Set `PDD_PROVIDER=official` with credentials. |

**Important:** All `mobile.yangkeduo.com` pages require login — there is no guest mode. The H5 adapter requires valid session cookies via `PDD_H5_COOKIES_JSON`. Without cookies it returns `NEED_AUTH` and falls back to mock data.

**Note on H5 scraping:** Scraping PDD may violate their Terms of Service. Use for personal research only.

## Getting PDD Session Cookies

1. Log in to Pinduoduo in Chrome (or on your phone)
2. Open DevTools → Application → Cookies → `mobile.yangkeduo.com`
3. Copy cookies to a JSON array format
4. Set `PDD_H5_COOKIES_JSON` in your `.env` file

Cookie format:
```json
[
  {"name": "PDDAccessToken", "value": "...", "domain": ".yangkeduo.com", "path": "/"},
  {"name": "api_uid", "value": "...", "domain": ".yangkeduo.com", "path": "/"}
]
```

Cookies expire — you may need to refresh them periodically.

## Setup

```bash
git clone <repo>
cd pdd-shopping-mcp
npm install
npx playwright install chromium
cp .env.example .env
# Edit .env as needed (default is mock mode, no config required)
```

## Run

```bash
# Development (mock mode — no config needed)
npm run dev

# Real H5 scraping (requires PDD_H5_COOKIES_JSON in .env)
PDD_PROVIDER=h5 npm run dev

# Tests
npm test
```

## Claude Code Config

Add to `~/.claude/claude_desktop_config.json` (or project `.claude/mcporter.json`):

```json
{
  "mcpServers": {
    "pdd-shopping": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/pdd-shopping-mcp/src/index.ts"],
      "env": {
        "PDD_PROVIDER": "h5",
        "CNY_RUB_RATE": "13.5",
        "CARGO_RATE_RUB_PER_KG": "600"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
|---|---|
| `health_check` | Check server and provider status |
| `translate_query_to_chinese` | Dictionary-based query translation helper |
| `search_pdd_products` | Search products, returns `Product[]` with signals |
| `get_pdd_product_detail` | Get full detail by goodsId or URL |
| `compare_pdd_products` | Sort by quality signals, generate Russian warnings list |
| `estimate_cargo_cost` | Calculate total cost including Russia cargo |

## Product Signals

Each `Product` has a `signals` field pre-computed before Claude sees the data:

| Signal | Meaning |
|---|---|
| `replicaKeywordsFound` | Chinese replica keywords in title: 同款, 高仿, 复刻, 潮牌… |
| `priceSuspiciouslyLow` | Price below 15% of expected brand range |
| `priceVsExpectedRatio` | Ratio of actual to minimum expected price (0.05 = 5% = almost certainly fake) |
| `brandMismatch` | Price below 50% of brand minimum |
| `hasBuyerPhotos` | Whether buyers posted real photos |
| `noShopInfo` | Shop data completely absent |

Claude uses these signals to reason about authenticity and risk.

## Example Session

```
User: Find Ray-Ban Meta smart glasses on Pinduoduo. Compare and warn about fakes.

Claude calls: search_pdd_products("Ray-Ban Meta 智能眼镜")
Claude calls: compare_pdd_products([...results])

Analysis:
• 99 CNY — replicaKeywordsFound: ["同款","潮牌"], priceVsExpectedRatio: 0.07 → AVOID
• 399 CNY — priceSuspiciouslyLow: true, no buyer photos → RISKY  
• 1800 CNY — ratio: 1.2, but only 7 reviews → needs more verification

None are confirmed genuine. Real Ray-Ban Meta retails ~$299 USD (~2200+ CNY).
```

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PDD_PROVIDER` | `mock` | `h5`, `mock`, or `official` |
| `PDD_H5_COOKIES_JSON` | — | JSON cookie array (required for `h5` mode) |
| `PLAYWRIGHT_HEADLESS` | `true` | Set `false` to see browser |
| `CNY_RUB_RATE` | `13.5` | CNY to RUB exchange rate |
| `CARGO_RATE_RUB_PER_KG` | `600` | Cargo rate RUB/kg |
| `CARGO_MIN_KG` | `0.3` | Minimum billable weight kg |
| `DEBUG` | `false` | Include raw PDD data in Product output |

## Roadmap

- PDD Open Platform / DDK API integration
- Third-party API connectors (RapidAPI)
- Buyer review and image extraction
- Price history tracking
- Taobao / 1688 / Poizon adapters
- Telegram bot wrapper
- Image-based search
- Real cargo company calculator