# Amazon 日本站 ABA MCP

基于亚马逊官方 `amzn/selling-partner-api-samples` 中的 SP-API Developer Assistant 源码，提供供 Codex 使用的 Streamable HTTP 接口。官方源码、来源提交和修改说明分别位于 `vendor/amazon/`、`UPSTREAM.json` 与下文。

当前部署地址为 `https://spapi-mcp.bamboost.info/mcp`。

**支持的用途**

只处理日本站 `A1VC38T7YXB528` 的两种报表。

- `GET_BRAND_ANALYTICS_SEARCH_TERMS_REPORT`
- `GET_BRAND_ANALYTICS_SEARCH_QUERY_PERFORMANCE_REPORT`

服务提供 `aba_status`、`aba_create_report`、`aba_get_report`、`aba_download_report`、`aba_read_artifact` 五个工具。创建报表后按状态轮询，完成后下载。下载结果以 artifact ID 返回，读取内容采用 base64 字节块，拼接解码后的字节再解析 UTF-8 或 JSON。

SP-API 应用需要 Brand Analytics 角色及对应卖家账号授权。搜索词报表还要求账号具有对应的品牌代表资格。SQP 查询需要填写账号有权查看的自家 ASIN。

**在已部署服务器上配置亚马逊凭证**

```sh
ssh -t root@8.216.38.233 spapi-mcp-configure
```

依次输入 `client_id`、`client_secret` 和 `refresh_token`。三个输入均隐藏。配置工具先向 Amazon LWA 验证，成功后写入 `/etc/spapi-mcp/amazon.env` 并重启服务。该文件权限为 `0600`。

轮换 client secret 后重新执行此命令，输入当前 client ID、新 secret 和现有 refresh token。凭证验证失败时保留此前的配置。

服务器自己的 MCP Bearer Token 与报表加密密钥位于 `/etc/spapi-mcp/server.env`。它们和亚马逊的三个凭证分别管理。备份报表时同时安全备份加密密钥。

**本地开发**

需要 Node.js 22 或以上版本。

```sh
npm ci --ignore-scripts
npm test
npm audit --omit=dev
```

启动时通过环境提供 `.env.example` 中列出的变量。程序不会自动读取 `.env`。未配置亚马逊凭证时，服务仍支持健康检查和工具发现，`aba_status` 返回 `credentialsConfigured=false`。

**安全与资源边界**

- HTTP 认证先于请求体解析，Bearer Token 至少 32 字符。
- 固定日本站、报表类型与 API 操作，访问 Amazon LWA 和 FE SP-API。报表下载仅接受 Amazon 或 CloudFront 的 HTTPS 地址，拒绝跳转。
- 官方请求执行逻辑保留在 vendor 目录，HTTP 层只向客户端返回所需数据，屏蔽签名 URL、请求头和凭证。
- 报表按 1 MiB 块使用 AES-256-GCM 加密，块位置和 artifact ID 绑定到认证附加数据。文件权限为 `0600`，目录为 `0700`。
- 压缩下载上限 256 MiB，解压上限 512 MiB，报表存储上限 1 GiB。一次只执行一个报表写入。创建报表和读取状态的 Amazon 请求并发上限为 2。
- 每日任务清理超过 7 天的报表和超过 24 小时的未完成文件。
- systemd 将服务限制为独立账号、768 MiB 内存和一个 CPU 核配额，监听 `127.0.0.1:9108`。
- Nginx 提供 HTTPS、32 KiB 请求体限制、入口速率限制和连接限制。

MCP 客户端接收获授权的报表内容，模型服务也会按客户端的数据处理条款处理这些内容。此部署的安全测试覆盖本仓库代码、模拟 API 流程和部署入口，真实账号权限与 ABA 取数需要配置凭证后验证。

**官方源码的修改**

固定上游提交为 `8510af955ac022a4bd814ee3ddff2c0d30f7a027`。保留官方认证器、请求执行器和 Swagger 目录加载代码，只随附 Reports API 模型。

- 认证器增加超时、禁止重定向并固定 LWA 地址。
- 执行器增加结构化响应方法、请求体和响应体限制、超时，以及发送请求头的 token 脱敏。
- 日志实现关闭正文和调试输出，错误对象不进入日志。
- 升级并锁定 HTTP、MCP、Axios 与模式校验依赖。
- 自建 HTTP 入口、ABA 参数校验、下载和加密存储。该改造由本仓库维护，亚马逊未对其作认证。

**运维命令**

```sh
systemctl status spapi-mcp
systemctl restart spapi-mcp
journalctl -u spapi-mcp --since today
systemctl list-timers spapi-mcp-cleanup.timer
curl https://spapi-mcp.bamboost.info/health
```

服务文件和 Nginx 配置在 `deploy/`。升级使用新的发布目录 `/opt/spapi-mcp/releases/`，测试通过后切换 `/opt/spapi-mcp/current` 链接并重启服务。