Sellersprite Amazon Research skill

卖家精灵 Amazon 数据调研

重要：MCP 连接配置

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

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

配置项	正确值	错误值
URL	https://mcp.sellersprite.com/mcp	.../sse 或 .../mcp?key=xxx
认证方式	headers.secret-key	URL 查询参数 ?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"] → 嵌套对象

---

全局参数默认值

参数	默认值	说明
marketplace	US	目标站点：US/JP/UK/DE/FR/IT/ES/CA/IN
matchType	2	1=词组匹配 2=模糊匹配 3=精准匹配
size	50	每页返回条数（最大 100）

---

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

改名规律（网页 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 字符串，需二次解析。

数据组织结构差异

工具类型	data 结构	示例
market_research	{ items: [...] }	子市场数组在 items
market_brand_concentration	[{...}]（直接数组）	品牌列表直接返回
market_price_distribution	{ items: [...] }（嵌套）	价格区间在 items
product_node	[{...}]（直接数组）	节点列表直接返回

安全取值：

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

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

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

工具	你以为的字段	实际字段	后果
keyword_research_trends	month, searches	time, search	全显示 N/A
keyword_research_trends	growth, change	chainGrowth(环比), yearlyGrowth(同比)	无增长率
keyword_research_trends	purchaseCount	purchase	无购买数据
aba_research_trend	clickShareRate, conversionShareRate	没有这两个字段	全显示 0%
aba_research_trend	month	label, date, searches, rank	无趋势
traffic_keyword_stat	searchTotal, naturalTotal	keywords(总数), ranks(有排名), ads(有广告)	全显示空
review	body, createTime	content, date	评论内容为空
keepa_info	currentPrice, bsrHistory	buyBox([{timePoint,value}]), bsr([{timePoint,value}])	全显示空
traffic_source	request 嵌套对象	实际需扁平参数 + "q": "asin"	HTTP 200 但返回 q is required
keyword_research	传入 keyword 参数	返回按搜索量排序的全局关键词，无视筛选	数据全为不相关词

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/ 下对应文件。

命令	名称	核心工具	详见
/product-research	智能选品助手	product_research + product_node	comprehensive/product-research.md
/market-analysis	市场全景分析	market_research + 分布工具集	comprehensive/market-analysis.md
/competitor-analysis	竞品深度拆解	asin_detail + traffic_keyword	comprehensive/competitor-analysis.md
/keyword-research	关键词选品研究	keyword_research + keyword_miner	comprehensive/keyword-research.md
/listing-optimizer	Listing 优化诊断	traffic_listing + keyword_order	comprehensive/listing-optimizer.md
/traffic-analysis	流量结构分析	traffic_source + traffic_keyword_stat	comprehensive/traffic-analysis.md
/opportunity-finder	蓝海机会挖掘	aba_research_trend + google_trend	comprehensive/opportunity-finder.md
/review-insights	买家评论洞察	review + NLP 分析	comprehensive/review-insights.md
/pricing-strategy	定价策略分析	market_price_distribution	comprehensive/pricing-strategy.md
/ad-optimizer	广告投放优化	keyword_order + traffic_keyword	comprehensive/ad-optimizer.md

---

二、战术选品策略卡

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

新品爆发型

策略	核心工具	逻辑	详见
新品快速爆发	product_research	上架≤2月+销量≥300+Review≤100	tactical/new-product-burst.md
隐形爆款	product_research	上架≤3月+销量≥500+Review≤50	tactical/hidden-bestseller.md

关键词趋势型

策略	核心工具	逻辑	详见
ABA 高增长趋势词	keyword_research	近3月持续增长+点击不集中	tactical/aba-high-growth-trend.md
流量分散关键词	keyword_miner	搜索≥5000+集中度<50%	tactical/low-monopoly-keyword.md
标题密度漏洞	keyword_miner	标题密度≤5的长尾词	tactical/title-density-gap.md

产品缺陷型

策略	核心工具	逻辑	详见
热销低评分产品	product_research	月销≥1000+评分≤4.2	tactical/hot-low-rating.md
评论语义分析	review	差评NLP聚类→改良指南	tactical/review-sentiment.md

类目结构型

