dsers-mcp-product

Category: Tools & Productivity | Uploader: lofder | Downloads: 0 | Version: v1.0（Latest）

Automate DSers dropshipping — search products, import from AliExpress/Alibaba/Accio, apply pricing rules, push to Shopify & Wix, and replace broken suppliers at the SKU level. 13 tools for the full product lifecycle.

Changelog: Source: GitHub https://github.com/lofder/dsers-mcp-product

Directory Structure

Current level: tree/main/

📁 .github/
- 📁 ISSUE_TEMPLATE/
  - 📄 bug_report.md 663 B
  - 📄 feature_request.md 447 B
- 📁 workflows/
  - 📄 ci.yml 396 B
📁 app/
- 📁 .well-known/
  - 📁 oauth-authorization-server/
    
    📄 route.ts 786 B
- 📁 dropshipping/
  - 📁 [transport]/
    
    📄 route.ts 3.4 KB
- 📁 oauth/
  - 📁 authorize/
    
    📄 page.tsx 3.6 KB
  - 📁 callback/
    
    📄 route.ts 2.6 KB
  - 📁 register/
    
    📄 route.ts 1.9 KB
  - 📁 token/
    
    📄 route.ts 3.9 KB
- 📁 privacy-policy/
  - 📄 page.tsx 3.2 KB
- 📄 layout.tsx 286 B
📁 docs/
- 📄 dsers-retry-spec.md 13.8 KB
- 📄 sku-mapping-pool-decoration-spec.md 11.1 KB
- 📄 sku-mapping-spec.md 12.8 KB
📁 public/
- 📄 favicon.svg 359 B
📁 src/
- 📁 auth/
  - 📄 browser-finder.ts 511 B
  - 📄 index.ts 277 B
  - 📄 oauth.ts 8.9 KB
  - 📄 token-store.ts 6.0 KB
- 📁 dsers/
  - 📄 account.ts 2.3 KB
  - 📄 auth.ts 4.8 KB
  - 📄 client.ts 4.3 KB
  - 📄 config.ts 1.8 KB
  - 📄 product.ts 17.0 KB
  - 📄 retry.ts 9.7 KB
  - 📄 settings.ts 3.8 KB
- 📁 oauth/
  - 📄 crypto.ts 4.3 KB
- 📁 provider/
  - 📄 helpers.ts 9.6 KB
  - 📄 import-ops.ts 15.9 KB
  - 📄 index.ts 8.7 KB
  - 📄 normalize.ts 10.7 KB
  - 📄 push.ts 18.7 KB
  - 📄 sku-matcher.ts 59.7 KB
  - 📄 store.ts 6.6 KB
- 📁 service/
  - 📄 browse-shared.ts 1.1 KB
  - 📄 find-product.ts 3.2 KB
  - 📄 helpers.ts 5.8 KB
  - 📄 import-flow.ts 6.0 KB
  - 📄 import-list.ts 4.3 KB
  - 📄 index.ts 6.8 KB
  - 📄 my-products.ts 2.3 KB
  - 📄 preview.ts 10.9 KB
  - 📄 push-flow.ts 11.1 KB
  - 📄 sku-mapping.ts 105.4 KB
  - 📄 status.ts 4.1 KB
- 📁 types/
  - 📄 dsers-api.ts 2.7 KB
