category-selection

Quick Reference

One-Click Execution Workflow (Recommended)

# 使用品类名称
python .claude/skills/category-selection/scripts/workflow.py "Sofas" US 20

# 直接使用 NodeID (推荐，避免类目搜索问题)
python .claude/skills/category-selection/scripts/workflow.py 679394011 US 20

# 指定分析数量
python .claude/skills/category-selection/scripts/workflow.py "Kitchen" US 50

Important Updates (v4.0):

✅ Automatically Read API Key: No need to set environment variables, automatically from .mcp.json read
✅ Fix Control Characters: Automatically handle unescaped line breaks and tabs in JSON string values
✅ Improved Category Search: Supports fuzzy matching and keyword variants
✅ Detailed Logs: Execution logs are saved to execution.log

Core API Tools

Step	Tool/Operation	Purpose	Returned Data Size
1. Search Category	`category_name_search`	Get category nodeId	Small
2. Category Report	`category_report`	Get Top product list and statistical data	Large (>25KB)
3. Product Details	`product_detail`	Get details of a single product	Small
4. Category Keywords	`category_keywords`	Get core category keywords	Large (>25KB)
5. Category Trends	`category_trend`	Get 25-month historical trends	Medium
6. 1688 Procurement	`products_1688`	Get procurement cost data	Small

Call Format

curl -s -X POST "https://mcp.sorftime.com?key=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":N,"method":"tools/call","params":{"name":"TOOL_NAME","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'

Trigger Conditions

This analysis process is started when the user makes a request in the following ways:

Command: /category-selection {品类名称} {站点} [--limit N]
Example: /category-selection "Sofas" US --limit 20
Natural Language: "Analyze the Sofas category on Amazon US", "Sofas category market research", "Sofas category product selection"

Role Setting

You are an "Amazon product selection expert" and "market analyst" with 10 years of experience. You are proficient in category analysis methodologies and can use data to provide insight into market opportunities, competitive landscape, and entry barriers, providing users with actionable product selection recommendations.

Five-Dimensional Scoring Model (Standard Version)

Detailed Explanation of Scoring Standards:

Dimension	Score	Scoring Standards	Data Source
Market Size	20 points	>$10M=20 points, >$5M=17 points, >$1M=14 points, others=10 points	Category monthly sales (monthly sales of top100 products)
Growth Potential	25 points	Proportion of low-review products >40%=22 points, >20%=18 points, others=14 points	Proportion of products with reviews <100
Competition Intensity	20 points	Top3 brand share <30%=18 points, <50%=14 points, others=8 points	CR3 brand concentration
Entry Barriers	20 points	Amazon share <20% and new products >40%=20 points, other combinations 6-18 points	Amazon self-operated share + low-review share
Profit Margin	15 points	Average price >$300=12 points, >$150=10 points, >$50=7 points, others=4 points	Average price of Top100 products

Rating criteria:

Total score	Rating	Recommendation
80-100	Excellent	Strongly recommend entering
70-79	Good	Can consider entering
50-69	Average	Enter with caution
0-49	Poor	Not recommended to enter

For complete criteria please refer to: scoring-standard.md

Complete analysis workflow

Phase 1: Data collection

Step 1: Search category to obtain nodeId

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"category_name_search","arguments":{"amzSite":"US","searchName":"品类关键词"}}}'

When processing multiple category results：

Major categories (such as "Clothing, Shoes & Jewelry") usually only return a list of subcategories
Display them to the user for selection of the most matching category
Or use a specific subcategory NodeID to query directly

Common category NodeID reference:

Traditional Laptop Computers: 13896615011
2 in 1 Laptop Computers: 13896609011
Women's Fashion Sneakers: 679394011
Women's Road Running Shoes: 14210388011
Men's Fashion Sneakers: 679312011
Kitchen Storage Accessories: 3744031

Step 2: Obtain category report (Top100 + statistics)

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"category_report","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'

