卖家精灵 Amazon 数据调研

重要：MCP 连接配置

.mcp.json 必须使用以下格式（⚠️ 密钥通过 header 传入，不是 URL 参数）：

{
  "mcpServers": {
    "sellersprite": {
      "url": "https://mcp.sellersprite.com/mcp",
      "headers": {
        "secret-key": "你的密钥"
      }
    }
  }
}

工具调用方式

方式 A：通过 MCP 客户端（推荐）

MCP 客户端直接调用工具：

mcp__sellersprite__<tool_name>

例: mcp__sellersprite__product_research

方式 B：通过 curl（无 MCP 客户端时备用）

curl -s -X POST "https://mcp.sellersprite.com/mcp" \
  -H "Content-Type: application/json" \
  -H "secret-key: <YOUR_KEY>" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "<tool_name>",
      "arguments": { <扁平参数或{"request":{...}}> }
    }
  }'

方式 C：通过 Python（批量调用场景）

import json, urllib.request
payload = json.dumps({"jsonrpc":"2.0","id":1,"method":"tools/call",
    "params":{"name":"market_research","arguments":{"request":{
        "marketplace":"US","nodeIdPath":"...","topNum":10}}}}).encode()
req = urllib.request.Request("https://mcp.sellersprite.com/mcp", data=payload,
    headers={"Content-Type":"application/json","secret-key":"<KEY>"})
with urllib.request.urlopen(req) as resp:
    data = json.loads(resp.read().decode('utf-8'))
    result = json.loads(data['result']['content'][0]['text'])

方式 D：通过 mcp_call.py 工具脚本（项目内预置）

python3 mcp_call.py <tool_name> '{"param1":"value1"}'

关键：参数传递模式

模式 A："扁平参数"（少部分工具）

直接在顶层传字段。例如 asin_detail、keyword_research_trends、review：

{"marketplace": "US", "asin": "B0XXXXX"}

模式 B："request 嵌套对象"（大部分工具）

绝大多数筛选/搜索类工具（market_research、product_research、keyword_miner 等）的唯一必填参数是 request，其值为一个嵌套对象：

{
  "request": {
    "marketplace": "US",
    "nodeIdPath": "11091801:11974521:8882489011:11974711",
    "topNum": 10,
    "size": 50
  }
}

MCP 客户端调用时，arguments 写为 {"request": {...}}。

识别方法

查看工具的 required 字段：
- required=["marketplace","asin"] → 扁平参数
- required=["request"] → 嵌套对象

全局参数默认值

字段映射与刻度陷阱（重要）

改名规律（网页 API → MCP 响应）

• totalUnits → units（月销量）
• totalAmount → revenue（月销售额）
• reviews → ratings（评分数）
• bsrRank → bsr（BSR 排名）
• sellerType → fulfillment（配送方式）
• *Ratio → *Proportion，HeadListing* → Top*

刻度陷阱

