@sea-ecommerce/admin-mcp-server 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,31 @@
 {
   "name": "@sea-ecommerce/admin-mcp-server",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "让运营同学用本地 AI agent（Codex / Workbuddy / Claude / Cursor / CodeBuddy）运营 Medusa 后台的 MCP server。",
+  "bin": {
+    "derlux-admin-mcp": "dist/derlux-admin-mcp.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skill"
+  ],
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "node scripts/bundle.mjs",
+    "start": "node dist/derlux-admin-mcp.js",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "node scripts/bundle.mjs",
+    "publish:npm": "node scripts/bundle.mjs && npm publish --access public --registry https://registry.npmjs.org"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "@types/node": "^20.14.0",
+    "esbuild": "^0.21.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0",
+    "zod": "^3.23.8"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: derlux-admin-mcp-ops
+description: 运营使用本地 AI agent（derlux-admin MCP server）操作 DERLUX Store 后台的指南。覆盖商品创建/修改/下架、仓库与库存调整、订单/退货/仓库作业查询、后台使用问答。当用户要让 agent 创建、修改或下架商品、调整某仓库库存、查询订单或退货、或询问「后台怎么操作某功能」时使用。
+---
+
+# DERLUX 运营后台 MCP 操作指南（derlux-admin）
+
+> 本文件随 npm 包 `@sea-ecommerce/admin-mcp-server` 一同发布，运营/agent 可经 npm 公开文件链接读取，
+> 例如：`https://unpkg.com/@sea-ecommerce/admin-mcp-server/skill/SKILL.md`
+> 或 `https://cdn.jsdelivr.net/npm/@sea-ecommerce/admin-mcp-server/skill/SKILL.md`
+
+## 你是谁 / 这个 skill 是做什么的
+
+你已接入一个名为 **`derlux-admin`** 的 MCP server。它把 DERLUX Store（面向马来西亚/印尼的东南亚电商，法律主体「香港德樂仕股份有限公司」）Medusa 后台的运营动作封装成一批语义化工具（tool），由你直接调用，代替运营同学在后台界面手动点选。
+
+关键前提（务必记牢）：
+
+- **认证复用真实后台管理员账号**（须持有 `csr` 或 `super_admin` 角色），权限受现有 RBAC 约束。敏感动作若账号无权限，后端会直接拦截。
+- **所有写操作默认是「预览（dry_run）」**，只有显式设 `confirm=true` 才会真正落到后台。这是给运营的兜底保护，不要跳过预览。
+- 每次调用都会写入审计日志 `~/.derlux/mcp-audit.log`，操作可追溯。
+
+## ⚠️ 必须遵守的硬规则（每次调用写工具前自查）
+
+1. **预览优先，确认后执行**：任何写工具先以 `confirm=false`（默认）跑一次，把返回的预览读给运营确认；得到明确确认后，再用 `confirm=true` 真正执行。绝不在未确认时直接写库。
+2. **价格单位 = 主货币单位（元），不要 ×100**：金额直接透传主单位，例如 `200.51` 就是 RM200.51 / MYR200.51。Medusa v2.21 以主单位存储金额，**绝不要写成 20051**。
+3. **Handle 自动归一化**：商品 `handle` 会被自动转小写、空格/下划线/点→连字符、剔除其余非法字符。归一化后仍非法（空或全部被剔除）工具会直接报错，你无需手工处理，但应避免给无意义输入；未填时由 `title` 自动生成。
+4. **多语言必填**：`create_product` / `update_product` 的 `translations` 应覆盖 `en` / `zh` / `ms` / `id` 四种语言的 `title`（建议也带 `description`）。缺语言时：预览会告警；真正写入需 `confirm=true` **且** `acknowledge_missing_languages=true`。创建前主动提醒运营补全翻译，不要默默放行。工具会**自动**把翻译写入 Medusa v2.21 专用的 `/admin/translations/batch` 端点（商品创建体本身不接受 `translations` 字段），你无需手动调用该端点。
+5. **审计可追溯**：无需你处理，但要知道每次动作都在 `~/.derlux/mcp-audit.log` 留痕。
+6. **商品必须挂销售渠道才在前端可见**：新建商品默认**不在任何销售渠道**，storefront（按 publishable key → 渠道过滤）拉不到它，详情页表现成「空/404」。录入后用 `add_product_to_sales_channel`（`confirm=true`）把它加入渠道（默认第一个启用渠道；马来西亚站用 `sc_01M4K4F0D6HBHZ0NH6WB7H5KPT`「MY Storefront」）。
+7. **两套 locale 码，别混**：
+   - 商品标题/描述的**翻译**（`create_product` 的 `translations`、后端 `/admin/translations/batch`）：用**简码** `en` / `zh` / `ms` / `id`。store `/store/products?locale=zh` 即回退到 zh 翻译。
+   - 商品详情页**富内容块**（`create_product_content` 的 `locale`）：必须用**区域码** `en-US` / `zh-CN` / `ms-MY` / `id-ID`（与前端 `useProductContent` 的 localeMap 一致）。用简码会导致该语言详情页读不到内容。
+8. **详情页「富内容」区靠 `create_product_content`，不是 `description`**：storefront 详情页下方大块内容由 `product_content` 模块渲染（`richtext`/`specs`/`image_gallery` 等）。只填 `product.description` 不会显示在那里——录入完整商品时必须再建一份 `product_content`（建议每语言一份）。`get_product` 默认不含该字段，核对请用 `get_product_content`。
+
+## 工具速查表
+
+| 工具 | 类型 | 写库？ | 默认行为 |
+|---|---|---|---|
+| `list_products` | 读 | 否 | 直接返回 |
+| `get_product` | 读 | 否 | 直接返回 |
+| `list_stock_locations` | 读 | 否 | 直接返回 |
+| `get_inventory_levels` | 读 | 否 | 直接返回（按 location_id 列库存条目与水平）|
+| `list_orders` | 读 | 否 | 直接返回 |
+| `get_order` | 读 | 否 | 直接返回 |
+| `list_warehouse_tasks` | 读 | 否 | 直接返回（自定义端点）|
+| `list_return_requests` | 读 | 否 | 直接返回（自定义端点）|
+| `search_docs` | 读 | 否 | 检索后台知识库 |
+| `ask_usage` | 读 | 否 | 回答「后台怎么操作」类问题 |
+| `create_product` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+| `update_product` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+| `deactivate_product` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，置 `archived` |
+| `upload_product_image` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，给已有商品追加图片 |
+| `add_product_to_sales_channel` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，把商品加入销售渠道使其在前端可见 |
+| `create_product_content` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览，写商品详情页富内容块（hero/richtext/image_gallery/video/faq/specs）|
+| `get_product_content` | 读 | 否 | 读取某商品某语言的富内容块 |
+| `create_stock_location` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+| `update_inventory_level` | 写 | 是（`confirm=true` 才写）| `confirm=false` → 仅预览 |
+
+## 各工具参数与说明
+
+### 读 —— 商品
+- **`list_products`**：查询商品列表。
+  - `q`（string，可选）关键词；`status`（enum：`draft|published|proposed|rejected|archived`，可选）状态过滤；`handle`（string，可选）；`limit`（int 1–100，默认 20）。
+- **`get_product`**：按商品 id 或 handle 获取详情。
+  - `id_or_handle`（string，**必填**）。
+
+### 读 —— 仓库与库存
+- **`list_stock_locations`**：列出仓库（StockLocation）。
+  - `q`（string，可选）按名称过滤；`limit`（int 1–100，默认 50）。
+- **`get_inventory_levels`**：列出某仓库下的库存条目及库存水平。
+  - `location_id`（string，**必填**）；`q`（string，可选）；`limit`（int 1–100，默认 50）。
+
+### 读 —— 订单 / 履约 / 退货
+- **`list_orders`**：查询订单列表。
+  - `q`（string，可选）；`status`（string，可选）；`limit`（int 1–100，默认 20）。
+- **`get_order`**：按订单 id 或 `display_id` 获取详情。
+  - `id`（string，**必填**）。
+- **`list_warehouse_tasks`**：查询仓库作业任务（自定义端点 `/admin/warehouse-tasks`）。
+  - `order_id`（string，可选）；`stage`（string，可选）；`limit`（int 1–200，默认 200）。
+- **`list_return_requests`**：查询退货/售后请求（自定义端点 `/admin/return-requests`）。
+  - `status`（string，可选）；`limit`（int 1–100，默认 50）。
+
+### 读 —— 后台知识问答
+- **`search_docs`**：在知识库（docs）中检索相关段落，返回文件、章节与摘要。
+  - `query`（string，**必填**）；`limit`（int 1–20，默认 5）。
+- **`ask_usage`**：回答「后台怎么操作」类问题，返回最相关段落与出处文件。
+  - `question`（string，**必填**）；`limit`（int 1–10，默认 5）。若搜不到，提示运营换关键词或查后台手册。
+
+### 写 —— 商品
+- **`create_product`**：新增商品。
+  - `title`（string，**必填**）；`handle`（string，可选，缺省由 title 归一化）；`status`（enum，默认 `draft`）；`subtitle`（可选）；`description`（可选）；`price`（number ≥0，主货币单位，**切勿 ×100**）；`currency_code`（默认 `MYR`）；`translations`（`record<locale,{title?,description?}>`，建议覆盖 `en/zh/ms/id`）；`images`（string[]，可选，本地图片路径或图片 URL，工具自动上传并挂接）；`sku`（string，可选，写入默认变体 SKU）；`metadata`（`record<string,string>`，可选，存规格参数/来源链接等任意键值）；`confirm`（bool，默认 false）；`acknowledge_missing_languages`（bool，默认 false）。
+  - 行为：`confirm=false` 返回预览（含缺语言清单）；`confirm=true` 才真正创建；缺语言时须同时 `acknowledge_missing_languages=true`。创建时**自动**补上 Medusa v2 必需的 `options`（单一 Default）、把图片上传到文件服务并挂接、把 `sku` 写入默认变体、把 `translations` 写入 v2.21 专用的 `/admin/translations/batch` 端点。
+- **`update_product`**：修改商品字段（标题/handle/状态/描述/多语言）。
+  - `id`（string，**必填**）；`title`/`handle`/`status`/`subtitle`/`description`/`translations`（均可选）；`confirm`（默认 false）。`confirm=false` 返回预览。
+- **`deactivate_product`**：下架商品（status 置 `archived`）。
+  - `id`（string，**必填**）；`confirm`（默认 false）。`confirm=false` 返回预览。
+- **`upload_product_image`**：给**已存在**的商品追加图片（与已有图片合并，不覆盖）。
+  - `product_id`（string，**必填**）；`images`（string[]，本地图片路径或图片 URL）；`confirm`（默认 false）。`confirm=false` 仅预览；`confirm=true` 才上传并挂接。
+- **`add_product_to_sales_channel`**：把商品加入销售渠道，使其在前端商城可见。
+  - `product_ids`（string[]，**必填**，商品 id 列表）；`channel_id`（string，可选，省略则取第一个启用渠道）；`confirm`（默认 false）。`confirm=false` 仅预览。
+- **`get_product_content`**：读取商品详情页富内容块。
+  - `product_id`（string，**必填**）；`locale`（`en-US` / `zh-CN` / `ms-MY` / `id-ID`，默认 `en-US`）；`status`（`draft` / `published`，默认 `published`）。返回 `{ product_content: { id, product_id, locale, status, blocks(已解析数组) } | null }`。
+- **`create_product_content`**：创建/更新商品详情页富内容块（按 `product_id` + `locale` upsert）。**这是填充详情页主体内容的工具**——只填 `description` 详情页大块区域仍是空白。
+  - `product_id`（string，**必填**）；`locale`（区域码，默认 `en-US`，见硬规则 7）；`status`（默认 `published`）；`blocks`（ContentBlock[]，**必填**）；`confirm`（默认 false）。
+  - 区块 `type` 与 `data`：
+    - `richtext`：`data.{ html }`（直接渲染 HTML，可含 `<p>/<h2>/<ul>`）
+    - `image_gallery`：`data.{ images:string[], caption? }`
+    - `hero`：`data.{ image?, title?, subtitle? }`
+    - `video`：`data.{ url, poster? }`（支持 YouTube）
+    - `faq`：`data.{ items: {question,answer}[] }`
+    - `specs`：`data.{ rows: {label,value}[] }`
+  - `confirm=false` 返回预览（含块数量与类型）；`confirm=true` 才写入。
+
+### 写 —— 仓库与库存
+- **`create_stock_location`**：新增仓库（StockLocation）。
+  - `name`（string，**必填**）；`address`（可选：`{address_1?,address_2?,city?,country_code?,province?,postal_code?,phone?}`）；`metadata`（`record<string,string>`，可选）；`confirm`（默认 false）。
+- **`update_inventory_level`**：修改某库存条目在指定仓库的库存数量（`stocked_quantity`）。
+  - `inventory_item_id`（string，**必填**）；`location_id`（string，**必填**）；`stocked_quantity`（int ≥0，**必填**）；`confirm`（默认 false）。底层走 `POST /admin/inventory-items/{id}/location-levels`，字段/端点以 Medusa 2.21 契约为准。
+
+## 推荐操作流程（SOP）
+
+**创建商品**
+1. 先收集：标题、handle（或告知由标题生成）、价格（主单位）、四语言标题、状态、图片、规格、详情页富文本内容（按语言）。
+2. 调用 `create_product`（`confirm=false`）→ 展示预览与「缺语言」告警。
+3. 提醒运营补全缺失语言；确认无误后调用 `create_product`（`confirm=true`，必要时 `acknowledge_missing_languages=true`）。
+4. **`add_product_to_sales_channel`（`confirm=true`）** → 把商品加入销售渠道，否则前端看不到。
+5. **`create_product_content`（`confirm=true`，逐语言 `en-US/zh-CN/ms-MY/id-ID`）** → 写详情页富内容块（richtext 描述 + specs 规格 + image_gallery 图集）。否则详情页主体空白。
+6. 把返回的新商品 id/handle 告知运营。
+
+**修改 / 下架商品**
+1. `get_product` 或 `list_products` 确认目标 id。
+2. `update_product` / `deactivate_product`（`confirm=false`）→ 展示预览。
+3. 确认后同名工具 `confirm=true` 执行。
+
+**调整库存**
+1. `list_stock_locations` 拿到 `location_id`；`get_inventory_levels` 拿到 `inventory_item_id`。
+2. `update_inventory_level`（`confirm=false`）→ 展示将写入的数量。
+3. 确认后 `confirm=true` 执行。
+
+**查询类**：直接调用对应读工具即可，无需 `confirm`。
+
+## 常见任务示例（运营怎么说 / 你怎么调）
+
+- 「下架 handle 为 `summer-serum` 的商品」→ `get_product`(id_or_handle=`summer-serum`) 取 id → `deactivate_product`(id, confirm=false 预览 → 确认后 confirm=true)。
+- 「给马来西亚仓的 A 商品加 50 件库存」→ `list_stock_locations` 找 MY 仓 → `get_inventory_levels`(location_id) 找 A 的 inventory_item_id → `update_inventory_level`(confirm=false 预览 → 确认后 confirm=true)。
+- 「查一下最近 10 个待发货订单」→ `list_orders`(status=`pending`, limit=10)。
+- 「后台怎么新建优惠券」→ `ask_usage`(question=`如何新建优惠券`)。
+- 「列出所有退货请求」→ `list_return_requests`()。
+- 「把这份抓取的 Lazada 商品录入：标题 DR.CYJ Hair Filler、价格 420 MYR、4 张本地图 `/Users/fire/temp/images/product_1..4.webp`、SKU `4820...`、规格存 metadata、并补全中/马来/印尼语翻译」→ 先整理数据，再 `create_product`（`confirm=false` 看预览含 images/sku/metadata/缺语言清单 → 确认后 `confirm=true`，必要时 `acknowledge_missing_languages=true`）。工具会自动上传图片、写 SKU/metadata、并把四语言简码翻译写入翻译端点。随后 `add_product_to_sales_channel`(`confirm=true`) 让前端可见，再 `create_product_content`(`locale=en-US/zh-CN/ms-MY/id-ID`, `confirm=true`) 逐语言写富内容块（richtext 描述 + specs 规格 + image_gallery 图集）。
+- 「让这个商品在前端能搜到」→ `get_product` 取 id → `add_product_to_sales_channel`(`product_ids=[id]`, `confirm=true`)。
+- 「补全某商品中文详情页内容」→ `create_product_content`(`product_id`, `locale=zh-CN`, `blocks=[{type:'richtext',data:{html:'...'}},{type:'specs',data:{rows:[...]}}]`, `confirm=true`)。可用 `get_product_content` 先核对现状。
+
+## 给运营的一次性安装配置
+
+agent 客户端（Codex / Claude Desktop / Cursor / Workbuddy / CodeBuddy 等）的 MCP 配置里加一条即可（机器只需 Node ≥ 18，无需 clone 仓库、无需 build）：
+
+```json
+{
+  "mcpServers": {
+    "derlux-admin": {
+      "command": "npx",
+      "args": ["-y", "@sea-ecommerce/admin-mcp-server"],
+      "env": {
+        "MEDUSA_BACKEND_URL": "https://admin.internal.derlux.com",
+        "DERLUX_ADMIN_EMAIL": "你的后台账号",
+        "DERLUX_ADMIN_PASSWORD": "你的密码"
+      }
+    }
+  }
+}
+```
+
+### 环境变量说明
+
+| 变量 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `MEDUSA_BACKEND_URL` | 否 | `http://localhost:9000` | 后端地址（生产填内部域名）|
+| `DERLUX_ADMIN_EMAIL` | **是** | — | 后台管理员账号（须持 `csr`/`super_admin`）|
+| `DERLUX_ADMIN_PASSWORD` | **是** | — | 该账号密码 |
+| `DERLUX_AUTH_PATH` | 否 | `/auth/user/emailpass` | 登录端点 |
+| `DERLUX_SESSION_FILE` | 否 | `~/.derlux/mcp-session` | 会话持久化文件（权限 0600）|
+| `DERLUX_AUDIT_FILE` | 否 | `~/.derlux/mcp-audit.log` | 审计日志 |
+| `DERLUX_DOCS_DIR` | 否 | `./docs` | 问答知识源目录（npx 形态下通常留默认或指向本地 docs 副本）|
+| `DERLUX_REQUIRED_LOCALES` | 否 | `en,zh,ms,id` | 商品必须覆盖的语言 |
+
+## 已知限制 / 注意事项
+
+- 本 MCP **不改动任何数据库 schema**，仅复用现有 `/admin/*` 接口；运营动作本身按既有逻辑写库。
+- 登录走**用户账号**而非 API Key（现有 RBAC 依赖 `user.metadata.rbac_roles`）。
+- 金额以**主货币单位**存储（见上「硬规则 2」），不要换算成分。
+- **Medusa v2.21 差异（重要）**：
+  - 有变体就必须有 product options，工具已自动补一个 `Default` 选项，你无需关心。
+  - 商品创建/更新体**不接受 `translations` 字段**；翻译由工具自动走 `/admin/translations/batch`。`get_product` 默认字段不含 `translations` 关系，想核对翻译请用 `ask_usage` 或后台「多语言」面板，不要凭 `get_product` 返回为空就误判没写入。
+  - 图片走 `/admin/uploads` 上传后再挂到商品（无独立 `/admin/products/{id}/images` 端点）。
+- 库存写入的端点/字段以 Medusa 2.21 契约为准；自定义端点 `warehouse-tasks` / `return-requests` 为本项目扩展。
+- 文档问答（`search_docs` / `ask_usage`）依赖知识源目录；npx 形态下默认 `./docs`，若问不到相关内容，提示运营换关键词或查后台手册。
+- 用受限的 `csr` 账号即可完成日常运营；敏感动作由后端 RBAC 拦截。