@sea-ecommerce/admin-mcp-server 0.1.2 → 0.1.4

package/README.md

@@ -17,7 +17,7 @@
 | `update_product_prices` | 替换变体价格（多币种） | 写（dry_run 默认） |
 | `upload_product_image` / `add_product_to_sales_channel` | 追加图片 / 挂渠道 | 写（dry_run 默认） |
 | `create_product_content` / `get_product_content` | 详情页富内容块（hero/richtext/specs/图集/faq/video） | 写 / 读 |
-| `set_product_stock` | 给商品建仓/改库存（自动建库存条目，幂等） | 写（dry_run 默认） |
+| `set_product_stock` | 给商品建仓/改库存（自动建库存条目 + 关联变体，幂等） | 写（dry_run 默认） |
 | `list_stock_locations` / `create_stock_location` | 列 / 增仓库 | 写（dry_run 默认） |
 | `get_inventory_levels` / `update_inventory_level` | 查 / 改库存水平 | 写（dry_run 默认） |
 | `list_orders` / `get_order` | 查订单 | 读 |

package/dist/derlux-admin-mcp.js

@@ -21567,6 +21567,23 @@ function loadConfig() {
     requiredLocales
   };
 }
+var LOCALE_CANON = {
+  en: "en-US",
+  "en-us": "en-US",
+  "en-US": "en-US",
+  zh: "zh-CN",
+  "zh-cn": "zh-CN",
+  "zh-CN": "zh-CN",
+  ms: "ms-MY",
+  "ms-my": "ms-MY",
+  "ms-MY": "ms-MY",
+  id: "id-ID",
+  "id-id": "id-ID",
+  "id-ID": "id-ID"
+};
+function normalizeLocale(input) {
+  return LOCALE_CANON[input] ?? LOCALE_CANON[input.trim().toLowerCase()] ?? null;
+}
 
 // src/auth.ts
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
@@ -21858,6 +21875,19 @@ var MedusaAdminClient = class {
       body
     );
   }
