catalog-cli-pro

目录 CLI

适用于 Agent 的 Amazon 目录审核工具

首款适用于 AI Agent 的 Amazon 目录分析工具。使用结构化输入查询你的 CLR，通过 MCP 服务集成，并自动执行目录审核。

可使用托管 API：api.catalogcli.com——持久化存储、无限扫描和 API 访问权限，每月 $9.99。了解详情

v2.3 新增内容

• Seller Central AJAX 查询 - 使用 catalog listing fetch <asin> 获取 Amazon Seller Central 实时商品信息 JSON
• 实时商品信息与 CLR 差异对比 - 使用 catalog listing diff <asin> <clr-file> 将 Amazon 当前商品信息字段与 Category Listing Report 进行比较
• 适用于 Agent 的 Seller Central 工具 - 新增 MCP 工具 catalog_seller_listing_fetch 和 catalog_seller_listing_diff
• 本地 Cookie 身份验证 - 使用 --cookie、--cookie-file 或 CATALOG_SELLER_CENTRAL_COOKIE；Seller Central Cookie 保留在本地

v2.2 标题就绪度

• Amazon 标题就绪度 - mobile-title-readiness 会标记超过 75 个字符的标题，以适配 Amazon 的移动端标题更新
• 可直接用于改写的输出 - 返回前 75 个字符的标题片段、溢出文本、重要词项、商品亮点状态和建议的后续操作
• 适合 Agent 工作流 - 别名 title-75 和 amazon-title-75 便于从 Claude、MCP 客户端和自动化工作流中调用
• 内置 14 项检查 - 新增标题分诊工作流，同时保留经典的 200 字符 long-titles 检查，不作更改

v2.0 Agent 基础功能

• 共享核心架构 - 将业务逻辑拆分到 catalog/core/，同时为 CLI 和 MCP 提供支持
• MCP 服务 - catalog mcp 可启动包含 4 个工具的 stdio MCP 服务，可用于 Claude Desktop 和任何 MCP 客户端
• JSON 输入 - 提供 --json 和 --stdin 标志，用于结构化 Agent 输入
• Schema 自省 - catalog schema --format json 返回完整的请求和响应 Schema
• 字段掩码 - 使用 --fields sku,severity,details 减少输出大小
• 分页 - 使用 --limit 和 --offset 控制结果大小
• NDJSON 流式传输 - 使用 --format ndjson 逐行流式传输大型结果
• 输入强化 - Pydantic 验证会拒绝路径遍历、注入和格式错误的输入
• 环境变量 - 使用 CATALOG_CLI_DEFAULT_FORMAT=json 适用于无头/CI 场景
• 向后兼容 - 所有 v1.x 命令均可照常使用

功能

• 原生支持 Agent - CLI 和 MCP 服务同等重要，支持 JSON/NDJSON 输出和 Schema 自省
• 快速 - 数秒内即可查询包含 1000+ SKU 的目录
• 可扩展 - 提供自定义查询插件系统
• 全面 - 内置 14 项目录健康检查
• 针对意图优化 - 为要点提供受 COSMO 启发的购物者意图覆盖

安装

pip install amazon-catalog-cli

也可以从源代码安装：

git clone https://github.com/BWB03/amazon-catalog-cli.git
cd amazon-catalog-cli
pip install -e .

快速入门

面向用户

# Run all catalog checks
catalog scan my-catalog.xlsx

# Detailed results
catalog scan my-catalog.xlsx --show-details

# Run specific check
catalog check intent-bullets my-catalog.xlsx

# Audit titles for Amazon's 75-character mobile title update
catalog check mobile-title-readiness my-catalog.xlsx

# List available queries
catalog list-queries

面向 AI Agent

# JSON output with field mask and limit
catalog scan my-catalog.xlsx --format json --fields sku,severity,details --limit 20

# Title rewrite triage for agents
catalog check mobile-title-readiness my-catalog.xlsx --format json \
  --fields sku,details,title_char_count,mobile_visible_title,overflow_title,all_significant_terms

# Structured JSON input
catalog scan --json '{"file": "my-catalog.xlsx", "queries": ["missing-attributes"], "limit": 10}'

# Piped input
echo '{"file": "my-catalog.xlsx"}' | catalog scan --stdin --format json

# NDJSON streaming for large results
catalog scan my-catalog.xlsx --format ndjson

# Schema introspection (discover queries, params, response shapes)
catalog schema --format json

# Fetch live Seller Central listing JSON for an ASIN
CATALOG_SELLER_CENTRAL_COOKIE='session-id=...' catalog listing fetch B000TEST01 --format json

