Metadata-Version: 2.4
Name: jubaozan-supplier-mcp
Version: 0.8.2
Summary: 聚宝赞供应商只读 MCP Server（商品查询与白名单 GET 接口调用）
Author: Jubaozan
License: Proprietary
Keywords: mcp,supplier,jubaozan
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp==1.26.0
Requires-Dist: cryptography>=41
Requires-Dist: pywin32>=306; sys_platform == "win32"

# 聚宝赞供应商 MCP 0.8.2（生产环境）

WorkBuddy Connector，stdio 传输，通过 `uvx` 从 PyPI 拉起。范围：生产环境、当前供应商身份、白名单只读 GET 接口查询；不提供写操作。

- 认证方式：`auth_mode: "token"`，凭证由用户在连接器设置中填写，WorkBuddy 注入 `JBZ_SUP_TOKEN` 环境变量。
- 可选的本机登录页：`supplier_login` 在 `127.0.0.1` 起一次性页面，用手机号 + 密码 + 滑块验证换取凭证；默认只在生产环境开启（`environments.json` 的 `login.allowed`），`SUPPLIER_MCP_ALLOW_LOGIN=0` 可运行时关闭。
- 业务工具自身不打开浏览器、不弹窗；凭证缺失或过期时只返回 `reauthorization_required`。
- 跨平台：Windows 可选使用凭据管理器做本机缓存，macOS / Linux 直接使用环境变量。

## 运行前置条件