- 📄 cli.ts 7.1 KB
- 📄 error-map.ts 17.8 KB
- 📄 index.ts 2.8 KB
- 📄 instructions.ts 7.7 KB
- 📄 job-store-memory.ts 647 B
- 📄 job-store.ts 1.4 KB
- 📄 logger.ts 4.6 KB
- 📄 push-guard.ts 4.5 KB
- 📄 push-options.ts 6.1 KB
- 📄 resolver.ts 4.6 KB
- 📄 rules.ts 30.9 KB
- 📄 tools.ts 56.4 KB
- 📄 util.ts 701 B
📁 test/
- 📄 browse.test.ts 17.4 KB
- 📄 bugfix-v1.5.1.test.ts 7.0 KB
- 📄 denormalize-price.test.ts 5.4 KB
- 📄 dsers-product-retry.test.ts 8.6 KB
- 📄 dsers-retry.test.ts 21.0 KB
- 📄 error-map.test.ts 5.2 KB
- 📄 job-store-security.test.ts 2.0 KB
- 📄 logger.test.ts 8.6 KB
- 📄 oauth-security.test.ts 2.3 KB
- 📄 provider-normalize.test.ts 10.4 KB
- 📄 provider-push.test.ts 3.9 KB
- 📄 provider-store.test.ts 6.9 KB
- 📄 push-guard.test.ts 5.6 KB
- 📄 push-options.test.ts 5.5 KB
- 📄 rules.test.ts 32.9 KB
- 📄 service.test.ts 26.2 KB
- 📄 sku-mapping-error-channels.test.ts 4.2 KB
- 📄 sku-mapping-numeric-edges.test.ts 15.2 KB
- 📄 sku-mapping-path-a-fallback.test.ts 16.3 KB
- 📄 sku-mapping-pool-decoration.test.ts 32.4 KB
- 📄 sku-mapping-rank.test.ts 19.8 KB
- 📄 sku-mapping-store-ownership.test.ts 30.3 KB
- 📄 sku-matcher-single-sku.test.ts 17.2 KB
- 📄 tools-input-shape.test.ts 15.5 KB
- 📄 tools.test.ts 3.0 KB
📄 .env.example 670 B
📄 .gitignore 233 B
📄 .mcpbignore 1.1 KB
📄 .prettierrc 107 B
📄 ARCHITECTURE.md 14.1 KB
📄 CHANGELOG.md 23.6 KB
📄 eslint.config.js 706 B
📄 glama.json 97 B
📄 LAUNCHGUIDE.md 4.0 KB
📄 LICENSE 1.0 KB
📄 logo.svg 359 B
📄 manifest.json 5.7 KB
📄 next.config.mjs 249 B
📄 package-lock.json 151.7 KB
📄 package.json 1.9 KB
📄 README.md 32.1 KB
📄 SECURITY.md 7.0 KB
📄 server.json 843 B
📄 SKILL-CN.md 7.2 KB
📄 SKILL.md 12.0 KB
📄 smithery-config-schema.json 1.3 KB
📄 tsconfig.build.json 458 B
📄 tsconfig.json 701 B
📄 USAGE.md 11.7 KB
📄 vercel.json 420 B
📄 vitest.config.ts 323 B

SKILL.md

---
name: dsers-mcp-product
description: Automate DSers dropshipping — search products, import from AliExpress/Alibaba/Accio, apply pricing rules, push to Shopify & Wix, and replace broken suppliers at the SKU level. 13 tools for the full product lifecycle.
---

# DSers MCP Product

## Authentication

### OAuth 2.1

Authentication uses DSers OAuth 2.1 with PKCE. The user runs `npx @lofder/dsers-mcp-product login`, a browser opens to the DSers authorization page, and the user logs in on DSers's own website. No passwords are stored or transmitted through this tool.

Tokens are automatically refreshed using a long-lived refresh token — the user should rarely need to re-login.

### Credential resolution (priority order)

1. **Local credentials file** `~/.dsers-mcp/credentials` — created by `login` command (recommended)
2. **Environment variable** `DSERS_ACCESS_TOKEN` — OAuth access token (headless/CI)
3. **Bearer token** (HTTP header) — automatic on remote MCP server

### Agent decision tree for authentication

**Scenario 1: "DSers credentials not configured"**
- No token exists. The user has never logged in, or they ran `logout`.
- Tell the user: "I need you to log in to DSers first. Please run this in your terminal: `npx @lofder/dsers-mcp-product login` — this opens the DSers website in your browser. Your password never passes through this tool."
- After they confirm, retry.

**Scenario 2: "DSers session expired"**
- Token and refresh token are both expired.
- Tell the user: "Your DSers session has expired. Please run `npx @lofder/dsers-mcp-product login` again."
- Reassure them: import data is still saved, they can continue after re-authenticating.

**Scenario 3: User wants to switch accounts**
1. `npx @lofder/dsers-mcp-product logout`
2. `npx @lofder/dsers-mcp-product login`

### Rules for you (the agent)

- NEVER ask the user for their password
- NEVER retry tool calls in a loop on auth errors — stop and ask the user to re-authenticate
- Call `dsers_store_discover` at the start of any workflow to verify auth before doing imports or pushes

## Workflows

```
(1) New product:      discover → find_product → import → preview → (update rules) → push
(2) Browse staging:   discover → import_list → preview / delete / push
(3) Browse store:     discover → my_products → supplier_url → re-import
(4) Direct import:    discover → import (with supplier URL) → preview → push
(5) Replace supplier: discover → my_products → sku_remap (mode='preview')
                        → review diffs → sku_remap (mode='apply')
```

Always start with `dsers_store_discover` — it returns store IDs, shipping profiles, pricing rules, and capabilities.

### When to use `dsers_sku_remap`

Trigger this tool when the user says any of (or the equivalent in another language):

- "supplier is out of stock / 缺货 / 换源 / 换供应商"
- "find me a replacement supplier for this product"
- "the supplier link is broken / 供应商链接失效"
- "swap the supplier on this product to <URL>"
- "this product's supplier got delisted"

