# 橙岛跨境电商数据 MCP

读取卖家明确授权并导入的 JSON 报表，使用确定性公式完成订单、商品、库存、利润、广告、达人和客服分析。

## 当前能力

- 版本：0.1.0
- 传输：本地 stdio
- 存储：SQLite
- 工具：12 个
- 外部平台写操作：无
- 实时 API：未连接

## 工具

| 工具 | 作用 |
|---|---|
| `report_import` | 导入卖家授权的标准化 JSON 报表 |
| `report_list` | 查看已经导入的报表 |
| `product_metrics_get` | 按 SKU 汇总曝光、点击、订单、收入等指标 |
| `order_summary_get` | 汇总订单、销量、退款、客单价和国家 |
| `inventory_risk_detect` | 计算库存覆盖天数和补货风险 |
| `profit_calculate` | 计算贡献利润并指出缺少的成本字段 |
| `listing_audit` | 检查标题、图片、描述、价格和状态 |
| `ad_anomaly_detect` | 检测烧钱无收入、高 ACOS、低 CTR |
| `creator_performance_get` | 计算达人 ROAS 和单均成本 |
| `customer_service_issue_summary` | 汇总客服类别、响应、解决时间和 CSAT |
| `daily_operation_brief` | 使用各类最新报表生成每日经营简报 |
| `evidence_export` | 导出可交给经营底座 MCP 保存的证据结构 |

字段规范可通过 MCP Resource `oi-commerce://schema` 获取。

## 使用顺序

1. 调用 `report_import` 导入一种标准化报表。
2. 保存返回的 `report_id`。
3. 将正确类型的报表交给对应分析工具。
4. 检查返回结果中的 warning、null 和边界说明。
5. 调用 `evidence_export`。
6. 把返回结果交给 `orange_island_core.evidence_add` 长期留档。
7. 改价、上架、投放、退款和采购仍需人工确认，并由获得平台授权的执行系统完成。

## 支持的报表

- `orders`
- `products`
- `inventory`
- `ads`
- `creators`
- `service`

详细字段见 [报表字段文档](docs/REPORT-SCHEMA.md)。

## 运行与测试

```bash
npm ci
npm run check
node dist/index.js
```

默认数据库：`data/commerce.sqlite`。

## 安装到 Codex

```bash
codex mcp add orange_island_commerce_data -- \
  /usr/local/bin/node \
  /Users/borytan/Documents/Codex/proj_018_mcp_橙岛跨境电商数据/dist/index.js
```

安装后新开 Codex 任务。

## 边界

这个版本处理用户导入的数据，不等于已经连接 TikTok Shop、Amazon、Shopify、Shopee、Ozon 或其他平台。分析结果不能自动修改店铺、广告或订单。缺少字段时保留缺口，不补造成本和收入。