@lofder/dsers-mcp-product 1.5.7 → 1.5.9

package/CHANGELOG.md

@@ -8,6 +8,55 @@
 
 ## English
 
+### 1.5.9 — 2026-04-21
+
+Tiny feature release — one user-requested CLI flag, no behaviour changes elsewhere.
+
+#### Features
+
+- **`--version` / `-v` / `version` CLI flag** (thanks [@fuleinist](https://github.com/lofder/dsers-mcp-product/issues/2)). The CLI now prints the installed package version and exits, matching the convention every other CLI follows. The version constant was already read from `package.json` internally; this just exposes it. The help text also now leads with `dsers-mcp-product vX.Y.Z — ...` so you can see the version without knowing the flag.
+
+Version output goes to stdout (pipeable: `npx @lofder/dsers-mcp-product --version | grep ...` works). Everything else the CLI prints still goes to stderr so it doesn't pollute MCP stdio.
+
+### 1.5.8 — 2026-04-15
+
+Catch-up release folding 1.5.2 → 1.5.8 into a single published npm version. The npm CLI behaviour on this release is effectively identical to 1.5.7 — the code changes since 1.5.1 either landed in intermediate releases already on your machine, or affect only the Vercel-hosted deployment. The main user-facing update is a documentation pass and affiliate links in the README.
+
+#### Bugfixes (`persist_failed` saga — 1.5.2 → 1.5.7)
+
+Five releases chasing one DSers-BFF bug with progressively more correct fixes. Summary for anyone who saw `status=persist_failed` on `dsers_product_update_rules` or `dsers_store_push`:
+
+- **1.5.2** — `deepCleanNone` introduced for DSers API writes; top-level-only `cleanNone` was preserving nested `null` values DSers rejects.
+- **1.5.3** — rolled back GET → merge → PUT pattern that was masking the real error, added surface-level DSers error messages.
+- **1.5.4** — restored GET → merge → PUT but matched the Python `vendor-dsers` reference implementation exactly: filter nulls from the updates dict, never from the original product. 7 integration tests added.
+- **1.5.5** — root cause #1: `Cookie: sessionId=...; state=...` header was required in addition to `Authorization: Bearer` on all DSers BFF write endpoints. Without it, writes silently failed.
+- **1.5.6** — confirmed 1.5.5 fix against live DSers API; added diagnostic logging in `saveDraftImpl`.
+- **1.5.7** — **actual root cause**: DSers BFF uses Protobuf encoding on the import-list PUT endpoint. Sending `tags: ["foo"]` as a JSON string array triggered `CODEC: body unmarshal proto: syntax error`. Fix: skip `tags` in the PUT body entirely and apply them at push time. Also: diagnostic warnings no longer truncated at `MAX_WARNING_CHARS=120`.
+
+If you were stuck on 1.5.0–1.5.6, upgrade to 1.5.8 fixes it.
+
+#### Bugfixes (other)
+
+- **`deepCleanNone` safety** (R-PERF-06). Depth limit (20) + `WeakSet` cycle detection prevents infinite recursion on malformed or self-referential payloads.
+- **Vercel OAuth metadata — broken issuer removed.** The `OAUTH_ISSUER_URL` env var pointed at a missing `silentrillmcp.com` deployment by default, causing every remote OAuth client to hit `DEPLOYMENT_NOT_FOUND`. The env var support is removed entirely; the issuer is now always computed from the request host. (Affects self-hosted deployments only.)
+- **OAuth callback — friendly stale-state page.** When a browser re-hit the callback URL after the real 302 redirect already consumed the state (back button, preconnect, extension strip), the old `400 Missing state parameter` made users think the whole OAuth flow was broken. Now a polite HTML page explains the URL already did its job.
+
+#### Features (Vercel-hosted only)
+
+- **Proper OAuth proxy to DSers.** Replaced the legacy "paste your DSers session cookie" stub page with a real two-layer PKCE OAuth proxy. Client ↔ Vercel uses the client's PKCE; Vercel ↔ DSers uses our own generated verifier. All state is AES-GCM encrypted into the URL — no server-side session storage required.
+- **Analytics dashboard.** PV / UV (HyperLogLog) / tool-call count / per-tool success rate / MCP client identity / country / hourly activity — surfaced via `/admin/stats?pw=...` HTML dashboard. Writes are fire-and-forget pipelined to Upstash Redis (no-op if env vars are missing). Auto-detects any Vercel Storage prefix.
+- **`registerTools` accepts an optional `onToolCall` callback** so analytics hooks can observe tool invocations without each tool needing to be touched. Backwards compatible; the npm CLI does not pass the callback.
+
+#### Docs
+
+- **README polish.** Tool table tightened (13 tools, consistent verb-first voice, tool 13 now fits on one line). FAQ expanded with four new entries: remote vs local server, 1688 authorization, store currency, headless token. New Troubleshooting section covering `persist_failed`, pricing rule conflict, 1688 unsupported source, OAuth port conflict, remote 401, and `npx command-not-found` exit 127.
+- **DSers affiliate links** added in Hero, Prerequisites ("A DSers account"), and the "Is it free?" FAQ. Existing users are unaffected; new users hitting npm or GitHub get a referral link.
+- **Accio.com links updated** to the referral URL.
+- **"What's Next" refreshed** — order-level tools and refresh-token support for the remote MCP are now the top priorities.
+- **Python version positioning clarified** — it is a feature-parity subset; the TypeScript version is the primary maintained release.
+
+---
+
 ### 1.5.1 — 2026-04-10
 
 Security hardening + 7 bugfixes from npm testing. No new tools, no algorithm changes — purely defensive.
@@ -145,6 +194,55 @@ Previous releases live in the git history. Mostly OAuth 2.1 + remote MCP + Verce
 
 ## 中文
 
+### 1.5.9 — 2026-04-21
+
+小功能版本 —— 加了一个社区提议的 CLI 参数，其余没改动。
+
+#### 新功能
+
+- **`--version` / `-v` / `version` CLI 参数**（感谢 [@fuleinist](https://github.com/lofder/dsers-mcp-product/issues/2) 的建议）。CLI 现在能直接打印已装版本号然后退出，跟所有其他 CLI 工具的惯例对齐。内部其实一直从 `package.json` 读了版本号，只是没 expose 出来。顺手把 help 文本也改了，第一行现在直接写 `dsers-mcp-product vX.Y.Z — ...`，不知道这个 flag 的人也能看到版本。
+
+版本号走 stdout（可以 pipe：`npx @lofder/dsers-mcp-product --version | grep ...`）。CLI 其他输出继续走 stderr，不会污染 MCP 的 stdio 通道。
+
+### 1.5.8 — 2026-04-15
+
+追尾版本，把 1.5.2 → 1.5.8 合成单次 npm 发布。如果你已经在 1.5.7，npm CLI 行为基本没变化 —— 1.5.1 之后的代码改动要么已经在中间版本里被你拿到过，要么只影响 Vercel 托管部署。这一版面向用户的更新主要是 README 打磨和 affiliate 链接。
+
+#### Bug 修复（`persist_failed` saga — 1.5.2 → 1.5.7）
+
+5 次版本追同一个 DSers BFF bug，每次都修得更接近真相。如果你在 `dsers_product_update_rules` 或 `dsers_store_push` 上看到过 `status=persist_failed`，下面是完整叙事：
+
+- **1.5.2** — 为 DSers API 写入引入 `deepCleanNone`；顶层 `cleanNone` 会保留 DSers 拒绝的嵌套 `null`。
+- **1.5.3** — 回退了 GET → merge → PUT，之前它掩盖了真实错误；把 DSers 的错误消息直接暴露出来。
+- **1.5.4** — 重新启用 GET → merge → PUT，但严格对齐 Python `vendor-dsers` 参考实现：只过滤更新 dict 里的 null，永远不过滤原始 product。新增 7 个集成测试。
+- **1.5.5** — 根因 #1：DSers BFF 所有写入 endpoint 除了 `Authorization: Bearer` 之外，还**必须带** `Cookie: sessionId=...; state=...`。少了这个头，写入会静默失败。
+- **1.5.6** — 用 live DSers API 验证 1.5.5 修复；`saveDraftImpl` 里加诊断日志。
+- **1.5.7** — **真正的根因**：DSers BFF 在 import-list PUT endpoint 用的是 Protobuf 编码。把 `tags: ["foo"]` 作为 JSON 字符串数组发过去会触发 `CODEC: body unmarshal proto: syntax error`。修复：PUT body 完全跳过 `tags`，改到推送时应用。顺带把诊断 warning 从 `MAX_WARNING_CHARS=120` 截断里解放出来。
+
+如果你卡在 1.5.0–1.5.6，升到 1.5.8 即可。
+
+#### Bug 修复（其他）
+
+- **`deepCleanNone` 安全性** (R-PERF-06)。深度上限 20 + `WeakSet` 循环检测，防止恶意或自引用 payload 把进程卡死。
+- **Vercel OAuth metadata — 去掉坏的 issuer**。`OAUTH_ISSUER_URL` 默认指向一个不存在的 `silentrillmcp.com` 部署，导致所有远程 OAuth 客户端吃 `DEPLOYMENT_NOT_FOUND`。整个 env var 支持被移除，issuer 改为始终由请求 host 计算。（仅影响 self-hosted 部署）
+- **OAuth callback — 失效 state 显示友好页面**。当浏览器在真正的 302 redirect 之后又二次请求 callback URL（后退、预连接、扩展剥查询）时，旧代码返回干巴的 `400 Missing state parameter`，让人以为整个 OAuth 都炸了。现在返回礼貌 HTML 页面说明"这个页面已经完成了它的任务"。
+
+#### 新功能（仅 Vercel 托管版）
+
+- **真正的 DSers OAuth 代理**。替换掉旧版"把 DSers session cookie 贴进来"的 stub 页，改为标准双层 PKCE OAuth 代理。客户端 ↔ Vercel 用客户端的 PKCE；Vercel ↔ DSers 用我们自己生成的 verifier。所有 state AES-GCM 加密塞进 URL —— 不需要服务端 session 存储。
+- **数据看板**。PV / UV（HyperLogLog 去重）/ 每 tool 调用数 / 成功率 / MCP 客户端识别 / 国家 / 小时活跃度 —— 全部通过 `/admin/stats?pw=...` 的 HTML dashboard 暴露。写入是 pipelined fire-and-forget 到 Upstash Redis（env 不存在时自动 noop）。自动识别任意 Vercel Storage prefix。
+- **`registerTools` 接受可选 `onToolCall` 回调**，analytics 能 hook 每次工具调用而不用修改 13 个 tool 的 handler。向后兼容；npm CLI 不传这个回调。
+
+#### 文档
+
+- **README 打磨**。工具表收紧（13 个工具动词开头统一语气，第 13 个现在一行放得下）。FAQ 新增 4 条：远程 vs 本地服务端、1688 授权、店铺币种、headless token。新增 Troubleshooting 小节涵盖 `persist_failed`、定价规则冲突、1688 来源不支持、OAuth 端口冲突、远程 401、`npx command-not-found` 退出码 127。
+- **DSers affiliate 链接** 放到 Hero、Prerequisites（"A DSers account"）、FAQ "Is it free?" 三处。老用户无感知；从 npm / GitHub 新流量会带 referral。
+- **Accio.com 链接** 更新为 referral URL。
+- **"What's Next" 刷新** —— 订单级工具和远程 MCP refresh-token 支持放到首位。
+- **Python 版本定位澄清** —— 功能对齐的精简子集，TypeScript 版是主维护。
+
+---
+
 ### 1.5.1 — 2026-04-10
 
 安全加固 + npm 测试发现的 7 个 bugfix。没有新工具，没有算法改动，纯防御性更新。

package/README.md

@@ -8,15 +8,11 @@
 
 > An open-source MCP server to automate DSers product sourcing, import, bulk edit, and push to Shopify or Wix using AI.
 
-> [English](#english) | [中文](#中文)
+> **English** | [中文](README.zh-CN.md)
 
 ---
 
-<a id="english"></a>
-
-## English
-
-**DSers MCP Product** is an open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI Agents automate the entire DSers import workflow — from product sourcing to Shopify or Wix store listing. Search the DSers product pool, import from AliExpress / Alibaba / [Accio.com](https://www.accio.com/), bulk edit variants, apply pricing rules, and push to multiple stores — all with a single sentence to your AI agent.
+**DSers MCP Product** is an open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that lets AI Agents automate the entire [DSers](https://www.dsers.com/partner/2044332769636515840) import workflow — from product sourcing to Shopify or Wix store listing. Search the DSers product pool, import from AliExpress / Alibaba / [Accio.com](https://www.accio.com/login?sId=fsBYirNWqq7FyJFV4GnoXw%3D%3D&ic=IC407236504434&tenant=accio), bulk edit variants, apply pricing rules, and push to multiple stores — all with a single sentence to your AI agent.
 
 #### What can it do?
 
@@ -24,11 +20,12 @@
 - **One-click import** — paste a product link, your AI agent imports it into DSers automatically
 - **Browse your catalog** — view your import staging list and products already pushed to stores
 - **Clean up titles** — strips the messy keyword-stuffed AliExpress titles into something readable
-- **Pricing rules** — markup multiplier (e.g. 2.5x), fixed markup (e.g. +$5), compare-at / sale prices
+- **Pricing rules** — markup multiplier (e.g. 2.5×), fixed markup (e.g. +$5), fixed price (e.g. $9.99), compare-at / sale prices, per-variant overrides
 - **Batch import** — import multiple products at once with a list of URLs
 - **Multi-store push** — push one product to all your connected Shopify & Wix stores in one go
-- **Safety checks** — automatically blocks pushes that would result in below-cost pricing, zero price, or zero stock
+- **Safety checks** — blocks pushes that price below supplier cost, at $0, or with all variants out of stock; warns on <10% margin, <5 units per variant, or sell price under $1
 - **SEO optimization** — let AI rewrite the title and description for better search rankings before pushing
+- **Supplier swap (SKU Remap)** — replace an existing store product's supplier at the SKU level, with reverse-image-search to auto-find a cheaper or in-stock replacement
 
 The server is hosted on [Vercel](https://ai.silentrillmcp.com/dropshipping/mcp) and published across multiple platforms:
 
@@ -49,15 +46,15 @@ The server is hosted on [Vercel](https://ai.silentrillmcp.com/dropshipping/mcp)
 
 ### Supported product sources
 
-Works with product links from **AliExpress**, **Alibaba.com**, and **[Accio.com](https://www.accio.com/)**. Just give your AI agent a product link from any of these platforms, and it will import the product into DSers and push it to your store. (1688.com links are also recognized but require your DSers account to have 1688 source authorization enabled.)
+Works with product links from **AliExpress**, **Alibaba.com**, and **[Accio.com](https://www.accio.com/login?sId=fsBYirNWqq7FyJFV4GnoXw%3D%3D&ic=IC407236504434&tenant=accio)**. Just give your AI agent a product link from any of these platforms, and it will import the product into DSers and push it to your store. (1688.com links are also recognized but require your DSers account to have 1688 source authorization enabled.)
 
 ### Accio.com — AI-powered product sourcing
 
-[Accio.com](https://www.accio.com/) is Alibaba's AI sourcing assistant. You describe what you're looking for (e.g. "wireless earbuds under $5"), and it searches AliExpress & Alibaba for you.
+[Accio.com](https://www.accio.com/login?sId=fsBYirNWqq7FyJFV4GnoXw%3D%3D&ic=IC407236504434&tenant=accio) is Alibaba's AI sourcing assistant. You describe what you're looking for (e.g. "wireless earbuds under $5"), and it searches AliExpress & Alibaba for you.
 
 **How to use it with DSers MCP:**
 
-1. Go to [accio.com](https://www.accio.com/) and search for products in natural language.
+1. Go to [accio.com](https://www.accio.com/login?sId=fsBYirNWqq7FyJFV4GnoXw%3D%3D&ic=IC407236504434&tenant=accio) and search for products in natural language.
 2. Browse the results. When you find a product you like, **click on it** to open the product detail panel.
 3. **Copy the URL** from your browser address bar — it will look something like:
    `https://www.accio.com/c/xxx?productId=1005009871053792&ds=aliexpress.com`
@@ -77,9 +74,9 @@ This works for both AliExpress and Alibaba products found on Accio.
 ### What You Need
 
 - **Node.js** >= 20.0.0
-- A [DSers](https://www.dsers.com/) account (free plan works)
+- A [DSers](https://www.dsers.com/partner/2044332769636515840) account (free plan works)
 - A Shopify or Wix store already connected in DSers
-- An MCP-compatible AI client — [Cursor](https://cursor.sh/), [Claude Desktop](https://claude.ai/desktop), [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), [Windsurf](https://codeium.com/windsurf), or any client that supports MCP
+- An MCP-compatible AI client — [Cursor](https://cursor.sh/), [Claude Desktop](https://claude.ai/desktop), [Claude Code](https://docs.claude.com/en/docs/claude-code/overview), [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), [Codex CLI](https://github.com/openai/codex), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [OpenClaw](https://docs.openclaw.ai/), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) (agent mode), [Windsurf](https://codeium.com/windsurf), [Cline](https://cline.bot/), [Zed](https://zed.dev/), [Continue](https://continue.dev/), or any client that speaks MCP
 
 ### Quick Start
 
@@ -93,6 +90,8 @@ A browser window opens to the official DSers login page. You log in on DSers's o
 
 **Step 2: Add to your MCP client (no credentials needed)**
 
+The standard `mcpServers` JSON works for **Cursor, Windsurf, Cline, Zed, Continue, opencode, and most MCP clients**:
+
 ```json
 {
   "mcpServers": {
@@ -106,6 +105,59 @@ A browser window opens to the official DSers login page. You log in on DSers's o
 
 That's it. No passwords in config files.
 
+<details>
+<summary><b>Other clients — Claude Desktop, Claude Code, Codex CLI, Gemini CLI, VS Code, OpenClaw</b></summary>
+
+**Claude Desktop** — edit `claude_desktop_config.json` (same JSON as above).
+
+**Claude Code** (CLI):
+
+```bash
+claude mcp add dsers -- npx -y @lofder/dsers-mcp-product
+```
+
+**Codex CLI** — add to `~/.codex/config.toml` (note the TOML format and `mcp_servers` snake_case):
+
+```toml
+[mcp_servers.dsers]
+command = "npx"
+args = ["-y", "@lofder/dsers-mcp-product"]
+```
+
+**Gemini CLI** — add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "dsers": {
+      "command": "npx",
+      "args": ["-y", "@lofder/dsers-mcp-product"]
+    }
+  }
+}
+```
+
+**VS Code (Copilot agent mode)** — `mcp.json` uses `servers` (not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "dsers": {
+      "command": "npx",
+      "args": ["-y", "@lofder/dsers-mcp-product"]
+    }
+  }
+}
+```
+
+**OpenClaw** — use the `openclaw mcp set` command:
+
+```bash
+openclaw mcp set dsers '{"command":"npx","args":["-y","@lofder/dsers-mcp-product"]}'
+```
+
+</details>
+
 **Remote server (no install needed):**
 
 If you don't want to install anything locally, you can connect directly to the hosted MCP server at `https://ai.silentrillmcp.com/dropshipping/mcp`. This works with any MCP client that supports Streamable HTTP transport. You'll be prompted to authorize with your DSers account on first connect.
@@ -264,21 +316,19 @@ dsers-mcp-product/
 
 | # | Tool | What it does |
 |---|------|-------------|
-| 1 | `dsers_store_discover` | See your connected stores, shipping methods, pricing rules, and capabilities |
-| 2 | `dsers_rules_validate` | Test your pricing or title rules before applying — catches mistakes early |
-| 3 | `dsers_product_import` | Paste a product URL, optionally apply pricing/title rules, and get a preview before pushing |
-| 4 | `dsers_product_preview` | Review a product you already imported — title, price, variants, stock at a glance |
-| 5 | `dsers_product_update_rules` | Edit pricing, content, images, or variant rules on an already-imported product (incremental merge — no re-import needed) |
-| 6 | `dsers_product_visibility` | Set whether the product shows up in your store or stays as a hidden draft |
-| 7 | `dsers_store_push` | Send products to your Shopify or Wix store — one at a time, in bulk, or to all stores at once |
-| 8 | `dsers_job_status` | Check if a push finished and whether it succeeded |
-| 9 | `dsers_product_delete` | Delete a product from the DSers import list (irreversible, requires confirmation) |
-| 10 | `dsers_import_list` | Browse your import staging list with cost & sell price, stock, markup status |
-| 11 | `dsers_my_products` | See products already pushed to a store, with supplier links for re-import |
-| 12 | `dsers_find_product` | Search the DSers product pool by keyword or image — results link directly to import |
-| 13 | `dsers_sku_remap` | Replace the supplier on an existing store product at the SKU level. Two modes: provide `new_supplier_url` for a strict swap, or omit it to reverse-image-search the DSers pool and auto-pick the best replacement via multi-factor ranking. Always run `mode='preview'` first (read-only) and inspect `diffs` + `pool_additions` before `mode='apply'`. Requires the `product:mapping` OAuth scope. |
-
-All tools return clear error messages so your AI agent knows what went wrong and what to do next.
+| 1 | `dsers_store_discover` | List connected stores, shipping methods, pricing rules, and supported capabilities |
+| 2 | `dsers_rules_validate` | Dry-run pricing or content rules without applying them — catches schema mistakes early |
+| 3 | `dsers_product_import` | Import a product URL, optionally apply rules at import time, returns a full preview |
+| 4 | `dsers_product_preview` | Reload preview for an imported product — title, price, variants, stock, active rules |
+| 5 | `dsers_product_update_rules` | Edit pricing, content, images, variants, or option edits on an imported product (incremental merge — no re-import) |
+| 6 | `dsers_product_visibility` | Toggle a draft between "hidden draft" and "published/live" before pushing |
+| 7 | `dsers_store_push` | Push to Shopify / Wix — single product, batch, or fan-out to multiple stores in one call |
+| 8 | `dsers_job_status` | Poll the status of a push (queued / running / completed / failed) |
+| 9 | `dsers_product_delete` | Permanently remove a product from the DSers import list (irreversible, requires confirmation) |
+| 10 | `dsers_import_list` | Browse the import staging list with cost, sell price, stock, markup status, and low-stock warnings |
+| 11 | `dsers_my_products` | List products already pushed to a specific store, with supplier URLs for re-import |
+| 12 | `dsers_find_product` | Search the DSers product pool by keyword or image; results include `import_url` for one-step import |
+| 13 | `dsers_sku_remap` | SKU-level supplier swap on a live store product. Strict mode (`new_supplier_url`) or discover mode (reverse-image search + multi-factor ranking). Run `mode='preview'` before `mode='apply'`. Requires `product:mapping` scope |
 
 ### Pre-Push Safety Checks
 
@@ -317,10 +367,10 @@ Ready-made workflows your AI client can use directly:
 
 ### What's Next
 
-- Product pool search enhancements (category filters, URL-based search, product detail view)
-- Support more store platforms that DSers already connects to (eBay, Wish, etc.)
-- Smarter pricing rule templates
-- More granular inventory sync options
+- Product pool search enhancements — category filters, URL-based reverse lookup, product detail view
+- More store platforms — TikTok Shop, Etsy, eBay (whatever DSers already integrates with)
+- Order-level tools — fulfillment status, tracking, order sync
+- Remote MCP refresh-token support — extend OAuth sessions beyond the initial access-token lifetime
 
 Got an idea or feature request? [Open an issue](https://github.com/lofder/dsers-mcp-product/issues) — contributions are very welcome.
 
@@ -333,306 +383,56 @@ DSers MCP Product is a free, open-source MCP server that automates dropshipping
 You type a command like "Import this product, mark up 2.5x, push to my store" in Cursor or Claude Desktop. The MCP server handles the entire workflow: fetching product data, applying pricing rules, editing variants, and pushing to your connected stores.
 
 **Is it free?**
-Yes. The tool is open-source (MIT license) and completely free to use. You only need a free DSers account and a Shopify or Wix store connected in DSers.
+Yes. The tool is open-source (MIT license) and completely free to use. You only need a free [DSers](https://www.dsers.com/partner/2044332769636515840) account and a Shopify or Wix store connected in DSers.
 
 **Is it safe? Do I need to share my password?**
 No passwords are stored or transmitted. Authentication uses a zero-password browser login — you log in on DSers's own website, and the tool picks up the session token. Your credentials never touch the MCP server. The project scored 92/100 on [SafeSkill](https://safeskill.dev/scan/@lofder/dsers-mcp-product) security scanning.
 
 **What AI clients does it support?**
-Cursor, Claude Desktop, Claude Code, Claude Managed Agents, Windsurf, and any MCP-compatible client that supports stdio transport.
+Cursor, Claude Desktop, Claude Code, Claude Managed Agents, Codex CLI, Gemini CLI, OpenClaw, VS Code Copilot (agent mode), Windsurf, Cline, Zed, Continue, and any MCP-compatible client. Use stdio transport with the npm package, or Streamable HTTP with the hosted remote server.
+
+**Should I use the remote server or install locally?**
+Use the **remote server** (`https://ai.silentrillmcp.com/dropshipping/mcp`) if your MCP client supports Streamable HTTP and you want zero install — you skip Node.js setup entirely. Use the **local npm package** if your client only supports stdio (e.g. some Claude Desktop setups), you need custom env vars, or you want to run it fully offline from your own machine.
 
 **How is this different from AliDropify, AutoDS, or other dropshipping tools?**
 Most dropshipping tools have their own UI and require you to click through web interfaces. DSers MCP Product takes a fundamentally different approach — it connects directly to your AI agent, so you automate workflows through conversation instead of clicking buttons. It's also open-source and free, with no subscription tiers.
 
 **What product sources does it support?**
-AliExpress, Alibaba.com, Accio.com (Alibaba's AI sourcing tool), and 1688 (requires DSers authorization).
+AliExpress, Alibaba.com, Accio.com (Alibaba's AI sourcing tool), and 1688. For 1688, your DSers account needs the 1688 source authorization enabled — open [DSers → Settings → Suppliers](https://app.dsers.com/) and link your 1688 account there.
+
+**What currency does pricing use?**
+The agent displays prices in USD for readability, but pricing is actually applied in your store's native currency. DSers handles the conversion based on the store's configured currency (Shopify / Wix). Per-variant overrides and fixed prices are interpreted in store currency — confirm with the AI if you're not sure.
 
 **Can I push to multiple stores at once?**
 Yes. The `dsers_store_push` tool supports pushing a single product to all your connected Shopify and Wix stores in one command, with per-store pricing and visibility options.
 
-### Also Available
-
-A [Python version](https://github.com/lofder/dsers-mcp-product-py) is available for local stdio deployments.
-
-### License
-
-MIT
-
----
-
-<a id="中文"></a>
-
-## 中文
-
-**DSers MCP Product** 是一个开源的 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，让 AI Agent 自动完成 DSers 的整个商品流程 —— 从选品搜索到 Shopify 或 Wix 店铺上架。搜索 DSers 商品池、从速卖通 / Alibaba / [Accio.com](https://www.accio.com/) 导入商品、批量编辑变体、应用定价规则、推送到多个店铺 —— 只需一句话给你的 AI agent。
-
-#### 能做什么？
-
-- **选品搜索** — 在 DSers 商品池里按关键词或图片搜索，找到值得卖的商品
-- **一句话导入** — 贴个商品链接，AI 助手自动导入到 DSers
-- **浏览商品库** — 查看导入待推送列表和已上架商品，包含成本价、售价、加价状态
-- **标题清理** — 把速卖通那些关键词堆砌的乱标题整理成人话
-- **定价规则** — 加价倍率（比如 2.5 倍）、固定加价（比如 +5 美金）、划线价
-- **批量导入** — 一次丢一堆链接，全部导入
-- **多店铺推送** — 一个商品一次推到你所有的 Shopify 和 Wix 店铺
-- **安全校验** — 推送前自动拦截低于成本价、零售价为零、库存为零的商品
-- **SEO 优化** — 让 AI 重写标题和描述，提高搜索排名后再推送
-
-服务已托管在 [Vercel](https://ai.silentrillmcp.com/dropshipping/mcp)，并发布到多个平台：
-
-### 发布平台
-
-| 平台 | 链接 |
-|------|------|
-| npm | [npmjs.com/package/@lofder/dsers-mcp-product](https://www.npmjs.com/package/@lofder/dsers-mcp-product) |
-| MCP Registry（官方） | [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product) |
-| Smithery | [smithery.ai/server/@dsersx/product-mcp](https://smithery.ai/server/@dsersx/product-mcp) |
-| Glama.ai | [glama.ai/mcp/servers/lofder/dsers-mcp-product](https://glama.ai/mcp/servers/lofder/dsers-mcp-product) |
-| mcp.so | [mcp.so/server/dsers-mcp-product](https://mcp.so/server/dsers-mcp-product) |
-| mcpservers.org | [mcpservers.org](https://mcpservers.org) |
-| MCP Marketplace | [mcp-marketplace.io](https://mcp-marketplace.io/server/io-github-lofder-dsers-mcp-product) |
-| awesome-mcp-servers | [punkpeye/awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) |
-| Dev.to | [技术文章：I Built an MCP Server to Automate Dropshipping](https://dev.to/_95a3e57463e6442feacd0/i-built-an-mcp-server-to-automate-dropshipping-product-imports-3m5b) |
-| Dev.to | [教程：How to Automate AliExpress to Shopify with AI](https://dev.to/_95a3e57463e6442feacd0/how-to-automate-aliexpress-to-shopify-product-import-with-ai-step-by-step-guide-3f5a) |
-
-### 支持的商品来源
-
-支持 **速卖通（AliExpress）**、**Alibaba.com** 和 **[Accio.com](https://www.accio.com/)** 的商品链接。把任意平台的商品链接丢给你的 AI 助手，它就能自动导入 DSers 并上架到你的店铺。（1688 链接也能识别，但需要你的 DSers 账号开通了 1688 来源权限。）
-
-### Accio.com — AI 智能找商
-
-[Accio.com](https://www.accio.com/) 是阿里巴巴的 AI 选品助手。你用自然语言描述想找的商品（比如"5 美金以下的蓝牙耳机"），它会帮你在速卖通和阿里巴巴上搜索。
-
-**怎么配合 DSers MCP 用：**
-
-1. 打开 [accio.com](https://www.accio.com/)，用自然语言搜索你想要的商品。
-2. 在搜索结果里浏览，看到感兴趣的商品**点击进去**看详情。
-3. **复制浏览器地址栏的链接**，大概长这样：
-   `https://www.accio.com/c/xxx?productId=1005009871053792&ds=aliexpress.com`
-4. 把链接丢给你的 AI 助手，比如说：*"帮我导入这个商品并上架：[粘贴链接]"*
-5. 剩下的 AI 助手会自动搞定，不需要任何额外设置。
-
-Accio 上搜出来的速卖通和阿里巴巴商品都能用。
-
-### 文档
-
-| 文档 | 说明 |
-|------|------|
-| [ARCHITECTURE.md](ARCHITECTURE.md) | 三层架构、目录结构、数据流 |
-| [USAGE.md](USAGE.md) | 安装、客户端配置（Cursor、Claude Desktop）、使用场景 |
-| [SKILL.md](SKILL.md) | AI agent 指令文件 — 工作流、规则、推送选项、错误处理 |
-
-### 使用前提
-
-- 一个 [DSers](https://www.dsers.com/) 账号（免费版就行）
-- Shopify 或 Wix 店铺已经在 DSers 里绑定好了
-- 一个支持 MCP 的 AI 客户端 — [Cursor](https://cursor.sh/)、[Claude Desktop](https://claude.ai/desktop)、[Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview)、[Windsurf](https://codeium.com/windsurf) 或其他支持 MCP 的工具
-
-### 快速开始
-
-**第 1 步：登录（一次性操作，会打开浏览器）**
-
-```bash
-npx @lofder/dsers-mcp-product login
-```
-
-浏览器会自动打开 DSers 官方登录页。你在 DSers 自己的网站上登录 —— 密码**完全不经过**本工具。登录后 session 加密保存到本地。
-
-**第 2 步：添加到你的 MCP 客户端（不需要密码）**
-
-```json
-{
-  "mcpServers": {
-    "dsers-mcp-product": {
-      "command": "npx",
-      "args": ["-y", "@lofder/dsers-mcp-product"]
-    }
-  }
-}
-```
-
-搞定。配置文件里不需要任何密码。
-
-**在线版（免安装）：**
-
-如果不想在本地安装，可以直接连接托管的 MCP 服务端 `https://ai.silentrillmcp.com/dropshipping/mcp`。支持 Streamable HTTP transport 的 MCP 客户端都能用，首次连接会引导你授权 DSers 账号。
-
-```json
-{
-  "mcpServers": {
-    "dropshipping": {
-      "url": "https://ai.silentrillmcp.com/dropshipping/mcp"
-    }
-  }
-}
-```
-
-同时已收录到官方 [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product)。
-
-**Claude Managed Agents ([文档](https://platform.claude.com/docs/en/managed-agents/overview))：**
-
-通过 [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/mcp) 构建 7×24 自主运行的 dropshipping agent：
-
-```python
-from claude_agent_sdk import query, ClaudeAgentOptions
-
-async for message in query(
-    prompt="帮商品 dp-123 在店铺 st-456 找个更便宜的供应商并更新映射",
-    options=ClaudeAgentOptions(
-        mcp_servers={
-            "dsers": {"command": "npx", "args": ["-y", "@lofder/dsers-mcp-product"]}
-        }
-    ),
-):
-    print(message)
-```
-
-### 授权认证 — OAuth 2.1
-
-你的 DSers 密码**完全不经过本工具**。登录过程是这样的：
-
-1. 运行 `npx @lofder/dsers-mcp-product login`
-2. 浏览器自动打开 DSers OAuth 授权页
-3. 你在 DSers 网站上授权
-4. 工具拿到 OAuth token，加密存到本地
-5. 搞定 — 之后 MCP 直接能用，配置文件里不需要写任何密码
-
-**Token 自动续期** — refresh token 会自动保持登录状态，你基本不需要重新登录。
-
-**换账号？**
-
-```bash
-npx @lofder/dsers-mcp-product logout
-npx @lofder/dsers-mcp-product login
-```
-
-> **开发者注：** headless / CI 环境支持通过 `DSERS_ACCESS_TOKEN` 和 `DSERS_REFRESH_TOKEN` 环境变量传入凭据。
-
-> **从源码工作（不是从 npm 包跑）？** 登录用 `node dist/cli.js login`，**不是** `npx @lofder/dsers-mcp-product login`。后者要求 `dsers-mcp-product` binary 解析到 PATH，本地 workspace 没 `npm link`（或者没真正 npm install）的话会 `command not found` 直接退出码 127。先 `npm run build` 让 `dist/cli.js` 存在再跑。
+**Can I skip the browser login and hardcode a token?**
+For headless / CI environments, yes — set `DSERS_ACCESS_TOKEN` (and optionally `DSERS_REFRESH_TOKEN`) as env vars and the tool will skip the OAuth flow. Tokens come from running `login` once on any machine and copying them out of `~/.dsers-mcp/session.json`. Interactive users should stick with `npx @lofder/dsers-mcp-product login` — it's safer and handles refresh automatically.
 
-### 使用示例
+### Troubleshooting
 
-装好之后，直接用自然语言跟 AI 助手说就行：
+**Push returns `persist_failed` or `CODEC` error**
+Fixed in v1.5.7. If you still see it, make sure you're on the latest version: `npm view @lofder/dsers-mcp-product version`. Reinstall with `npx -y @lofder/dsers-mcp-product@latest` to pick up the new release.
 
-> "帮我导入这个商品，推到我的 Shopify 店铺草稿：https://www.aliexpress.com/item/1005006372921430.html"
+**Push blocked with "pricing rule conflict"**
+Your DSers store has its own Pricing Rule enabled, and you also set MCP pricing rules. Pick one: either add `pricing_rule_behavior='apply_store_pricing_rule'` to the push options (accepts the store-side rule), or disable the Pricing Rule in DSers settings and let MCP drive pricing. See the [Pricing Rule Conflict Detection](#pricing-rule-conflict-detection) section above.
 
-> "导入这个商品，加价 2.5 倍，然后推送：https://www.aliexpress.com/item/1005006372921430.html"
+**1688 link imports fail with "unsupported source"**
+Your DSers account needs 1688 source authorization. Open [DSers Settings → Suppliers](https://app.dsers.com/) and link your 1688 seller account. AliExpress works out of the box; 1688 is opt-in.
 
-> "批量导入这 3 个商品，全部推到店铺：[链接1] [链接2] [链接3]"
+**`npx @lofder/dsers-mcp-product login` opens browser but gets stuck**
+The login flow needs ports 3001–3003 free on localhost for the OAuth callback. If any of those are in use (another MCP server, a dev server), kill them or set `PORT=3004` before running login.
 
-> "帮我搜一下 5 美金以下的手机壳"
+**Remote server returns 401 after working for a while**
+OAuth access tokens expire. The remote server currently doesn't auto-refresh — reauthorize via your MCP client (disconnect and reconnect the MCP server). Refresh-token support is on the [What's Next](#whats-next) list.
 
-> "看下我的导入列表里有什么"
+**`npx dsers-mcp-product: command not found` (exit 127)**
+You're working from a local source clone, not the published npm package. Use `node dist/cli.js login` instead — the `npx` binary only resolves after `npm link` or a real install. Run `npm run build` first if `dist/` doesn't exist.
 
-> "我已经推送了哪些商品到店铺？"
-
-> "把这个商品推到我所有店铺"
-
-> "帮我把标题和描述重写一下做 SEO 优化，然后推送"
-
-AI 助手会自己判断调用哪个工具，你不需要知道工具名称或参数。
-
-### 通过 Smithery 安装
-
-```bash
-npx @smithery/cli mcp add @dsersx/product-mcp --client cursor
-```
-
-或在 [smithery.ai/server/@dsersx/product-mcp](https://smithery.ai/server/@dsersx/product-mcp) 浏览和安装。
-
-### 从源码安装
-
-```bash
-git clone https://github.com/lofder/dsers-mcp-product.git
-cd dsers-mcp-product
-npm install
-npm run build
-npm test
-```
-
-### 十三个工具
-
-| # | 工具 | 干什么的 |
-|---|------|---------|
-| 1 | `dsers_store_discover` | 查看你绑定了哪些店铺、有哪些配送方式、定价规则、能用什么规则 |
-| 2 | `dsers_rules_validate` | 先试试定价或标题规则对不对，不会真改东西 |
-| 3 | `dsers_product_import` | 贴个商品链接，可以顺便加定价/标题规则，推送前先给你看预览 |
-| 4 | `dsers_product_preview` | 看一下已经导入的商品 — 标题、价格、变体、库存一目了然 |
-| 5 | `dsers_product_update_rules` | 对已导入的商品修改定价、标题、图片或变体规则（增量合并，不需要重新导入） |
-| 6 | `dsers_product_visibility` | 设置商品在店铺里是上架展示还是隐藏草稿 |
-| 7 | `dsers_store_push` | 把商品推到你的 Shopify 或 Wix 店铺 — 单个推、批量推、或一次推到所有店铺 |
-| 8 | `dsers_job_status` | 看看推送完了没、成功了没 |
-| 9 | `dsers_product_delete` | 从 DSers 导入列表中删除商品（不可恢复，需确认） |
-| 10 | `dsers_import_list` | 浏览导入待推送列表，含成本价、售价、库存、加价状态 |
-| 11 | `dsers_my_products` | 查看已推到店铺的商品，带供应商链接方便重新导入 |
-| 12 | `dsers_find_product` | 在 DSers 商品池搜索，支持关键词和以图搜图，结果可直接导入 |
-| 13 | `dsers_sku_remap` | SKU 级别替换已上架商品的供应商。两种模式：传 `new_supplier_url` 走精确替换，不传则反向图搜 DSers 池 + 多因子打分自动挑最佳替代。务必先用 `mode='preview'`（只读）看 `diffs` 和 `pool_additions`，确认无误后再 `mode='apply'`。需要 `product:mapping` OAuth scope。 |
-
-报错时会返回清晰的消息，AI 助手能看懂出了什么问题、该怎么办。
-
-### 推送前安全校验
-
-推送到店铺之前，工具会自动帮你检查常见问题：
-
-- **直接拦截**（不让推）：售价低于进货成本、零售价为 0、所有变体都没库存
-- **警告提醒**（能推，但会提示你）：利润率低于 10%、库存少于 5 件、售价低于 1 美金
-
-有问题的话，AI 助手会告诉你具体是哪个变体出了什么问题。确定没问题的话可以用 `force_push` 强制推送。
-
-### 定价规则冲突检测
-
-如果你的 DSers 店铺自己启用了**定价规则**（基础/标准/高级），同时你又通过 MCP 设置了定价规则，推送会被**直接拦截**而不是仅警告。AI 助手会给出两个解决方案：
-
-1. 在推送选项中设置 `pricing_rule_behavior='apply_store_pricing_rule'` 接受店铺端的定价规则
-2. 在 DSers 店铺设置中关闭定价规则，使用 MCP 的定价
-
-### 四个预设提示
-
-MCP 客户端可直接展示给用户的工作流模板：
-
-| 提示 | 说明 |
-|------|------|
-| `dsers_workflow_quick-import` | 一键导入单个商品并推送为草稿 |
-| `dsers_workflow_bulk-import` | 批量导入 + 统一定价倍率 |
-| `dsers_workflow_multi-push` | 一个商品推送到所有店铺 |
-| `dsers_workflow_seo-optimize` | 导入后 AI 重写标题和描述做 SEO 优化，再推送 |
-
-### 后续计划
-
-- 商品池搜索增强（分类过滤、URL 搜索、商品详情查看）
-- 支持更多 DSers 已接入的店铺平台（eBay、Wish 等）
-- 更智能的定价规则模板
-- 更精细的库存同步选项
-
-有想法或需求？欢迎 [提 issue](https://github.com/lofder/dsers-mcp-product/issues) —— 非常欢迎其他开发者的建议和贡献。
-
-### 常见问题
-
-**DSers MCP Product 是什么？**
-一个免费开源的 MCP 服务器，让 AI Agent（如 Claude、Cursor）自动完成从速卖通/Alibaba/1688 到 Shopify/Wix 店铺的商品导入全流程。不用手动复制商品数据，用自然语言对话就能操作。
-
-**怎么用？**
-在 Cursor 或 Claude Desktop 里输入"导入这个商品，加价 2.5 倍，推送到我的店铺"，MCP 服务器自动完成抓取商品数据、应用定价规则、编辑变体、推送到店铺的全部流程。
-
-**收费吗？**
-完全免费。项目开源（MIT 协议），你只需要一个免费的 DSers 账号和已连接的 Shopify 或 Wix 店铺。
-
-**安全吗？需要提供密码吗？**
-不需要。登录采用零密码浏览器认证——你在 DSers 官网登录，工具只接收会话令牌，密码永远不会经过 MCP 服务器。项目在 [SafeSkill](https://safeskill.dev/scan/@lofder/dsers-mcp-product) 安全扫描中获得 92/100 分。
-
-**支持哪些 AI 客户端？**
-Cursor、Claude Desktop、Claude Code、Windsurf，以及任何支持 stdio 传输的 MCP 兼容客户端。
-
-**和 AliDropify、AutoDS 等 Dropshipping 工具有什么区别？**
-大多数 Dropshipping 工具有自己的界面，需要点来点去。DSers MCP Product 完全不同——它直接连接你的 AI Agent，用对话代替点击来自动化工作流。而且完全开源免费，没有订阅分级。
-
-**能同时推送到多个店铺吗？**
-可以。`dsers_store_push` 支持一条命令将商品推送到所有已连接的 Shopify 和 Wix 店铺，支持按店铺设置不同的定价和可见性。
-
-### 其他版本
+### Also Available
 
-也提供 [Python 版本](https://github.com/lofder/dsers-mcp-product-py)，适用于本地 stdio 部署。
+A [Python version](https://github.com/lofder/dsers-mcp-product-py) is available as a feature-parity subset for local stdio deployments. The TypeScript version is the primary maintained release — use it first.
 
-### 许可证
+### License
 
 MIT