# ECShopX_Ai-mcp-cli

**Repository Path**: ShopeX/ECShopX_Ai-mcp-cli

## Basic Information

- **Project Name**: ECShopX_Ai-mcp-cli
- **Description**: ECShopX Ai工具集
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-03
- **Last Updated**: 2026-04-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## 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` |

```bash
cd ECShopX_Ai-mcp-cli
```

---

### 1. 安装依赖

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

要求 Node.js **>= 20**。

---

### 2. 构建与测试

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

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

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

---

### 3. 启动 MCP Server

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

```bash
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` 形式）：

```json
{
  "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 客户端）

```bash
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 鉴权：

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

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

---

### 4. Docker 相关

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

```bash
# 构建 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/`：

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

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

```bash
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`。

常用命令：

```bash
# 版本信息（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`）：

```bash
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`）：

```bash
cd ECShopX_Ai-mcp-cli
npm run pack:archive
```

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

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

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