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

package/README.md

@@ -11,9 +11,15 @@
 | 工具 | 说明 | 写操作 |
 |---|---|---|
 | `list_products` / `get_product` | 查商品 | 读 |
-| `create_product` / `update_product` / `deactivate_product` | 增 / 改 / 下线商品 | 写（dry_run 默认） |
+| `list_sales_channels` / `list_collections` | 列渠道 / 集合 | 读 |
+| `get_translations` | 查多语言翻译（核对翻译用） | 读 |
+| `create_product` / `update_product` / `deactivate_product` | 增 / 改 / 下线商品（含图片、SKU、渠道、物理/海关字段、metadata 合并） | 写（dry_run 默认） |
+| `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 默认） |
 | `list_stock_locations` / `create_stock_location` | 列 / 增仓库 | 写（dry_run 默认） |
-| `get_inventory_levels` / `update_inventory_level` | 查 / 改库存 | 写（dry_run 默认） |
+| `get_inventory_levels` / `update_inventory_level` | 查 / 改库存水平 | 写（dry_run 默认） |
 | `list_orders` / `get_order` | 查订单 | 读 |
 | `list_warehouse_tasks` / `list_return_requests` | 查履约 / 退货 | 读 |
 | `search_docs` / `ask_usage` | 基于 `docs/` 回答后台使用问题 | 读 |

package/dist/derlux-admin-mcp.js

@@ -21638,6 +21638,15 @@ var AuthManager = class {
 };
 
 // src/client.ts
+import { readFileSync as readFileSync2, existsSync as existsSync2 } from "node:fs";
+function mimeOf(path) {
+  const ext = path.split(".").pop()?.toLowerCase() || "";
+  if (ext === "webp") return "image/webp";
+  if (ext === "png") return "image/png";
+  if (ext === "jpg" || ext === "jpeg") return "image/jpeg";
+  if (ext === "gif") return "image/gif";
+  return "application/octet-stream";
+}
 var MedusaAdminError = class extends Error {
   constructor(status, message) {
     super(message);
@@ -21685,12 +21694,122 @@ var MedusaAdminClient = class {
   getProduct(id) {
     return this.request("GET", `/admin/products/${encodeURIComponent(id)}`);
   }
+  /** 列出销售渠道（用于默认渠道解析） */
+  listSalesChannels(params = {}) {
+    return this.request("GET", `/admin/sales-channels${buildQuery(params)}`);
+  }
   createProduct(body) {
     return this.request("POST", "/admin/products", body);
   }
   updateProduct(id, body) {
     return this.request("POST", `/admin/products/${encodeURIComponent(id)}`, body);
   }
+  /**
+   * 整体替换某变体的价格（多币种）。Medusa v2 价格挂在「变体」上，
+   * POST /admin/products/{id} 携带 variants:[{id, prices}] 即整体替换该变体价格（不会累加）。
+   * prices 数组形如 [{ currency_code, amount }, ...]，amount 为主货币单位（元），切勿 ×100。
+   */
+  updateProductPrices(productId, variantId, prices) {
+    return this.request("POST", `/admin/products/${encodeURIComponent(productId)}`, {
+      variants: [{ id: variantId, prices }]
+    });
+  }
+  /** 批量写入翻译（POST /admin/translations/batch）。reference 一般为 "product"。 */
+  async batchTranslations(create, update = []) {
+    return this.request("POST", "/admin/translations/batch", { create, update });
+  }
+  /**
+   * 查询翻译（GET /admin/translations）——用于核对多语言是否写入成功。
+   * ?reference=product&reference_id=<productId>[&locale_code=zh]
+   */
+  listTranslations(params = {}) {
+    return this.request("GET", `/admin/translations${buildQuery(params)}`);
+  }
+  /** 列出集合（GET /admin/collections），用于按名称找 collection_id。 */
+  listCollections(params = {}) {
+    return this.request("GET", `/admin/collections${buildQuery(params)}`);
+  }
+  /**
+   * 把一组商品加入销售渠道（POST /admin/sales-channels/{id}/products）。
+   * ⚠️ 注意：Medusa v2 该端点挂在「渠道」下，不是商品下；body 为 { add:[productIds], remove:[] }。
+   * 商品只有挂到渠道，storefront（按 publishable key → 渠道）才能查到，否则详情页拉不到。
+   */
+  addProductsToSalesChannel(channelId, productIds) {
+    return this.request("POST", `/admin/sales-channels/${encodeURIComponent(channelId)}/products`, {
+      add: productIds,
+      remove: []
+    });
+  }
+  // ─── 商品详情页富内容（product_content 模块）───
+  /**
+   * 读取某商品某语言的富内容块（GET /admin/product-contents）。
+   * locale 用区域码：en-US / zh-CN / ms-MY / id-ID（与 storefront useProductContent 的 localeMap 一致）。
+   * 返回 { product_content: { id, product_id, locale, status, blocks(JSON 字符串) } | null }。
+   */
+  getProductContent(productId, locale = "en-US", status = "published") {
+    return this.request(
+      "GET",
+      `/admin/product-contents${buildQuery({ product_id: productId, locale, status })}`
+    );
+  }
+  /**
+   * 创建/更新某商品某语言的富内容块（POST /admin/product-contents）。
+   * body: { product_id, locale, status?, blocks }；blocks 为 ContentBlock[] 数组
+   * （type ∈ hero/richtext/image_gallery/video/faq/specs）。按 (product_id, locale) upsert。
+   */
+  createProductContent(body) {
+    return this.request("POST", "/admin/product-contents", body);
+  }
+  /**
+   * 上传一组文件到 Medusa 文件服务（POST /admin/uploads，multipart 字段名 files），
+   * 返回上传后的公开 URL 列表。
+   */
+  async uploadFiles(files) {
+    if (!files.length) return [];
+    const form = new FormData();
+    for (const f of files) {
+      form.append("files", new Blob([new Uint8Array(f.buffer)], { type: f.mimetype }), f.filename);
+    }
+    const doPost = async () => {
+      const res = await fetch(`${this.config.backendUrl}/admin/uploads`, {
+        method: "POST",
+        headers: this.auth.headers(),
+        body: form
+      });
+      if (res.status === 401) {
+        this.auth.clear();
+        await this.auth.login();
+        return doPost();
+      }
+      if (!res.ok) {
+        const text = await res.text();
+        throw new MedusaAdminError(res.status, text || res.statusText);
+      }
+      return await res.json();
+    };
+    const data = await doPost();
+    return (data.files || []).map((f) => f.url);
+  }
+  /**
+   * 把一组「本地文件路径 或 图片 URL」解析为可挂到商品的 URL：
+   * - http(s) URL 原样透传；
+   * - 本地路径读取后走 /admin/uploads 上传，返回 URL。
+   */
+  async uploadProductAssets(pathsOrUrls) {
+    const urls = [];
+    const toUpload = [];
+    for (const p of pathsOrUrls) {
+      if (/^https?:\/\//i.test(p)) {
+        urls.push(p);
+        continue;
+      }
+      if (!existsSync2(p)) throw new MedusaAdminError(0, `\u56FE\u7247\u6587\u4EF6\u4E0D\u5B58\u5728: ${p}`);
+      const buf = readFileSync2(p);
+      toUpload.push({ filename: p.split("/").pop() || "image", mimetype: mimeOf(p), buffer: buf });
+    }
+    if (toUpload.length) urls.push(...await this.uploadFiles(toUpload));
+    return urls;
+  }
   // ─── 仓库（StockLocation）/ 库存 ───
   listStockLocations(params = {}) {
     return this.request("GET", `/admin/stock-locations${buildQuery(params)}`);
@@ -21698,25 +21817,66 @@ var MedusaAdminClient = class {
   createStockLocation(body) {
     return this.request("POST", "/admin/stock-locations", body);
   }
-  /** 某仓库下的库存条目及库存水平 */
-  listInventoryItems(locationId, params = {}) {
+  /**
+   * 库存条目列表（GET /admin/inventory-items，Medusa 2.21 契约）。
+   * ⚠️ 2.21 没有 GET /admin/stock-locations/{id}/inventory-items 路由；
+   * 按仓库过滤用查询参数：`location_levels.location_id=<sloc_xxx>`（点号写法）。
+   * 常用参数：q（匹配 sku/title）、sku（精确）、location_levels.location_id。
+   */
+  listInventoryItems(params = {}) {
+    return this.request("GET", `/admin/inventory-items${buildQuery(params)}`);
+  }
+  /**
+   * 创建库存条目（POST /admin/inventory-items）。
+   * body: { sku, title?, weight?, length?, height?, width?, requires_shipping?, ... }，
+   * 可附带 location_levels: [{ location_id, stocked_quantity }] 一步建仓。
+   * sku 有唯一约束（未删除项），同 sku 重复创建会 409。
+   */
+  createInventoryItem(body) {
+    return this.request("POST", "/admin/inventory-items", body);
+  }
+  /** 某库存条目已有的库存水平（GET /admin/inventory-items/{id}/location-levels[?location_id=]） */
+  getInventoryItemLevels(inventoryItemId, params = {}) {
     return this.request(
       "GET",
-      `/admin/stock-locations/${encodeURIComponent(locationId)}/inventory-items${buildQuery(params)}`
+      `/admin/inventory-items/${encodeURIComponent(inventoryItemId)}/location-levels${buildQuery(params)}`
     );
   }
-  /**
-   * 设置/更新某库存条目在指定仓库的库存水平。
-   * ⚠️ 实施时按 Medusa 2.21 官方契约核对端点与字段
-   * （v2 常见为 POST /admin/inventory-items/{id}/location-levels，body 含 location_id + stocked_quantity）。
-   */
-  updateInventoryLevel(inventoryItemId, body) {
+  /** 新建某库存条目在某仓库的库存水平（POST .../location-levels，body: { location_id, stocked_quantity? }） */
+  createInventoryItemLevel(inventoryItemId, body) {
     return this.request(
       "POST",
       `/admin/inventory-items/${encodeURIComponent(inventoryItemId)}/location-levels`,
       body
     );
   }
+  /** 更新某库存条目在指定仓库的库存水平（POST .../location-levels/{location_id}，body: { stocked_quantity? }） */
+  updateInventoryItemLevel(inventoryItemId, locationId, body) {
+    return this.request(
+      "POST",
+      `/admin/inventory-items/${encodeURIComponent(inventoryItemId)}/location-levels/${encodeURIComponent(locationId)}`,
+      body
+    );
+  }
+  /**
+   * 幂等地设置某库存条目在指定仓库的库存数量：
+   * 已有 (item, location) 水平 → 更新；没有 → 创建。
+   */
+  async upsertInventoryLevel(inventoryItemId, locationId, stockedQuantity) {
+    const existing = await this.getInventoryItemLevels(inventoryItemId, {
+      location_id: locationId
+    });
+    const found = (existing?.inventory_levels || []).find((l) => l.location_id === locationId);
+    if (found) {
+      await this.updateInventoryItemLevel(inventoryItemId, locationId, { stocked_quantity: stockedQuantity });
+      return { created: false, stocked_quantity: stockedQuantity };
+    }
+    await this.createInventoryItemLevel(inventoryItemId, {
+      location_id: locationId,
+      stocked_quantity: stockedQuantity
+    });
+    return { created: true, stocked_quantity: stockedQuantity };
+  }
   // ─── 订单 ───
   listOrders(params = {}) {
     return this.request("GET", `/admin/orders${buildQuery(params)}`);
@@ -21733,6 +21893,180 @@ var MedusaAdminClient = class {
   }
 };
 
+// src/tools/stock.ts
+async function applyProductStock(ctx2, opts) {
+  const { client: client2 } = ctx2;
+  const prod = await client2.getProduct(opts.productId);
+  const product = prod?.product ?? prod;
+  if (!product?.variants?.length) throw new Error(`\u5546\u54C1 ${opts.productId} \u6CA1\u6709\u53D8\u4F53\uFF0C\u65E0\u6CD5\u5EFA\u4ED3`);
+  const variant = opts.sku ? product.variants.find((v) => v.sku === opts.sku) : product.variants[0];
+  if (!variant) throw new Error(`\u627E\u4E0D\u5230\u76EE\u6807\u53D8\u4F53\uFF08sku=${opts.sku || "\u7B2C\u4E00\u4E2A"}\uFF09`);
+  let location = null;
+  if (opts.locationId) {
+    const locs = await client2.listStockLocations({ limit: 100 });
+    location = (locs?.stock_locations || []).find((l) => l.id === opts.locationId);
+    if (!location) throw new Error(`\u627E\u4E0D\u5230\u4ED3\u5E93 ${opts.locationId}`);
+  } else {
+    const locs = await client2.listStockLocations({ limit: 100 });
+    const list = locs?.stock_locations || [];
+    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 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({
+      sku: variant.sku,
+      title: variant.title || void 0
+    });
+    iitem = created?.inventory_item ?? 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 }]
+    });
+  }
+  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
+  };
+}
+var stockTools = [
+  {
+    name: "list_stock_locations",
+    description: "\u5217\u51FA\u4ED3\u5E93\uFF08Medusa StockLocation\uFF09\u3002\u53EF\u9009\u5173\u952E\u8BCD q \u8FC7\u6EE4\u540D\u79F0\u3002",
+    schema: {
+      q: external_exports.string().optional(),
+      limit: external_exports.number().int().positive().max(100).default(50)
+    },
+    async run(input, { client: client2 }) {
+      return client2.listStockLocations({ q: input.q, limit: input.limit });
+    }
+  },
+  {
+    name: "create_stock_location",
+    description: "\u589E\u52A0\u4E00\u4E2A\u4ED3\u5E93\uFF08StockLocation\uFF09\u3002\u9ED8\u8BA4 dry_run\u3002",
+    schema: {
+      name: external_exports.string(),
+      address: external_exports.object({
+        address_1: external_exports.string().optional(),
+        address_2: external_exports.string().optional(),
+        city: external_exports.string().optional(),
+        country_code: external_exports.string().optional(),
+        province: external_exports.string().optional(),
+        postal_code: external_exports.string().optional(),
+        phone: external_exports.string().optional()
+      }).optional(),
+      metadata: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2 }) {
+      const payload = { name: input.name };
+      if (input.address) payload.address = input.address;
+      if (input.metadata) payload.metadata = input.metadata;
+      if (!input.confirm) return { dry_run: true, will_create: payload };
+      return client2.createStockLocation(payload);
+    }
+  },
+  {
+    name: "get_inventory_levels",
+    description: `\u67E5\u8BE2\u5E93\u5B58\u6761\u76EE\u53CA\u5E93\u5B58\u6C34\u5E73\uFF08GET /admin/inventory-items\uFF0CMedusa 2.21 \u5951\u7EA6\uFF09\u3002
+location_id \u53EF\u9009\uFF1A\u4F20\u4E86\u5219\u53EA\u56DE\u8BE5\u4ED3\u5E93\u4E0B\u6709\u6C34\u5E73\u7684\u6761\u76EE\uFF1B\u4E0D\u4F20\u5219\u5217\u5168\u90E8\u3002q \u6309 sku/title \u6A21\u7CCA\u8FC7\u6EE4\u3002`,
+    schema: {
+      location_id: external_exports.string().optional().describe("\u4ED3\u5E93 id\uFF1B\u7701\u7565\u5219\u4E0D\u9650\u4ED3\u5E93"),
+      q: external_exports.string().optional(),
+      limit: external_exports.number().int().positive().max(100).default(50)
+    },
+    async run(input, { client: client2 }) {
+      const params = { limit: input.limit };
+      if (input.q) params.q = input.q;
+      if (input.location_id) params["location_levels.location_id"] = input.location_id;
+      return client2.listInventoryItems(params);
+    }
+  },
+  {
+    name: "set_product_stock",
+    description: `\u7ED9\u5546\u54C1\u5EFA\u4ED3/\u6539\u5E93\u5B58\uFF08\u5E42\u7B49\uFF09\uFF1A\u786E\u4FDD\u53D8\u4F53\u5BF9\u5E94\u7684\u5E93\u5B58\u6761\u76EE\u5B58\u5728\uFF08\u7F3A\u5931\u5219\u6309\u53D8\u4F53 SKU \u81EA\u52A8\u521B\u5EFA\uFF09\uFF0C
+\u518D\u628A\u6307\u5B9A\u4ED3\u5E93\u7684\u5E93\u5B58\u6570\u91CF\u8BBE\u4E3A quantity\uFF0C\u5E76\u628A\u53D8\u4F53 manage_inventory \u7F6E\u4E3A true\u3002
+\u26A0\uFE0F \u4E0D\u6307\u5B9A location_id \u65F6\u9ED8\u8BA4\u5199\u5165\u540D\u79F0\u542B "Main Warehouse" \u7684\u4ED3\u5E93\uFF08\u5426\u5219\u53D6\u7B2C\u4E00\u4E2A\u4ED3\u5E93\uFF09\u3002
+\u26A0\uFE0F \u672A\u5EFA\u4ED3\uFF08manage_inventory=false \u6216 0 \u5E93\u5B58\uFF09\u7684\u5546\u54C1\u5728\u524D\u7AEF\u8868\u73B0\u4E3A\u300C\u7F3A\u8D27\u300D\uFF0C\u6B63\u5F0F\u4E0A\u67B6\u524D\u5FC5\u987B\u5EFA\u4ED3\u3002
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\uFF1Bconfirm=true \u624D\u5199\u5165\u3002`,
+    schema: {
+      product_id: external_exports.string().describe("\u5546\u54C1 id \u6216 handle"),
+      sku: external_exports.string().optional().describe("\u76EE\u6807\u53D8\u4F53 SKU\uFF1B\u7701\u7565\u5219\u53D6\u7B2C\u4E00\u4E2A\u53D8\u4F53"),
+      location_id: external_exports.string().optional().describe("\u4ED3\u5E93 id\uFF1B\u7701\u7565\u5219 Main Warehouse/\u7B2C\u4E00\u4E2A"),
+      quantity: external_exports.number().int().nonnegative().describe("\u8BE5\u4ED3\u5E93\u5E93\u5B58\u6570\u91CF\uFF08\u7EDD\u5BF9\u503C\uFF0C\u975E\u589E\u91CF\uFF09"),
+      manage_inventory: external_exports.boolean().default(true).describe("\u53D8\u4F53\u662F\u5426\u542F\u7528\u5E93\u5B58\u7BA1\u7406\uFF0C\u9ED8\u8BA4 true"),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, ctx2) {
+      const plan = {
+        product_id: input.product_id,
+        sku: input.sku || "(\u7B2C\u4E00\u4E2A\u53D8\u4F53)",
+        location_id: input.location_id || "(Main Warehouse/\u7B2C\u4E00\u4E2A\u4ED3\u5E93)",
+        quantity: input.quantity,
+        manage_inventory: input.manage_inventory
+      };
+      if (!input.confirm) {
+        return { dry_run: true, will_set_stock: plan };
+      }
+      try {
+        const result = await applyProductStock(ctx2, {
+          productId: input.product_id,
+          sku: input.sku,
+          locationId: input.location_id,
+          quantity: input.quantity,
+          manageInventory: input.manage_inventory
+        });
+        return { set_stock: result };
+      } catch (e) {
+        return `\u9519\u8BEF\uFF1A\u5EFA\u4ED3\u5931\u8D25 \u2014\u2014 ${e?.message || e}`;
+      }
+    }
+  },
+  {
+    name: "update_inventory_level",
+    description: `\u4FEE\u6539\u67D0\u5E93\u5B58\u6761\u76EE\u5728\u6307\u5B9A\u4ED3\u5E93\u7684\u5E93\u5B58\u6570\u91CF\uFF08\u7EDD\u5BF9\u503C\uFF0C\u5E42\u7B49 upsert\uFF09\u3002
+\u76F4\u63A5\u7ED9\u5546\u54C1\u5EFA\u4ED3\u8BF7\u4F18\u5148\u7528 set_product_stock\uFF08\u4F1A\u81EA\u52A8\u627E/\u5EFA\u5E93\u5B58\u6761\u76EE\uFF09\u3002\u9ED8\u8BA4 dry_run\u3002`,
+    schema: {
+      inventory_item_id: external_exports.string(),
+      location_id: external_exports.string(),
+      stocked_quantity: external_exports.number().int().nonnegative(),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2 }) {
+      if (!input.confirm) {
+        return {
+          dry_run: true,
+          will_update: {
+            inventory_item_id: input.inventory_item_id,
+            location_id: input.location_id,
+            stocked_quantity: input.stocked_quantity
+          }
+        };
+      }
+      const level = await client2.upsertInventoryLevel(
+        input.inventory_item_id,
+        input.location_id,
+        input.stocked_quantity
+      );
+      return { updated: { ...level, inventory_item_id: input.inventory_item_id, location_id: input.location_id } };
+    }
+  }
+];
+
 // src/tools/products.ts
 var PRODUCT_STATUS = [
   "draft",
@@ -21776,12 +22110,77 @@ var productTools = [
       return client2.getProduct(input.id_or_handle);
     }
   },
+  {
+    name: "list_sales_channels",
+    description: "\u5217\u51FA\u9500\u552E\u6E20\u9053\uFF08GET /admin/sales-channels\uFF09\u3002\u65B0\u589E\u5546\u54C1\u524D\u7528\u5B83\u786E\u8BA4\u6E20\u9053 id/\u540D\u79F0\u3002",
+    schema: {
+      q: external_exports.string().optional(),
+      limit: external_exports.number().int().positive().max(100).default(50)
+    },
+    async run(input, { client: client2 }) {
+      return client2.listSalesChannels({ q: input.q, limit: input.limit });
+    }
+  },
+  {
+    name: "list_collections",
+    description: "\u5217\u51FA\u96C6\u5408\uFF08GET /admin/collections\uFF09\uFF0C\u7528\u4E8E\u628A\u5546\u54C1\u6302\u8FDB\u96C6\u5408\uFF08\u5982\u6D3B\u52A8\u96C6\u5408\uFF09\u3002",
+    schema: {
+      q: external_exports.string().optional(),
+      limit: external_exports.number().int().positive().max(100).default(50)
+    },
+    async run(input, { client: client2 }) {
+      return client2.listCollections({ q: input.q, limit: input.limit });
+    }
+  },
+  {
+    name: "get_translations",
+    description: `\u8BFB\u53D6\u67D0\u5B9E\u4F53\u7684\u591A\u8BED\u8A00\u7FFB\u8BD1\uFF08GET /admin/translations\uFF09\u2014\u2014\u6838\u5BF9\u5546\u54C1\u56DB\u8BED\u8A00\u662F\u5426\u5199\u5165\u6210\u529F\u7684\u552F\u4E00\u53EF\u9760\u9014\u5F84
+\uFF08get_product \u9ED8\u8BA4\u5B57\u6BB5\u4E0D\u542B translations\uFF09\u3002reference \u4E00\u822C\u4E3A product\uFF0Creference_id \u4F20\u5546\u54C1 id \u6216 handle\u3002
+\u8FD4\u56DE\u6BCF\u6761 { locale_code, title, description }\u3002`,
+    schema: {
+      reference: external_exports.string().default("product"),
+      reference_id: external_exports.string().describe("\u5546\u54C1 id \u6216 handle"),
+      locale_code: external_exports.string().optional().describe("\u53EA\u53D6\u67D0\u4E00\u8BED\u8A00\uFF0C\u5982 zh"),
+      limit: external_exports.number().int().positive().max(100).default(50)
+    },
+    async run(input, { client: client2 }) {
+      let refId = input.reference_id;
+      if (!/^[a-z]+_[a-z0-9]+$/i.test(refId)) {
+        const prod = await client2.getProduct(refId).catch(() => null);
+        const id = prod?.product?.id || prod?.id;
+        if (!id) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230 ${input.reference} "${refId}"\uFF08\u8BF7\u4F20 id \u6216\u6709\u6548 handle\uFF09`;
+        refId = id;
+      }
+      const params = {
+        reference: input.reference,
+        reference_id: refId,
+        limit: input.limit
+      };
+      if (input.locale_code) params.locale_code = input.locale_code;
+      const data = await client2.listTranslations(params);
+      const rows = (data?.translations || []).map((t) => {
+        const tr = t.translations || {};
+        return {
+          locale_code: t.locale_code,
+          title: tr.title ?? null,
+          description: tr.description ? tr.description.slice(0, 120) + "\u2026" : null,
+          has_full_description: Boolean(tr.description)
+        };
+      });
+      return { reference: input.reference, reference_id: input.reference_id, translations: rows, count: rows.length };
+    }
+  },
   {
     name: "create_product",
     description: `\u5728\u540E\u53F0\u589E\u52A0\u4E00\u4E2A\u5546\u54C1\u3002
 \u89C4\u5219\uFF08\xA716.1\uFF09\uFF1AHandle \u53EA\u80FD\u542B\u5C0F\u5199\u5B57\u6BCD\u3001\u6570\u5B57\u3001\u8FDE\u5B57\u7B26(-)\uFF0C\u5DE5\u5177\u4F1A\u81EA\u52A8\u5F52\u4E00\u5316\uFF0C\u975E\u6CD5\u5219\u62A5\u9519\u3002
 \u591A\u8BED\u8A00\uFF08\xA716.2\uFF09\uFF1Atranslations \u5FC5\u987B\u5305\u542B en/zh/ms/id \u56DB\u79CD\u8BED\u8A00\u7684 title\uFF1B\u7F3A\u5931\u65F6\u9700 confirm=true \u4E14 acknowledge_missing_languages=true\u3002
-\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u53EA\u8FD4\u56DE\u9884\u89C8\uFF0C\u4E0D\u771F\u6B63\u521B\u5EFA\u3002`,
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u53EA\u8FD4\u56DE\u9884\u89C8\uFF0C\u4E0D\u771F\u6B63\u521B\u5EFA\u3002
+\u56FE\u7247\uFF1Aimages \u53EF\u4F20\u672C\u5730\u6587\u4EF6\u8DEF\u5F84\uFF08\u81EA\u52A8\u4E0A\u4F20\u5230\u6587\u4EF6\u670D\u52A1\uFF09\u6216\u56FE\u7247 URL\uFF0C\u4EC5\u5728 confirm=true \u65F6\u624D\u771F\u6B63\u4E0A\u4F20/\u6302\u63A5\u3002
+SKU / \u89C4\u683C\uFF1Asku \u5199\u5165\u9ED8\u8BA4\u53D8\u4F53\uFF1Bmetadata \u53EF\u5B58\u4EFB\u610F\u952E\u503C\uFF08\u5982\u89C4\u683C\u53C2\u6570\u3001\u6765\u6E90\u94FE\u63A5\uFF09\u3002
+\u6E20\u9053\uFF1Asales_channels \u4F20\u6E20\u9053 id \u6216\u540D\u79F0\uFF08\u5982 "MY Storefront"\uFF09\uFF0C\u521B\u5EFA\u5373\u6302\u8F7D\uFF0C\u5426\u5219\u524D\u7AEF\u4E0D\u53EF\u89C1\u3002
+\u5E93\u5B58\uFF1Amanage_inventory \u9ED8\u8BA4 true\uFF1B\u6B63\u5F0F\u4E0A\u67B6\u5FC5\u987B\u7ED9 initial_stock\uFF08\u5982 {quantity:100}\uFF0C\u9ED8\u8BA4\u4E3B\u4ED3\uFF09\uFF0C\u5426\u5219 0 \u5E93\u5B58=\u524D\u7AEF\u7F3A\u8D27\u3002
+\u7269\u7406/\u6D77\u5173\u5B57\u6BB5\uFF1Aweight(\u514B)/length/height/width(\u5398\u7C73)/origin_country/hs_code/mid_code/material \u5747\u53EF\u9009\u3002`,
     schema: {
       title: external_exports.string(),
       handle: external_exports.string().optional().describe("\u4E0D\u586B\u5219\u7528 title \u5F52\u4E00\u5316\u751F\u6210"),
@@ -21792,9 +22191,28 @@ var productTools = [
       // 并非最小单位（分）。官方 ESLint 规则 prices-in-major-units 明确：
       // "Medusa stores prices in major units"，期望 19.99 而非 1999。
       // 本项目 seed 与 storefront 均遵循此官方约定，故直接透传，不要 ×100。
-      price: external_exports.number().nonnegative().optional().describe("\u4E3B\u8D27\u5E01\u5355\u4F4D\u91D1\u989D\uFF0C\u5982 200.51 \u5373 RM200.51\uFF1BMedusa \u4EE5\u4E3B\u5355\u4F4D\u5B58\u50A8\uFF0C\u5207\u52FF\u6362\u7B97"),
+      price: external_exports.number().nonnegative().optional().describe("\u4E3B\u8D27\u5E01\u5355\u4F4D\u91D1\u989D\uFF0C\u5982 200.51 \u5373 RM200.51\uFF1BMedusa \u4EE5\u4E3B\u5355\u4F4D\u5B58\u50A8\uFF0C\u5207\u52FF\u6362\u7B97\u3002\u4E0E prices \u4E8C\u9009\u4E00\uFF0Cprices \u4F18\u5148"),
       currency_code: external_exports.string().default("MYR"),
+      prices: external_exports.array(external_exports.object({ currency_code: external_exports.string(), amount: external_exports.number().nonnegative() })).optional().describe('\u591A\u5E01\u79CD\u4EF7\u683C\uFF08\u4E3B\u8D27\u5E01\u5355\u4F4D\uFF09\uFF0C\u5982 [{currency_code:"myr",amount:420},{currency_code:"sgd",amount:127}]\u3002\u4E1C\u5357\u4E9A\u5E97\u901A\u5E38\u9700\u8986\u76D6 myr/sgd/idr/thb/php/cny\u3002\u4F18\u5148\u4E8E\u5355\u4E00 price'),
       translations: external_exports.record(external_exports.string(), translationShape).optional(),
+      images: external_exports.array(external_exports.string()).optional().describe("\u672C\u5730\u56FE\u7247\u8DEF\u5F84\u6216\u56FE\u7247 URL\uFF0Cconfirm=true \u65F6\u4E0A\u4F20\u5E76\u6302\u5230\u5546\u54C1"),
+      sku: external_exports.string().optional().describe("\u5199\u5165\u9ED8\u8BA4\u53D8\u4F53\u7684 SKU"),
+      metadata: external_exports.record(external_exports.string(), external_exports.string()).optional().describe("\u4EFB\u610F\u952E\u503C\uFF0C\u5982\u89C4\u683C\u53C2\u6570 / source_url"),
+      sales_channels: external_exports.array(external_exports.string()).optional().describe('\u9500\u552E\u6E20\u9053 id \u6216\u540D\u79F0\uFF08\u5982 "MY Storefront"\uFF09\uFF0C\u521B\u5EFA\u5373\u6302\u8F7D\uFF0C\u5426\u5219\u524D\u7AEF\u4E0D\u53EF\u89C1'),
+      collection_id: external_exports.string().optional().describe('\u96C6\u5408 id \u6216\u540D\u79F0\uFF08\u5982 "\u53CC11\u6D3B\u52A8"\uFF09'),
+      weight: external_exports.number().nonnegative().optional().describe("\u91CD\u91CF\uFF0C\u5355\u4F4D\u514B"),
+      length: external_exports.number().nonnegative().optional().describe("\u957F\uFF0C\u5355\u4F4D\u5398\u7C73"),
+      height: external_exports.number().nonnegative().optional().describe("\u9AD8\uFF0C\u5355\u4F4D\u5398\u7C73"),
+      width: external_exports.number().nonnegative().optional().describe("\u5BBD\uFF0C\u5355\u4F4D\u5398\u7C73"),
+      origin_country: external_exports.string().optional().describe("\u539F\u4EA7\u56FD ISO \u7801\uFF0C\u5982 KR/MY"),
+      hs_code: external_exports.string().optional(),
+      mid_code: external_exports.string().optional(),
+      material: external_exports.string().optional(),
+      manage_inventory: external_exports.boolean().default(true).describe("\u53D8\u4F53\u662F\u5426\u542F\u7528\u5E93\u5B58\u7BA1\u7406\uFF0C\u9ED8\u8BA4 true"),
+      initial_stock: external_exports.object({
+        location_id: external_exports.string().optional().describe("\u4ED3\u5E93 id\uFF1B\u7701\u7565\u5219 Main Warehouse/\u7B2C\u4E00\u4E2A\u4ED3\u5E93"),
+        quantity: external_exports.number().int().nonnegative()
+      }).optional().describe("\u5EFA\u5E93\u5B58\uFF1A\u6309\u53D8\u4F53 SKU \u81EA\u52A8\u521B\u5EFA\u5E93\u5B58\u6761\u76EE\u5E76\u5199\u5165\u8BE5\u4ED3\u5E93\u6570\u91CF"),
       confirm: external_exports.boolean().default(false),
       acknowledge_missing_languages: external_exports.boolean().default(false)
     },
@@ -21808,6 +22226,29 @@ var productTools = [
       const missing = config3.requiredLocales.filter(
         (l) => !provided.includes(l) || !input.translations?.[l]?.title
       );
+      let channelIds = [];
+      if (input.sales_channels?.length) {
+        const ch = await client2.listSalesChannels({ limit: 100 });
+        const list = ch?.sales_channels || [];
+        channelIds = input.sales_channels.map((name) => list.find((c) => c.id === name || c.name === name)?.id).filter(Boolean);
+        const unknown2 = input.sales_channels.filter(
+          (name) => !list.some((c) => c.id === name || c.name === name)
+        );
+        if (unknown2.length) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u9500\u552E\u6E20\u9053\uFF1A${unknown2.join(", ")}\uFF08\u7528 list_sales_channels \u67E5\u770B\u53EF\u7528\u6E20\u9053\uFF09`;
+      }
+      let collectionId = input.collection_id;
+      if (collectionId && !collectionId.startsWith("pcol_")) {
+        const cols = await client2.listCollections({ limit: 100 });
+        const hit = (cols?.collections || []).find((c) => c.id === collectionId || c.title === collectionId);
+        if (!hit) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u96C6\u5408 "${collectionId}"\uFF08\u7528 list_collections \u67E5\u770B\u53EF\u7528\u96C6\u5408\uFF09`;
+        collectionId = hit.id;
+      }
+      const warnings = [];
+      if (input.manage_inventory !== false && !input.initial_stock) {
+        warnings.push(
+          "manage_inventory=true \u4F46\u672A\u7ED9 initial_stock\uFF1A\u521B\u5EFA\u540E\u4E3A 0 \u5E93\u5B58\uFF0C\u524D\u7AEF\u5C06\u663E\u793A\u7F3A\u8D27\u3002\u6B63\u5F0F\u4E0A\u67B6\u524D\u5FC5\u987B\u8C03\u7528 set_product_stock \u5EFA\u4ED3\u3002"
+        );
+      }
       if (!input.confirm) {
         return {
           dry_run: true,
@@ -21817,38 +22258,102 @@ var productTools = [
             status: input.status,
             price: input.price,
             currency_code: input.currency_code,
+            prices: input.prices,
+            sku: input.sku,
+            images: input.images,
+            metadata: input.metadata,
+            sales_channels: channelIds,
+            collection_id: collectionId || null,
+            weight: input.weight,
+            manage_inventory: input.manage_inventory,
+            initial_stock: input.initial_stock,
             missing_translations: missing
           },
+          warnings,
           note: "\u672A confirm\uFF0C\u4EC5\u9884\u89C8\u3002\u786E\u8BA4\u8BF7\u8BBE confirm=true\u3002"
         };
       }
       if (missing.length > 0 && !input.acknowledge_missing_languages) {
         return `\u9519\u8BEF\uFF1A\u7F3A\u5C11\u4EE5\u4E0B\u8BED\u8A00\u7684 title\uFF1A${missing.join(", ")}\u3002\u5982\u786E\u8BA4\u4ECD\u8981\u521B\u5EFA\uFF0C\u8BF7\u8BBE acknowledge_missing_languages=true\u3002`;
       }
+      let imageUrls = [];
+      if (input.images?.length) {
+        try {
+          imageUrls = await client2.uploadProductAssets(input.images);
+        } catch (e) {
+          return `\u9519\u8BEF\uFF1A\u56FE\u7247\u4E0A\u4F20\u5931\u8D25 \u2014\u2014 ${e?.message || e}`;
+        }
+      }
       const payload = {
         title: input.title,
         handle,
         status: input.status,
         subtitle: input.subtitle,
-        description: input.description
+        description: input.description,
+        options: [{ title: "Default", values: ["Default"] }]
       };
-      if (input.translations) payload.translations = input.translations;
-      if (input.price != null) {
-        payload.variants = [
-          {
-            title: "Default",
-            prices: [{ amount: input.price, currency_code: input.currency_code }],
-            manage_inventory: false
-          }
-        ];
+      if (input.metadata) payload.metadata = input.metadata;
+      if (imageUrls.length) payload.images = imageUrls.map((url) => ({ url }));
+      if (channelIds.length) payload.sales_channels = channelIds.map((id) => ({ id }));
+      if (collectionId) payload.collection_id = collectionId;
+      for (const k of ["weight", "length", "height", "width"]) {
+        if (input[k] != null) payload[k] = input[k];
+      }
+      for (const k of ["origin_country", "hs_code", "mid_code", "material"]) {
+        if (input[k]) payload[k] = input[k];
+      }
+      const variantPrices = input.prices && input.prices.length ? input.prices.map((p) => ({ amount: p.amount, currency_code: p.currency_code })) : input.price != null ? [{ amount: input.price, currency_code: input.currency_code }] : void 0;
+      if (variantPrices) {
+        const variant = {
+          title: "Default",
+          options: { Default: "Default" },
+          prices: variantPrices,
+          manage_inventory: input.manage_inventory
+        };
+        if (input.sku) variant.sku = input.sku;
+        payload.variants = [variant];
       }
       const data = await client2.createProduct(payload);
-      return { created: data, warning_missing_languages: missing };
+      const productId = data?.product?.id || data?.id;
+      let translationResult = null;
+      if (input.translations && Object.keys(input.translations).length) {
+        const create = Object.entries(input.translations).map(([locale, t]) => ({
+          reference: "product",
+          reference_id: productId,
+          locale_code: locale,
+          translations: { title: t?.title, description: t?.description }
+        }));
+        try {
+          translationResult = await client2.batchTranslations(create);
+        } catch (e) {
+          return { created: data, warning_translations: `\u7FFB\u8BD1\u5199\u5165\u5931\u8D25 \u2014\u2014 ${e?.message || e}` };
+        }
+      }
+      let stock = null;
+      if (input.initial_stock && productId) {
+        try {
+          stock = await applyProductStock(
+            { client: client2, config: config3 },
+            {
+              productId,
+              sku: input.sku,
+              locationId: input.initial_stock.location_id,
+              quantity: input.initial_stock.quantity,
+              manageInventory: input.manage_inventory
+            }
+          );
+        } catch (e) {
+          warnings.push(`\u5EFA\u5E93\u5B58\u5931\u8D25\uFF08\u5546\u54C1\u5DF2\u521B\u5EFA\uFF0C\u8BF7\u8865\u8C03 set_product_stock\uFF09\u2014\u2014 ${e?.message || e}`);
+        }
+      }
+      return { created: data, translations: translationResult, stock, warnings, warning_missing_languages: missing };
     }
   },
   {
     name: "update_product",
-    description: "\u4FEE\u6539\u5546\u54C1\u5B57\u6BB5\uFF08\u6807\u9898/handle/\u72B6\u6001/\u63CF\u8FF0/\u591A\u8BED\u8A00\uFF09\u3002Handle \u81EA\u52A8\u5F52\u4E00\u5316\u3002\u9ED8\u8BA4 dry_run\u3002",
+    description: `\u4FEE\u6539\u5546\u54C1\u5B57\u6BB5\uFF08\u6807\u9898/handle/\u72B6\u6001/\u63CF\u8FF0/\u591A\u8BED\u8A00/\u7269\u7406\u5C3A\u5BF8/\u6D77\u5173/\u96C6\u5408/metadata\uFF09\u3002Handle \u81EA\u52A8\u5F52\u4E00\u5316\u3002
+weight \u5355\u4F4D\u514B\uFF1Blength/height/width \u5355\u4F4D\u5398\u7C73\uFF1Borigin_country \u7528 ISO \u7801\uFF08\u5982 KR\uFF09\u3002
+metadata \u4E3A**\u5408\u5E76**\u8BED\u4E49\uFF1A\u65B0\u952E\u8986\u76D6\u540C\u540D\u952E\u3001\u672A\u63D0\u53CA\u7684\u65E7\u952E\u4FDD\u7559\uFF08\u4E0D\u652F\u6301\u5220\u9664\u952E\uFF09\u3002\u9ED8\u8BA4 dry_run\u3002`,
     schema: {
       id: external_exports.string(),
       title: external_exports.string().optional(),
@@ -21857,6 +22362,16 @@ var productTools = [
       subtitle: external_exports.string().optional(),
       description: external_exports.string().optional(),
       translations: external_exports.record(external_exports.string(), translationShape).optional(),
+      collection_id: external_exports.string().optional().describe("\u96C6\u5408 id \u6216\u540D\u79F0"),
+      weight: external_exports.number().nonnegative().optional().describe("\u91CD\u91CF\uFF0C\u5355\u4F4D\u514B"),
+      length: external_exports.number().nonnegative().optional().describe("\u957F\uFF0C\u5355\u4F4D\u5398\u7C73"),
+      height: external_exports.number().nonnegative().optional().describe("\u9AD8\uFF0C\u5355\u4F4D\u5398\u7C73"),
+      width: external_exports.number().nonnegative().optional().describe("\u5BBD\uFF0C\u5355\u4F4D\u5398\u7C73"),
+      origin_country: external_exports.string().optional(),
+      hs_code: external_exports.string().optional(),
+      mid_code: external_exports.string().optional(),
+      material: external_exports.string().optional(),
+      metadata: external_exports.record(external_exports.string(), external_exports.string()).optional().describe("\u5408\u5E76\u8FDB\u73B0\u6709 metadata\uFF08\u4E0D\u6574\u4F53\u8986\u76D6\uFF09"),
       confirm: external_exports.boolean().default(false)
     },
     async run(input, { client: client2 }) {
@@ -21870,9 +22385,79 @@ var productTools = [
       if (input.status) patch.status = input.status;
       if (input.subtitle) patch.subtitle = input.subtitle;
       if (input.description) patch.description = input.description;
-      if (input.translations) patch.translations = input.translations;
+      if (input.collection_id) {
+        let cid = input.collection_id;
+        if (!cid.startsWith("pcol_")) {
+          const cols = await client2.listCollections({ limit: 100 });
+          const hit = (cols?.collections || []).find((c) => c.id === cid || c.title === cid);
+          if (!hit) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u96C6\u5408 "${cid}"\uFF08\u7528 list_collections \u67E5\u770B\u53EF\u7528\u96C6\u5408\uFF09`;
+          cid = hit.id;
+        }
+        patch.collection_id = cid;
+      }
+      for (const k of ["weight", "length", "height", "width"]) {
+        if (input[k] != null) patch[k] = input[k];
+      }
+      for (const k of ["origin_country", "hs_code", "mid_code", "material"]) {
+        if (input[k]) patch[k] = input[k];
+      }
+      if (input.metadata && Object.keys(input.metadata).length) {
+        const cur = await client2.getProduct(input.id).catch(() => null);
+        const existingMeta = (cur?.product ?? cur)?.metadata || {};
+        patch.metadata = { ...existingMeta, ...input.metadata };
+      }
       if (!input.confirm) return { dry_run: true, will_update: patch };
