# sellerarith-mcp

> 把 **SELLERARITH 卖家智算** 的核心决策引擎，开放为标准的 [MCP](https://modelcontextprotocol.io) 工具，供 WorkBuddy、Claude Desktop 等任意 MCP 客户端一键安装、直接调用。

SELLERARITH 是一套面向跨境电商卖家的数字决策工具套件，内置装箱规划、货代运费比价、备货测算、1688 订单解析、FBA 仓库码映射等算法。本服务把这些**纯计算函数**封装成 9 个 MCP 工具，无需启动 sellerarith 服务、无需数据库，离线可用。

---

## 一、9 个工具

| 工具名 | 作用 |
| --- | --- |
| `sellerarith_pack_plan` | **【专业版·含AI Agent - MCP·需密钥】** 多箱装箱规划：自动求解箱数、每箱装载、自由多箱 vs 同款箱运费对比 |
| `sellerarith_pack_single` | 单箱操作：算箱（反推最小合规箱型）/ 算量（满载件数）/ 交互装载 + 运费估算 |
| `sellerarith_pack_amazon` | **【专业版·含AI Agent - MCP·需密钥】** 亚马逊美西/美东分仓装箱测算 |
| `sellerarith_freight_optimize` | 货代运费比价优化：跨货代求全局最低总价，并给出线路数（方便度）权衡 |
| `sellerarith_ship_calc` | 备货测算：按周期销量/库存/安全库存算补货缺口与建议清单 |
| `sellerarith_ship_csv_import` | 备货明细 CSV → 结构化行 |
| `sellerarith_ship_csv_export` | 备货测算结果 → CSV |
| `sellerarith_parse_1688` | 1688 订单纯文本 → 结构化订单（确定性解析，无需大模型） |
| `sellerarith_fba_country` | FBA 仓库代码 → 国家 / 从文本提取目的国家 |

> **免费版 vs 专业版（v1 边界）**：单箱 `pack_single` 与全部纯计算辅助工具无需任何配置、离线免费可用，作为获客钩子；`pack_plan`（多箱规划）与 `pack_amazon`（亚马逊分仓）为**专业版**，需接入 SellerArith 服务器并按调用计费——无 `SELLERARITH_API_KEY` 时调用会返回升级提示，不暴露计算逻辑。离线 MCP 跑在用户本机、无后端可计量，因此凡要收费的能力都须走服务端（auth + 积分 + 支付宝）。

### 解锁专业版（付费接入）

在 `mcp.json` 的服务器配置中加入环境变量即可解锁专业版工具：

```json
{
  "mcpServers": {
    "sellerarith": {
      "command": "npx",
      "args": ["-y", "sellerarith-mcp"],
      "env": {
        "SELLERARITH_API_KEY": "在门户生成的 MCP 密钥",
        "SELLERARITH_API_URL": "https://你的 sellerarith 部署地址"
      }
    }
  }
}
```

- 未配置 `SELLERARITH_API_KEY`：专业版工具返回升级提示，免费工具照常可用。
- 已配置：专业版工具带 `Authorization: Bearer <key>` 调用服务器 `POST /api/mcp/charge` 完成**按调用计费**（密钥在服务端 `api_keys` 表签发、sha256 存储；计量复用 `credits` 积分池，与 AI 智算同一池，约 5 积分/次 ≈ 0.05 元/次）。计费失败（密钥失效 / 非专业版 / 余额不足）则拦截并返回提示。详见 `MCP-PAID-TIER-DESIGN.md` §4.1 / §5。

---

## 二、在 WorkBuddy 中安装（推荐：npx 一行接入）

编辑 WorkBuddy 的 MCP 配置 `~/.workbuddy/mcp.json`，在 `mcpServers` 下加入：

```json
{
  "mcpServers": {
    "sellerarith": {
      "command": "npx",
      "args": ["-y", "sellerarith-mcp"]
    }
  }
}
```

保存后，在 WorkBuddy 的「连接器管理」里对该服务器点 **信任（Trust）**，即可在对话中直接调用上面 9 个工具。

> 提示：本机若尚未安装 Node 18+，请先安装 Node。

---

## 三、本地路径接入（不出公网，适合自己调试）

如果你直接克隆了 `sellerarith` 仓库，可以让 MCP 指向本地代码，并实时跟随算法更新：

```json
{
  "mcp.json 同上路径": {
    "mcpServers": {
      "sellerarith": {
        "command": "node",
        "args": ["/你的路径/sellerarith/mcp/index.mjs"],
        "env": {
          "SELLERARITH_LIB": "/你的路径/sellerarith/lib"
        }
      }
    }
  }
}
```

设置 `SELLERARITH_LIB` 后，服务会直接加载 sellerarith 仓库里的 `lib/` 算法源码（而不是包内 vendored 副本），算法更新后无需重新发版。

---

## 四、本地开发 / 自测

```bash
cd mcp
npm install
npm test          # 端到端冒烟测试：启动 stdio 服务器并调用全部 9 个工具
node index.mjs    # 以 stdio 模式常驻（MCP 客户端连接用）
```

---

## 五、发布到 npm（让任何人都能 `npx sellerarith-mcp`）

本包已 `npm pack` 验证可发布。发布只需两步（需你自己的 npm 账号）：

```bash
npm login          # 登录你的 npm 账号
npm publish        # 发布（包名 sellerarith-mcp 当前可用）
```

发布后，任何人都能在 WorkBuddy / Claude Desktop 的 mcp 配置里写 `npx -y sellerarith-mcp` 完成安装。

---

## 六、说明

- 本服务仅封装 sellerarith 的**无状态计算函数**，不接触数据库、支付、鉴权等线上业务，可安全对外分发。
- 包内 `lib/` 为算法模块的 vendored 副本；若希望跟随主仓库更新，请用 `SELLERARITH_LIB` 指向主仓库 `lib/`。
- 环境变量：
  - `SELLERARITH_LIB`（可选，覆盖算法目录）
  - `SELLERARITH_API_KEY`（可选，专业版密钥；在门户「后台 → MCP 接入密钥」生成）
  - `SELLERARITH_API_URL`（可选，默认占位；专业版需指向你的 sellerarith 部署地址，用于按调用计费）