@lofder/dsers-mcp-product 1.0.2 → 1.3.8

package/README.md

@@ -1,11 +1,12 @@
-# DSers MCP Product — Automate Dropshipping AI tools/AliExpress to Shopify & Wix Import
+# DSers MCP Product — Dropshipping Automation: AliExpress to Shopify & Wix with AI
 
+[![SafeSkill](https://img.shields.io/badge/SafeSkill-92%2F100-brightgreen)](https://safeskill.dev/scan/@lofder/dsers-mcp-product)
 [![Smithery](https://smithery.ai/badge/@dsersx/product-mcp)](https://smithery.ai/server/@dsersx/product-mcp)
 [![npm](https://img.shields.io/npm/v/@lofder/dsers-mcp-product)](https://www.npmjs.com/package/@lofder/dsers-mcp-product)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-blue)](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product)
 [![Glama](https://glama.ai/mcp/servers/lofder/dsers-mcp-product/badges/score.svg)](https://glama.ai/mcp/servers/lofder/dsers-mcp-product)
 
-> An open-source MCP server to automate DSers product import, bulk edit variants, and push to Shopify or Wix using AI.
+> An open-source MCP server to automate DSers product sourcing, import, bulk edit, and push to Shopify or Wix using AI.
 
 > [English](#english) | [中文](#中文)
 
@@ -15,9 +16,55 @@
 
 ## 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 AliExpress / Alibaba / 1688 product URL to Shopify or Wix store listing. Bulk import, batch edit variants, clean AliExpress titles, 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 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.
 
-The server is hosted on [Vercel](https://dsers-mcp-product.vercel.app/api/mcp), published on [Smithery](https://smithery.ai/server/@dsersx/product-mcp), [npm](https://www.npmjs.com/package/@lofder/dsers-mcp-product), and the official [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product).
+#### What can it do?
+
+- **Product sourcing** — search the DSers product pool by keyword or image, find products to sell
+- **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
+- **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
+- **SEO optimization** — let AI rewrite the title and description for better search rankings before pushing
+
+The server is hosted on [Vercel](https://dsers-mcp-product.vercel.app/api/mcp) and published across multiple platforms:
+
+### Available On
+
+| Platform | Link |
+|----------|------|
+| npm | [npmjs.com/package/@lofder/dsers-mcp-product](https://www.npmjs.com/package/@lofder/dsers-mcp-product) |
+| MCP Registry (Official) | [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 | [Article: 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 | [Tutorial: 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) |
+
+### 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.)
+
+### 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.
+
+**How to use it with DSers MCP:**
+
+1. Go to [accio.com](https://www.accio.com/) 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`
+4. Give that link to your AI agent, e.g.: *"Import this product and push to my store: [paste URL]"*
+5. The agent handles the rest — no extra setup needed.
+
+This works for both AliExpress and Alibaba products found on Accio.
 
 ### Documentation
 
@@ -26,33 +73,85 @@ The server is hosted on [Vercel](https://dsers-mcp-product.vercel.app/api/mcp),
 | [ARCHITECTURE.md](ARCHITECTURE.md) | Three-layer architecture, directory structure, data flow |
 | [USAGE.md](USAGE.md) | Installation, client config (Cursor, Claude Desktop), scenario examples |
 | [SKILL.md](SKILL.md) | AI agent instruction file — workflow, rules, push options, error handling |
-| [SKILL-CN.md](SKILL-CN.md) | Chinese human-readable guide for SKILL.md |
 
-### Install via npm
+### What You Need
+
+- A [DSers](https://www.dsers.com/) 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), [Windsurf](https://codeium.com/windsurf), or any client that supports MCP
+
+### Quick Start
+
+**Step 1: Log in (one time — opens your browser)**
 
 ```bash
-npx @lofder/dsers-mcp-product
+npx @lofder/dsers-mcp-product login
 ```
 
-Set environment variables `DSERS_EMAIL` and `DSERS_PASSWORD` before running, or add to your MCP client config:
+A browser window opens to the official DSers login page. You log in on DSers's own website — your password **never** passes through this tool. After login, the session is encrypted and saved locally.
+
+**Step 2: Add to your MCP client (no credentials needed)**
 
 ```json
 {
   "mcpServers": {
     "dsers-mcp-product": {
       "command": "npx",
-      "args": ["-y", "@lofder/dsers-mcp-product"],
-      "env": {
-        "DSERS_EMAIL": "your-email",
-        "DSERS_PASSWORD": "your-password"
-      }
+      "args": ["-y", "@lofder/dsers-mcp-product"]
     }
   }
 }
 ```
 
+That's it. No passwords in config files.
+
 Also listed on the official [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product).
 
+### Authentication — Zero-Password Login
+
+Your DSers password **never touches this tool**. Here's how login works:
+
+1. You run `npx @lofder/dsers-mcp-product login`
+2. Your browser opens the official DSers login page
+3. You log in on DSers's own website, as usual
+4. The tool picks up your login session and encrypts it locally
+5. Done — from now on, the MCP server just works. No passwords in any config file.
+
+Works with Chrome, Edge, Brave, and other Chromium browsers. On Mac, Safari works too.
+
+**Sessions last about 6 hours.** When it expires, your AI agent will ask you to run `login` again — takes 10 seconds.
+
+**Switching accounts?**
+
+```bash
+npx @lofder/dsers-mcp-product logout
+npx @lofder/dsers-mcp-product login
+```
+
+> **For developers:** The server also accepts a `DSERS_TOKEN` env var for headless/CI environments. For most users, just use `login`.
+
+### Usage Examples
+
+Once set up, just talk to your AI agent in plain language:
+
+> "Import this product and push to my Shopify store as a draft: https://www.aliexpress.com/item/1005006372921430.html"
+
+> "Import this product, mark up the price by 2.5x, and push it: https://www.aliexpress.com/item/1005006372921430.html"
+
+> "Batch import these 3 products and push them all to my store: [URL1] [URL2] [URL3]"
+
+> "Search for phone cases under $5 on the DSers product pool"
+
+> "Show me what's in my import list"
+
+> "What products have I pushed to my store?"
+
+> "Push this product to all my connected stores"
+
+> "Rewrite the title and description for SEO, then push to my store"
+
+The agent figures out the right tools to call. You don't need to know tool names or parameters.
+
 ### Install via Smithery
 
 ```bash
@@ -64,21 +163,11 @@ Or browse at [smithery.ai/server/@dsersx/product-mcp](https://smithery.ai/server
 ### Install from Source
 
 ```bash
-# Clone
 git clone https://github.com/lofder/dsers-mcp-product.git
 cd dsers-mcp-product
-
-# Install
 npm install
-
-# Configure (copy and fill in your DSers credentials)
-cp .env.example .env
-
-# Type check
-npx tsc --noEmit
-
-# Run with Smithery dev
-npx @smithery/cli dev ./src/index.ts
+npm run build
+npm test
 ```
 
 ### Project Structure
@@ -86,71 +175,132 @@ npx @smithery/cli dev ./src/index.ts
 ```
 dsers-mcp-product/
 ├── src/
-│   ├── index.ts              # MCP server entry — tool registration
-│   ├── service.ts            # Import flow orchestration (7 operations)
-│   ├── provider.ts           # DSers API adapter
+│   ├── cli.ts                # npx entry — stdio transport, login/logout
+│   ├── index.ts              # MCP server init, tool registration
+│   ├── instructions.ts       # Server-level prompts (agent instructions)
+│   ├── tools.ts              # 12 MCP tools — schema + handler
 │   ├── rules.ts              # Rule validation & application engine
+│   ├── push-guard.ts         # Pre-push safety checks
 │   ├── push-options.ts       # Push option normalization
-│   ├── resolver.ts           # URL normalization (AliExpress/Alibaba/1688)
-│   ├── job-store.ts          # File-based job persistence
-│   └── dsers/                # Low-level DSers API wrappers
-│       ├── config.ts         # Configuration & environment
-│       ├── auth.ts           # Login, session cache, auto-refresh
-│       ├── client.ts         # Authenticated HTTP client
-│       ├── account.ts        # Store & user management APIs
-│       ├── product.ts        # Import list & push APIs
-│       └── settings.ts       # Shipping, pricing, billing APIs
-├── test/                     # Smoke tests
-├── smithery.yaml             # Smithery runtime config
+│   ├── resolver.ts           # URL normalization (AliExpress/Alibaba/Accio)
+│   ├── provider/             # DSers API adapter (split by concern)
+│   │   ├── index.ts          # Provider class + interface
+│   │   ├── store.ts          # Store discovery, platform detection
+│   │   ├── import-ops.ts     # Import, save draft, delete
+│   │   ├── push.ts           # Push execution, shipping logistics
+│   │   ├── normalize.ts      # Data normalization
+│   │   └── helpers.ts        # Shared utilities
+│   ├── service/              # Business logic orchestration
+│   │   ├── index.ts          # ImportFlowService class
+│   │   ├── import-flow.ts    # Import workflows
+│   │   ├── push-flow.ts      # Push workflows
+│   │   ├── preview.ts        # Preview & visibility
+│   │   ├── status.ts         # Job status & deletion
+│   │   ├── import-list.ts    # Import list browsing (with enrich)
+│   │   ├── my-products.ts    # Pushed products browsing
+│   │   └── find-product.ts   # Product pool search
+│   ├── dsers/                # Low-level DSers API wrappers
+│   │   ├── config.ts         # Configuration
+│   │   ├── auth.ts           # Session management
+│   │   ├── client.ts         # Authenticated HTTP client
+│   │   ├── account.ts        # Store & user APIs
+│   │   ├── product.ts        # Product & import APIs
+│   │   └── settings.ts       # Shipping, pricing, billing APIs
+│   └── auth/                 # Browser login (CDP)
+├── test/                     # Vitest unit tests (298 tests)
 ├── package.json
-├── tsconfig.json
-└── .env.example
+└── tsconfig.json
 ```
 
-### Seven Tools
+### Twelve Tools
 
-| # | Tool | Title | Description |
-|---|------|-------|-------------|
-| 1 | `dsers.store.discover` | DSers Store & Rule Discovery | Discover stores, shipping profiles, supported rules |
-| 2 | `dsers.rules.validate` | Pricing & Content Rule Validator | Dry-run rule validation |
-| 3 | `dsers.product.import` | AliExpress / Alibaba / 1688 Import | Import from URL(s), apply rules, get preview; re-apply mode via job_id |
-| 4 | `dsers.product.preview` | Import Draft Preview | Reload a saved preview |
-| 5 | `dsers.product.visibility` | Shopify / Wix Visibility Toggle | Toggle draft / published |
-| 6 | `dsers.store.push` | Push to Shopify / Wix Store | Push single/batch/multi-store |
-| 7 | `dsers.job.status` | Job Status Tracker | Check push result |
+| # | 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 |
 
-All tools include MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) and return structured error messages with `{Error, Cause, Action}` for AI agent consumption. `dsers.store.discover` also returns `account_info` with AliExpress authorization status and plan limits.
+All tools return clear error messages so your AI agent knows what went wrong and what to do next.
 
-### Four Prompts
+### Pre-Push Safety Checks
 
-Pre-built workflow templates that MCP clients can present to users:
+Before pushing a product to your store, the tool automatically checks for common mistakes:
 
-| Prompt | Description |
-|--------|-------------|
-| `dsers.workflow.quick-import` | Import a single product and push to store as draft |
-| `dsers.workflow.bulk-import` | Batch import with pricing multiplier |
-| `dsers.workflow.multi-push` | Push one product to all connected stores |
-| `dsers.workflow.seo-optimize` | Import, AI-rewrite title & description for SEO, then push |
+- **Hard blocks** (push won't go through): selling below supplier cost, zero sell price, all variants out of stock
+- **Warnings** (push goes through, but you'll see a heads-up): profit margin below 10%, stock under 5 units, sell price under $1
 
-### Credentials
+If something looks wrong, your AI agent will tell you exactly which variant has the problem and why. If you're sure it's fine, you can override with `force_push`.
 
-The server supports two credential sources (checked in order):
+### Pricing Rule Conflict Detection
 
-1. **HTTP headers** `x-dsers-email` / `x-dsers-password` — used by Smithery and direct HTTP connections
-2. **Environment variables** `DSERS_EMAIL` / `DSERS_PASSWORD` — used by local stdio (Cursor, Claude Desktop)
+If your DSers store has its own **Pricing Rule** enabled (basic/standard/advanced), and you also set pricing rules through MCP, the push will be **blocked** — not just warned. The agent will show two fix options:
 
-See [USAGE.md](USAGE.md) for setup details per connection method.
+1. Set `pricing_rule_behavior='apply_store_pricing_rule'` in push options to accept the store's pricing rule
+2. Disable the Pricing Rule in your DSers store settings to use MCP pricing instead
+
+### Four Prompts
+
+Ready-made workflows your AI client can use directly:
+
+| Prompt | Description |
+|--------|-------------|
+| `dsers_workflow_quick-import` | Import a single product and push to store as draft |
+| `dsers_workflow_bulk-import` | Batch import with pricing multiplier |
+| `dsers_workflow_multi-push` | Push one product to all connected stores |
+| `dsers_workflow_seo-optimize` | Import, AI-rewrite title & description for SEO, then push |
 
 ### Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `DSERS_EMAIL` | Yes* | DSers account email (*or provide via HTTP header) |
-| `DSERS_PASSWORD` | Yes* | DSers account password (*or provide via HTTP header) |
 | `DSERS_ENV` | No | `production` (default) or `test` |
 | `DSERS_BASE_URL` | No | Override API base URL |
 | `IMPORT_MCP_STATE_DIR` | No | Job state directory (default: `.state`) |
 
+### 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
+
+Got an idea or feature request? [Open an issue](https://github.com/lofder/dsers-mcp-product/issues) — contributions are very welcome.
+
+### FAQ
+
+**What is DSers MCP Product?**
+DSers MCP Product is a free, open-source MCP server that automates dropshipping product imports from AliExpress, Alibaba, and 1688 to Shopify and Wix stores using AI agents like Claude and Cursor. Instead of manually copying product data, you tell your AI agent what to do in plain English.
+
+**How does it work?**
+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.
+
+**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, Windsurf, and any MCP-compatible client that supports stdio transport.
+
+**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).
+
+**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.
@@ -165,9 +315,55 @@ MIT
 
 ## 中文
 
-**DSers MCP Product** 是一个开源的 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 服务器，让 AI Agent 自动完成 DSers 的整个商品导入流程 —— 从速卖通 / Alibaba / 1688 商品链接到 Shopify 或 Wix 店铺上架。批量导入、批量编辑变体、清理速卖通标题、应用定价规则、推送到多个店铺 —— 只需一句话给你的 AI agent。
+**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://dsers-mcp-product.vercel.app/api/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 助手会自动搞定，不需要任何额外设置。
 
-服务已托管在 [Vercel](https://dsers-mcp-product.vercel.app/api/mcp)，并发布到 [Smithery](https://smithery.ai/server/@dsersx/product-mcp)、[npm](https://www.npmjs.com/package/@lofder/dsers-mcp-product) 和官方 [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product)。
+Accio 上搜出来的速卖通和阿里巴巴商品都能用。
 
 ### 文档
 
@@ -176,33 +372,85 @@ MIT
 | [ARCHITECTURE.md](ARCHITECTURE.md) | 三层架构、目录结构、数据流 |
 | [USAGE.md](USAGE.md) | 安装、客户端配置（Cursor、Claude Desktop）、使用场景 |
 | [SKILL.md](SKILL.md) | AI agent 指令文件 — 工作流、规则、推送选项、错误处理 |
-| [SKILL-CN.md](SKILL-CN.md) | SKILL.md 的中文说明 |
 
-### 通过 npm 安装
+### 使用前提
+
+- 一个 [DSers](https://www.dsers.com/) 账号（免费版就行）
+- Shopify 或 Wix 店铺已经在 DSers 里绑定好了
+- 一个支持 MCP 的 AI 客户端 — [Cursor](https://cursor.sh/)、[Claude Desktop](https://claude.ai/desktop)、[Windsurf](https://codeium.com/windsurf) 或其他支持 MCP 的工具
+
+### 快速开始
+
+**第 1 步：登录（一次性操作，会打开浏览器）**
 
 ```bash
-npx @lofder/dsers-mcp-product
+npx @lofder/dsers-mcp-product login
 ```
 
-运行前设置环境变量 `DSERS_EMAIL` 和 `DSERS_PASSWORD`，或在 MCP 客户端配置中添加：
+浏览器会自动打开 DSers 官方登录页。你在 DSers 自己的网站上登录 —— 密码**完全不经过**本工具。登录后 session 加密保存到本地。
+
+**第 2 步：添加到你的 MCP 客户端（不需要密码）**
 
 ```json
 {
   "mcpServers": {
     "dsers-mcp-product": {
       "command": "npx",
-      "args": ["-y", "@lofder/dsers-mcp-product"],
-      "env": {
-        "DSERS_EMAIL": "your-email",
-        "DSERS_PASSWORD": "your-password"
-      }
+      "args": ["-y", "@lofder/dsers-mcp-product"]
     }
   }
 }
 ```
 
+搞定。配置文件里不需要任何密码。
+
 同时已收录到官方 [MCP Registry](https://registry.modelcontextprotocol.io/servers/io.github.lofder/dsers-mcp-product)。
 
+### 授权认证 — 零密码登录
+
+你的 DSers 密码**完全不经过本工具**。登录过程是这样的：
+
+1. 运行 `npx @lofder/dsers-mcp-product login`
+2. 浏览器自动打开 DSers 官方登录页
+3. 你在 DSers 网站上正常登录
+4. 工具拿到登录状态，加密存到本地
+5. 搞定 — 之后 MCP 直接能用，配置文件里不需要写任何密码
+
+支持 Chrome、Edge、Brave 等主流浏览器。Mac 上 Safari 也行。
+
+**登录大约 6 小时有效。** 过期了 AI 助手会提醒你重新跑一下 `login`，10 秒的事。
+
+**换账号？**
+
+```bash
+npx @lofder/dsers-mcp-product logout
+npx @lofder/dsers-mcp-product login
+```
+
+> **开发者注：** headless / CI 环境也支持通过 `DSERS_TOKEN` 环境变量传入凭据。普通用户直接用 `login` 就行。
+
+### 使用示例
+
+装好之后，直接用自然语言跟 AI 助手说就行：
+
+> "帮我导入这个商品，推到我的 Shopify 店铺草稿：https://www.aliexpress.com/item/1005006372921430.html"
+
+> "导入这个商品，加价 2.5 倍，然后推送：https://www.aliexpress.com/item/1005006372921430.html"
+
+> "批量导入这 3 个商品，全部推到店铺：[链接1] [链接2] [链接3]"
+
+> "帮我搜一下 5 美金以下的手机壳"
+
+> "看下我的导入列表里有什么"
+
+> "我已经推送了哪些商品到店铺？"
+
+> "把这个商品推到我所有店铺"
+
+> "帮我把标题和描述重写一下做 SEO 优化，然后推送"
+
+AI 助手会自己判断调用哪个工具，你不需要知道工具名称或参数。
+
 ### 通过 Smithery 安装
 
 ```bash
@@ -214,36 +462,47 @@ npx @smithery/cli mcp add @dsersx/product-mcp --client cursor
 ### 从源码安装
 
 ```bash
-# 克隆
 git clone https://github.com/lofder/dsers-mcp-product.git
 cd dsers-mcp-product
-
-# 安装
 npm install
+npm run build
+npm test
+```
 
-# 配置（复制并填写你的 DSers 账户信息）
-cp .env.example .env
+### 十二个工具
 
-# 类型检查
-npx tsc --noEmit
+| # | 工具 | 干什么的 |
+|---|------|---------|
+| 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 商品池搜索，支持关键词和以图搜图，结果可直接导入 |
 
-# 开发运行
-npx @smithery/cli dev ./src/index.ts
-```
+报错时会返回清晰的消息，AI 助手能看懂出了什么问题、该怎么办。
+
+### 推送前安全校验
 
-### 七个工具
+推送到店铺之前，工具会自动帮你检查常见问题：
 
-| # | 工具 | 标题 | 说明 |
-|---|------|------|------|
-| 1 | `dsers.store.discover` | 店铺与规则发现 | 查询店铺、配送方案、支持的规则 |
-| 2 | `dsers.rules.validate` | 定价与内容规则校验 | 规则校验试运行 |
-| 3 | `dsers.product.import` | 速卖通/Alibaba/1688 导入 | 从 URL 导入、应用规则、获取预览；支持 re-apply 模式 |
-| 4 | `dsers.product.preview` | 导入草稿预览 | 重新加载已保存的预览 |
-| 5 | `dsers.product.visibility` | Shopify/Wix 可见性切换 | 切换草稿 / 上架 |
-| 6 | `dsers.store.push` | 推送到 Shopify/Wix | 单条/批量/多店铺推送 |
-| 7 | `dsers.job.status` | 任务状态跟踪 | 查看推送结果 |
+- **直接拦截**（不让推）：售价低于进货成本、零售价为 0、所有变体都没库存
+- **警告提醒**（能推，但会提示你）：利润率低于 10%、库存少于 5 件、售价低于 1 美金
 
-所有工具均包含 MCP 注解（`readOnlyHint`、`destructiveHint`、`idempotentHint`、`openWorldHint`），错误返回结构化格式 `{Error, Cause, Action}`，方便 AI agent 理解和处理。
+有问题的话，AI 助手会告诉你具体是哪个变体出了什么问题。确定没问题的话可以用 `force_push` 强制推送。
+
+### 定价规则冲突检测
+
+如果你的 DSers 店铺自己启用了**定价规则**（基础/标准/高级），同时你又通过 MCP 设置了定价规则，推送会被**直接拦截**而不是仅警告。AI 助手会给出两个解决方案：
+
+1. 在推送选项中设置 `pricing_rule_behavior='apply_store_pricing_rule'` 接受店铺端的定价规则
+2. 在 DSers 店铺设置中关闭定价规则，使用 MCP 的定价
 
 ### 四个预设提示
 
@@ -251,10 +510,42 @@ MCP 客户端可直接展示给用户的工作流模板：
 
 | 提示 | 说明 |
 |------|------|
-| `dsers.workflow.quick-import` | 一键导入单个商品并推送为草稿 |
-| `dsers.workflow.bulk-import` | 批量导入 + 统一定价倍率 |
-| `dsers.workflow.multi-push` | 一个商品推送到所有店铺 |
-| `dsers.workflow.seo-optimize` | 导入后 AI 重写标题和描述做 SEO 优化，再推送 |
+| `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 店铺，支持按店铺设置不同的定价和可见性。
 
 ### 其他版本
 

package/dist/auth/browser-finder.d.ts

@@ -0,0 +1,6 @@
+export interface BrowserMatch {
+    name: string;
+    path: string;
+}
+export declare function findChromiumBrowser(): BrowserMatch | null;
+//# sourceMappingURL=browser-finder.d.ts.map

package/dist/auth/browser-finder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-finder.d.ts","sourceRoot":"","sources":["../../src/auth/browser-finder.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AA8FD,wBAAgB,mBAAmB,IAAI,YAAY,GAAG,IAAI,CAMzD"}