+  /**
+   * 把库存条目关联到变体（POST /admin/products/{pid}/variants/{vid}/inventory-items）。
+   * ⚠️ 关联是「变体能查到库存」的关键：只有关联后，变体的 manage_inventory 才指向该条目，
+   * 且设置 manage_inventory=true 时 Medusa 不会因「无关联条目」而另建同 SKU 条目（撞唯一约束）。
+   * 重复关联会报已存在，调用方应 try/catch 吞掉「已关联」类错误。
+   */
+  linkVariantInventoryItem(productId, variantId, inventoryItemId) {
+    return this.request(
+      "POST",
+      `/admin/products/${encodeURIComponent(productId)}/variants/${encodeURIComponent(variantId)}/inventory-items`,
+      { inventory_item_id: inventoryItemId, required_quantity: 1 }
+    );
+  }
   /**
    * 幂等地设置某库存条目在指定仓库的库存数量：
    * 已有 (item, location) 水平 → 更新；没有 → 创建。
@@ -21912,35 +21942,65 @@ async function applyProductStock(ctx2, opts) {
     location = list.find((l) => /main warehouse/i.test(l.name)) || list[0];
     if (!location) throw new Error("\u6CA1\u6709\u4EFB\u4F55\u53EF\u7528\u4ED3\u5E93\uFF0C\u8BF7\u5148 create_stock_location");
   }
-  let iitem = null;
-  if (variant.sku) {
+  const findItem = async () => {
+    if (!variant.sku) return null;
     const items = await client2.listInventoryItems({ sku: variant.sku, limit: 10 });
-    iitem = (items?.inventory_items || []).find((i) => i.sku === variant.sku) || null;
-  }
-  if (!iitem) {
-    if (!variant.sku) throw new Error(`\u53D8\u4F53\u6CA1\u6709 SKU\uFF0C\u65E0\u6CD5\u5173\u8054\u5E93\u5B58\u6761\u76EE\uFF08\u8BF7\u5148 update_product \u8865 sku\uFF09`);
-    const created = await client2.createInventoryItem({
+    return (items?.inventory_items || []).find((i) => i.sku === variant.sku) || null;
+  };
+  if (opts.manageInventory) {
+    if (!variant.sku) {
+      throw new Error(`\u53D8\u4F53\u6CA1\u6709 SKU\uFF0C\u65E0\u6CD5\u5173\u8054\u5E93\u5B58\u6761\u76EE\uFF08\u8BF7\u5148 update_product \u8865 sku\uFF09`);
+    }
+    let iitem2 = await findItem();
+    if (!iitem2) {
+      const created = await client2.createInventoryItem({
+        sku: variant.sku,
+        title: variant.title || void 0
+      });
+      iitem2 = created?.inventory_item ?? created;
+    }
+    try {
+      await client2.linkVariantInventoryItem(product.id, variant.id, iitem2.id);
+    } catch {
+    }
+    if (Boolean(variant.manage_inventory) !== opts.manageInventory) {
+      await client2.updateProduct(product.id, {
+        variants: [{ id: variant.id, manage_inventory: opts.manageInventory }]
+      });
+    }
+    iitem2 = await findItem() || iitem2;
+    const level = await client2.upsertInventoryLevel(iitem2.id, location.id, opts.quantity);
+    return {
+      product_id: product.id,
+      variant_id: variant.id,
       sku: variant.sku,
-      title: variant.title || void 0
-    });
-    iitem = created?.inventory_item ?? created;
+      location_id: location.id,
+      location_name: location.name,
+      inventory_item_id: iitem2.id,
+      manage_inventory: opts.manageInventory,
+      stocked_quantity: level.stocked_quantity,
+      level_created: level.created
+    };
   }
-  const level = await client2.upsertInventoryLevel(iitem.id, location.id, opts.quantity);
   if (Boolean(variant.manage_inventory) !== opts.manageInventory) {
     await client2.updateProduct(product.id, {
       variants: [{ id: variant.id, manage_inventory: opts.manageInventory }]
     });
   }
+  const iitem = await findItem();
+  if (iitem) {
+    await client2.upsertInventoryLevel(iitem.id, location.id, 0);
+  }
   return {
     product_id: product.id,
     variant_id: variant.id,
     sku: variant.sku,
     location_id: location.id,
     location_name: location.name,
-    inventory_item_id: iitem.id,
-    manage_inventory: opts.manageInventory,
-    stocked_quantity: level.stocked_quantity,
-    level_created: level.created
+    inventory_item_id: iitem?.id ?? null,
+    manage_inventory: false,
+    stocked_quantity: 0,
+    note: "\u5DF2\u5173\u95ED\u5E93\u5B58\u7BA1\u7406\u5E76\u6E05\u96F6\u5E93\u5B58"
   };
 }
 var stockTools = [
@@ -22530,15 +22590,19 @@ metadata \u4E3A**\u5408\u5E76**\u8BED\u4E49\uFF1A\u65B0\u952E\u8986\u76D6\u540C\
   {
     name: "get_product_content",
     description: `\u8BFB\u53D6\u5546\u54C1\u8BE6\u60C5\u9875\u5BCC\u5185\u5BB9\u5757\uFF08GET /admin/product-contents\uFF09\u3002
-locale \u7528\u533A\u57DF\u7801\uFF1Aen-US / zh-CN / ms-MY / id-ID\uFF08\u4E0E\u524D\u7AEF useProductContent \u7684 localeMap \u4E00\u81F4\uFF09\u3002
+locale \u63A5\u53D7\u533A\u57DF\u7801 en-US / zh-CN / ms-MY / id-ID\uFF08\u63A8\u8350\uFF0C\u4E0E\u524D\u7AEF\u4E00\u81F4\uFF09\u6216\u77ED\u7801 en / zh / ms / id\uFF08\u81EA\u52A8\u5F52\u4E00\u5316\u4E3A\u533A\u57DF\u7801\uFF09\u3002
 \u8FD4\u56DE { product_content: { id, product_id, locale, status, blocks(\u5DF2\u89E3\u6790\u6570\u7EC4) } | null }\u3002`,
     schema: {
       product_id: external_exports.string(),
-      locale: external_exports.enum(["en-US", "zh-CN", "ms-MY", "id-ID"]).default("en-US"),
+      locale: external_exports.string().default("en-US").describe("\u533A\u57DF\u7801 en-US/zh-CN/ms-MY/id-ID\uFF0C\u6216\u77ED\u7801 en/zh/ms/id"),
       status: external_exports.enum(["draft", "published"]).default("published")
     },
     async run(input, { client: client2 }) {
-      const data = await client2.getProductContent(input.product_id, input.locale, input.status);
+      const locale = normalizeLocale(input.locale);
+      if (!locale) {
+        return `\u9519\u8BEF\uFF1Alocale "${input.locale}" \u4E0D\u53D7\u652F\u6301\uFF0C\u8BF7\u7528 en-US / zh-CN / ms-MY / id-ID\uFF08\u6216\u77ED\u7801 en/zh/ms/id\uFF09\u3002`;
+      }
+      const data = await client2.getProductContent(input.product_id, locale, input.status);
       const pc = data?.product_content;
       if (!pc) return { product_content: null };
       let blocks = [];
@@ -22561,11 +22625,11 @@ storefront \u8BE6\u60C5\u9875\u300C\u5BCC\u5185\u5BB9\u300D\u533A\u7531\u8FD9\u4
 - video: data.{ url, poster? }\uFF08\u652F\u6301 YouTube\uFF09
 - faq: data.{ items: {question,answer}[] }
 - specs: data.{ rows: {label,value}[] }
-\u26A0\uFE0F locale \u5FC5\u987B\u7528\u533A\u57DF\u7801 en-US / zh-CN / ms-MY / id-ID\uFF08\u4E0E\u524D\u7AEF\u4E00\u81F4\uFF09\uFF1B\u5546\u54C1\u6807\u9898/\u63CF\u8FF0\u7684\u7FFB\u8BD1\u7528\u77ED\u7801 en/zh/ms/id\uFF0C\u4E8C\u8005\u4E0D\u540C\u3002
+\u26A0\uFE0F locale \u7528\u533A\u57DF\u7801 en-US / zh-CN / ms-MY / id-ID\uFF08\u4E0E\u524D\u7AEF\u4E00\u81F4\uFF0C\u63A8\u8350\uFF09\uFF1B\u4E5F\u63A5\u53D7\u77ED\u7801 en/zh/ms/id\uFF08\u81EA\u52A8\u5F52\u4E00\u5316\u4E3A\u533A\u57DF\u7801\uFF09\u3002\u5546\u54C1\u6807\u9898/\u63CF\u8FF0\u7684\u7FFB\u8BD1\u7528\u77ED\u7801\uFF0C\u4E8C\u8005\u4E0D\u540C\u3002
 \u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
     schema: {
       product_id: external_exports.string(),
-      locale: external_exports.enum(["en-US", "zh-CN", "ms-MY", "id-ID"]).default("en-US"),
+      locale: external_exports.string().default("en-US").describe("\u533A\u57DF\u7801 en-US/zh-CN/ms-MY/id-ID\uFF0C\u6216\u77ED\u7801 en/zh/ms/id"),
       status: external_exports.enum(["draft", "published"]).default("published"),
       blocks: external_exports.array(
         external_exports.object({
@@ -22577,12 +22641,16 @@ storefront \u8BE6\u60C5\u9875\u300C\u5BCC\u5185\u5BB9\u300D\u533A\u7531\u8FD9\u4
       confirm: external_exports.boolean().default(false)
     },
     async run(input, { client: client2 }) {
+      const locale = normalizeLocale(input.locale);
+      if (!locale) {
+        return `\u9519\u8BEF\uFF1Alocale "${input.locale}" \u4E0D\u53D7\u652F\u6301\uFF0C\u8BF7\u7528 en-US / zh-CN / ms-MY / id-ID\uFF08\u6216\u77ED\u7801 en/zh/ms/id\uFF09\u3002`;
+      }
       if (!input.confirm) {
         return {
           dry_run: true,
           will_create: {
             product_id: input.product_id,
-            locale: input.locale,
+            locale,
             status: input.status,
             block_count: input.blocks.length,
             types: input.blocks.map((b) => b.type)
@@ -22591,7 +22659,7 @@ storefront \u8BE6\u60C5\u9875\u300C\u5BCC\u5185\u5BB9\u300D\u533A\u7531\u8FD9\u4
       }
       const data = await client2.createProductContent({
         product_id: input.product_id,
-        locale: input.locale,
+        locale,
         status: input.status,
         blocks: input.blocks
       });
@@ -22779,7 +22847,7 @@ var config2 = loadConfig();
 var auth = new AuthManager(config2);
 var client = new MedusaAdminClient(config2, auth);
 var ctx = { client, config: config2 };
-var server = new McpServer({ name: "derlux-admin", version: "0.1.2" });
+var server = new McpServer({ name: "derlux-admin", version: "0.1.4" });
 for (const def of toolDefs) {
   server.tool(def.name, def.description, def.schema, async (args) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sea-ecommerce/admin-mcp-server",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "private": false,
   "type": "module",
   "description": "让运营同学用本地 AI agent（Codex / Workbuddy / Claude / Cursor / CodeBuddy）运营 Medusa 后台的 MCP server。",

package/skill/SKILL.md

@@ -29,7 +29,7 @@ description: 运营使用本地 AI agent（derlux-admin MCP server）操作 DERL
 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 一致）。用简码会导致该语言详情页读不到内容。
+   - 商品详情页**富内容块**（`create_product_content` / `get_product_content` 的 `locale`）：推荐用**区域码** `en-US` / `zh-CN` / `ms-MY` / `id-ID`（与前端 `useProductContent` 的 localeMap 一致）；**简码 `en`/`zh`/`ms`/`id` 也会被工具自动归一化为区域码**，两种写法都能命中，但请统一用区域码避免歧义。
 8. **详情页「富内容」区靠 `create_product_content`，不是 `description`**：storefront 详情页下方大块内容由 `product_content` 模块渲染（`richtext`/`specs`/`image_gallery` 等）。只填 `product.description` 不会显示在那里——录入完整商品时必须再建一份 `product_content`（建议每语言一份）。`get_product` 默认不含该字段，核对请用 `get_product_content`。
 9. **不建库存 = 前端缺货**：变体 `manage_inventory` 默认 `true`，但新商品默认 0 库存——`create_product` 时必须给 `initial_stock`（如 `{quantity:100}`，默认写 Main Warehouse），或对已有商品调 `set_product_stock`，否则前台显示缺货、无法下单。
 10. **多语言核对用 `get_translations`**：`get_product` 默认字段**不含** translations，不要凭它为空就判断没翻译。用 `get_translations`(reference_id=商品id或handle) 读取实际写入的各语言 title/description。
@@ -130,7 +130,9 @@ description: 运营使用本地 AI agent（derlux-admin MCP server）操作 DERL
   - `name`（string，**必填**）；`address`（可选：`{address_1?,address_2?,city?,country_code?,province?,postal_code?,phone?}`）；`metadata`（`record<string,string>`，可选）；`confirm`（默认 false）。
 - **`set_product_stock`**：给商品建仓/改库存（**运营最常用的库存工具**，幂等）。
   - `product_id`（string，**必填**，商品 id 或 handle）；`sku`（string，可选，目标变体；省略取第一个变体）；`location_id`（string，可选，省略=Main Warehouse/第一个仓库）；`quantity`（int ≥0，**必填**，绝对值非增量）；`manage_inventory`（bool，默认 true）；`confirm`（默认 false）。
-  - 行为：按变体 SKU 查找库存条目（缺失则自动 `POST /admin/inventory-items` 创建）→ 幂等写 (条目, 仓库) 库存水平（有则更新、无则创建）→ 确保变体 `manage_inventory` 为 true。重复调用安全。
+  - 行为（`manage_inventory=true`）：按变体 SKU 查库存条目（缺失则自动创建）→ **关联条目到变体**（`POST .../variants/{id}/inventory-items`，已关联则忽略）→ 置变体 `manage_inventory=true` → 幂等写 (条目, 仓库) 库存水平。重复调用安全。
+  - ⚠️ 「关联」是变体能查到库存的关键：只建条目不关联，前台仍显示缺货。本工具已自动处理关联，运营无需关心。
+  - （`manage_inventory=false`）关闭库存管理并把库存清零。
 - **`update_inventory_level`**：直接改某**库存条目**（`inventory_item_id`）在某仓库的数量（upsert，幂等）。
   - `inventory_item_id`（string，**必填**）；`location_id`（string，**必填**）；`stocked_quantity`（int ≥0，**必填**）；`confirm`（默认 false）。已知 `inventory_item_id` 时用；否则优先 `set_product_stock`。
 
@@ -209,7 +211,7 @@ agent 客户端（Codex / Claude Desktop / Cursor / Workbuddy / CodeBuddy 等）
   - 有变体就必须有 product options，工具已自动补一个 `Default` 选项，你无需关心；**更新**商品时 `options` 字段被移除（2.16+），工具不会误传。
   - 商品创建/更新体**不接受 `translations` 字段**；翻译由工具自动走 `/admin/translations/batch`。`get_product` 默认字段不含 `translations` 关系，**核对翻译请用 `get_translations`**，不要凭 `get_product` 返回为空就误判没写入。
   - 图片走 `/admin/uploads` 上传后再挂到商品（无独立 `/admin/products/{id}/images` 端点）。
-  - 库存查询/写入端点已按 2.21 契约校准（`/admin/inventory-items` + `location-levels`，sku 唯一约束）；`set_product_stock` 全程幂等可重放。
+  - 库存查询/写入端点已按 2.21 契约校准（`/admin/inventory-items` + `location-levels`，sku 唯一约束）；`set_product_stock` 会**关联条目↔变体**并幂等可重放（变体只有关联到库存条目，前台才显示有货；只建条目不关联会撞唯一约束或前台缺货，工具已自动处理）。
 - 自定义端点 `warehouse-tasks` / `return-requests` / `product-contents` 为本项目扩展。
 - 文档问答（`search_docs` / `ask_usage`）依赖知识源目录；npx 形态下默认 `./docs`，若问不到相关内容，提示运营换关键词或查后台手册。
 - 用受限的 `csr` 账号即可完成日常运营；敏感动作由后端 RBAC 拦截。