<a id="zh"></a>

<p align="right"> <a href="#zh"><kbd>中文</kbd></a> <a href="#en"><kbd>English</kbd></a> </p>

Product MCP

Product MCP 是一个面向 ERP 商品业务的 MCP 服务，包含远程 HTTP MCP Server 和本地 Chrome Token Bridge。

它的目标不是让用户手动复制 token，而是让 AI Agent 在用户已经登录 ERP 的前提下，通过本地桥接自动取得当前用户登录态，并安全地完成商品资料预检、文件上传、基础资料查询和商品创建。

给 AI Agent 的快速契约

如果你是 AI Agent，请优先遵守本节。

你应该做什么

• 先调用 product_auth_status，确认本地 Chrome 中存在 ERP 登录态。
• 使用只读工具查询真实后端 ID，不要让用户手填分类、单位、供应商、区域等 ID。
• 处理本地商品资料包时，先调用 product_precheck_package，再根据返回的 uploadQueue 调用 product_upload_file。
• 调用 product_upload_file 时保留 uploadQueue 中的 dedupeKey/sourceRelativePath/sourceLocalPath，重复文件会复用第一次上传得到的 OSS URL。
• 创建商品前，向用户总结即将写入的关键信息，并取得明确确认。
• 只有在用户确认后，才调用 product_create，并传入 confirm: true。
• 商品创建成功后，调用 product_get_detail 验证结果。
• 大整数 ID 一律按字符串传入，避免 JavaScript 精度丢失。

你不应该做什么

• 不要要求用户粘贴或暴露 Admin-Token。
• 不要在没有用户明确确认的情况下调用 product_create。
• 不要把本地文件路径直接交给远程 HTTP MCP；远程服务不能读取用户本地文件。
• status=3 表示作废状态；只有用户明确要求创建为作废状态时才传入。

推荐创建流程

1. product_auth_status
2. product_precheck_package
3. product_list_categories
4. product_get_category_config
5. product_list_suppliers
6. product_list_regions
7. product_get_dict
8. product_upload_file
9. 向用户总结并确认写入操作
10. product_create，必须包含 confirm: true
11. product_get_detail

这个仓库做什么

Product MCP 提供三类能力：

能力	说明
远程 HTTP MCP Server	对外暴露 ERP 商品相关 MCP tools，转发用户 Authorization 到 ERP 后端
本地 Chrome Token Bridge	通过 Chrome DevTools MCP 读取用户已登录 ERP 页面中的 localStorage.Admin-Token
本地文件工具	预检商品资料包、校验文件、按要求裁剪图片、通过 STS 上传 OSS

架构

MCP Client
  -> Local Token Bridge, stdio
    -> Chrome DevTools MCP
      -> logged-in ERP tab
      -> localStorage.Admin-Token
    -> Remote Product MCP, HTTP /mcp
      -> ERP backend APIs
      -> OSS STS API

工具清单

远程 HTTP MCP 工具

这些工具运行在远程 MCP Server 中，需要请求携带当前用户的 Authorization。

Tool	读写	用途
product_list_categories	只读	查询商品分类树
product_get_category_config	只读	查询分类下的单位、基础配置、技术参数、可选配置
product_list_suppliers	只读	查询并扁平化供应商选项
product_list_regions	只读	查询适用区域
product_get_dict	只读	查询系统字典
product_get_detail	只读	创建后查询商品详情，用于验收
product_create	写入	通过 ERP 后端创建真实商品

本地 Bridge 工具

这些工具在本地 bridge 中可用。本地路径读取、图片裁剪和文件上传都应通过本地 bridge 完成。

Tool	读写	用途
product_auth_status	只读	检查 Chrome ERP 登录态是否可用，不返回 token 内容
product_precheck_package	本地只读	解析并校验本地商品资料包
product_upload_file	上传写入	校验、必要时裁剪并上传本地文件到 OSS
远程工具代理	混合	自动携带 Chrome token 调用远程 MCP