• 集中度字段（top*Crn/l*NewRatio）为 0~1 小数，展示需 ×100
• returnRatio/*Proportion 已是 0~100 百分数，不再换算
• purchaseRate/cvsShareRate/monopolyClickRate 为 0~1，展示 ×100
• supplyDemandRatio 已是真实比值（如 78.88），不换算
• 多值参数（brands/sellers/fulfillment）传逗号字符串，非数组

类名翻译陷阱 ⚠️

product_node 返回的 nodeLabelLocale（中文翻译）不可靠，常见错误：
| 英文名 | 错误翻译 |
|--------|---------|
| Microphones | 显微镜 ❌ |
| Microphone Accessories | 辅料 ❌ |
| Hand Percussion | 手部打击乐 ❌ |
| Stands | 摊位 ❌ |
| Sound | 声音 ❌ |

始终以 nodeLabelPath（英文完整路径）为准。

MCP 响应解析要点

标准响应结构

{
  "jsonrpc": "2.0", "id": 1,
  "result": {
    "content": [{"type": "text", "text": "{\"code\":\"OK\",\"data\":...}"}],
    "isError": false
  }
}

result.content[0].text 是卖家精灵 API 的 JSON 字符串，需二次解析。

数据组织结构差异

安全取值：

def safe_items(data):
    if isinstance(data, dict): return data.get('items', [])
    if isinstance(data, list): return data
    return []

⚠️ 实际 API 响应字段陷阱（实测发现，与文档不一致）

部分工具的 JSON 响应字段名与文档描述不同，必须按实际响应取值：

review 工具采样限制（重要）

• review 工具 每次最多返回 20 条（size=100 也会被限制）
• 所以评分分布是 样本，不代表总体
• 报告中必须注明："⚠️ 仅展示最近 20 条评论，不代表总体分布"
• 情感分析和差评主题也要加"基于样本"限定

keepa 时间序列数据提取

keepa_info 返回的价格/BSR 均为 [{timePoint: timestamp, value: number}] 格式数组：

price_data = keepa.get('buyBox', [])
if price_data:
    prices = [p['value'] for p in price_data if p.get('value', 0) > 10]
    current_price = prices[-1] if prices else 'N/A'
    avg_price = sum(prices)/len(prices) if prices else 'N/A'

HTML 实体解码

API 返回的标题/描述中可能包含 & " < 等 HTML 实体，必须解码：

import html
clean_title = html.unescape(raw_title)

一、综合分析工作流

通过 /命令 调用，执行多步骤分析。详细步骤见 comprehensive/ 下对应文件。

二、战术选品策略卡

对话中引用名称触发。详细参数见 tactical/ 下对应文件。

新品爆发型

关键词趋势型

产品缺陷型

类目结构型

流量防伪型

机会捕捉型

三、MCP 工具参考

详细参数、响应字段映射和陷阱见 reference/ 下文件：

四、输出格式（必读：必须保存为文件）

HTML 可视化报告生成（固定步骤，不可跳过）

完成 market_report.md 后，必须自动生成对应的 market_report.html：

1. 数据源 — 以刚完成的 market_report.md 为数据源，不额外调 API
2. 全面展示 — 覆盖报告的每个核心维度（概览、销量、流量、关键词、竞争、市场、评论、价格、SWOT、行动建议）
3. 图表呈现 — 关键数据用 Canvas 图表展示（价格/BSR 趋势、对比柱状图、趋势线等）
4. 设计风格 — 深色专业主题、配色统一、响应式适配、交互流畅
5. 输出 — 保存到与 MD 相同的目录 {类别名}/market_report.html

> 如果用户明确说"不需要 HTML"可以跳过，否则必须生成。

铁律：报告禁止仅打印到控制台

所有分析报告必须保存为文件，不得只 print/echo 到控制台。用户看不到控制台输出。

文件保存规范

目录命名：以调研的类别名为目录名，如 wirelessinstruments/、bluetooth-speaker/。

⚡ 铁律：MD 报告完成后必须生成 HTML 报告

每次完成 market_report.md 后，必须立即 基于 MD 内容生成对应的 market_report.html。这是不可跳过的步骤，原因：

1. 用户体验 — HTML 报告包含可视化图表（Canvas 折线图/柱状图/趋势图），比纯文本直观得多
2. 数据验证 — 图表能暴露 Markdown 表格中不易察觉的数据异常
3. 分享便利 — 非技术背景的团队成员可直接在浏览器打开查看

> 注意：HTML 报告是 MD 报告的 可视化增强版本，不是替代。两者共存，各有用途。

报告内容结构

所有报告必须包含：
1. 筛选口径 — 工具参数、数据月份、ASIN/关键词、Review 采样说明
2. KPI 摘要 — 关键指标高亮
3. 多维分析 — 表格 + 评分卡 + 洞察
4. 分级结论 — 推荐/谨慎/不推荐

报告质量检查清单（生成后必须自查）

报告保存前，逐项检查以下内容，确保没有质量问题：

数值格式化

销量/销售额千分位（12,345）、占比/评分 1 位小数（23.4%）、价格 $X.XX。注意 0~1 刻度换算。

五、推荐组合链路

品类扫描 -> 低品牌垄断 / 高新品占比（找蓝海类目）
    ↓
关键词挖掘 -> ABA增长词 / 流量分散词 / 标题密度漏洞（找增长词）
    ↓
竞品锁定 -> 新品爆发 / 隐形爆款 / 热销低评分（找目标竞品）
    ↓
竞品验真 -> 自然流量反查（流量防伪）
    ↓
痛点提炼 -> 评论语义分析（产品改进）
    ↓
产品开发 -> 变体拆解 + 高毛利轻小（利润验证）

六、实操技巧（实测经验）

类目节点查找技巧

• 用英文关键词搜索（"wireless microphone" 比 "无线麦克风" 结果更准）
• 找到后记录 nodeIdPath 供后续调用
• 父节点数据可能包含自身汇总行，取数据时注意过滤

批处理策略

• 市场全景分析至少调用 13 个工具（market_research + 12 分布工具）
• 工具间无数据依赖，可以全并行
• 关注响应中的 code: "OK" 字段判断调用成功

常见故障排查

七、实测经验与参数陷阱

> 以下为 2026-07-05 JOYO JW-03 深度调研中实测发现的工具行为差异，已修复到文档中。记录在此供未来快速参考。

7.1 连接与认证

7.2 工具参数模式实测纠正

7.3 流量工具注意事项

• traffic_source 即使调用成功，asinInfo 也可能返回无关产品的流量（实测返回了空气净化器、SD 卡等），数据不可信赖
• 流量来源分析建议使用 traffic_keyword + traffic_keyword_stat 组合来代替
• traffic_listing_stat 和 traffic_listing 正常工作，可用 request 嵌套对象

7.4 评论工具缺陷

• review 工具 size 参数无效，最多永远返回 20 条
• 所以评分分布永远是样本，报告中必须注明"仅最近 20 条样本"
• 字段名：content（非 body）、date（非 createTime）

7.5 Keepa 数据处理

• keepa_info 返回的是时间序列数组：buyBox: [{timePoint, value}]、bsr: [{timePoint, value}]
• 不存在 currentPrice 或 bsrHistory 字段
• 提取当前价：取 buyBox 数组最后一个 value；BSR 同理

7.6 类目节点注意事项

• product_node 返回的 nodeLabelLocale（中文翻译）经常错误（Microphones → 显微镜）
• 始终以 nodeLabelPath（英文完整路径）为准
• 必须使用叶子节点 nodeIdPath，父节点返回全 0 数据

7.7 混合类目识别

某些子类目下混合了不同类型的商品（如 "Electric Guitar Electronics" 下既有 $5-15 的电子元件，也有 $40+ 的无线吉他系统）。分析时需注意：

1. 价格分布会两极分化 — 不代表目标产品的合理定价区间
2. 品牌集中度可能失真 — 高价品牌销售额占比虚高
3. 解决方法：手动标注类目内真实竞品，单独圈定可比价格区间

7.8 数据质量标注规范

报告中凡是遇到以下情况，必须加 ⚠️ 标注：

八、报告质量检查清单

> 报告保存前，逐项检查以下内容，确保没有质量问题。此清单为生产报告的最后一道门禁。

8.1 数据完整性检查

8.2 字段正确性检查

8.3 逻辑正确性检查

8.4 格式规范检查

8.5 发布前最终确认

• [ ] 以上 20 项检查已逐项通过
• [ ] research_data.json 已保存且包含所有 API 原始返回
• [ ] 报告包含筛选口径、KPI 摘要、多维分析、分级结论四要素
• [ ] 无仅打印到控制台的调试输出
• [ ] market_report.html 已生成 — 在 market_report.md 同级目录，包含图表可视化