Positioning
Based on Sorftime MCP + LLM Agent in-depth product research. The LLM directly executes the analysis logic, while scripts are only responsible for data collection and report rendering.
Core Features：
- LLM-driven: analysis, insights, and decisions are all completed by the LLM
- Interactive execution: advances step by step, and users can intervene midway
- Lightweight scripts: used only for API calls and Dashboard rendering
Script Directory
| Script | Purpose | When to Call |
|---|---|---|
run_analysis.py |
Main entry script: integrates data collection, analysis, and report generation | Recommended for use |
collect_data.py |
Sorftime data collection (category, Top100, keywords, trends) | Step 1 |
get_reviews.py |
Competitor negative review data collection | Step 4 |
api_client.py |
Sorftime API calls + SSE parsing + encoding fixes | Every API call |
render_dashboard.py |
Generate the Dashboard visualization board (v3.1 fixed version) | Report generation stage |
fix_data_json.py |
Data validation and repair script: validates and automatically repairs data.json | Before Dashboard generation |
validate_data.py |
Data validation script: validates data.json field naming and data consistency | Before report generation |
Script Responsibilities：
- No analytical judgment: all analysis is completed by the LLM
- No complex calculations: let the LLM discover cross-analysis from the data
- Only data handling: API → structured data
Recommended Usage：
# 阶段1：数据采集（基础版 Dashboard）
python scripts/run_analysis.py "earbuds" US
# 阶段2：LLM 分析完成后，生成最终版报告
python scripts/run_analysis.py "earbuds" US --final
# 其他选项
python scripts/run_analysis.py "earbuds" US --collect-only # 仅数据采集
python scripts/run_analysis.py "earbuds" US --no-reviews # 跳过差评采集
Execution Flow (Two Stages)
Important: product research is divided into two stages. Data collection is completed automatically by scripts, while LLM analysis requires manual participation.
Stage 1: Data Collection (Automatic by Script)
python scripts/run_analysis.py "keyword" US
Output：
data.json- Basic data structure (excluding analysis conclusions)dashboard.html- Basic version board (excluding decision scores, VOC, etc.)raw/- Raw data files
Automatically completed by script：
- Category search → obtain nodeId
- Top100 product data collection
- Keyword data collection
- Category trend data collection
- Competitor negative review collection
- Market analysis (price range, brand distribution)
Stage 2: LLM Analysis (Interactive)
LLM Analysis Tasks That Must Be Completed：
| Step | Task | Output to data.json |
|---|---|---|
| 1 | Attribute tagging | product_types、dimensions_analysis |
| 2 | Cross-analysis | cross_analysis |
| 3 | VOC analysis | voc_analysis.dimensions |
| 4 | Barrier assessment | barriers |
| 5 | Decision evaluation | decision (overall_score, verdict) |
Run after completion：
python scripts/run_analysis.py "keyword" US --final
--final parameters will:
- ✅ Validate analysis data completeness
- ✅ Update data.json
- ✅ Generate the full version Dashboard (including decision scores, VOC, etc.)
- ✅ If the data is incomplete, the missing fields will be indicated
Data completeness check
You can also check data completeness separately:
python scripts/render_dashboard.py data.json --check
Example output:
✓ 数据完整，可以渲染完整版 Dashboard
包含: decision.overall_score, voc_analysis.dimensions, barriers, cross_analysis
Or
⚠️ 数据不完整，缺少以下字段:
- decision.overall_score
- voc_analysis.dimensions
ℹ️ 请先完成 LLM 分析，然后重新运行渲染
Execution flow (interactive)
Step 0: Information gathering
📋 选品分析 - 信息确认
1. 产品/类目关键词：[用户提供]
2. 目标站点：[US/GB/DE/FR/IT/ES/CA/JP，默认US]
3. 选品场景：[新手入门/蓝海发现/季节性/品牌打造/定向品类]
4. 约束条件（可选）：
- 价格区间：如 $10-40
- 月销量：如 > 1000
- 预算：如 10万人民币
Step 1: Data collection (enhanced version v3.0)
API call sequence：
| Step | API | Output | Description | Priority |
|---|---|---|---|---|
| 0.5 | search_categories_broadly |
blue_ocean_categories.json | [New] Blue ocean market discovery | 📋 On demand |
| 1.1 | category_name_search |
category_info.json | Search category by product name (using the searchName parameter) | ⛔ Required |
| 1.2 | category_report |
top100.json | Top100 product data | ⛔ Required |
| 1.3 | keyword_detail × 3+ |
keywords.json | Multi-dimensional keyword comparison | ⛔ Required |
| 1.4 | category_trend |
trend.json | New product share trend | ⛔ Required |
| 1.5 | keyword_extends |
keyword_extends.json | [New] Keyword extended terms (dimension discovery) | 📋 Recommended |
| 1.6 | potential_product |
potential_products.json | [New] Potential product discovery | 📋 Recommended |
| 1.7 | product_detail × 6-10 |
products.json | Competitor details (on demand) | 📋 On demand |
| 1.8 | product_reviews × 6-10 |
reviews.json | Competitor negative reviews (on demand) | 📋 On demand |
⚠️ Important: API parameter description (v3.0)
category_name_searchparameters:{"amzSite": "US", "searchName": "bluetooth speaker"}- The correct category search API, the parameter name is searchName
search_categories_broadlyparameters (blue ocean discovery):{"amzSite": "US", "top3Product_sales_share": 0.4}potential_productparameters (potential products):{"amzSite": "US", "monthlySales_min": 500}keyword_extendsparameters (extended terms):{"amzSite": "US", "keyword": "bluetooth speaker"}category_reportparameters:{"amzSite": "US", "nodeId": "7073956011"}- nodeId is of string type
Script invocation method：
# 方法1: 使用 collect_data.py (推荐)
from scripts.collect_data import collect_data
result = collect_data("bluetooth speaker", "US")
# 方法2: 使用 api_client.py
from scripts.api_client import SorftimeClient
client = SorftimeClient()
# 获取类目ID（正确的方式）
category = client.search_category_by_product_name("US", "bluetooth speaker")
node_id = category[0]['nodeId']
# 获取Top100
top100 = client.get_category_report("US", node_id)
# 获取关键词详情
keywords = client.get_keyword_detail("US", "bluetooth speaker")
Step 2: Attribute labeling (LLM-driven)
LLM task: Extract key differentiation dimensions from Top100 titles
## 属性标注任务
基于以下 Top100 产品标题，提取 3-6 个关键差异化维度：
### 标题样本
[提供 Top20-30 标题作为样本]
### 提取要求
1. 识别差异化维度（如：功率、防水、续航、形态等）
2. 为每个产品标注维度值
3. 标注置信度（高/中/低）
### 输出格式
| ASIN | 功率 | 防水 | 续航 | ... | 置信度 |
For low-confidence products: Call product_detail for supplementary verification
Step 3: Cross-analysis (LLM direct discovery)
LLM task: Discover supply-demand gaps from labeled data
## 交叉分析任务
基于以下已标注的 Top100 产品数据，执行交叉分析：
### 数据
[提供标注后的产品数据]
### 分析要求
1. 选择 2-3 对有意义的维度组合（如：功率×价格、防水×场景）
2. 识别：空白点（0产品）、薄供给（≤2产品）、高需求低供给
3. 分析每个缺口的原因（技术限制？需求不存在？被忽视？）
4. 按机会价值排序
### 输出格式
| 维度组合 | 状态 | 产品数 | 月销量 | 原因分析 | 机会评级 |
Key point: Have the LLM discover patterns directly from the data, rather than calculating them with a Python script
Step 4: Competitor and VOC analysis
Competitor selection logic table(LLM selects by segment):
| ASIN | Brand | Reason for selection | Type | Coverage dimension |
|---|---|---|---|---|
| [LLM selects 6-10 representative competitors] |
⛔ Negative review dimension classification (key step)
Must be classified by dimension; organizing by ASIN is prohibited
LLM task: Classify competitor negative reviews by attribute dimension, and map them to brand capabilities and product solutions
Input：competitor_reviews.json(raw negative reviews organized by ASIN)
Output：data.json in the voc_analysis field (classified by dimension)
Classification requirements：
- Identify main dimensions(3-6) - Extract pain point categories based on negative review content
- Each dimension includes：
dimension: Dimension name (e.g., sound quality/volume, comfort, battery life)pain_point: Pain point descriptionfrequency: Mention frequencypercentage: Proportion (e.g., "32%")affected_brands: List of brands involvedbrand_opportunity: How brand/supply chain capabilities can solve itproduct_solution: Specific product improvement directions
Output format example：
{
"voc_analysis": {
"dimensions": [
{
"dimension": "音质/音量",
"pain_point": "音量太小，户外听不清",
"frequency": 45,
"percentage": "32%",
"affected_brands": ["SHOKZ", "JLab"],
"brand_opportunity": "有14.2mm大动圈供应链",
"product_solution": "14.2mm动圈+音量增强模式"
}
],
"summary": "主要痛点集中在音质(32%)、舒适度(28%)、续航(18%)"
}
}
Prohibited output methods：
- ❌ Organized by ASIN:
{"B0XXX": {"reviews": [...]}} - ❌ Missing frequency/share data
- ❌ Missing mapping between brand opportunities and product solutions
Step 5: Evaluation and decision-making
Barrier to entry assessment：
| Barrier type | Level | Data anchor | Estimated cost | Mitigation plan |
|---|---|---|---|---|
| Review barrier | Medium/High | Top10 average XXX reviews | $XXX | Vine + PPC |
| Capital barrier | Medium/High | First batch stocking + advertising | ¥XX | Control first batch MOQ |
| ... | ... | ... | ... | ... |
Product selection decision evaluation (five-dimension scoring)：
| Dimension | Weight | Score (1-10) | Weighted score | Basis |
|---|---|---|---|---|
| Market size | 20% | [LLM score] | X.X | [Data basis] |
| Competitive landscape | 25% | [LLM score] | X.X | [Data basis] |
| ... | ... | ... | ... | ... |
| Total score | 100% | - | X.XX | Decision conclusion |
Decision conclusion mapping：
- 7.5-10 points → Recommended to enter (prioritize advancement)
- 6.0-7.4 points → Enter cautiously (requires precise positioning and clear entry conditions)
- 4.0-5.9 points → Wait and observe (requires more data validation)
- 0-3.9 points → Not recommended to enter (risks outweigh opportunities)
Product matrix(Tier 1 must specify concrete specifications):
### Tier 1: [产品定位]
**目标市场**：[维度组合空白/机会]
**决策理由**：[数据依据]
| 维度 | 规格 | 决策依据 |
|------|------|----------|
| [维度1] | [具体值] | [为什么] |
| [维度2] | [具体值] | [为什么] |
**目标定价**：$XX.XX
**差异化主张**：[一句话]
**对标竞品**：[ASIN] — [我们的优势]
**预估月销潜力**：XX-XX 件
Step 6: Report output
Output file：
product-research-reports/
└── {category}_{site}_{YYYYMMDD}/
├── report.md # Markdown 完整报告（LLM 直接输出）
├── data.json # 结构化数据（供 Dashboard 使用）
├── dashboard.html # 可视化看板（脚本渲染）
└── raw/ # 数据文件
├── category_info.json # 类目信息
├── top100.json # Top100 产品数据
├── trend.json # 趋势数据
└── keywords.json # 关键词数据
data.json structure(simplified version):
{
"metadata": {
"category": "bluetooth speaker",
"site": "US",
"date": "20260319"
},
"market_overview": {
"top100_monthly_sales": 55000,
"top100_monthly_revenue": 5200000,
"avg_price": 95,
"top3_product_concentration": 0.2578,
"top3_brand_concentration": 0.5058,
"top10_brand_concentration": 0.8234
},
"dimensions": [...],
"cross_analysis": [...],
"competitors": [...],
"voc_analysis": {
"dimensions": [
{
"dimension": "音质/音量",
"pain_point": "音量太小，户外听不清",
"frequency": 45,
"percentage": "32%",
"affected_brands": ["SHOKZ", "JLab"],
"brand_opportunity": "采用更大驱动单元",
"product_solution": "14.2mm动圈+音量增强模式"
}
],
"summary": "主要痛点集中在音质(32%)、舒适度(28%)、续航(18%)"
},
"barriers": [...],
"go_nogo": {...}
}
⛔ Important: Data field naming conventions
| Field name | Description | Example |
|---|---|---|
top3_product_concentration |
Top3 ProductShare of sales in the total sales of Top100 | 0.2578 = 25.78% |
top3_brand_concentration |
Top3 BrandShare of sales in the total sales of Top100 | 0.5058 = 50.58% |
top10_brand_concentration |
Top10 BrandShare of sales in the total sales of Top100 | 0.8234 = 82.34% |
new_product_share |
Sales share of new products (listed <6 months) | 0.26 = 26% |
Vague naming prohibited：
- ❌
top3_concentration(unclear whether it is product or brand) - ✅
top3_product_concentrationortop3_brand_concentration
⛔ Important: VOC analysis data structure
voc_analysis The field must include analysis bydimension categorizationof negative reviews, rather than being organized by ASIN:
| Field | Type | Description |
|---|---|---|
dimension |
string | Pain point dimension (e.g., sound quality/volume, comfort, battery life, etc.) |
pain_point |
string | Pain point description |
frequency |
number | Mention frequency |
percentage |
string | Share (e.g., "32%") |
affected_brands |
array | List of brands involved |
brand_opportunity |
string | How brand/supply chain capabilities can solve it |
product_solution |
string | Specific product improvement plan |
Dashboard rendering specifications
render_dashboard.py is responsible for data.json Render as a visual dashboard. Key rendering rules:
Product Dimension Distribution
- Must use table format, bar charts are prohibited
- Two-column layout: price range distribution on the left, product form distribution on the right
- Each row displays: dimension value, product count, percentage (with color label)
- Percentage label color rules: ≥30% blue, ≥20% green, ≥10% yellow, <10% gray
Cross Analysis (Price Range × Product Form)
- Must use matrix table format, charts are prohibited
- Rows: price range ($0-30 to $200+)
- Columns: product form (bone conduction, clip-on, open-ear hook, in-ear)
- Cells: product count
- Special markers:
- Intense competition (≥15 items): red "Red Ocean" label
- Market gap (0 items) and an opportunity point: green "Opportunity" label
- There must be an insight callout box at the bottom explaining the red ocean and opportunity areas
Example Output
<!-- 维度分布：双表格布局 -->
<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 24px;">
<!-- 价格区间表格 -->
<!-- 产品形态表格 -->
</div>
<!-- 交叉分析：矩阵表格 -->
<table>
<thead><!-- 表头：产品形态 --></thead>
<tbody><!-- 行：价格区间，列：产品数 --></tbody>
</table>
<div class="insight-box">洞察：...</div>
LLM Prompt Template Library
For detailed Prompt templates, please refer to:references/prompt_templates.md
Includes 6 templates:
- Attribute Annotation - Extract differentiation dimensions from product titles
- Cross Analysis - Discover supply-demand gaps
- Competitor Selection - Select representative competitors
- Negative Review Categorization - Categorize pain points by attribute dimension
- Product Selection Decision Evaluation - Five-dimension weighted decision
- Product Matrix Planning - Tier 1/2/3 specific specifications
Hard Rules (⛔ Cannot Be Omitted)
- ⛔ Top100 must be complete with 100 items
- ⛔ Keywords must compare at least 3 dimensions
- ⛔ Select 6-10 competitors, covering volume benchmarks/feature differences/price bands/pain points
- ⛔ Negative reviews must be categorized by dimension(not categorized by ASIN), output to
data.jsonthevoc_analysisfield - ⛔ VOC analysis must include: frequency, percentage, brands involved, brand opportunities, product solutions
- ⛔ Product selection decision evaluation must be quantitatively scored
- ⛔ Tier 1 products must be specific down to specifications ("to be confirmed" placeholders are prohibited)
- ⛔ Each data table must be followed by a "Key Insights" paragraph
- ⛔ Blank/thin supply must be accompanied by cause analysis
- ⛔ Data field naming must be clear: use
top3_product_concentration/top3_brand_concentration, vaguetop3_concentration - ⛔ Data consistency validation: before report generation, must validate
data.jsonthe values in are consistent with the report text
Common Scenario Strategies
Scenario 1: Beginner Entry (Budget < 150K)
- Price $10-20
- Light and small items
- No after-sales risk
- Chinese seller share > 70%
Scenario 2: Blue Ocean Discovery
- Top3 concentration < 30%
- New product share > 15%
- Keyword first-page reviews < 500
Scenario 3: Targeted Category Analysis (User-Specified)
- Skip category scanning, proceed directly to data collection
- ⛔ Attribute annotation must be performed
- ⛔ Cross analysis must be performed
- ⛔ Product selection decision evaluation (five-dimension scoring) must be performed
Relationship with Other Skills
category-selection (品类筛选五维评分)
↓
product-research (深度选品调研) ← 本 Skill
↓
amazon-analyse (竞品 Listing 深挖)
↓
review-analysis (评论深度分析)
Differences：
category-selection: Rapid screening at the category level, five-dimension scoringproduct-research: In-depth research on a specified category, multi-dimensional analysis + product selection decision assessmentamazon-analyse: Detailed analysis of a single competitor's Listingreview-analysis: In-depth pain point analysis of reviews
Supported marketplaces
US, GB, DE, FR, IT, ES, CA, JP, MX, AE, AU, BR, SA
Notes
- API Key: Automatically from
.mcp.jsonread - Data freshness: Sorftime data may have a 1-7 day delay
- API rate limiting: At most 8 concurrent requests per batch
- Encoding issues: The script automatically handles Unicode-escape and Mojibake
- Raw data: All API responses are saved in the
raw/directory for verification
Troubleshooting
Common errors and solutions
| Error message | Cause | Solution |
|---|---|---|
HTTP Error 406: Not Acceptable |
API parameter error | Check whether the parameter name is searchName instead of productName |
An error occurred invoking 'xxx' |
API tool does not exist | Check the tool name in the TOOLS mapping table |
未查询到对应产品 |
Invalid ASIN or wrong marketplace | Verify the ASIN format and confirm the product is sold on that marketplace |
Authentication required |
API Key error | Check the .mcp.json key parameter in |
| Chinese garbled text | Mojibake encoding | The script fixes it automatically, or run fix_encoding.py |
IndentationError: unexpected indent |
Windows command line issue | Use a script file instead of python -c |
输出目录路径错误 |
Relative path issue | Use run_analysis.py, which handles paths automatically |
NameError: name 'xxx' is not defined |
Missing datetime import | Check the script's import statements |
| Dashboard rendering issue | ||
| Dashboard displays blank | data.json structure mismatch | Fixed in v3.5：run_analysis.py automatically renders the Dashboard |
| Dashboard not automatically generated | Older versions did not integrate rendering | Fixed in v3.5: Automatically renders after data collection is complete |
PermissionError: [Errno 13] |
Passed a directory path instead of a file path | Call using an absolute path:python render_dashboard.py -o output.html data.json |
unrecognized arguments |
Wrong parameter order | Correct format:python render_dashboard.py -o dashboard.html data.json |
| Dashboard missing VOC data | The LLM did not generate a complete voc_analysis | Ensure the LLM generates a complete data.json containing voc_analysis.dimensions |
| Dashboard cross-analysis is empty | price_type_matrix data is missing | Ensure data collection includes price range analysis |
KeyError: 'xxx' |
Inconsistent field names | Fixed in v3.4: Supports compatibility with both old and new field names |
AttributeError: 'str' object has no attribute 'get' |
data.json format issue | Fixed in v3.4: Automatically converts to list format |
Dashboard manual rendering method
If automatic rendering fails, you can call it manually:
# 从输出目录调用
python .claude/skills/product-research/scripts/render_dashboard.py \
-o product-research-reports/{keyword}_{site}_{date}/dashboard.html \
product-research-reports/{keyword}_{site}_{date}/data.json
# 或者使用绝对路径
python "D:\amazon-mcp\.claude\skills\product-research\scripts\render_dashboard.py" \
-o "D:\amazon-mcp\product-research-reports\{keyword}_{site}_{date}\dashboard.html" \
"D:\amazon-mcp\product-research-reports\{keyword}_{site}_{date}\data.json"
API tool name mapping table
| Function | Tool name | Parameters |
|---|---|---|
| Category Search | category_name_search |
amzSite, searchName |
| Category Report | category_report |
amzSite, nodeId |
| Category Trends | category_trend |
amzSite, nodeId, trendIndex |
| Keyword Details | keyword_detail |
amzSite, keyword |
| Product Details | product_detail |
amzSite, asin |
| Product Reviews | product_reviews |
amzSite, asin, reviewType |
Debugging Tips
- Enable Verbose Output: Add
print()debug information in the script - Check the Raw Response: View the actual content of the SSE response
- Step-by-Step Execution: Use the Python interactive environment to debug line by line
- Verify API Key:
curl "https://mcp.sorftime.com?key=YOUR_KEY" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
Version: v3.6 (two-phase workflow + data validation) | Last updated: 2026-03-19