策略	核心工具	逻辑	详见
低品牌垄断类目	market_research	品牌集中度<45%	tactical/low-brand-monopoly.md
高新品占比市场	market_research	新品占比>5%+新品仍出单	tactical/high-new-product-ratio.md
高毛利轻小品	product_research	FBA≤$4+毛利≥50%	tactical/high-margin-lightweight.md

流量防伪型

策略	核心工具	逻辑	详见
自然流量反查	traffic_source	自然流量占比>60%	tactical/natural-traffic-audit.md
变体拆解模型	asin_detail	找未被覆盖的变体缺口	tactical/variant-gap-analysis.md

机会捕捉型

策略	核心工具	逻辑	详见
本土溢价降维	product_research	美国卖家+高价+高销	tactical/local-premium-disruption.md
FBM 拦截	product_research	FBM发货+月销≥300	tactical/fbm-intercept.md
低质量 Listing 高销量	product_research	LQS≤60+月销≥400	tactical/poor-listing-winner.md
高客单长尾	keyword_miner	均价≥$80+搜索量适中	tactical/high-ticket-long-tail.md
季节前置爆破	keyword_miner	历史同期环比增长>100%	tactical/seasonal-prepositioning.md

---

三、MCP 工具参考

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

参考文件	对应工具	已验证
reference/product_research.md	product_research	✅
reference/market_research.md	market_research + 11 分布工具	✅
reference/traffic_keyword.md	traffic_keyword + traffic_extend	✅
reference/competitor_lookup.md	competitor_lookup	✅
reference/keyword_miner.md	keyword_miner + keyword_research	✅
reference/asin_detail.md	asin_detail + keepa_info 等 ASIN 工具
reference/tools_index.md	全部 42 个工具清单 + 参数模式	✅ 已更新

---

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

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 到控制台。用户看不到控制台输出。

文件保存规范

文件	必存	命名规则	说明
分析报告	✅ 必须	{类别名}/market_report.md	结构化 Markdown，用户可直接阅读
HTML 可视化报告	✅ 必须（新增）	{类别名}/market_report.html	生成 MD 报告后自动配套生成，单文件纯 HTML+CSS+JS，基于 MD 数据，无需额外 API 调用
原始数据	✅ 必须	{类别名}/research_data.json	API 原始返回，供后续二次分析

目录命名：以调研的类别名为目录名，如 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. 分级结论 — 推荐/谨慎/不推荐

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

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

#	检查项	说明
1	标题/描述 HTML 实体	检查 & " 等是否用 html.unescape() 解码
2	销量汇总有重叠	多卖家/多变体叠加的合计要加⚠️注解
3	流量来源工具容错	traffic_source 可能不返回数据，必须有 fallback
4	ABA 字段正确	用 searches/rank，不要用不存在的 clickShareRate
5	趋势字段正确	用 time/search/chainGrowth/yearlyGrowth
6	Review 样本说明	必须注明"仅 20 条样本"，评分分布不能代表总体
7	关键词相关性过滤	高价值/蓝海词列表必须排除不相关泛词
8	品牌词不要列为机会	纯品牌词（"dji"等）不应出现在蓝海表中
9	Keepa 数据展示	调用 keepa_info 后必须在报告中展示
10	ASIN vs 市场数据区分	每个表格注明数据是 ASIN 自身的还是搜索市场的

数值格式化

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

---

五、推荐组合链路

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

---

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

类目节点查找技巧

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

批处理策略

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

常见故障排查

现象	原因	解决方法
返回 secret_invalid	key 配置错误	检查 header 名是 secret-key，非 Authorization
数据全是 0	节点是根节点	必须使用叶子节点 nodeIdPath
HTTP 400	请求格式错误	检查 request 嵌套是否正确
q is required	traffic_source 用了 request 嵌套	改用扁平参数 + "q": "asin"
返回不相关数据	keyword_research 传了 keyword 但忽略筛选	该工具会忽略 keyword 参数，改用 keyword_miner 替代
翻译名称怪	nodeLabelLocale 不可靠	使用英文 nodeLabelPath
报告显示 N/A 或全 0	字段名与文档不符	查本文「实际 API 响应字段陷阱」表，用实际字段名
ABA/趋势数据空白	用了 clickShareRate/conversionShareRate	实际只有 searches/rank 字段
评论只有 20 条	review 工具采样限制	size 参数无效，最多返回 20 条
趋势月份显示 N/A	用了 month 或 label	keyword_research_trends 用 time
报告中有 &	HTML 实体未解码	必须用 html.unescape()
Keepa 数据空白	用了 currentPrice 等不存在字段	用 buyBox / bsr 数组，内部是 {timePoint, value}