Always run with `mode='preview'` (the default) first — it is byte-level read-only and returns the planned diffs, top candidates, and pool history additions. Only call `mode='apply'` after the user confirms the diffs.

## Thirteen Tools

### Discovery & Browse

| Tool | Purpose |
|------|---------|
| `dsers_store_discover` | See connected stores, shipping profiles, pricing rules, capabilities. **Call this first.** |
| `dsers_import_list` | Browse the import staging list with enriched data: cost & sell price ranges, stock, markup status, low stock warnings. Use `import_item_id` with `dsers_product_preview` or `dsers_product_delete`. |
| `dsers_my_products` | See products already pushed to a store. Requires `store_id`. Returns supplier links for re-import. |
| `dsers_find_product` | Search the DSers product pool (AliExpress catalog) by keyword or image. Results include `import_url` for direct use with `dsers_product_import`. Uses cursor pagination (`search_after`). |

### Import & Edit

| Tool | Purpose |
|------|---------|
| `dsers_product_import` | Import from URL(s), apply pricing/content/image rules, get preview with `job_id`. Supports AliExpress, Alibaba, Accio.com URLs. |
| `dsers_product_preview` | Review an imported product — title, price, variants, stock. Use `variant_detail='full'` for compare_at/cost columns. |
| `dsers_product_update_rules` | Edit rules after import. Pricing/images/variant_overrides replace by family. Content fields merge individually. `option_edits` always fully replaced. |
| `dsers_rules_validate` | Dry-run rule validation before importing — catches mistakes early. |

### Push & Manage

| Tool | Purpose |
|------|---------|
| `dsers_product_visibility` | Toggle `backend_only` (draft) / `sell_immediately` (published). |
| `dsers_store_push` | Push to Shopify/Wix. Single, batch (`job_ids_json`), or multi-store (`target_stores_json`). |
| `dsers_job_status` | Check push result. |
| `dsers_product_delete` | Delete from import list. Irreversible, requires `confirm: true`. |

### Supplier Replacement (SKU Remap)

| Tool | Purpose |
|------|---------|
| `dsers_sku_remap` | Replace the supplier on an already-pushed store product at the SKU level. **STRICT mode**: caller passes `new_supplier_url`, tool swaps to that exact supplier. **DISCOVER mode**: omit the URL, tool reverse-image-searches the DSers pool and auto-picks the best replacement via multi-factor scoring (sku-matcher score + image frequency + product/store rating + price + stock + orders, with `SKU_HARD_CUTOFF=50` two-tier hard isolation). Two-step: always call with `mode='preview'` (read-only, default) first to inspect `diffs`, `discovery.top_candidates`, and `pool_additions`, then re-call with `mode='apply'`. Apply writes both the mapping update and a pool[] history archive of the displaced suppliers atomically. Requires the `product:mapping` OAuth scope. |

## Key Decisions

### Accio.com URLs

