catalog-cli-pro

Catalog CLI

エージェントネイティブなAmazonカタログ監査ツール

初のAIエージェント向けAmazonカタログ分析ツールです。構造化入力でCLRをクエリし、MCP サーバー経由で統合して、カタログ監査を自動化できます。

api.catalogcli.comでホステッドAPIを利用できます。永続ストレージ、無制限のスキャン、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を比較します
• エージェント対応の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は、Amazonのモバイルタイトル更新に向けて、75文字を超えるタイトルにフラグを付けます
• 書き換えに適した出力 - 先頭75文字のタイトル部分、超過テキスト、重要な用語、商品ハイライトの状態、推奨される次のアクションを返します
• エージェントのワークフローに最適 - エイリアスtitle-75とamazon-title-75により、Claude、MCPクライアント、自動化ワークフローから簡単に呼び出せます
• 14種類の組み込みチェック - 従来の200文字を対象とするlong-titlesチェックは変更せずに、タイトルのトリアージワークフローを追加します

v2.0 エージェント基盤

• 共有コアアーキテクチャ - ビジネスロジックをcatalog/core/に分離し、CLIとMCPの両方で使用します
• MCP サーバー - catalog mcpで4つのツールを備えたstdio MCP サーバーを起動します。Claude DesktopやあらゆるMCPクライアントですぐに利用できます
• JSON入力 - 構造化されたエージェント入力用の--jsonフラグと--stdinフラグ
• スキーマのイントロスペクション - catalog schema --format jsonでリクエスト／レスポンスの完全なスキーマを返します
• フィールドマスク - --fields sku,severity,detailsで出力サイズを削減します
• ページネーション - --limitと--offsetで結果サイズを制御します
• NDJSONストリーミング - 大きな結果を1行ずつストリーミングするための--format ndjson
• 入力の堅牢化 - Pydanticによる検証で、パストラバーサル、インジェクション、不正な形式の入力を拒否します
• 環境変数 - ヘッドレス／CI環境で使用するCATALOG_CLI_DEFAULT_FORMAT=json
• 後方互換性 - v1.xのすべてのコマンドは変更なしで動作します

機能

• エージェントネイティブ - CLIとMCP サーバーを同等にサポートし、JSON／NDJSON出力とスキーマのイントロスペクションを提供します
• 高速 - 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エージェント向け

# 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 の最新の出品情報 JSON を ASIN で取得します。

ご自身のブラウザーセッションから取得した、ログイン済みの 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 が指定されている場合は、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

Catalog CLI を MCP ツールサーバーとして使うように Claude Code を設定します。

# 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": {}
        }
      ]
    }
  ]
}

エージェントとの連携

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 サーバーを任意の 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 > カタログ > カテゴリー出品レポート に移動します
2. レポートを生成 をクリックします
3. .xlsm または .xlsx ファイルをダウンロードします
4. そのファイルに対して catalog CLI を実行します

無料版と Pro 版

	オープンソース CLI	無料 API	Pro API（$9.99/月）
14 の品質監査	はい	はい	はい
スキャン	無制限（ローカル）	生涯 2 回	無制限
保存されるカタログ数	—	1	無制限
結果の保存期間	—	7 日間	永続
API アクセス	—	はい	はい
レート制限	—	10 req/min	100 req/min
Claude Code との連携	ローカル MCP	—	ホスト型 MCP
バリエーション作成ツール	—	—	近日公開

catalogcli.com で利用を開始 | API ドキュメント

コントリビューション

これはオープンソースプロジェクトです。コントリビューションを歓迎します！

• 新しいクエリプラグインの追加
• 解析ロジックの改善
• 出力形式の拡充
• 連携機能の構築

ライセンス

MIT License - 自由に使用、変更、配布できます。

作者

Brett Bohannon が作成（@BWB03）

関連プロジェクト

• amazon-catalog-auditor-skill - エージェントのワークフロー向け OpenClaw スキル
• clr-auditor - 元となった CLR 監査ツール
• amazon-tool - Amazon のバリエーション作成ツール

---

エージェントネイティブな Amazon カタログツールです。 カタログ管理の未来に向けて構築されています。