---

七、实测经验与参数陷阱

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

7.1 连接与认证

经验	说明
Accept header 必须	调用 MCP endpoint 时必须传 Accept: application/json, text/event-stream，仅传 application/json 会 HTTP 400
密钥传 header	secret-key 放 headers，非 URL 参数，非 Authorization
SSE 方案不可用	SDK SSE 连接 /sse → 阿里云 Tengine CDN session affinity 导致 302/504 Gateway Timeout，放弃。始终用 HTTP POST 到 /mcp

7.2 工具参数模式实测纠正

工具	文档声称	实测正确方式	后果
traffic_source	request 嵌套对象	扁平参数 + "q": "asin"：{"marketplace":"US","asin":"B0XXX","q":"asin"}	HTTP 200 但返回 q is required
traffic_keyword_stat	request 嵌套对象	扁平参数：{"marketplace":"US","asin":"B0XXX"}	空数据
keyword_research	传 keyword 筛选	该工具完全忽略 keyword 参数，返回全局热词按搜索量排序	数据全为不相关词

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 数据质量标注规范

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

场景	⚠️ 原因
多 ASIN 销量汇总	多变体/多卖家合计可能重叠
价格 vs 销量交叉表合计不一致	统计口径不同或重复计数
品牌集中度工具间差异	market_research 和 market_brand_concentration 可能口径不同
Google Trends 异常峰值	可能是短期事件（新品发布/KOL），不代表长期趋势
评论评分分布	review 仅 20 条样本，不能代表总体
关联流量数据	traffic_listing_stat 关联流量为快照值，非月度累计

---

八、报告质量检查清单

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

8.1 数据完整性检查

#	检查项	说明
1	报告和原始数据均已保存	market_report.md + research_data.json 都必须在 {类别目录}/ 下
2	至少调用 3+ 工具	单一工具的报告结论不可靠，must cross-reference
3	流量来源数据有 fallback	traffic_source 可能失败，必须有替代方案（traffic_keyword + traffic_keyword_stat）
4	Keepa 数据已展示	调用 keepa_info 后必须在报告中展示价格/BSR 历史
5	谷歌趋势已调用	大型调研必须包含 Google Trends 数据进行外部验证

8.2 字段正确性检查

#	检查项	说明
6	趋势字段使用正确	用 time/search 非 month/searches；chainGrowth(环比) 非 growth
7	ABA 字段使用正确	用 searches/rank，不要用 clickShareRate/conversionShareRate（不存在）
8	刻度转换正确	集中度 01 → ×100；purchaseRate 01 → ×100；returnRatio 已是百分数不再换算
9	HTML 实体已解码	& " 等必须用 html.unescape() 解码
10	Review 样本已注明	必须标注"仅最近 20 条样本"，评分分布不具总体代表性

8.3 逻辑正确性检查

#	检查项	说明
11	关键词列表排除了品牌词	纯品牌词（"dji"、"lekato"等）不应列为蓝海机会
12	关键词列表排除了不相关泛词	高价值/蓝海词列表必须人工过滤无关词
13	ASIN vs 市场数据区分	每个表格注明数据是 ASIN 自身的还是搜索市场的
14	混合类目已识别并标注	如 $5-15 元件 + $40+ 系统的混合类目，需加 ⚠️ 说明
15	销量汇总重叠已标注	多卖家/多变体叠加的合计要加 ⚠️

8.4 格式规范检查

#	检查项	说明
16	数值格式化	销量/销售额千分位（12,345），占比/评分 1 位小数（23.4%），价格 $X.XX
17	表格可读性	Markdown 表格对齐（:--- 左对齐 :---: 居中 ---: 右对齐）
18	标题层级合理	使用 ## / ### / #### 层级结构，不超过 4 级
19	筛查口径已记录	报告中必须标注：调用工具列表、数据月份、ASIN/关键词、采样说明
20	数据质量警告	数据异常处必须使用 ⚠️ 标注（参考 7.8 节）

8.5 发布前最终确认

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