`mcp.json` 的 `command` 是 `uvx`，因此**运行连接器的机器需要已安装 [uv](https://docs.astral.sh/uv/)**（`uvx` 随 uv 一同安装）。MCP 方案的 `runtime` 字段目前只支持托管 Node.js，Python 没有托管运行时，无法由平台代装。

```powershell
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

未安装时点击「连接」会提示进程启动失败（找不到 `uvx`），不是凭证问题。`uvx` 会自行创建隔离环境并安装依赖，不需要预先 `pip install`。

## 目录结构

```
jubaozan-supplier-mcp/
├── connector-meta.json     # 市场展示元信息
├── mcp.json                # uvx 启动配置（提交平台用）
├── token-schema.json       # 凭证表单
├── icon.svg
├── skills/jubaozan-supplier/SKILL.md
├── pyproject.toml          # PyPI 打包
├── src/jubaozan_supplier_mcp/
│   ├── environments.json   # 环境唯一开关（域名与标签的单一来源）
│   ├── config.py           # 读取并校验 environments.json
│   ├── endpoints.json      # 接口白名单（parse_endpoints.py 生成）
│   └── verification.json   # 实测结果（verify_endpoints.py 生成）
├── verify_endpoints.py     # 接口实测执行器
├── switch_env.py           # 环境切换与一致性校验
└── server.py               # 本机开发入口（等价于 console script）
```

## 切换部署环境

域名只在 `src/jubaozan_supplier_mcp/environments.json` 声明一次，代码不再硬编码，**切换环境不需要改任何 `.py`**：

```powershell
# 1. 先把目标环境的域名填进 environments.json（必须是 https 根地址，不带路径与端口）
# 2. 切换并同步文档、校验残留
.\.venv\Scripts\python.exe switch_env.py --use prod
# 只校验
.\.venv\Scripts\python.exe switch_env.py
```

脚本做三件事：把 `active` 切到目标环境；把 `connector-meta.json`、`token-schema.json`、`SKILL.md`、`README.md` 里的域名与中英文标签一并替换；然后校验「源码无硬编码域名、文档无旧环境残留」。

`environments.json` 里 `prod` 的域名故意留空。**留空时切换会被拒绝**，避免半配状态下连到错误后端——填好再切。

`supplier_client.BASES`（客户端只允许打到的根地址白名单）也由 config 派生，这是最容易漏改的一处。

切换后 `verification.json` 里的实测记录会自动失效（记录带 `environment` 字段，与当前环境不符即不计入 `verified`），需重跑 `verify_endpoints.py --apply`。

## 本地开发

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\python.exe -m unittest discover -v
.\.venv\Scripts\python.exe verify_mcp.py
python build_release.py
```

`server.py` 只是把 `src/` 加进 `sys.path` 后调用 `jubaozan_supplier_mcp.server:main`，与发布形态完全同一条入口。`verify_mcp.py` 默认不访问后台、不读取授权；加 `--online` 才执行一次真实商品查询（需要已配置凭证）。

## 工具

- `supplier_login`：打开本机登录页（手机号 + 密码 + 滑块验证换取凭证），立即返回、异步完成；`login.allowed=false` 或 `SUPPLIER_MCP_ALLOW_LOGIN=0` 时不注册。
- `supplier_auth_status`：离线检查凭证格式与有效期，不代表后台授权成功。
- `supplier_goods_list`：商品列表，默认第一页 5 条，最多 100 条。
- `supplier_api_list`：分页列出只读接口白名单（随包 129 个，由 `parse_endpoints.py` 生成、`scripts/narrow_to_readonly.py` 收敛为 GET、`scripts/retire_endpoints.py` 按实测下线）；支持关键字、方法、只看已实测过滤，并返回每个接口的 `verified` 证据。
- `supplier_api_query`：调用白名单中的 GET 接口；params 填充路径占位符与查询参数。

### 为什么没有写工具

随包分发的 `endpoints.json` 只保留 129 个只读 GET 接口：427 条全量清单里 287 个 POST/PUT/DELETE 已被剔除，另有 11 条按生产实测下线（见「接口实测状态」）。连接器定位是只读查询，写接口清单没有必要公开随包发布到 PyPI。相应地 `supplier_api_write` 不会注册，`WRITE_ENABLED` 保持 False。若重新运行 `parse_endpoints.py` 生成了完整清单，必须再执行一次：

```
.\.venv\Scripts\python.exe scripts\narrow_to_readonly.py
.\.venv\Scripts\python.exe scripts\retire_endpoints.py --apply
```

否则写接口会回到公开包里，`test_api_tools.RegistryTest.test_whitelist_ships_read_only_endpoints` 会失败。

### 白名单范围与排除

源文档共 511 个接口，全量清单收录 427 个（排除 84 个），随包只发其中 129 个只读 GET：

1. **凭据与账号流程 29 个**——登录、验证码、短信、密码、注销、OCR 证件识别、外部 URL 代理 `{url}`、七牛上传 Token，模型不得经手凭据；
2. **导出/下载类 42 个**——返回文件流而非 JSON，会把整表业务数据带出本机，从源头排除而不依赖调用层兜底；
3. **后端常量占位符 13 个**——形如 `/micro/supplier/parameters/{PLATFORM}getItems`，`{PLATFORM}` 是 Java 常量而非调用方输入，交给模型填写即可构造同级路径。

另有路径残缺无法安全使用的静态定义一并排除。文件上传（formData）在调用层明确拒绝。

## 接口实测状态

白名单里的接口来自静态接口清单，参数契约不可能全部准确。`verification.json` 记录逐个实测的结果，`supplier_api_list` 据此返回 `verified`：

| status | 含义 | 是否计入 `verified` |
| --- | --- | --- |
| `ok` | HTTP 200 且业务码成功 | 是 |
| `reachable` | 路由存在、服务端已处理，但缺少必填参数 | 否 |
| `failed` | HTTP 非 2xx、非 JSON 或网络失败 | 否 |

生成方式（需要本机已配置凭证）：

```
.\.venv\Scripts\python.exe verify_endpoints.py --limit 40        # 只报告
.\.venv\Scripts\python.exe verify_endpoints.py --apply           # 写入 verification.json
.\.venv\Scripts\python.exe verify_endpoints.py --only A124,O003  # 指定编号
.\.venv\Scripts\python.exe verify_endpoints.py --only A124 --params '{"data.id":133527}' --apply
```

执行器只发 GET，默认跳过带路径参数的接口（无法凭空构造 ID）、文件上传，以及路径含 `delete`/`update`/`audit` 等写语义动词的接口。带路径参数或必填字段的接口用 `--params` 指定固定取值后单独验证。实测记录与 `endpoints.json` 分开存放，重新生成白名单不会丢失。

当前实测（生产 `https://bk.jbzyun.com`，2026-11-18）：129 个只读 GET 中 101 个有实测记录——50 个业务成功、51 个仅连通待补参、0 个失败。共 53 个接口标记为 `verified`。剩下 28 个未自动验证：25 个路径含 `update`/`audit`/`withdraw`/`send` 等写语义动词被跳过，3 个仍缺路径参数（A016/A111/A245）。

生产实测中暴露的 11 条不可用接口已下线，名单固化在 `scripts/retired_endpoints.json`，重新生成白名单也不会回来：9 条在生产返回 404（A035/A036/A038/A045/A047/A182/A217/A331/A415，路径只在 `test` 网关存在）、`A268 /micro/order/`（路径缺订单号占位，订单详情实际走 `A211`）、`A323 subscription-records`（接口侧返回业务码 101）。

## 凭证与授权

读取顺序：环境变量 `JBZ_SUP_TOKEN`（表单注入，优先）→ 本机凭据缓存（仅 Windows）→ 既有外部凭据文件 `~/.workbuddy/credentials/jubaozan-supplier-test.json`（只读，不重写）。

调用后台时由内置客户端构建 SUP 请求头。JWT 内容解析只用于本地身份绑定和有效期检查，不验证签名，不授予权限；签名、会话与业务权限最终由后台校验。服务进程绑定供应商及账号，凭证切换账号会被拒绝，需重启连接器。凭据不出现在工具参数、返回值、日志或配置文件里。

表单接受纯 JWT、整段 Cookie 串、`Bearer <jwt>` 与 JSON 形态，由 `normalize_credential` 归一化，用户不必手工截取子串。

凭证有效期以后台签发为准（`supplier_auth_status` 会给出实际剩余时间，实测可达数十天）。`expires_at` 与 `remaining_minutes` 之外，剩余不足 10 分钟时附 `expiry_warning`。过期后：

1. `supplier_auth_status` 与业务工具都返回 `{"ok": false, "reauthorization_required": true}`，文案写明已过期多久或还剩多久；
2. 不重试、不自动改写本机缓存；
3. 用户可调用 `supplier_login` 用手机号密码重登，或在连接器设置里重新填写凭证。

后台未提供 refresh-token 接口，因此这里是用户参与的重新获取，不是静默续期。

## 本机登录页

`supplier_login` 是 0.8.0 新增的可选通道，0.8.1 把页面宿主改成独立进程（回合结束不再中断），实现依据是抓取门户前端 `app.378ff721.js` 与真实接口实测：

| 环节 | 接口 | 说明 |
| --- | --- | --- |
| 取加密密钥 | `POST /micro/auth-center/security/auth/key` | `body` 为 base64 的 AES 密钥（16 字节） |
| 密码加密 | 本地完成 | AES-128-ECB + PKCS7 + base64 |
| 取验证码 | `POST /micro/auth-center/captcha/get` | 返回 `token`、`secretKey`、背景图与拼图块 |
| 校验滑块 | `POST /micro/auth-center/captcha/check` | `pointJson = AES('{"x":位移,"y":5}', secretKey)`，`repCode=0000` 才通过 |
| 登录 | `POST /micro/supplier/v1/login` | `mobile` + 加密后的 `password` + `captchaVerification` |

两点与开源 AJ-Captcha 不同，照抄会失败：**坐标必须是对象 `{"x":..,"y":5}`（数组会返回 `code 101`）**；验证码 `secretKey` 是 16 字符原文，按 UTF-8 取字节，而登录密钥接口返回的是 base64。

安全边界：只绑 `127.0.0.1` 随机端口；一次性 nonce + Origin 校验；`secretKey` 不下发页面，坐标由页面回传、服务端加密；密码只在一次请求内存中存在；登录失败只返回固定文案；成功时只把 token 写入本机凭据存储，token 不回传对话。滑块必须由本人拖动，不实现自动识别。

## 复用与边界

内置客户端 `src/jubaozan_supplier_mcp/supplier_client.py` 从原只读客户端独立收录，保留原调用契约与保护逻辑，不依赖目录外的 Skill。不提供任意 URL、请求头、身份或方法参数。

固定请求走 `https://bk.jbzyun.com`；客户端负责 TLS 校验、禁止重定向、业务成功判断、敏感字段过滤与请求超时，MCP 层再做分页参数限制和返回字段白名单。

本连接器只面向单一环境（由 `src/jubaozan_supplier_mcp/environments.json` 的 `active` 决定，当前为生产环境），不是多人共享服务：一个进程绑定一个供应商身份。