# Compare live Seller Central JSON with a CLR row
catalog listing diff B000TEST01 my-catalog.xlsx --sku SKU-123 --format json

MCP 服务（适用于 Claude Desktop、CLR Pro 等）

# Start MCP server
catalog mcp

添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "catalog": {
      "command": "catalog",
      "args": ["mcp"]
    }
  }
}

MCP 工具：catalog_scan、catalog_scan_summary、catalog_check、catalog_seller_listing_fetch、catalog_seller_listing_diff、catalog_list_queries、catalog_schema

可用查询

属性审核

• missing-attributes - 查找商品信息中缺失的必填属性
• missing-any-attributes - 查找所有缺失的属性（必填属性和条件属性）
• new-attributes - 查找可能有助益但尚未使用的模板字段

内容质量

• intent-bullets - 根据购物者意图覆盖情况为要点打分
• bullet-prohibited-content - 查找包含违禁字符、表情符号、声明或占位符的要点
• bullet-formatting - 检查要点格式（大小写、长度、标点）
• bullet-awareness - 检查要点中的轻微违规（过多大写字母、有问题的字符）
• mobile-title-readiness - 查找超过 75 个字符的标题，并准备改写输入内容
• long-titles - 查找超过 200 个字符的标题
• title-prohibited-chars - 查找包含违禁字符的标题
• prohibited-chars - 查找标题/品牌中的违禁字符

目录结构

• product-type-mismatch - 查找不匹配的商品类型和商品关键词
• missing-variations - 查找应设为变体、但尚未设置为变体的商品

CLI 命令

catalog scan

对 CLR 文件运行所有查询。

catalog scan <clr-file> [OPTIONS]

Options:
  --format [terminal|json|csv|ndjson]  Output format (default: terminal)
  --output PATH                        Output file path
  --show-details / --no-details        Show detailed results
  --include-fbm-duplicates             Legacy: include repeated exact-SKU rows
  --json TEXT                          JSON request body
  --stdin                              Read JSON request from stdin
  --queries TEXT                       Comma-separated query names
  --fields TEXT                        Comma-separated field mask
  --limit INTEGER                      Max issues to return
  --offset INTEGER                     Skip first N issues

catalog check

运行指定查询。

catalog check <query-name> <clr-file> [OPTIONS]

Options:
  --format [terminal|json|csv|ndjson]  Output format (default: terminal)
  --output PATH                        Output file path
  --show-details / --no-details        Show detailed results
  --json TEXT                          JSON request body
  --stdin                              Read JSON request from stdin
  --fields TEXT                        Comma-separated field mask
  --limit INTEGER                      Max issues to return
  --offset INTEGER                     Skip first N issues

catalog listing fetch

获取 Amazon Seller Central 中该 ASIN 对应的实时商品信息 JSON。

需要使用您自己的浏览器会话中已登录 Seller Central 的 Cookie。通过 --cookie、--cookie-file 或 CATALOG_SELLER_CENTRAL_COOKIE 环境变量传入。

catalog listing fetch <asin> [OPTIONS]

Options:
  --format [terminal|json]  Output format (default: terminal)
  --output PATH             Output file path
  --cookie TEXT             Seller Central Cookie header value
  --cookie-file PATH        File containing the Cookie header value
  --timeout FLOAT           HTTP timeout in seconds
  --json TEXT               JSON request body
  --stdin                   Read JSON request from stdin

catalog listing diff

将 Amazon Seller Central 中的实时商品信息 JSON 与匹配的 CLR 行进行比较。

如果提供了 --sku，则按其匹配行。否则，Catalog CLI 会在 CLR 中查找 Product Id Type = ASIN 和 Product Id = <asin>。

catalog listing diff <asin> <clr-file> [OPTIONS]

Options:
  --sku TEXT                Optional SKU to match in the CLR
  --format [terminal|json]  Output format (default: terminal)
  --output PATH             Output file path
  --cookie TEXT             Seller Central Cookie header value
  --cookie-file PATH        File containing the Cookie header value
  --timeout FLOAT           HTTP timeout in seconds
  --json TEXT               JSON request body
  --stdin                   Read JSON request from stdin

catalog schema

显示查询、参数和响应结构的架构。

catalog schema [query-name] [OPTIONS]

Options:
  --format [terminal|json]  Output format

catalog list-queries

列出可用查询。

catalog list-queries [OPTIONS]

Options:
  --format [terminal|json]  Output format

catalog mcp

启动 MCP 服务（stdio 传输）。

