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 reads from .mcp.json read
✅ Fix control characters: Automatically handles unescaped newlines 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 for a single product	Small
4. Category keywords	`category_keywords`	Get core keywords for the category	Large (>25KB)
5. Category trends	`category_trend`	Get 25 months of 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

Start this analysis workflow 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 insights into market opportunities, competitive landscape, and barriers to entry, offering users actionable product selection recommendations.

Five-Dimension Scoring Model (Standard Version)

Detailed Scoring Criteria:

Dimension	Score	Scoring Criteria	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 products with low reviews >40%=22 points, >20%=18 points, others=14 points	Proportion of products with review count <100
Competition Intensity	20 points	Top3 brand share <30%=18 points, <50%=14 points, others=8 points	CR3 brand concentration
Barriers to Entry	20 points	Amazon share <20% and new products >40%=20 points, other combinations 6-18 points	Amazon private-label 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 categories 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：

Broad categories (such as "Clothing, Shoes & Jewelry") usually only return a list of subcategories
Display them to the user so they can choose 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 fields → standardized fields:

API field	Standardized field	Description
ASIN	asin	Unique product identifier
Title/title	title	Product title
Price/price	price	Current selling price
Monthly sales/monthlySales	monthly_sales	Monthly sales
Monthly revenue/monthlyRevenue	monthly_revenue	Monthly sales amount
Review count/reviews	review_count	Number of reviews
Star rating/rating	rating	Average rating
Brand/brand	brand	Brand name
Seller/seller	seller	Seller name
Listing time/daysOnline	days_online	Days listed

HTML visualization dashboard

Features

Interactive charts based on ECharts
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 detailed table
Intelligent analysis of key findings

Template variable support

Variable type	Example variable	Description
Basic information	`{{CATEGORY_NAME}}`, `{{SITE}}`, `{{DATA_DATE}}`	Basic report information
Five-dimension score	`{{MARKET_SIZE_SCORE}}`, `{{MARKET_SIZE_PERCENT}}`	Score for each dimension and progress bar percentage
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 an invalid format

Solution (fixed in v4.0):

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

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

Manually set environment variables (fallback):

# Windows PowerShell
$env:SORFTIME_API_KEY="your_api_key"

# Linux/Mac
export SORFTIME_API_KEY="your_api_key"

2. JSON parsing failure - 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 newline characters (\n) and tab characters (\t), and these control characters were not properly 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: When searching for a category, "no corresponding category found" is returned

Cause:

Broad categories (such as "Computers & Accessories") may return only a list of subcategories
The 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 obtain 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 failure (Mojibake encoding issue)

Issue: Chinese text in data.json is displayed as garbled characters 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 the encoding issue
Immediately after Unicode-escape decoding, apply .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: Searches for major categories 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
Use known NodeIDs directly

Version update history

Script	Version	Update content
`workflow.py`	v4.0	✅ Automatically read the API Key from .mcp.json ✅ Fix unescaped control characters in JSON strings ✅ Improve category search strategy ✅ Add execution logs ✅ More detailed error messages
`sse_decoder.py`	v6.0	Mojibake auto-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))

Verify 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 timeliness: Data may be delayed by 1-7 days
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-Dimension Scoring Model (Standard Version)

Complete analysis workflow

Phase 1: Data collection

Step 1: Search categories 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 visualization dashboard

Features

Template variable support

Troubleshooting

Common issues and solutions (v4.0 update)

1. API Key not set

2. JSON parsing failure - unescaped control characters

3. Category not found

4. Data parsing failure (Mojibake encoding issue)

5. Python dict format issue

6. Major category search failure

Version update history

Debugging tips

Supported sites

Notes

Reference documentation