Key: category_report Returned data is usually >25KB and will be saved to a temporary file

Response handling:

# 使用 workflow.py 自动处理 (推荐)
python .claude/skills/category-selection/scripts/workflow.py "Sofas" US 20

# 或手动解码 SSE 响应
python .claude/skills/category-selection/scripts/sse_decoder.py {temp_file} {output_dir} 20

Step 3: Obtain Top N product details (concurrent)

# 并发获取 Top3 产品详情
curl ... '{"id":3,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN1"}}}' &
curl ... '{"id":4,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN2"}}}' &
curl ... '{"id":5,"method":"tools/call","params":{"name":"product_detail","arguments":{"amzSite":"US","asin":"ASIN3"}}}' &
wait

Step 4: Obtain category keywords (optional)

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"category_keywords","arguments":{"amzSite":"US","nodeId":"NODE_ID","page":1}}}'

Process keyword data:

python .claude/skills/category-selection/scripts/keywords_parser.py \
  {temp_file} \
  {output_dir} \
  20

Step 5: Obtain historical trend data (optional)

curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"category_trend","arguments":{"amzSite":"US","nodeId":"NODE_ID"}}}'

Trend data types:

Category monthly sales trend (25 months)
Average selling price trend
Average star rating trend
Brand count trend

Phase 2: Data analysis

Core analysis metrics

1. Market concentration analysis

# HHI 指数 (赫芬达尔-赫希曼指数)
# 计算: 各品牌市场份额平方和 × 10000
# 解读: <1500=低集中度, 1500-2500=中等, >2500=高集中度

# CR3/CR5 (前N品牌集中度)
# 计算: 前N大品牌销量占比
# 解读: <30%=分散, 30-50%=中等, >50%=集中

2. Brand analysis

# 品牌分布: 按销量/销额排序
# 品牌数量: 统计独立品牌数
# 品牌多样性: HHI 指数评估

3. Seller source analysis

# Amazon 自营占比
# 中国卖家占比
# 美国本土卖家占比
# 其他国际卖家占比

4. Price analysis

# 价格区间分布
# 平均价格
# 价格中位数
# 价格标准差

5. New product analysis

# 新产品定义: 上架时间 < 90天
# 新品占比: 新品数量 / 总数量
# 新品表现: 新品平均销量、评论数

Phase 3: Report generation

Generate complete report

# 一键生成所有报告格式
python .claude/skills/category-selection/scripts/workflow.py "Sofas" US 20

# 或分步骤生成
python .claude/skills/category-selection/scripts/generate_reports.py {data_json}

Output file structure:

category-reports/
└── {Category}_{Site}_{YYYYMMDD}/
    ├── report.md                      # Markdown 分析报告
    ├── data.json                      # 完整解码数据 (中文键)
    ├── top_products.json              # Top N 产品列表
    ├── scores.json                    # 五维评分结果
    ├── execution.log                  # 执行日志 (v4.0 新增)
    ├── keywords.json                  # 类目关键词
    ├── trend_data.json                # 25个月趋势数据
    ├── adapted_data.json              # Excel 适配数据 (英文键)
    ├── category_analysis_report.xlsx  # Excel 报告
    ├── dashboard.html                 # HTML 可视化仪表板
    ├── data/                          # 原始数据目录
    │   ├── statistics.csv             # 统计数据
    │   ├── products.csv               # 产品列表
    │   └── scores.csv                 # 评分详情
    └── *_raw.txt                      # 原始 SSE 响应

Data processing tools

Core tool scripts

Script	Purpose	Version
`workflow.py`	One-click execution of the complete analysis workflow	v4.0
`sse_decoder.py`	Decode category_report SSE response	v6.0
`keywords_parser.py`	Decode category_keywords response	v3.0
`trend_parser.py`	Parse trend data	v1.0
`data_adapter.py`	Data format conversion (Chinese→English keys)	v1.0
`data_utils.py`	Data processing utility class	v2.0
`generate_reports.py`	Unified report generator	v3.0
`generate_excel_report.py`	Excel report generation	v2.0
`generate_markdown_report.py`	Markdown report generation	v2.0
`fix_encoding.py`	Encoding repair tool	v1.0

