@sea-ecommerce/admin-mcp-server 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,130 @@
-# Temporary Holding Version
+# @sea-ecommerce/admin-mcp-server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+让运营同学用**本地自带的 AI agent**（Codex / Workbuddy / Claude Desktop / Cursor / CodeBuddy 等）运营 Medusa 后台的 MCP server。
+
+它把后台运营动作封装成语义化 `tool`，由任意支持 MCP 的 agent 调用；认证复用现有后台管理员账号（会话 cookie / JWT），权限受现有 RBAC（`csr` / `super_admin`）约束。
+
+> 设计文档见 `docs/控制台通用/AI-Agent运营后台-MCP技术方案.md`。
+
+## 能力范围（P0）
+
+| 工具 | 说明 | 写操作 |
+|---|---|---|
+| `list_products` / `get_product` | 查商品 | 读 |
+| `create_product` / `update_product` / `deactivate_product` | 增 / 改 / 下线商品 | 写（dry_run 默认） |
+| `list_stock_locations` / `create_stock_location` | 列 / 增仓库 | 写（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/` 回答后台使用问题 | 读 |
+
+所有**写工具默认 `confirm=false` 仅返回预览**，设 `confirm=true` 才真正调用后端。
+
+## 分发与安装
+
+两种分发方式。**运营人员走「方式 B」即可，无需仓库、无需 pnpm、无需构建**；开发者 / 贡献者走「方式 A」。
+
+### 方式 A：仓库内运行（开发者 / 贡献者）
+
+```bash
+pnpm install
+pnpm --filter @sea-ecommerce/admin-mcp-server build   # 产出 dist/derlux-admin-mcp.js（自包含单文件）
+pnpm --filter @sea-ecommerce/admin-mcp-server start
+```
+
+也可直接用 bin：`node packages/admin-mcp-server/dist/derlux-admin-mcp.js`。
+
+### 方式 B：独立安装（运营人员，推荐）
+
+MCP server 已打成**自包含单文件**（SDK/zod 全部内联）。你（或从仓库发布一次）把它发布到内部 npm registry，或推到一个**独立精简仓库**（只需 `package.json` + `dist/`），运营人员就能用 `npx` 直接拉取运行，机器上**只需 Node ≥ 18**：
+
+- **npm（org `sea-ecommerce`，推荐）**：先登录 npmjs.org（注意：若本机 npm 默认源是镜像如 npmmirror，需单独对 npmjs.org 登录）：
+  ```bash
+  npm config set //registry.npmjs.org/:_authToken <你的npmjs-token>
+  pnpm --filter @sea-ecommerce/admin-mcp-server publish:npm
+  # 等价于：node scripts/bundle.mjs && npm publish --access public --registry https://registry.npmjs.org
+  ```
+  包名 `@sea-ecommerce/admin-mcp-server`，发布前会先打包 `dist/`（自包含单文件）再发布。`--access public` 使其可被任意人 `npx` 拉取。发布后运营人员即可 `npx -y @sea-ecommerce/admin-mcp-server`。
+- 或推到精简 git 仓库后用 `npx github:<org>/<repo>`（需把 `dist/` 一并提交，或加 `prepare` 构建步骤；无需发版）。
+
+发布 / 推送一次后，所有运营人员**完全不用 clone 本仓库、不用 pnpm、不用 build**，只需在各自 agent 的 MCP 配置里加一条（见下）。
+
+## 配置（环境变量）
+
+| 变量 | 必填 | 默认 | 说明 |
+|---|---|---|---|
+| `MEDUSA_BACKEND_URL` | 否 | `http://localhost:9000` | 后端地址（生产填内部域名，如 `https://admin.internal.derlux.com`） |
+| `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` | 商品必须覆盖的语言 |
+
+## 运行
+
+```bash
+# 方式 A
+pnpm --filter @sea-ecommerce/admin-mcp-server start
+# 方式 B（运营人员本地，发布后）
+npx -y @sea-ecommerce/admin-mcp-server            # 内部 npm
+# 或
+npx -y github:<org>/<repo>                        # 精简 git 仓库
+```
+
+## 接入 agent（各客户端配置）
+
+所有客户端都是「一条 MCP server 配置 = `command` + `args` + `env`」。运营人员统一用 **npx 形态**（无需仓库）；开发者可用 pnpm 形态。
+
+**通用配置（运营人员用 npx，推荐）**
+
+```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": "你的密码"
+      }
+    }
+  }
+}
+```
+
+把上面这段按各客户端的配置文件位置贴进去即可：
+
+| 客户端 | 配置文件位置 | 说明 |
+|---|---|---|
+| **Codex** | 项目或全局 `codex.json` 的 `mcpServers` | 直接贴上面这段 |
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） | 同上 |
+| **Claude Code (CLI)** | 仓库根 `.mcp.json`，或命令 `claude mcp add derlux-admin -e MEDUSA_BACKEND_URL=... -e DERLUX_ADMIN_EMAIL=... -e DERLUX_ADMIN_PASSWORD=... -- npx -y @sea-ecommerce/admin-mcp-server` | |
+| **Cursor** | `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局） | 同 JSON 结构 |
+| **Workbuddy** | 其 MCP 配置（JSON 同结构） | 同 JSON 结构 |
+| **CodeBuddy** | `.codebuddy/mcp.json` 或 IDE 设置里的 MCP Servers | 同 JSON 结构 |
+
+> 开发者若想在仓库内跑（方式 A），把 `command` / `args` 换成：
+> `"command": "pnpm", "args": ["--filter", "@sea-ecommerce/admin-mcp-server", "start"]`。
+
+接入后例如：「下架 handle 为 `xxx` 的商品」「给马来西亚仓的 A 商品加 50 件库存」「后台怎么新建优惠券」—— 分别调用 `deactivate_product` / `update_inventory_level` / `ask_usage`。
+
+## 运营防护（已实现）
+
+- **Handle 校验（§16.1）**：`create_product` / `update_product` 自动把 Handle 归一化为 `小写+数字+连字符`，非法则报错，不再触发后端 `Invalid product handle` 报错。
+- **多语言强提示（§16.2）**：`create_product` 默认要求 `translations` 覆盖 `en/zh/ms/id`；缺失时 preview 告警，`confirm=true` 仍需 `acknowledge_missing_languages=true` 才放行。
+- **写操作确认**：所有写工具 `confirm=false` 仅预览。
+- **审计**：每次调用写入 `~/.derlux/mcp-audit.log`。
+- **最小权限**：用受限的 `csr` 账号即可，敏感动作由后端 RBAC 拦截。
+
+## 注意事项 / 待核对
+
+- 本包**不改动任何数据库 schema**，仅复用现有 `/admin/*` 接口；运营动作本身会按既有逻辑写库。
+- 登录走**用户账号**而非 API Key（现有 RBAC 依赖 `user.metadata.rbac_roles`）。
+- **金额单位（重要）**：Medusa v2.21 官方即把 `amount` 以**主货币单位（元）**存储（并非最小单位/分）。官方 ESLint 规则 `prices-in-major-units` 明确说明 *"Medusa stores prices in major units"*，期望 `19.99` 而非 `1999`。本项目 seed 与 storefront 均遵循该官方约定，因此 `create_product` 的价格直接透传（如 `200.51` = RM200.51），**不要 ×100**。
+- 以下端点/字段以 Medusa 2.21 官方契约为准，实施联调时核对：
+  - 登录端点路径（默认 `/auth/user/emailpass`）。
+  - `create_product` 的变体/价格结构（当前为单一默认变体示意，金额为主单位）。
+  - 库存水平写入端点 `POST /admin/inventory-items/{id}/location-levels` 与 `stocked_quantity` 字段。