noon 运营 API for WorkBuddy

这是从 noon 工作区剥离出的独立只读 MCP 连接器。它只包含 noon 服务账号认证、报表读取、本地缓存和运营查询，不包含选品、1688、浏览器自动化、图片、Listing 发布、广告写入或 ASN 预订。

工具

• noon_connection_status
• noon_get_orders
• noon_get_order_details
• noon_get_inventory
• noon_get_product_card
• noon_get_replenishment
• noon_get_operational_alerts
• noon_get_todo
• noon_get_sales_traffic
• noon_export_report（高级白名单报表入口，最多返回100行）

全部业务能力为只读。报表导出接口只负责生成并下载 noon 报表，不修改订单、库存、价格或商品。

运行时前置条件

连接器以 stdio MCP 方式启动，mcp.json 里的启动命令是：

uvx --from noon-workbuddy-api noon-workbuddy-mcp

因此需要满足：

不需要浏览器、不需要管理员权限、不需要预装 Python（uv 会自行准备并隔离运行时）。 启动后第一次调用会初始化本地缓存目录，之后常规查询走 sqlite 缓存。

本机安装

./scripts/install-local.sh

安装后运行：

NOON_CREDENTIALS=/absolute/path/noon_credentials_sensitive.json \
NOON_DATA_DIR=/absolute/path/noon-data \
NOON_CONFIG=/absolute/path/config.json \
./.venv/bin/noon-workbuddy-check

WorkBuddy 使用根目录的 mcp.json。本机部署也可以直接把 .venv/bin/noon-workbuddy-mcp 作为 stdio MCP 命令添加到 WorkBuddy。

凭证

两种提供方式，任选其一：

1. 粘贴凭证内容（推荐，云端和本机都能用）：设置 NOON_CREDENTIALS_JSON 为凭证 JSON 的完整内容。 连接器会在启动时把它写入 <NOON_DATA_DIR>/credentials/noon_credentials.json，权限 0600，随后只使用这份副本。
2. 指向已有文件（仅本机模式）：设置 NOON_CREDENTIALS 为凭证文件的绝对路径，权限必须是 0600 （Windows 下必须是仅当前用户、SYSTEM 与管理员可读的 ACL）。

凭证 JSON 必须包含 key_id、private_key 和 project_code 三个字段。真实凭证、会话 Cookie、JWT、 报表下载链接和订单缓存不会进入发布 ZIP，也不会写入日志。

环境变量：

• NOON_CREDENTIALS_JSON：服务账号凭证 JSON 内容，与 NOON_CREDENTIALS 二选一。
• NOON_CREDENTIALS：已有凭证文件的绝对路径，仅本机部署可用。
• NOON_DATA_DIR：独立缓存目录，建议权限 0700，默认 ~/.workbuddy/noon-data。
• NOON_CONFIG：可选商品别名和补货参数配置。
• NOON_WAIT_SECONDS：单次报表等待秒数，默认 50，范围 0—60。

日期和数据口径

沙特站日期统一按 Asia/Riyadh。订单数按订单号去重，件数按非取消且非退回的商品行统计。库存使用报表最新快照；缺失不能视为零。补货建议使用日历日均销量，并明确输出缺项和滞后信息。