Metadata-Version: 2.5
Name: noon-workbuddy-api
Version: 1.0.1
Summary: Read-only noon seller operations MCP server for WorkBuddy
Author: noon 沙特站卖家工具集
License: MIT
Keywords: ecommerce,mcp,noon,operations,saudi,seller,workbuddy
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business
Requires-Python: >=3.11
Requires-Dist: cryptography<47,>=44
Requires-Dist: mcp<2,>=1.12
Requires-Dist: openpyxl<4,>=3.1
Description-Content-Type: text/markdown

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

因此需要满足：

| 前置条件 | 说明 |
|---|---|
| WorkBuddy 客户端 | **4.24.0 及以上**（本连接器使用了 `auth_mode: token`、`token-schema.json`、中英文字段，均需要该版本） |
| `uvx` 可执行 | 由 `uv` 提供。未安装时：macOS / Linux 执行 `curl -LsSf https://astral.sh/uv/install.sh \| sh`；Windows 用官方安装包。装完 `uvx --version` 应能正常输出。 |
| 可访问 PyPI | 首次启动会从 PyPI 解析并缓存依赖 `cryptography`、`mcp`、`openpyxl`。内网环境请配置镜像源。 |
| 网络可访问 noon | 需要能连通 `https://noon-api-gateway.noon.partners`（HTTPS，443）。 |

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

## 本机安装

```bash
./scripts/install-local.sh
```

安装后运行：

```bash
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`。订单数按订单号去重，件数按非取消且非退回的商品行统计。库存使用报表最新快照；缺失不能视为零。补货建议使用日历日均销量，并明确输出缺项和滞后信息。