-      return client2.updateProduct(input.id, patch);
+      const data = await client2.updateProduct(input.id, patch);
+      let translationResult = null;
+      if (input.translations && Object.keys(input.translations).length) {
+        const create = Object.entries(input.translations).map(([locale, t]) => ({
+          reference: "product",
+          reference_id: input.id,
+          locale_code: locale,
+          translations: { title: t?.title, description: t?.description }
+        }));
+        try {
+          translationResult = await client2.batchTranslations(create);
+        } catch (e) {
+          return { updated: data, warning_translations: `\u7FFB\u8BD1\u5199\u5165\u5931\u8D25 \u2014\u2014 ${e?.message || e}` };
+        }
+      }
+      return { updated: data, translations: translationResult };
+    }
+  },
+  {
+    name: "update_product_prices",
+    description: `\u8BBE\u7F6E/\u66FF\u6362\u67D0\u5546\u54C1\u7684\uFF08\u53D8\u4F53\uFF09\u4EF7\u683C\uFF0C\u652F\u6301\u591A\u5E01\u79CD\u3002Medusa \u4EF7\u683C\u6302\u5728\u300C\u53D8\u4F53\u300D\u4E0A\uFF0C\u5199\u5165\u5373\u6574\u4F53\u66FF\u6362\u8BE5\u53D8\u4F53\u7684\u5168\u90E8\u4EF7\u683C\uFF08\u4E0D\u4F1A\u7D2F\u52A0\u65E7\u4EF7\uFF09\u3002
+\u4EF7\u683C\u4EE5\u4E3B\u8D27\u5E01\u5355\u4F4D\uFF08\u5143\uFF09\u5B58\u50A8\uFF0C\u5207\u52FF \xD7100\u3002\u4E1C\u5357\u4E9A\u8DE8\u5883\u5E97\u901A\u5E38\u9700\u8986\u76D6 myr/sgd/idr/thb/php/cny\u3002
+\u4E0D\u6307\u5B9A variant_id \u65F6\u4F5C\u7528\u4E8E\u7B2C\u4E00\u4E2A\u53D8\u4F53\uFF08\u5355 SKU \u5546\u54C1\u5373\u552F\u4E00\u53D8\u4F53\uFF09\u3002\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
+    schema: {
+      product_id: external_exports.string(),
+      prices: external_exports.array(external_exports.object({ currency_code: external_exports.string(), amount: external_exports.number().nonnegative() })).describe('\u591A\u5E01\u79CD\u4EF7\u683C\u6570\u7EC4\uFF08\u4E3B\u8D27\u5E01\u5355\u4F4D\uFF09\uFF0C\u5982 [{currency_code:"myr",amount:420},{currency_code:"sgd",amount:127}]'),
+      variant_id: external_exports.string().optional().describe("\u76EE\u6807\u53D8\u4F53 id\uFF1B\u7701\u7565\u5219\u53D6\u7B2C\u4E00\u4E2A\u53D8\u4F53"),
+      confirm: external_exports.boolean().default(false)
+    },
+    async run(input, { client: client2 }) {
+      if (!input.confirm) {
+        return {
+          dry_run: true,
+          product_id: input.product_id,
+          will_set_prices: input.prices,
+          variant_id: input.variant_id || "(\u7B2C\u4E00\u4E2A\u53D8\u4F53)"
+        };
+      }
+      const prod = await client2.getProduct(input.product_id).catch(() => null);
+      const product = prod?.product ?? prod;
+      if (!product) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u5546\u54C1 ${input.product_id}`;
+      const variants = product.variants || [];
+      if (!variants.length) return `\u9519\u8BEF\uFF1A\u5546\u54C1\u6CA1\u6709\u53D8\u4F53\uFF0C\u65E0\u6CD5\u8BBE\u7F6E\u4EF7\u683C\u3002`;
+      const target = input.variant_id ? variants.find((v) => v.id === input.variant_id) : variants[0];
+      if (!target) return `\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u76EE\u6807\u53D8\u4F53\uFF08\u6307\u5B9A ${input.variant_id} \u6216\u7B2C\u4E00\u4E2A\u53D8\u4F53\uFF09\u3002`;
+      const data = await client2.updateProductPrices(
+        input.product_id,
+        target.id,
+        input.prices.map((p) => ({ amount: p.amount, currency_code: p.currency_code }))
+      );
+      return { updated: data };
     }
   },
   {
@@ -21886,76 +22471,131 @@ var productTools = [
       if (!input.confirm) return { dry_run: true, will_set_status: "archived" };
       return client2.updateProduct(input.id, { status: "archived" });
     }
-  }
-];
-
-// src/tools/stock.ts
-var stockTools = [
+  },
   {
-    name: "list_stock_locations",
-    description: "\u5217\u51FA\u4ED3\u5E93\uFF08Medusa StockLocation\uFF09\u3002\u53EF\u9009\u5173\u952E\u8BCD q \u8FC7\u6EE4\u540D\u79F0\u3002",
+    name: "upload_product_image",
+    description: `\u7ED9\u5DF2\u5B58\u5728\u7684\u5546\u54C1\u8FFD\u52A0\u56FE\u7247\u3002\u652F\u6301\u672C\u5730\u6587\u4EF6\u8DEF\u5F84\uFF08\u81EA\u52A8\u4E0A\u4F20\u5230\u6587\u4EF6\u670D\u52A1\uFF09\u6216\u56FE\u7247 URL\u3002
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\uFF1Bconfirm=true \u624D\u4E0A\u4F20\u5E76\u6302\u5230\u5546\u54C1\uFF08\u4E0E\u73B0\u6709\u56FE\u7247\u5408\u5E76\uFF0C\u4E0D\u4F1A\u8986\u76D6\u5DF2\u6709\u56FE\u7247\uFF09\u3002`,
     schema: {
-      q: external_exports.string().optional(),
-      limit: external_exports.number().int().positive().max(100).default(50)
+      product_id: external_exports.string(),
+      images: external_exports.array(external_exports.string()).describe("\u672C\u5730\u56FE\u7247\u8DEF\u5F84\u6216\u56FE\u7247 URL"),
+      confirm: external_exports.boolean().default(false)
     },
     async run(input, { client: client2 }) {
-      return client2.listStockLocations({ q: input.q, limit: input.limit });
+      if (!input.confirm) {
+        return { dry_run: true, product_id: input.product_id, will_upload: input.images };
+      }
+      let urls = [];
+      try {
+        urls = await client2.uploadProductAssets(input.images);
+      } catch (e) {
+        return `\u9519\u8BEF\uFF1A\u56FE\u7247\u4E0A\u4F20\u5931\u8D25 \u2014\u2014 ${e?.message || e}`;
+      }
+      const existing = await client2.getProduct(input.product_id).catch(() => null);
+      const prod = existing?.product ?? existing ?? {};
+      const existingUrls = (prod.images || []).map((i) => i.url).filter(Boolean);
+      const merged = Array.from(/* @__PURE__ */ new Set([...existingUrls, ...urls]));
+      const data = await client2.updateProduct(input.product_id, {
+        images: merged.map((u) => ({ url: u }))
+      });
+      return { updated: data };
     }
   },
   {
-    name: "create_stock_location",
-    description: "\u589E\u52A0\u4E00\u4E2A\u4ED3\u5E93\uFF08StockLocation\uFF09\u3002\u9ED8\u8BA4 dry_run\u3002",
+    name: "add_product_to_sales_channel",
+    description: `\u628A\u5546\u54C1\u52A0\u5165\u9500\u552E\u6E20\u9053\uFF0C\u4F7F\u5176\u5728\u524D\u7AEF\u5546\u57CE\uFF08\u6309 publishable key \u2192 \u6E20\u9053\u8FC7\u6EE4\uFF09\u53EF\u89C1\u3002
+\u26A0\uFE0F Medusa v2 \u7AEF\u70B9\u6302\u5728\u6E20\u9053\u4E0B\uFF1APOST /admin/sales-channels/{id}/products\uFF0C\u800C\u975E\u5546\u54C1\u4E0B\u3002
+\u4E0D\u6307\u5B9A channel_id \u65F6\u9ED8\u8BA4\u52A0\u5165\u7B2C\u4E00\u4E2A\u542F\u7528\u7684\u6E20\u9053\u3002\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
     schema: {
-      name: external_exports.string(),
-      address: external_exports.object({
-        address_1: external_exports.string().optional(),
-        address_2: external_exports.string().optional(),
-        city: external_exports.string().optional(),
-        country_code: external_exports.string().optional(),
-        province: external_exports.string().optional(),
-        postal_code: external_exports.string().optional(),
-        phone: external_exports.string().optional()
-      }).optional(),
-      metadata: external_exports.record(external_exports.string(), external_exports.string()).optional(),
+      product_ids: external_exports.array(external_exports.string()).describe("\u8981\u52A0\u5165\u6E20\u9053\u7684\u5546\u54C1 id \u5217\u8868"),
+      channel_id: external_exports.string().optional().describe("\u9500\u552E\u6E20\u9053 id\uFF1B\u7701\u7565\u5219\u53D6\u7B2C\u4E00\u4E2A\u542F\u7528\u7684\u6E20\u9053"),
       confirm: external_exports.boolean().default(false)
     },
-    async run(input, { client: client2 }) {
-      const payload = { name: input.name };
-      if (input.address) payload.address = input.address;
-      if (input.metadata) payload.metadata = input.metadata;
-      if (!input.confirm) return { dry_run: true, will_create: payload };
-      return client2.createStockLocation(payload);
+    async run(input, { client: client2, config: config3 }) {
+      if (!input.confirm) {
+        return { dry_run: true, will_add: input.product_ids, channel_id: input.channel_id || "(\u9ED8\u8BA4\u7B2C\u4E00\u4E2A\u542F\u7528\u6E20\u9053)" };
+      }
+      let channelId = input.channel_id;
+      if (!channelId) {
+        const ch = await client2.listSalesChannels?.();
+        const list = ch?.sales_channels || [];
+        const firstEnabled = list.find((c) => !c.is_disabled) || list[0];
+        if (!firstEnabled) return "\u9519\u8BEF\uFF1A\u627E\u4E0D\u5230\u53EF\u7528\u7684\u9500\u552E\u6E20\u9053\u3002";
+        channelId = firstEnabled.id;
+      }
+      const data = await client2.addProductsToSalesChannel(channelId, input.product_ids);
+      return { added_to_channel: channelId, result: data };
     }
   },
   {
-    name: "get_inventory_levels",
-    description: "\u67E5\u8BE2\u67D0\u4ED3\u5E93\u4E0B\u7684\u5E93\u5B58\u6761\u76EE\u53CA\u5E93\u5B58\u6C34\u5E73\uFF08\u6309 location_id\uFF09\u3002",
+    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
+\u8FD4\u56DE { product_content: { id, product_id, locale, status, blocks(\u5DF2\u89E3\u6790\u6570\u7EC4) } | null }\u3002`,
     schema: {
-      location_id: external_exports.string(),
-      q: external_exports.string().optional(),
-      limit: external_exports.number().int().positive().max(100).default(50)
+      product_id: external_exports.string(),
+      locale: external_exports.enum(["en-US", "zh-CN", "ms-MY", "id-ID"]).default("en-US"),
+      status: external_exports.enum(["draft", "published"]).default("published")
     },
     async run(input, { client: client2 }) {
-      return client2.listInventoryItems(input.location_id, { q: input.q, limit: input.limit });
+      const data = await client2.getProductContent(input.product_id, input.locale, input.status);
+      const pc = data?.product_content;
+      if (!pc) return { product_content: null };
+      let blocks = [];
+      try {
+        blocks = pc.blocks ? JSON.parse(pc.blocks) : [];
+      } catch {
+        blocks = [];
+      }
+      return { product_content: { ...pc, blocks } };
     }
   },
   {
-    name: "update_inventory_level",
-    description: `\u4FEE\u6539\u67D0\u5E93\u5B58\u6761\u76EE\u5728\u6307\u5B9A\u4ED3\u5E93\u7684\u5E93\u5B58\u6570\u91CF\uFF08stocked_quantity\uFF09\u3002
-\u26A0\uFE0F \u7AEF\u70B9/\u5B57\u6BB5\u4EE5 Medusa 2.21 \u5951\u7EA6\u4E3A\u51C6\uFF08POST /admin/inventory-items/{id}/location-levels\uFF09\u3002\u9ED8\u8BA4 dry_run\u3002`,
+    name: "create_product_content",
+    description: `\u521B\u5EFA/\u66F4\u65B0\u5546\u54C1\u8BE6\u60C5\u9875\u5BCC\u5185\u5BB9\u5757\uFF08POST /admin/product-contents\uFF0C\u6309 product_id+locale upsert\uFF09\u3002
+storefront \u8BE6\u60C5\u9875\u300C\u5BCC\u5185\u5BB9\u300D\u533A\u7531\u8FD9\u4E9B\u5757\u6E32\u67D3\u2014\u2014\u4EC5\u586B product.description \u4E0D\u4F1A\u663E\u793A\u5728\u8FD9\u91CC\uFF0C\u5FC5\u987B\u5EFA\u5185\u5BB9\u5757\uFF0C\u5426\u5219\u8BE6\u60C5\u9875\u4E3B\u4F53\u7A7A\u767D\u3002
+\u533A\u5757\u7C7B\u578B type \u2208 hero / richtext / image_gallery / video / faq / specs\uFF1A
+- richtext: data.{ html }\uFF08\u76F4\u63A5\u6E32\u67D3 HTML\uFF0C\u53EF\u542B <p>/<h2>/<ul> \u7B49\uFF09
+- image_gallery: data.{ images:string[], caption? }
+- hero: data.{ image?, title?, subtitle? }
+- 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
+\u9ED8\u8BA4 dry_run\uFF08confirm=false\uFF09\u4EC5\u9884\u89C8\u3002`,
     schema: {
-      inventory_item_id: external_exports.string(),
-      location_id: external_exports.string(),
-      stocked_quantity: external_exports.number().int().nonnegative(),
+      product_id: external_exports.string(),
+      locale: external_exports.enum(["en-US", "zh-CN", "ms-MY", "id-ID"]).default("en-US"),
+      status: external_exports.enum(["draft", "published"]).default("published"),
+      blocks: external_exports.array(
+        external_exports.object({
+          id: external_exports.string().optional(),
+          type: external_exports.enum(["hero", "richtext", "image_gallery", "video", "faq", "specs"]),
+          data: external_exports.record(external_exports.string(), external_exports.any())
+        })
+      ).describe("ContentBlock[] \u6570\u7EC4"),
       confirm: external_exports.boolean().default(false)
     },
     async run(input, { client: client2 }) {
-      const payload = {
-        location_id: input.location_id,
-        stocked_quantity: input.stocked_quantity
-      };
-      if (!input.confirm) return { dry_run: true, will_update: payload };
-      return client2.updateInventoryLevel(input.inventory_item_id, payload);
+      if (!input.confirm) {
+        return {
+          dry_run: true,
+          will_create: {
+            product_id: input.product_id,
+            locale: input.locale,
+            status: input.status,
+            block_count: input.blocks.length,
+            types: input.blocks.map((b) => b.type)
+          }
+        };
+      }
+      const data = await client2.createProductContent({
+        product_id: input.product_id,
+        locale: input.locale,
+        status: input.status,
+        blocks: input.blocks
+      });
+      return { created: data };
     }
   }
 ];
