Metadata-Version: 2.4
Name: sellersprite-mcp
Version: 0.2.0
Summary: 卖家精灵 Python SDK — 通过 MCP Server 调用全部 36 个数据工具
License-Expression: MIT
Project-URL: Homepage, https://www.sellersprite.com
Project-URL: Documentation, https://mcp.sellersprite.com
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Dynamic: license-file

# SellerSprite Python SDK

卖家精灵 Python SDK — 通过 MCP Server 调用全部 36 个 Amazon 数据工具。

[English](README.en.md)

## 安装

```bash
pip install sellersprite-mcp
```

## 配置密钥

推荐使用环境变量：

```bash
# Linux / macOS
export SELLERSPRITE_KEY="你的API密钥"

# Windows CMD
set SELLERSPRITE_KEY=你的API密钥

# Windows PowerShell
$env:SELLERSPRITE_KEY = "你的API密钥"
```

或在项目根目录创建 `.env` 文件：

```
SELLERSPRITE_KEY=你的API密钥
```

API 密钥在 [卖家精灵开放平台](https://open.sellersprite.com) 获取。

## Python SDK

```python
from sellersprite_mcp import SellerSprite

ss = SellerSprite()  # 自动读取 SELLERSPRITE_KEY 环境变量

# 搜索类目
nodes = ss.product_node(keyword="wireless earbuds")
print(f"找到 {len(nodes)} 个类目")

# ASIN 详情
detail = ss.asin_detail(asin="B0D6LQ5VZM")
print(detail["title"], detail["price"])

# 商品筛选
result = ss.product_research(keyword="earbuds", priceMin=10, priceMax=30)
for item in result["items"]:
    print(item["asin"], item["price"], item["amzUnit"])
```

### 错误处理

SDK 提供两种异常类型：

```python
from sellersprite_mcp import SellerSprite, McpError, ApiError

ss = SellerSprite()

try:
    result = ss.asin_detail(asin="INVALID")
except McpError as e:
    print(f"MCP 传输错误: {e.code} - {e.message}")
except ApiError as e:
    print(f"API 业务错误: {e.code} - {e.message}")
```

- `McpError` — 传输/协议层错误（网络、认证等）
- `ApiError` — API 业务逻辑错误（参数无效、余额不足等）

### 切换站点

```python
ss = SellerSprite(marketplace="JP")           # 默认日本站
ss.asin_detail(asin="B0D6LQ5VZM")             # 使用 JP
ss.asin_detail(asin="B0D6LQ5VZM", marketplace="US")  # 临时切换 US
```

支持站点：`US`、`JP`、`UK`、`DE`、`FR`、`IT`、`ES`、`CA`、`IN`

## CLI

安装后提供 `ssmcp` 命令行工具：

```bash
# 查看所有工具
ssmcp list

# 直接调用工具
ssmcp asin_detail --asin B0D6LQ5VZM
ssmcp product_research --keyword "wireless earbuds" --min-price 10 --max-price 30
ssmcp keyword_miner --keyword earbuds --size 20
ssmcp market_brand_concentration --node-id-path "172282:24046923011"
ssmcp traffic_extend --asin-list B0XXX1,B0XXX2
ssmcp bsr_prediction --bsr 10000 --category-id 172282

# 生成 AI 客户端 MCP 配置
ssmcp init claude-code                    # 仅 MCP 配置
ssmcp init claude-code --skills           # MCP 配置 + Skills 文件
ssmcp init cursor --skills                # Cursor
ssmcp init --all --skills                 # 全部客户端
ssmcp init --dry-run                      # 预览模式
```

### 全局参数

| 参数 | 说明 |
|------|------|
| `--key <密钥>` | API 密钥（默认读取 `SELLERSPRITE_KEY` 环境变量） |
| `--marketplace <站点>` | 站点代码（默认 `US`） |
| `--format json\|compact` | 输出格式（默认 `json`） |

### init 子命令

| 参数 | 说明 |
|------|------|
| `--all` | 为所有支持的客户端生成配置 |
| `--skills` | 同时复制 Skills 文件 |
| `--project <目录>` | 目标项目目录（默认当前目录） |
| `--dry-run` | 预览模式，不写入文件 |

支持客户端：`claude-code`、`cursor`、`cline`、`claude-desktop`、`vscode`、`windsurf`、`trae`、`codex`、`antigravity`、`openclaw`

## 36 个数据工具

| 分类 | 工具 |
|------|------|
| ASIN 分析 | `asin_detail`, `asin_prediction`, `asin_coupon_trend`, `asin_detail_with_coupon_trend`, `keepa_info` |
| 商品竞品 | `product_research`, `competitor_lookup`, `product_node` |
| 关键词 | `keyword_miner`, `keyword_research`, `keyword_order`, `bsr_prediction` |
| 流量 | `traffic_keyword`, `traffic_keyword_stat`, `traffic_source`, `traffic_listing_stat`, `traffic_listing`, `traffic_extend` |
| 市场分析 | `market_research`, `market_research_statistics`, `market_price_distribution`, `market_brand_concentration`, `market_product_concentration`, `market_seller_concentration`, `market_rating_distribution`, `market_ratings_count_distribution`, `market_listing_date_distribution`, `market_listing_trend_distribution`, `market_seller_country_distribution`, `market_seller_type_concentration`, `market_ebc_distribution`, `market_product_demand_trend` |
| ABA / 趋势 | `aba_research_weekly`, `aba_research_monthly`, `google_trend`, `review` |

## 支持站点

US, JP, UK, DE, FR, IT, ES, CA, IN

## 相关项目

- [sellersprite-skills](https://gitee.com/1433/sellersprite-skills) — 27 个 AI Skills 卡片
- [卖家精灵 MCP 文档](https://mcp.sellersprite.com)
- [卖家精灵开放平台](https://open.sellersprite.com)

## 许可证

[MIT License](LICENSE)
