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

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

@@ -21858,6 +21858,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 +21925,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 = [
@@ -22779,7 +22822,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.3" });
 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.3",
   "private": false,
   "type": "module",
   "description": "让运营同学用本地 AI agent（Codex / Workbuddy / Claude / Cursor / CodeBuddy）运营 Medusa 后台的 MCP server。",

package/skill/SKILL.md

@@ -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 拦截。