Skip to main content

聚宝赞供应商 MCP 0.8.1(生产环境)

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(uvx 随 uv 一同安装)。MCP 方案的 runtime 字段目前只支持托管 Node.js,Python 没有托管运行时,无法由平台代装。

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

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

本地开发

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 决定,当前为生产环境),不是多人共享服务:一个进程绑定一个供应商身份。

Metadata

Release files for jubaozan-supplier-mcp 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jubaozan-supplier-mcp 0.8.1
File Size Uploaded Provenance Actions
jubaozan_supplier_mcp-0.8.1.tar.gz 58.0 kB Without provenance Details for jubaozan_supplier_mcp-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jubaozan-supplier-mcp 0.8.1
File Interpreter ABI Platform Actions
jubaozan_supplier_mcp-0.8.1-py3-none-any.whl Python 3 none any Details for jubaozan_supplier_mcp-0.8.1-py3-none-any.whl

Total release size: 116.2 kB

Release files / jubaozan_supplier_mcp-0.8.1.tar.gz

Download URL jubaozan_supplier_mcp-0.8.1.tar.gz
Size 58.0 kB
Tags Source
SHA-256 checksum
How to use checksums
713f8a756e074f4facddc843c5af13b493e14767b40e9591cf0f428123f60a38
BLAKE2b-256 checksum
How to use checksums
a097a4623ea7a53e8f7763273385413c716211a9ffc0a1403efffe497ada959a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / jubaozan_supplier_mcp-0.8.1-py3-none-any.whl

Download URL jubaozan_supplier_mcp-0.8.1-py3-none-any.whl
Size 58.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e4e2e6eec598181350f857a8dbf431116554978f45729c2598cd225a7357a60b
BLAKE2b-256 checksum
How to use checksums
9867f6fc7fede88b6ea5b8c2e9adfd063ebf48cd5632edcd0f67f8421c30b578
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for jubaozan-supplier-mcp 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page