Ecshopx Ai MCP Cli - MCP Servers

ECShopX AI MCP / CLI（ecshopx-agent-workspace）

封装 ecshopx 后台与 H5 能力的 MCP Server（stdio / HTTP） 与命令行 shopex，三者为同一 workspace：

ecshopx-agent-core：TypeScript SDK（catalog、Token、缓存、审计等）
ecshopx-mcp-server：基于 agent-core 的 MCP Server
ecshopx-cli：CLI shopex，与 MCP 共用实现

0. 获取代码与目录说明

从远端克隆后，仓库根目录名为 ECShopX_Ai-mcp-cli（内含根级 package.json 与上述三个子目录）。若本项目作为其它仓库子目录使用（例如 ecshopx-Java 下的 ai-tool/），以下所有命令均在「含 package.json 的那一层」执行，把路径换成你的实际目录即可。

| 平台 | 克隆命令 | |------|----------| | GitHub | git clone https://github.com/ShopeX/ECShopX_Ai-mcp-cli.git | | Gitee | git clone https://gitee.com/ShopeX/ECShopX_Ai-mcp-cli.git |

cd ECShopX_Ai-mcp-cli

1. 安装依赖

cd ECShopX_Ai-mcp-cli   # 或 cd ai-tool（嵌入大仓时）
npm ci

要求 Node.js >= 20。

2. 构建与测试

# 构建三个包（agent-core / mcp-server / cli）
npm run build

# 运行全部单元测试（Vitest）
npm test

# 持续监听测试
npm run test:watch

3. 启动 MCP Server

3.1 stdio 模式（本地 Cursor / Claude Code 等）

cd ECShopX_Ai-mcp-cli
npm run build
npm run mcp:stdio
# 等价：node ecshopx-mcp-server/dist/index.js

Cursor / 客户端配置要点：

command: node
args: 指向 ecshopx-mcp-server/dist/index.js 的绝对路径（需先 npm run build 生成 dist）
cwd: 仓库根目录的绝对路径（与 ecshopx-cli、依赖解析一致，填 ECShopX_Ai-mcp-cli 那一层）
env（按需）：
- ECX_BASE_URL：API 基址，例如 Java 环境 http://ecxjava.test，或对接 PHP 时 http://ecxphp.test
- ECX_ACCESS_TOKEN：后台 JWT（可选，按你的鉴权方式配置）
- ECX_MCP_CONFIG_PATH：MCP 工具白名单等配置的绝对路径，一般指向仓库内 ecshopx-mcp-server/config.json

mcpServers 配置样例（将 /path/to/ECShopX_Ai-mcp-cli 全部替换为你本机克隆目录的绝对路径；Windows 使用 C:\\Users\\...\\ECShopX_Ai-mcp-cli 形式）：

{
  "mcpServers": {
    "ecshopx": {
      "command": "node",
      "args": [
        "/path/to/ECShopX_Ai-mcp-cli/ecshopx-mcp-server/dist/index.js"
      ],
      "cwd": "/path/to/ECShopX_Ai-mcp-cli",
      "env": {
        "ECX_BASE_URL": "http://ecxphp.test",
        "ECX_MCP_CONFIG_PATH": "/path/to/ECShopX_Ai-mcp-cli/ecshopx-mcp-server/config.json"
      }
    }
  }
}

若需长期 Token，可在 env 中增加 "ECX_ACCESS_TOKEN": "你的JWT"。对接 Java 网关时把 ECX_BASE_URL 改为例如 http://ecxjava.test 即可。

3.2 HTTP 模式（Dify / 远程 MCP 客户端）

cd ECShopX_Ai-mcp-cli
npm run build
npm run mcp:http
# 等价：node ecshopx-mcp-server/dist/transport/http.js

默认监听：http://127.0.0.1:3030

健康检查：GET /health
服务发现：GET /
MCP 调用：POST /mcp

可选开启 Bearer 鉴权：

export ECX_MCP_HTTP_TOKEN="your-secret"
npm run mcp:http

客户端访问 /mcp 时需带 Authorization: Bearer your-secret，/health 不校验。

4. Docker 相关

以下命令均在仓库根目录（ECShopX_Ai-mcp-cli）执行。

# 构建 MCP 镜像
npm run docker:build-mcp

# docker compose 启动/停止 MCP 服务
npm run docker:up-mcp
npm run docker:down-mcp

# 查看状态与日志
npm run docker:ps-mcp
npm run docker:logs-mcp

# 校验 compose 配置
npm run docker:config-mcp
npm run docker:config-mcp:print
npm run docker:validate-all

# 针对前台匿名 / 会员只读的 profile
npm run docker:up-mcp:front-public
npm run docker:up-mcp:front-member-readonly

5. CLI（`shopex`）使用

重要：shopex 由本仓库 workspace 包 ecshopx-cli 提供，未发布到 npm。若只写 npx shopex（不带 workspace），npm 会去 registry 找同名包并 404。请在仓库根目录（已执行 npm ci）使用下面任一方式：

npx -w ecshopx-cli shopex …（推荐）
npm exec -w ecshopx-cli -- shopex …
node ecshopx-cli/dist/index.js …

修改过 ecshopx-cli 源码后，必须重新编译，否则 npx -w ecshopx-cli shopex help 仍是旧的 dist/：

cd ECShopX_Ai-mcp-cli   # 或你的仓库根路径
npm run build -w ecshopx-cli

构建完成后，在仓库根目录执行：

npx -w ecshopx-cli shopex help
# 或
node ecshopx-cli/dist/index.js help