安装与运行

需要 Node.js 18.18 或更高版本。

npm ci
npm run build
npm start

本地 smoke 测试：

npm run smoke

smoke 测试不会创建真实商品。它会启动模拟后端，验证工具注册、请求映射和响应归一化。

远程 MCP Server

默认端点：

POST /mcp
GET /healthz

环境变量

复制 .env.example，并在部署环境中配置真实值。

PRODUCT_MCP_PORT=8787
PRODUCT_MCP_HOST=0.0.0.0
PRODUCT_MCP_PATH=/mcp
PRODUCT_MCP_ALLOWED_HOSTS=
PRODUCT_MCP_BACKEND_BASE_URL=https://your-frontend-or-gateway-domain/api
PRODUCT_MCP_CLIENT_ID=e5cd7e4891bf95d1d19206ce24a7b32e
PRODUCT_MCP_REQUEST_TIMEOUT_MS=50000
PRODUCT_MCP_DEFAULT_LANGUAGE=zh_CN

PRODUCT_MCP_BACKEND_BASE_URL 必须是服务端可访问的后端 API 基础地址，语义上应等同于前端 /api 或 /dev-api 指向的后端。

鉴权

远程 MCP 请求需要携带：

Authorization: Bearer <user-token>

服务端会把同一个 Authorization 转发给 ERP 后端，并附带配置中的 clientid 请求头。

本地 Token Bridge

本地 bridge 是推荐给 Codex 用户的入口。它可以避免用户手动复制 token。

Bridge 配置

默认配置文件：

product-token-bridge.config.json

关键字段：

{
  "projectUrl": "https://test.eysscm.com/erp/purchase",
  "matchUrlPrefixes": ["https://test.eysscm.com/erp/"],
  "tokenStorageKey": "Admin-Token",
  "remoteMcpUrl": "http://47.95.237.95:8787/mcp",
  "backendBaseUrl": "https://test.eysscm.com/api",
  "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
  "language": "zh_CN"
}

MCP Client 配置

如果希望 MCP 客户端自动从 Chrome 获取登录态，可以配置 stdio server：

{
  "mcpServers": {
    "product": {
      "command": "node",
      "args": [
        "D:\\path\\to\\product-mcp\\dist\\localBridge.js",
        "--config",
        "D:\\path\\to\\product-mcp\\product-token-bridge.config.json"
      ]
    }
  }
}

使用 bridge 前，用户必须先在 Chrome 中登录 ERP 系统，并保留一个匹配 matchUrlPrefixes 的 ERP 页面。

Token 缓存与失效

本地 bridge 会在进程内缓存第一次读取到的 Admin-Token，最长缓存 2 小时。缓存只存在于当前 bridge 进程内存中，不写入磁盘，也不会返回 token 内容。

缓存命中时，后续工具调用会直接复用 token，避免每次都重新唤起 Chrome DevTools MCP 调试确认窗口。

缓存失效规则：

• 超过 2 小时自动失效，下次调用会重新从 Chrome 读取。
• 远程 Product MCP 或 ERP 后端返回 401/403 时，bridge 会立即清空缓存，重新从 Chrome 读取 token，并自动重试一次。
• product_auth_status 支持 forceRefresh: true，用于主动绕过缓存并重新读取 Chrome。

部署

PM2

cd product-mcp
npm ci
npm run build
cp deploy.env.example deploy.env
# edit deploy.env and set PRODUCT_MCP_BACKEND_BASE_URL
set -a
. ./deploy.env
set +a
npx pm2 start ecosystem.config.cjs
npx pm2 save

验证：

curl http://127.0.0.1:8787/healthz

Docker

cd product-mcp
docker build -t product-mcp:0.1.0 .
docker run -d --name product-mcp --env-file deploy.env -p 8787:8787 product-mcp:0.1.0

如需 HTTPS，请放到公司网关或 Nginx 后面。