catalog mcp

catalog setup-claude

配置 Claude Code，将 Catalog CLI 用作 MCP 工具服务。

# Free (local) — data stays on your machine
catalog setup-claude

# Pro (hosted API) — persistent storage, unlimited scans
catalog setup-claude --pro --api-key YOUR_KEY

# Per-project instead of global
catalog setup-claude --project

完成设置后，重启 Claude Code 并尝试输入："扫描 my-catalog.xlsx，并告诉我最大的问题是什么"

JSON 输出示例

{
  "timestamp": "2026-03-05T10:30:00Z",
  "marketplace": "US",
  "is_us_marketplace": true,
  "total_queries": 14,
  "total_issues": 47,
  "total_affected_skus": 23,
  "results": [
    {
      "query_name": "missing-attributes",
      "description": "Find mandatory attributes missing from listings",
      "total_issues": 12,
      "affected_skus": 8,
      "issues": [
        {
          "row": 7,
          "sku": "ABC-123",
          "field": "brand",
          "severity": "required",
          "details": "Missing required field: brand",
          "product_type": "HAIR_STYLING_AGENT",
          "extra": {}
        }
      ]
    }
  ]
}

Agent 集成

通过 CLI（子进程）

import subprocess, json

result = subprocess.run(
    ['catalog', 'scan', 'my-catalog.xlsx', '--format', 'json',
     '--fields', 'sku,severity,details', '--limit', '20'],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

通过 Python（直接导入）

from catalog.core import execute_scan, ScanRequest

request = ScanRequest(
    file="my-catalog.xlsx",
    queries=["missing-attributes", "intent-bullets"],
    fields=["sku", "severity", "details"],
    limit=20,
)
response = execute_scan(request)

将 MCP 服务添加到任意 MCP 客户端（Claude Desktop、CLR Pro 等），然后调用 catalog_scan、catalog_check、catalog_seller_listing_fetch、catalog_seller_listing_diff、catalog_list_queries 或 catalog_schema。

基于意图的要点优化

intent-bullets 查询会根据受 COSMO 启发的购物者意图覆盖情况评估要点：

• 受众/需求匹配：适用对象、偏好或问题状态
• 功能/使用场景：任务、活动、事件或使用流程
• 情境/兼容性：适用地点、时间或搭配对象
• 决策依据：规格、属性、可信度信号或差异化特点
• 所有要点：检查意图覆盖情况、长度、含糊的营销用语和全大写内容

评分为 1–5 分，并提供可执行的建议。旧查询名称 rufus-bullets 仍可作为已弃用的兼容别名使用。

使用自定义查询进行扩展

from catalog.query_engine import QueryPlugin

class MyCustomQuery(QueryPlugin):
    name = "my-custom-check"
    description = "My custom catalog check"

    def execute(self, listings, clr_parser):
        issues = []
        for listing in listings:
            if some_condition:
                issues.append({
                    'row': listing.row_number,
                    'sku': listing.sku,
                    'field': 'FieldName',
                    'severity': 'warning',
                    'details': 'Issue description',
                    'product_type': listing.product_type
                })
        return issues

要求

• Python 3.10+
• openpyxl
• click
• rich
• pydantic
• mcp

如何获取 CLR

1. 前往 Amazon Seller Central > Catalog > Category Listing Report
2. 点击 Generate Report
3. 下载 .xlsm 或 .xlsx 文件
4. 对文件运行 catalog CLI

免费版与专业版

	开源 CLI	免费 API	Pro API（$9.99/月）
14 项质量审查	是	是	是
扫描次数	无限次（本地）	终身 2 次	无限次
存储的目录	—	1 个	无限个
结果保留时间	—	7 天	永久
API 访问	—	是	是
速率限制	—	10 次请求/分钟	100 次请求/分钟
Claude Code 集成	本地 MCP	—	托管 MCP
变体创建工具	—	—	即将推出

在 catalogcli.com 开始使用 | API 文档

参与贡献

这是一个开源项目，欢迎贡献！

• 添加新的查询插件
• 改进解析逻辑
• 丰富输出格式
• 构建集成

许可证

MIT 许可证 - 可免费使用、修改和分发。

作者

由 Brett Bohannon（@BWB03）构建。

相关项目

• amazon-catalog-auditor-skill - 面向 Agent 工作流的 OpenClaw 技能
• clr-auditor - 原版 CLR 审核工具
• amazon-tool - Amazon 变体创建工具

---

原生支持 Agent 的 Amazon 商品目录工具。 为商品目录管理的未来而构建。