约定：在仓库根目录下，下文 shopex 均指 npx -w ecshopx-cli shopex（与 node ecshopx-cli/dist/index.js 等价）。完整子命令列表以 shopex help 为准。

命令怎么接

C 端 / H5（推荐）：shopex goods list、shopex category list、shopex member login … 详见 help 里 「C-end / H5」。
后台 operator：shopex admin_goods search …、shopex admin_orders messages:new …（工具 key 带 admin_，与 C 端区分）。
只看 C 端 catalog：shopex catalog list front。
按 catalog key 调用（与 MCP 一致）：
- shopex ecshopx_h5_goods_list（默认 --json '{}'）
- 简写：shopex invoke ecshopx_h5_goods_list --json '{"page":1,"pageSize":10}'
- 完整：shopex tool invoke ecshopx_h5_goods_list --json '...'

分页与默认参数

ecshopx_h5_goods_list 未传参时，catalog 的 defaultQuery 会补 company_id=1、item_type=normal；分页默认 page=1、pageSize=3，上限以 catalog 为准。
其它带 page / pageSize 的 H5、会员工具，默认多为 pageSize=10 等；后台多为 page / page_size，见各工具的 defaultPageSize / maxPageSize。

输出长什么样

不加 --verbose（默认）
- 会员登录：{ "ok", "token" } 或 { "ok", "status", "message" }。
- 其它工具：{ "tool", "status", "data", "summary", … }。其中 tool 为 catalog 元数据，但不含 endpoint，且不输出顶层 HTTP request（避免暴露 method/path 等）。tool 内包含 key、title、title_zh、description、description_zh、cli_command（字段名为 snake_case，例如 description_zh，不是 descriptionZH）；这些键会排在 title / description 附近，避免被 params 挤到 JSON 末尾。
--verbose：输出完整 ToolInvokeResult（含 tool.endpoint、request），用于调试。

会员登录

shopex member login 必须带 --username、--password；catalog 会合并 defaultBody（如 auth_type=local、check_type=password）。
等价路径：shopex tool invoke ecshopx_member_auth_login --json '...'（输出规则同上）。

报错

EcshopxUserError（用法、参数校验等）：CLI 只打印 message（无堆栈）；MCP 侧 formatMcpToolError 同样只返回该文案。其它未预期异常仍会带堆栈，便于排查。

若 help 第一行没有 # If this text looks outdated...，说明跑的不是刚编出来的 dist，请检查是否在仓库根目录执行、是否已 npm run build -w ecshopx-cli。

常用命令：

# 版本信息（cli / agent-core / mcp-server / node）
npx -w ecshopx-cli shopex version

# 环境快照（ECX_* 等）
npx -w ecshopx-cli shopex env

# 综合体检（版本 + 环境 + catalog 数量）
npx -w ecshopx-cli shopex doctor

# 检查 HTTP MCP 连通性（需要先 npm run mcp:http 或 docker 启好服务）
npx -w ecshopx-cli shopex mcp ping
npx -w ecshopx-cli shopex mcp ping --soft

6. 作为独立模块迁移 / 上传时需包含的文件

若要单独提交 / 打包本 workspace，建议至少包含：

package.json
package-lock.json
tsconfig.base.json
vitest.config.ts
scripts/ 目录（所有脚本）
ecshopx-agent-core/（含 src/、tests/、package.json 等）
ecshopx-mcp-server/
ecshopx-cli/

一键校验（确认上述布局完整，并检查各包 src/、MCP 的 Dockerfile 与 docker-compose.yml）：

cd ECShopX_Ai-mcp-cli   # 或仓库根目录
npm run pack:verify

一键打包（生成 ../ai-tool-standalone-时间戳.tar.gz，排除各包 node_modules / dist / .git、以及 ecshopx-mcp-server/.env（勿把本机密钥打进包），保留 ecshopx-mcp-server/.env.example 等模板；压缩包内顶层目录名可能为 ai-tool/，以脚本为准；也可传输出路径：npm run pack:archive -- /tmp/out.tgz）：

cd ECShopX_Ai-mcp-cli
npm run pack:archive

在目标环境中解压后进入解压出的根目录，执行：

npm ci
npm run build
npm test
npm run mcp:stdio   # 或 npm run mcp:http

即可获得与当前环境一致的 MCP + CLI 能力。

MCP Servers

ECShopX AI MCP / CLI（ecshopx-agent-workspace）

0. 获取代码与目录说明

1. 安装依赖

2. 构建与测试

3. 启动 MCP Server

3.1 stdio 模式（本地 Cursor / Claude Code 等）

3.2 HTTP 模式（Dify / 远程 MCP 客户端）

4. Docker 相关

5. CLI（`shopex`）使用

命令怎么接

分页与默认参数

输出长什么样

会员登录

报错

6. 作为独立模块迁移 / 上传时需包含的文件

Install Package (if required)

Cursor configuration (mcp.json)

ECShopX AI MCP / CLI（ecshopx-agent-workspace）

0. 获取代码与目录说明

1. 安装依赖

2. 构建与测试

3. 启动 MCP Server

3.1 stdio 模式（本地 Cursor / Claude Code 等）

3.2 HTTP 模式（Dify / 远程 MCP 客户端）

4. Docker 相关

5. CLI（shopex）使用

命令怎么接

分页与默认参数

输出长什么样

会员登录

报错

6. 作为独立模块迁移 / 上传时需包含的文件

Install Package (if required)

Cursor configuration (mcp.json)

5. CLI（`shopex`）使用