[Accio.com](https://www.accio.com/) is Alibaba's AI sourcing platform. `dsers_product_import` accepts Accio URLs directly:
- `accio.com/c/{cid}?productId=xxx&ds=aliexpress.com`
- `accio.com/d/{id}?dataSource=Alibaba.com`

When `ds` contains `aliexpress` → AliExpress import. When `ds` contains `alibaba` → Alibaba import.

### Single vs Batch Import

- One URL → `source_url`
- Multiple URLs → `source_urls_json` (JSON array). Failures don't block others. Mixed sources work.

### Push Modes

- **Single**: `job_id` + `target_store`
- **Batch**: `job_ids_json` + `target_store`
- **Multi-store**: `job_id` + `target_stores_json`
- When `job_ids_json` is provided, it takes priority over `job_id`.

### Shipping Profiles

- 1 profile → auto-selected
- Multiple profiles → push is **BLOCKED** with `available_profiles` list. Use `shipping_profile_name` in `push_options_json`.
- `dsers_store_discover` returns available profiles per store.
- Non-Shopify stores skip shipping profile.

### Rules

Applied at import time and frozen into the job. Use `dsers_product_update_rules` for post-import edits.

- **pricing**: `multiplier`, `fixed_markup`, `fixed_price`
- **content**: `title_prefix`, `title_suffix`, `title_override`, `description_override_html`, `description_append_html`, `tags_add`
- **images**: `keep_first_n`, `drop_indexes`, `add_urls`, `reorder`
- **variant_overrides**: per-variant `sell_price`, `compare_at_price`, `stock`, `title`, `image_url`
- **option_edits**: `rename_option`, `rename_value`, `remove_value`, `remove_option`

Map natural language to rules:
- "3x the price" → `{"pricing": {"mode": "multiplier", "multiplier": 3}}`
- "add $5" → `{"pricing": {"mode": "fixed_markup", "fixed_markup": 5}}`
- "set all to $9.99" → `{"pricing": {"mode": "fixed_price", "fixed_price": 9.99}}`
- "add HOT before title" → `{"content": {"title_prefix": "HOT - "}}`
- "keep first 5 images" → `{"images": {"keep_first_n": 5}}`

### Pre-Push Safety Checks

**Hard blocks (push refused):**
- Sell price < supplier cost
- Sell price = $0
- All variants zero stock

**Warnings (push proceeds):**
- Margin < 10%
- Total stock < 5
- Sell price < $1

Show the user the exact issue. Use `force_push=true` only after explicit user confirmation.

### Pricing Rule Conflict

If the DSers store has its own Pricing Rule AND you set MCP pricing rules, push is **BLOCKED**. Two fix options:
1. `pricing_rule_behavior='apply_store_pricing_rule'` — accept store pricing
2. Disable the Pricing Rule in DSers settings — use MCP pricing

### SKU Remap: preview vs apply

`dsers_sku_remap` is the only DSers-writing tool with a hard preview/apply contract:

- `mode='preview'` (default) is byte-level read-only — repeated calls never mutate DSers, never accumulate `pool[]`, never decrement stock. Safe to call without confirmation.
- `mode='apply'` writes to `mapping[]` and appends to `mapping.pool[]` in a single atomic POST. Always run `preview` first and show the user `diffs[]` + `pool_additions[]` before flipping to `apply`.

The tool's MCP `destructiveHint: true` annotation refers to the apply path; LLM clients that gate destructive tools behind a confirm prompt should still let preview through automatically — the description's first sentence makes this contract explicit.

### Push Confirmation Checklist

Before calling `dsers_store_push`, show the user:
- Product (title, variant count)
- Price (sell vs cost)
- Store name
- Visibility (Draft or Published — warn if Published)
- Shipping profile (selected or NOT SELECTED)
- Pricing Rule (conflict or not)

ONLY push after explicit user confirmation. Exception: if the user's message already says "push it" / "推送", treat as pre-confirmed.

## Response Format

- **Compact mode (default)**: SKU table with [name, sell, qty], all variants shown
- **Full mode**: [name, sell, compare_at, cost, qty, supplier_qty], 3 variants by default
- **price_summary**: always included — {sell min/max, cost min/max, zero_stock_count, low_stock_count}
- **Batch**: summary mode (~100 tokens/product). Use `dsers_product_preview` for details.
- **Import list**: enriched with per-item variant data — cost_range, sell_price_range, no_markup, low_stock_warning

## v1.5.1 Behavior Changes

### Product Search
- Empty or whitespace-only keywords are rejected with a clear error — always provide a non-empty `keyword` or `image_url`
- Image search results are truncated to the requested `limit` client-side; check `truncated_from` field for the original count
- Paginated results may overlap by one item between pages; deduplicate by `product_id`
- When fewer items than `limit` are returned and no more pages exist, a `note` field explains the shortfall

### Rules & Push
- Extreme pricing values (multiplier >100x, fixed_markup >$500, fixed_price >$10K) trigger warnings — show them to the user
- HTML description fields (`description_override_html`, `description_append_html`) are validated against script injection (`<script>`, `<iframe>`, `on*` events, `javascript:` URLs) — dangerous content is blocked
- If rule persistence to DSers backend fails, job enters `persist_failed` status — push is blocked until rules are successfully re-applied or the product is re-imported
- `apply_store_pricing_rule` now displays the store's actual pricing rule configuration so the user knows what the final price will be

## Error Handling

All errors return `{Error, Cause, Action}`. Follow the Action field.

Push blocks return structured JSON with `blocked[]` + `fix_options[]`.

Common errors:
- Auth error → guide user to `npx ... login`
- "insufficient_scope" → OAuth token missing required permissions
- Shipping profile block → show available profiles, ask user to choose
- Pricing rule conflict → show fix options
- CSV store push → not supported, only Shopify/Wix/WooCommerce

## Deployment Options

### Local (stdio)

```json
{
  "mcpServers": {
    "dsers-mcp-product": {
      "command": "npx",
      "args": ["-y", "@lofder/dsers-mcp-product"]
    }
  }
}
```

### Remote (Streamable HTTP)

```json
{
  "mcpServers": {
    "dropshipping": {
      "url": "https://ai.silentrillmcp.com/dropshipping/mcp"
    }
  }
}
```

Comments 0

Latest | Hot

Please login before commenting.

Loading comments...

dsers-mcp-product

Directory Structure

SKILL.md

Report

Notice