location /mcp {
  proxy_pass http://127.0.0.1:8787/mcp;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

location /healthz {
  proxy_pass http://127.0.0.1:8787/healthz;
}

工具细节

product_auth_status

检查配置的 Chrome ERP 页面中是否存在 localStorage.Admin-Token。

成功结果示例：

{
  "ok": true,
  "projectUrl": "https://test.eysscm.com/erp/purchase",
  "matchedPageUrl": "https://test.eysscm.com/erp/commodity/commodity",
  "tokenStorageKey": "Admin-Token",
  "tokenPresent": true,
  "tokenLength": 245,
  "tokenSource": "cache",
  "tokenCache": {
    "enabled": true,
    "maxTtlSeconds": 7200,
    "fromCache": true,
    "fetchedAt": "2026-06-17T08:00:00.000Z",
    "expiresAt": "2026-06-17T10:00:00.000Z",
    "expiresInSeconds": 6500
  },
  "remoteMcpUrl": "http://47.95.237.95:8787/mcp"
}

product_precheck_package

本地运行。读取商品资料包目录或商品资料 Markdown 文件，解析已支持字段和文件表格，校验本地文件，并返回创建草稿和上传队列。

仓库内提供最新字段范本：

templates/商品资料模板.md

使用时把这个文件复制到用户自己的商品资料包目录，命名为 商品资料.md，再替换商品字段、供应商、分类名称和文件相对路径。模板中的本地文件路径只是结构示例，真实创建前必须指向用户资料包中实际存在的文件。

输入：

{
  "packagePath": "D:\\path\\to\\product-package",
  "includeDraft": true
}

说明：

• 不上传文件。
• 不创建商品。
• 必要时会使用 sharp 强制裁剪有比例要求的图片。
• 裁剪产物写入 .generated/prepared/。
• uploadQueue 每一项都会带上 dedupeKey、sourceRelativePath、sourceLocalPath。AI 调用 product_upload_file 时应原样保留这些字段，用于同一资料包内重复文件的 OSS URL 复用。

命令行验证：

npm run build
node dist/packagePrecheckCli.js "D:/path/to/product-package"

product_upload_file

本地运行。校验本地文件，必要时处理图片，通过 ERP 后端获取 OSS STS token，直传 OSS，并返回 OSS URL。同一 bridge 进程内，如果再次上传相同 dedupeKey 且源文件未变化，会直接复用第一次上传的 OSS URL，结果中 reusedUpload 为 true。

输入：

{
  "localPath": "D:/path/to/file.png",
  "usage": "productMainImage",
  "title": "optional title",
  "description": "optional description",
  "languageList": ["zh", "en"],
  "dedupeKey": "optional key from product_precheck_package",
  "sourceRelativePath": "./图片/main.png",
  "sourceLocalPath": "D:/path/to/product-package/图片/main.png"
}

常用 usage：

productMainImage
bannerImage
detailImage
sizeImage
sceneImage
packageImage
multiAngleImage
accessoriesImage
realVideo
loadingVideo
workVideo
installVideo
packingVideo
linkActualTestingVideo
thirdActualTestingVideo
model3d
productAttachment
certificateFile
certificateMainImage
graphicDetailImage
advantageImage
scenarioImage
caseImage
caseVideo
serviceSupportFile
partsImage
partsAttachment
richTextImage
richTextVideo
richTextAttachment

product_create

写入操作。通过以下后端接口创建真实 ERP 商品：

POST /user/erp/commodity

最小输入：

{
  "confirm": true,
  "productNameCn": "测试商品",
  "productNameEn": "Test Product",
  "productType": 1,
  "status": 1,
  "categoryFirstId": "1",
  "unitId": "9",
  "supplierId": "88",
  "useAllRegions": true
}

上传主图后的推荐输入：

{
  "confirm": true,
  "productNameCn": "测试商品",
  "productNameEn": "Test Product",
  "productType": 1,
  "status": 1,
  "categoryFirstId": "1",
  "unitId": "9",
  "supplierId": "88",
  "useAllRegions": true,
  "productMainImageUrl": "https://example.oss-cn-beijing.aliyuncs.com/path/main.png",
  "productMainImageName": "main.png",
  "packageInfo": {
    "packLength": 100,
    "packWidth": 100,
    "packHeight": 100,
    "packCubic": "0.01",
    "packingFee": 1,
    "packWeight": 2,
    "netWeight": 1
  }
}

confirm: true 是必填项。status 支持 1 上架、2 下架、3 作废；默认建议使用 1，只有用户明确要求作废状态时才传 3。

product_create 兼容两种输入风格：可以继续使用 supplierId、supplierName、packageInfo 等 MCP 便捷字段；也可以直接使用后端 CommoditySaveDTO 的 suppliers 数组、顶层包装/装柜字段、tenantId、relatedCommodityId 等字段。两者同时存在时，顶层后端 DTO 字段优先覆盖 packageInfo 中的同名包装字段。

成功结果示例：

{
  "ok": true,
  "id": "123456",
  "productId": "123456",
  "frontendEditPath": "/erp/commodity/editCommodity/123456",
  "frontendViewPath": "/erp/commodity/viewCommodity/123456"
}

排错

未获取到 Chrome token

可能原因：

• Chrome 未打开。
• ERP 页面未登录。
• 当前页面 URL 不匹配 matchUrlPrefixes。
• 目标环境的 token key 不是 Admin-Token。

推荐给用户的提示：

请打开 Chrome 并登录 ERP 系统，保留一个匹配配置 URL 前缀的 ERP 页面，刷新页面后重新调用 product_auth_status。

远程 MCP 返回 401

• 直接 HTTP 连接必须提供 Authorization: Bearer <user-token>。
• 使用本地 bridge 时，先检查 product_auth_status。

本地文件路径失败

• 远程 MCP 不能读取本地路径。
• 本地路径应通过本地 bridge 的 product_precheck_package 或 product_upload_file 处理。
• 确认路径为绝对路径，或相对于 bridge 进程工作目录。

仓库拆分建议

本仓库只负责 Product MCP 运行时代码。

推荐使用两个兄弟仓库：

product-mcp          # 本仓库，MCP server 和 bridge
erp-product-plugin   # Codex plugin marketplace wrapper

Codex plugin marketplace 可以通过 PRODUCT_MCP_HOME 或兄弟目录查找来启动本仓库的本地 bridge。

---

<a id="en"></a>

<p align="right"> <a href="#zh"><kbd>中文</kbd></a> <a href="#en"><kbd>English</kbd></a> </p>

Product MCP

Product MCP is an MCP service for ERP product operations. It includes a remote HTTP MCP Server and a local Chrome Token Bridge.

Its goal is to avoid manual token copying. When the user has already logged in to ERP in Chrome, an AI Agent can use the local bridge to obtain the current login state safely, then precheck product packages, upload files, query ERP references, and create products.

Quick Contract For AI Agents

If you are an AI Agent, read this section first.

What You Should Do

• Call product_auth_status first to confirm that the ERP login state is available in local Chrome.
• Use read-only lookup tools to resolve real backend IDs. Do not ask the user to manually fill category, unit, supplier, or region IDs.
• For a local product package, call product_precheck_package first, then call product_upload_file for items in the returned uploadQueue.
• Preserve dedupeKey/sourceRelativePath/sourceLocalPath from each uploadQueue item when calling product_upload_file; repeated files reuse the first OSS URL.
• Before creating a product, summarize the key fields that will be written and ask the user for explicit confirmation.
• Call product_create only after confirmation, and pass confirm: true.
• After creation succeeds, call product_get_detail to verify the result.
• Pass large numeric IDs as strings to avoid JavaScript precision loss.

What You Should Not Do

• Do not ask the user to paste or reveal Admin-Token.
• Do not call product_create without explicit user confirmation.
• Do not pass local file paths directly to the remote HTTP MCP. The remote server cannot read local user files.
• status=3 means void. Pass it only when the user explicitly asks to create the product in a voided state.

Recommended Creation Flow

1. product_auth_status
2. product_precheck_package
3. product_list_categories
4. product_get_category_config
5. product_list_suppliers
6. product_list_regions
7. product_get_dict
8. product_upload_file
9. Summarize the write operation and ask the user to confirm
10. product_create with confirm: true
11. product_get_detail

What This Repository Does

Product MCP provides three capability groups:

Capability	Description
Remote HTTP MCP Server	Exposes ERP product MCP tools and forwards the user's Authorization to the ERP backend
Local Chrome Token Bridge	Reads localStorage.Admin-Token from a logged-in ERP page through Chrome DevTools MCP
Local File Tools	Prechecks product packages, validates files, crops images when required, and uploads files to OSS through STS

Architecture

MCP Client
  -> Local Token Bridge, stdio
    -> Chrome DevTools MCP
      -> logged-in ERP tab
      -> localStorage.Admin-Token
    -> Remote Product MCP, HTTP /mcp
      -> ERP backend APIs
      -> OSS STS API

Tool Surface

Remote HTTP MCP Tools

These tools run on the remote MCP Server. Requests must carry the current user's Authorization.

Tool	Access	Purpose
product_list_categories	Read	Query the product category tree
product_get_category_config	Read	Query units, base configs, technical params, and optional configs for a category
product_list_suppliers	Read	Query and flatten supplier options
product_list_regions	Read	Query applicable regions
product_get_dict	Read	Query system dictionary values
product_get_detail	Read	Query product details after creation for verification
product_create	Write	Create a real product through the ERP backend

Local Bridge Tools

These tools are available in the local bridge. Local path reads, image preparation, and file uploads should go through the local bridge.

Tool	Access	Purpose
product_auth_status	Read	Check whether Chrome ERP login state is available without returning token content
product_precheck_package	Local read	Parse and validate a local product package
product_upload_file	Upload write	Validate, optionally crop, and upload a local file to OSS
Remote tool proxy	Mixed	Call remote MCP tools with the Chrome token attached automatically

Install And Run

Node.js 18.18 or later is required.

npm ci
npm run build
npm start

Local smoke test:

npm run smoke

The smoke test does not create a real product. It starts a fake backend and verifies tool registration, request mapping, and response normalization.

Remote MCP Server

Default endpoints:

POST /mcp
GET /healthz

Environment Variables

Copy .env.example and set real values in the deployment environment.

PRODUCT_MCP_PORT=8787
PRODUCT_MCP_HOST=0.0.0.0
PRODUCT_MCP_PATH=/mcp
PRODUCT_MCP_ALLOWED_HOSTS=
PRODUCT_MCP_BACKEND_BASE_URL=https://your-frontend-or-gateway-domain/api
PRODUCT_MCP_CLIENT_ID=e5cd7e4891bf95d1d19206ce24a7b32e
PRODUCT_MCP_REQUEST_TIMEOUT_MS=50000
PRODUCT_MCP_DEFAULT_LANGUAGE=zh_CN

PRODUCT_MCP_BACKEND_BASE_URL must be a server-side reachable backend API base URL. Semantically, it should point to the same backend as the frontend /api or /dev-api proxy.

Authentication

Remote MCP requests must include:

Authorization: Bearer <user-token>

The server forwards the same Authorization to ERP backend APIs and also sends the configured clientid request header.

Local Token Bridge

The local bridge is the recommended entry point for Codex users. It avoids manual token copying.

Bridge Config

Default config file:

product-token-bridge.config.json

Important fields:

{
  "projectUrl": "https://test.eysscm.com/erp/purchase",
  "matchUrlPrefixes": ["https://test.eysscm.com/erp/"],
  "tokenStorageKey": "Admin-Token",
  "remoteMcpUrl": "http://47.95.237.95:8787/mcp",
  "backendBaseUrl": "https://test.eysscm.com/api",
  "clientId": "e5cd7e4891bf95d1d19206ce24a7b32e",
  "language": "zh_CN"
}

MCP Client Config

Use this stdio server config when the MCP client should get the login state from Chrome automatically:

{
  "mcpServers": {
    "product": {
      "command": "node",
      "args": [
        "D:\\path\\to\\product-mcp\\dist\\localBridge.js",
        "--config",
        "D:\\path\\to\\product-mcp\\product-token-bridge.config.json"
      ]
    }
  }
}

Before using the bridge, the user must log in to ERP in Chrome and keep an ERP page that matches matchUrlPrefixes.

Token Cache And Invalidation

The local bridge caches the first Admin-Token it reads in process memory for up to 2 hours. The cache is memory-only, never written to disk, and the token value is never returned.

When the cache is valid, later tool calls reuse the token and avoid reopening the Chrome DevTools MCP confirmation flow for every call.

Cache invalidation rules:

• The token automatically expires after 2 hours; the next call reads from Chrome again.
• If the remote Product MCP or ERP backend returns 401/403, the bridge immediately clears the cache, reads the token from Chrome again, and retries once.
• product_auth_status supports forceRefresh: true to bypass the cache and read from Chrome manually.

Deployment

PM2

cd product-mcp
npm ci
npm run build
cp deploy.env.example deploy.env
# edit deploy.env and set PRODUCT_MCP_BACKEND_BASE_URL
set -a
. ./deploy.env
set +a
npx pm2 start ecosystem.config.cjs
npx pm2 save

Verify:

curl http://127.0.0.1:8787/healthz

Docker

cd product-mcp
docker build -t product-mcp:0.1.0 .
docker run -d --name product-mcp --env-file deploy.env -p 8787:8787 product-mcp:0.1.0

For HTTPS, place this service behind a company gateway or Nginx.

location /mcp {
  proxy_pass http://127.0.0.1:8787/mcp;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  proxy_set_header X-Forwarded-Proto $scheme;
}

location /healthz {
  proxy_pass http://127.0.0.1:8787/healthz;
}

Tool Details

product_auth_status

Checks whether the configured Chrome ERP page contains localStorage.Admin-Token.

Example success result:

{
  "ok": true,
  "projectUrl": "https://test.eysscm.com/erp/purchase",
  "matchedPageUrl": "https://test.eysscm.com/erp/commodity/commodity",
  "tokenStorageKey": "Admin-Token",
  "tokenPresent": true,
  "tokenLength": 245,
  "tokenSource": "cache",
  "tokenCache": {
    "enabled": true,
    "maxTtlSeconds": 7200,
    "fromCache": true,
    "fetchedAt": "2026-06-17T08:00:00.000Z",
    "expiresAt": "2026-06-17T10:00:00.000Z",
    "expiresInSeconds": 6500
  },
  "remoteMcpUrl": "http://47.95.237.95:8787/mcp"
}

product_precheck_package

Runs locally. It reads a product package directory or product Markdown file, parses supported fields and file tables, validates local files, and returns a create draft plus an upload queue.

The repository ships the latest field template:

templates/商品资料模板.md

Copy this file into the user's own product package directory as 商品资料.md, then replace product fields, supplier/category names, and relative file paths. File paths in the template are structural examples; before real creation they must point to files that actually exist in the user's package.

Input:

{
  "packagePath": "D:\\path\\to\\product-package",
  "includeDraft": true
}

Notes:

• It does not upload files.
• It does not create a product.
• Images with required aspect ratios are force-cropped by sharp when needed.
• Cropped outputs are written under .generated/prepared/.
• Every uploadQueue item includes dedupeKey, sourceRelativePath, and sourceLocalPath. AI agents should preserve these fields when calling product_upload_file so repeated files in the same package can reuse the first OSS URL.

CLI verification:

npm run build
node dist/packagePrecheckCli.js "D:/path/to/product-package"

product_upload_file

Runs locally. It validates a local file, prepares an image when needed, obtains an OSS STS token from the ERP backend, uploads directly to OSS, and returns the OSS URL. In the same bridge process, uploading the same dedupeKey again with an unchanged source file reuses the first OSS URL and returns reusedUpload: true.

Input:

{
  "localPath": "D:/path/to/file.png",
  "usage": "productMainImage",
  "title": "optional title",
  "description": "optional description",
  "languageList": ["zh", "en"],
  "dedupeKey": "optional key from product_precheck_package",
  "sourceRelativePath": "./图片/main.png",
  "sourceLocalPath": "D:/path/to/product-package/图片/main.png"
}

Common usage values:

productMainImage
bannerImage
detailImage
sizeImage
sceneImage
packageImage
multiAngleImage
accessoriesImage
realVideo
loadingVideo
workVideo
installVideo
packingVideo
linkActualTestingVideo
thirdActualTestingVideo
model3d
productAttachment
certificateFile
certificateMainImage
graphicDetailImage
advantageImage
scenarioImage
caseImage
caseVideo
serviceSupportFile
partsImage
partsAttachment
richTextImage
richTextVideo
richTextAttachment

product_create

Write operation. Creates a real ERP product through:

POST /user/erp/commodity

Minimal input:

{
  "confirm": true,
  "productNameCn": "测试商品",
  "productNameEn": "Test Product",
  "productType": 1,
  "status": 1,
  "categoryFirstId": "1",
  "unitId": "9",
  "supplierId": "88",
  "useAllRegions": true
}

Recommended input after uploading a main image:

{
  "confirm": true,
  "productNameCn": "测试商品",
  "productNameEn": "Test Product",
  "productType": 1,
  "status": 1,
  "categoryFirstId": "1",
  "unitId": "9",
  "supplierId": "88",
  "useAllRegions": true,
  "productMainImageUrl": "https://example.oss-cn-beijing.aliyuncs.com/path/main.png",
  "productMainImageName": "main.png",
  "packageInfo": {
    "packLength": 100,
    "packWidth": 100,
    "packHeight": 100,
    "packCubic": "0.01",
    "packingFee": 1,
    "packWeight": 2,
    "netWeight": 1
  }
}

confirm: true is mandatory. status supports 1 on shelf, 2 off shelf, and 3 void. Prefer the default 1; pass 3 only when the user explicitly asks for a voided state.

product_create accepts both input styles: existing MCP convenience fields such as supplierId, supplierName, and packageInfo; and backend CommoditySaveDTO fields such as suppliers, top-level package/container fields, tenantId, and relatedCommodityId. When both styles provide the same package field, the top-level backend DTO field wins over packageInfo.

Example success result:

{
  "ok": true,
  "id": "123456",
  "productId": "123456",
  "frontendEditPath": "/erp/commodity/editCommodity/123456",
  "frontendViewPath": "/erp/commodity/viewCommodity/123456"
}

Troubleshooting

Missing Chrome token

Likely causes:

• Chrome is not open.
• The ERP page is not logged in.
• The current page URL does not match matchUrlPrefixes.
• The token key in the target environment is not Admin-Token.

Recommended user-facing prompt:

Please open Chrome, log in to the ERP system, keep an ERP page that matches the configured URL prefix, refresh the page, then call product_auth_status again.

Remote MCP returns 401

• Direct HTTP clients must provide Authorization: Bearer <user-token>.
• Local bridge users should check product_auth_status first.

Local file path fails

• Remote MCP cannot read local paths.
• Local paths should be handled through product_precheck_package or product_upload_file in the local bridge.
• Make sure the path is absolute, or relative to the bridge process working directory.

Repository Split

This repository should stay focused on Product MCP runtime code.

Recommended sibling repositories:

product-mcp          # this repo, MCP server and bridge
erp-product-plugin   # Codex plugin marketplace wrapper

The Codex plugin marketplace wrapper can start this repository's local bridge through PRODUCT_MCP_HOME or sibling directory lookup.