@@ -22012,11 +22652,11 @@ var opsTools = [
 ];
 
 // src/resources/docs.ts
-import { readdirSync, readFileSync as readFileSync2, existsSync as existsSync2, statSync } from "node:fs";
+import { readdirSync, readFileSync as readFileSync3, existsSync as existsSync3, statSync } from "node:fs";
 import { join as join2 } from "node:path";
 var cache = null;
 function walk(dir, out = []) {
-  if (!existsSync2(dir)) return out;
+  if (!existsSync3(dir)) return out;
   for (const entry of readdirSync(dir)) {
     const full = join2(dir, entry);
     try {
@@ -22028,7 +22668,7 @@ function walk(dir, out = []) {
   return out;
 }
 function parseFile(path) {
-  const raw = readFileSync2(path, "utf8");
+  const raw = readFileSync3(path, "utf8");
   const lines = raw.split("\n");
   const title = lines.find((l) => l.startsWith("# "))?.slice(2).trim() || path;
   const sections = [];
@@ -22139,7 +22779,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.0" });
+var server = new McpServer({ name: "derlux-admin", version: "0.1.2" });
 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.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "让运营同学用本地 AI agent（Codex / Workbuddy / Claude / Cursor / CodeBuddy）运营 Medusa 后台的 MCP server。",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "skill"
   ],
   "scripts": {
     "dev": "tsx src/index.ts",

package/skill/SKILL.md

@@ -0,0 +1,215 @@
+---
+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`。
+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。
+
+## 工具速查表
+
+| 工具 | 类型 | 写库？ | 默认行为 |
+|---|---|---|---|
+| `list_products` | 读 | 否 | 直接返回 |
+| `get_product` | 读 | 否 | 直接返回 |
+| `list_sales_channels` | 读 | 否 | 直接返回（渠道 id/名称，建商品前确认用）|
+| `list_collections` | 读 | 否 | 直接返回 |
+| `get_translations` | 读 | 否 | 直接返回（某商品各语言的 title/description，多语言核对唯一可靠途径）|
+| `list_stock_locations` | 读 | 否 | 直接返回 |
+| `get_inventory_levels` | 读 | 否 | 直接返回（location_id 可选：按仓库列库存条目与水平；q 按 sku/title 过滤）|
+| `set_product_stock` | 写 | 是（`confirm=true` 才写）| 幂等建仓：自动找/建库存条目 + 写仓库数量 + manage_inventory；`confirm=false` 仅预览 |
+| `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_sales_channels`**：列出销售渠道（含 id / 名称 / 启用状态）。
+  - `q`（string，可选）按名称过滤；`limit`（int 1–100，默认 50）。
+- **`list_collections`**：列出集合（如「双11活动」）。
+  - `q`（string，可选）；`limit`（int 1–100，默认 50）。
+- **`get_translations`**：读取多语言翻译（GET /admin/translations）。
+  - `reference_id`（string，**必填**，商品 id 或 handle）；`reference`（默认 `product`）；`locale_code`（可选，如 `zh`）；`limit`（默认 50）。
+
+### 读 —— 仓库与库存
+- **`list_stock_locations`**：列出仓库（StockLocation）。
+  - `q`（string，可选）按名称过滤；`limit`（int 1–100，默认 50）。
+- **`get_inventory_levels`**：列出库存条目及库存水平（Medusa 2.21 走 `GET /admin/inventory-items`）。
+  - `location_id`（string，**可选**：只回该仓库有水平的条目）；`q`（string，可选，按 sku/title 过滤）；`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`）；`prices`（`{currency_code,amount}[]`，可选，多币种，优先于单一 price）；`translations`（`record<locale,{title?,description?}>`，建议覆盖 `en/zh/ms/id`）；`images`（string[]，可选，本地图片路径或图片 URL，工具自动上传并挂接）；`sku`（string，可选，写入默认变体 SKU）；`metadata`（`record<string,string>`，可选，存规格参数/来源链接等任意键值）；`sales_channels`（string[]，可选，渠道 id 或名称如 `"MY Storefront"`，创建即挂载）；`collection_id`（string，可选，集合 id 或名称）；`weight`/`length`/`height`/`width`（number，可选，克/厘米）；`origin_country`/`hs_code`/`mid_code`/`material`（string，可选）；`manage_inventory`（bool，**默认 true**）；`initial_stock`（`{location_id?, quantity}`，可选，建库存；**正式上架必给**，见硬规则 9）；`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` 端点、按 `initial_stock` 建库存条目并写仓库。
+- **`update_product`**：修改商品字段（标题/handle/状态/描述/多语言/物理尺寸/海关/集合/metadata）。
+  - `id`（string，**必填**）；`title`/`handle`/`status`/`subtitle`/`description`/`translations`/`collection_id`（集合 id 或名称）/`weight`/`length`/`height`/`width`/`origin_country`/`hs_code`/`mid_code`/`material`/`metadata`（均可选）。
+  - `metadata` 为**合并**语义：新键覆盖同名键、未提及的旧键保留（不支持删除键）。改库存请用 `set_product_stock`，改价格请用 `update_product_prices`。
+  - `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）。
+- **`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。重复调用安全。
+- **`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`。
+
+## 推荐操作流程（SOP）
+
+**创建商品**
+1. 先收集：标题、handle（或告知由标题生成）、价格（主单位）、四语言标题、状态、图片、规格、重量、初始库存数量、目标渠道、详情页富文本内容（按语言）。
+2. 调用 `create_product`（`confirm=false`）→ 展示预览与「缺语言 / 缺货」告警。
+3. 提醒运营补全缺失语言与 `initial_stock`；确认无误后调用 `create_product`（`confirm=true`，`sales_channels` 里带上目标渠道，必要时 `acknowledge_missing_languages=true`）。创建即完成：图片上传、SKU、翻译、渠道挂载、建库存。
+4. **`create_product_content`（`confirm=true`，逐语言 `en-US/zh-CN/ms-MY/id-ID`）** → 写详情页富内容块（richtext 描述 + specs 规格 + image_gallery 图集）。否则详情页主体空白。
+5. 用 `get_translations` + `get_product_content` 核对多语言与富内容；把新商品 id/handle 告知运营。
+
+**修改 / 下架商品**
+1. `get_product` 或 `list_products` 确认目标 id。
+2. `update_product` / `deactivate_product`（`confirm=false`）→ 展示预览。
+3. 确认后同名工具 `confirm=true` 执行。
+
+**建仓 / 调整库存**
+1. 直接 `set_product_stock`（`product_id` + `quantity`，`confirm=false` 预览 → 确认后 `confirm=true`）——自动处理库存条目与仓库。
+2. 查现状：`get_inventory_levels`（`location_id` 可选、`q` 按 sku 过滤）。
+3. 已知 `inventory_item_id` 的精细调整：`update_inventory_level`（upsert）。
+
+**查询类**：直接调用对应读工具即可，无需 `confirm`。
+
+## 常见任务示例（运营怎么说 / 你怎么调）
+
+- 「下架 handle 为 `summer-serum` 的商品」→ `get_product`(id_or_handle=`summer-serum`) 取 id → `deactivate_product`(id, confirm=false 预览 → 确认后 confirm=true)。
+- 「给 A 商品补 100 件库存」→ `set_product_stock`(product_id=A 的 id, quantity=100, confirm=false 预览 → 确认后 confirm=true；默认写 Main Warehouse，指定仓传 location_id)。
+- 「查一下最近 10 个待发货订单」→ `list_orders`(status=`pending`, limit=10)。
+- 「后台怎么新建优惠券」→ `ask_usage`(question=`如何新建优惠券`)。
+- 「列出所有退货请求」→ `list_return_requests`()。
+- 「把这份抓取的 Lazada 商品录入：标题 DR.CYJ Hair Filler、价格 420 MYR、4 张本地图、SKU `4820...`、规格存 metadata、补全中/马来/印尼语翻译」→ 先整理数据，`create_product`（`confirm=false` 看预览含 images/sku/metadata/缺语言/缺货告警 → 确认后 `confirm=true`，带 `sales_channels: ["MY Storefront"]`、`initial_stock: {quantity: 100}`、`weight: 150`，必要时 `acknowledge_missing_languages=true`）。工具会自动上传图片、写 SKU/metadata/物理字段、四语言翻译、渠道挂载并建库存。再 `create_product_content`(`locale=en-US/zh-CN/ms-MY/id-ID`, `confirm=true`) 逐语言写富内容块（richtext 描述 + specs 规格 + image_gallery 图集），最后 `get_translations` + `get_product_content` 核对。
+- 「核对某商品多语言是否齐全」→ `get_translations`(reference_id=商品 id 或 handle)，看 4 条 locale 是否都有 title/description。
+- 「让这个商品在前端能搜到」→ `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` 选项，你无需关心；**更新**商品时 `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` 全程幂等可重放。
+- 自定义端点 `warehouse-tasks` / `return-requests` / `product-contents` 为本项目扩展。
+- 文档问答（`search_docs` / `ask_usage`）依赖知识源目录；npx 形态下默认 `./docs`，若问不到相关内容，提示运营换关键词或查后台手册。
+- 用受限的 `csr` 账号即可完成日常运营；敏感动作由后端 RBAC 拦截。