Data field mapping

API response field → standardized field:

API field	Standardized field	Description
ASIN	asin	Product unique identifier
标题/title	title	Product title
价格/price	price	Current selling price
月销量/monthlySales	monthly_sales	Monthly sales volume
月销额/monthlyRevenue	monthly_revenue	Monthly sales revenue
评论数/reviews	review_count	Number of reviews
星级/rating	rating	Average rating
品牌/brand	brand	Brand name
Seller/seller	seller	Seller name
Listed time/daysOnline	days_online	Days online

HTML visual dashboard

Features

ECharts-based interactive charts
Five-dimension score visualization progress bars
KPI metric card display
7 dynamic charts: sales trend, price trend, price distribution, rating distribution, brand share, seller source, brand rating trend
Top50 product details table
Key findings intelligent analysis

Template variable support

Variable type	Example variable	Description
Basic information	`{{CATEGORY_NAME}}`, `{{SITE}}`, `{{DATA_DATE}}`	Report basic information
Five-dimension score	`{{MARKET_SIZE_SCORE}}`, `{{MARKET_SIZE_PERCENT}}`	Scores and progress bar percentages for each dimension
KPI metrics	`{{TOTAL_PRODUCTS}}`, `{{AVG_PRICE}}`, `{{CR3}}`	Key metric data
Chart data	`{{SALES_TREND_DATA}}`, `{{BRAND_SHARE_DATA}}`	JavaScript JSON data
Analysis conclusions	`{{CONCENTRATION_LEVEL}}`, `{{RECOMMENDATION}}`	Intelligent analysis text

Troubleshooting

Common issues and solutions (v4.0 update)

1. API Key not set

Issue: ❌ API Key 未设置 or Authentication required

Cause:

Environment variable SORFTIME_API_KEY not set
.mcp.json file does not exist or has incorrect format

Solution (fixed in v4.0):

workflow.py v4.0 will automatically read the API Key from .mcp.json Read API Key
Ensure the project root directory contains the .mcp.json file, with the following format:

{
  "mcpServers": {
    "sorftime": {
      "url": "https://mcp.sorftime.com?key=YOUR_API_KEY"
    }
  }
}

Manually set environment variable (alternative):

# Windows PowerShell
$env:SORFTIME_API_KEY="your_api_key"

# Linux/Mac
export SORFTIME_API_KEY="your_api_key"

2. JSON parsing failed - unescaped control characters

Issue: JSONDecodeError: Invalid control character at: line 1 column 3401

Cause: The JSON string values returned by the API contain raw control characters such as newlines (\n) and tabs (\t), and these control characters are not correctly escaped

Example:

// 错误格式（API 返回的原始格式）
{"标题": "类目：Renewed Laptops，排名:2
类目：Traditional Laptops，排名:11"}

// 正确格式
{"标题": "类目：Renewed Laptops，排名:2\\n类目：Traditional Laptops，排名:11"}

Solution (fixed in v4.0):

escape_control_chars_in_json_strings() The function automatically escapes control characters within string values
This function only handles control characters inside string values and does not affect the JSON structure

3. Category not found

Issue: Searching for a category returns "no corresponding category found"

Cause:

Broad categories (such as "Computers & Accessories") may only return a list of subcategories
Category name is inaccurate

Solution (improved in v4.0):

workflow.py v4.0 will automatically try multiple search variants
Use a more specific subcategory name
Recommended: Query directly using the category NodeID

How to get the NodeID:

# 先用大类目搜索，查看返回的子类目列表
curl -s -X POST "https://mcp.sorftime.com?key={API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"category_name_search","arguments":{"amzSite":"US","searchName":"Laptop"}}}'

4. Data parsing failed (Mojibake encoding issue)

Issue: Chinese in data.json displays as garbled text such as "Top100äº§å"

Cause: The API returns Unicode-escape format (\u4ea7\u54c1), which produces Mojibake after decoding

Solution (automatically fixed in v4.0):

fix_mojibake() The function automatically fixes encoding issues
Apply immediately after Unicode-escape decoding .encode('latin-1').decode('utf-8')

5. Python dict format issue

Problem: "Expecting property name enclosed in double quotes"

Cause: API returns Python dict format (single quotes), not standard JSON

Solution (fixed in v4.0):

python_dict_to_json() The function correctly handles single-quote conversion
Also handles True/False/None literals

6. Major category search failure

Problem: Major category searches such as "Computers & Accessories" return no results

Solution:

Use subcategory names (such as "Laptops", "Computer Accessories")
First search the major category to get the subcategory list, and let the user choose
Directly use a known NodeID

Version update history

Script	Version	Update details
`workflow.py`	v4.0	✅ Automatically read API Key from .mcp.json ✅ Fixed unescaped control characters in JSON strings ✅ Improved category search strategy ✅ Added execution logs ✅ More detailed error messages
`sse_decoder.py`	v6.0	Automatic Mojibake repair, bracket matching, Python dict conversion
`generate_reports.py`	v3.0	Complete variable substitution, analysis text generation

Debugging tips

View execution logs:

# workflow.py v4.0 会自动保存执行日志
cat category-reports/{Category}_{Site}_{YYYYMMDD}/execution.log

View raw response:

# workflow.py 会自动保存原始 SSE 响应
cat category-reports/{Category}_{Site}_{YYYYMMDD}/category_report_raw.txt

Check encoding issues:

# 检查文件字节
with open('data.json', 'rb') as f:
    print(f.read(100))

Validate JSON format:

# 使用 Python 验证 JSON
python -m json.tool data.json

Test API connection:

curl -s -X POST "https://mcp.sorftime.com?key={YOUR_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"category_name_search","arguments":{"amzSite":"US","searchName":"Kitchen"}}}'

Supported sites

Amazon: US, GB, DE, FR, IN, CA, JP, ES, IT, MX, AE, AU, BR, SA TikTok: US, GB, MY, PH, VN, ID 1688: China wholesale platform

Notes

API Key configuration:
- Recommended to configure in .mcp.json (automatically read in v4.0)
- You can also use the environment variable SORFTIME_API_KEY
Parameter name: Use amzSite instead of site
id increment: The id field of each request must increment (1, 2, 3...)
Concurrency limit: A maximum of 3-5 concurrent requests is recommended
Data freshness: Data may have a 1-7 day delay
Report naming: Use the {Category}_{Site}_{YYYYMMDD} format

Reference documentation

This Skill is maintained by Claude Code | Last updated: 2026-03-05 (v4.0)

About this skill

Quick Reference

One-Click Execution Workflow (Recommended)

Core API Tools

Call Format

Trigger Conditions

Role Setting

Five-Dimensional Scoring Model (Standard Version)

Complete analysis workflow

Phase 1: Data collection

Step 1: Search category to obtain nodeId

Step 2: Obtain category report (Top100 + statistics)

Step 3: Obtain Top N product details (concurrent)

Step 4: Obtain category keywords (optional)

Step 5: Obtain historical trend data (optional)

Phase 2: Data analysis

Core analysis metrics

Phase 3: Report generation

Generate complete report

Data processing tools

Core tool scripts

Data field mapping

HTML visual dashboard

Features

Template variable support

Troubleshooting

Common issues and solutions (v4.0 update)

1. API Key not set

2. JSON parsing failed - unescaped control characters

3. Category not found

4. Data parsing failed (Mojibake encoding issue)

5. Python dict format issue

6. Major category search failure

Version update history

Debugging tips

Supported sites

Notes

Reference documentation