Catalog Attribute Normalizer

カタログ属性ノーマライザー

分類体系に基づくカタログ属性ノーマライザー — 実際の Google Product Taxonomy に照らして検証済みのため、汎用 LLM が生成する、もっともらしくても誤ったカテゴリ ID を見つけられます。複数のソースにまたがる雑多なカタログ（タイトル、説明、画像）を入力すると、一貫性のある属性、単位、根拠のあるカテゴリマッピングを出力します。Shopify のエクスポート、仕入先の CSV、マーケットプレイスから取得したデータで、「サイズ」や「素材」の表記がそれぞれ異なる場合に、マーチャント運用チームやフィードツールの開発者に役立ちます。

できること

• 商品の生データ（title、description、raw_attributes）をまとめて受け取り、正規化された属性（標準化されたサイズ、色、単位）と、指定した分類体系（Google Product Taxonomy、Shopify、Amazon）のカテゴリマッピングを返します。
• MCP サーバー（normalize_catalog ツール）または通常の HTTPS API として動作します。

例（MCP ツールの呼び出し）

{
  "tool": "normalize_catalog",
  "input": {
    "products": [{ "title": "...", "description": "...", "raw_attributes": { "size": "Lrg", "Color": "Navy Blue" } }],
    "target_taxonomies": ["google", "shopify"]
  }
}

{
  "results": [
    {
      "schema_version": "2.0",
      "source_title": "...",
      "category_paths": {
        "google": { "path": ["Apparel & Accessories", "Clothing", "Shirts & Tops"], "leaf_id": null, "confidence": 0.9 },
        "shopify": { "path": ["Apparel & Accessories", "Clothing", "Tops"], "leaf_id": "aa-3-1", "confidence": 0.85 }
      },
      "attributes": {
        "size": { "value": "L", "provenance": "canonicalized" },
        "color": { "value": "navy", "provenance": "canonicalized" }
      }
    }
  ]
}

attributes は統制語彙（size、color、material、gender、sleeve_length）をキーとして使用します（認識されないキーは削除され、モデルが選んだ名前のまま引き継がれることはありません）。各値の provenance は、その商品について入力した raw_attributes に由来する場合は "canonicalized"（決定的なクリーンアップのみで、再現ではありません）、モデルがタイトルや説明から推定し、入力には含まれていなかった場合は "extracted" になります。"extracted" の値は、信頼度の低い category_paths エントリと同様に、提案として扱ってください。

属性は構造上、信頼できます — 入力にすでに含まれている値を正規化するものであり、再現ではありません。 カテゴリ分類は検索結果を根拠としています。記憶からの再現ではありません。実際の最新の Google および Shopify の分類体系ファイルから候補を取得し、提案としてモデルに提示するため、leaf_id はほぼ常に実在するノードを指します。Google と Shopify の両方の分類体系に照らして各商品を確認した、12 商品の評価セットでは、24 件中 22 件のチェック（91.7％）で、パスとリーフ ID が完全一致しました。それでも、confidence と null の leaf_id は、保証ではなく「手短に確認する価値がある」ものとして扱ってください。leaf_id が返されるのは、パスが実際の分類体系ファイルに照らして個別に検証された場合に限られるため、null は正直な「確認してください」という合図であり、捏造された ID ではありません。Amazon には候補取得に使える包括的な公開分類体系の参照ファイルがないため、検索結果を根拠とせず、ベストエフォート（記憶からの再現）となります。

料金

現在、無料プランはセルフサービスで利用できます。有料プランは近日提供開始予定です。

• 無料 — 月 500 商品まで。カード登録不要。現在セルフサービスで利用できます。
• 従量課金（近日提供開始）— 商品 1 件あたり $0.01、最低利用料金なし。
• Pro（近日提供開始）— 月額 $29 で 5,000 商品（実質、商品 1 件あたり約 $0.0058）。

今すぐ有料プランをご希望ですか？ ご利用のご意向をお知らせください。優先してご案内します。

1 単位の数え方： 1 回の呼び出しではなく、商品 1 件が 1 単位です。40 商品を含む normalize_catalog の呼び出しでは、月間利用枠を 40 件分使用します。バッチ処理は利便性のためであり、割引にはなりません。バッチは全件成功か全件失敗です。残りの利用枠を超える大きさの場合、呼び出し全体が 402 で拒否され（本文には required と remaining が記載されます）、分類は一切行われません。そのため、完成したように見える部分的な結果に料金が発生することはありません。呼び出しが完全に失敗した場合、料金はかかりません。

キーの取得

MCP サーバーは https://catalog-normalizer.acjlabs.com/mcp で稼働しています（別のアドレス https://acjlabs-catalog-normalizer.acjlabs.workers.dev/mcp も同じデプロイ先に接続し、 引き続き利用できるため、既存の設定を変更する必要はありません）。無料プランのキーは セルフサービスで取得できます。POST /v1/signup に { "email": "[email protected]" } を送信すると、 キーがレスポンスに直接返されます。月500件の商品に利用でき、カードは不要です。キーはすぐに保存してください。一度だけ表示され、紛失すると復元できません（新しいキーを取得するには再登録してください）。同じ手順に加え、料金と 他のサービスとの比較については https://acjlabs-catalog.pages.dev をご覧ください。Pro／従量課金制の請求が開始された後、有料キーも同様に、 一度限りの申請リンクを通じて発行されます。

MCP クライアントへの接続

Claude Code の場合：

claude mcp add --transport http catalog-normalizer \
  https://catalog-normalizer.acjlabs.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

カスタムヘッダーに対応したリモート HTTP サーバーをサポートする他の MCP クライアント（Cursor、Cline、VS Code など）も同様に利用できます。上記の URL を指定し、Authorization: Bearer YOUR_API_KEY ヘッダーを設定してください。キーの値をそのまま（Bearer プレフィックスなしで）転送するゲートウェイやスキャナーも利用できます。 どちらの形式でも認証されます。ツールの検出（initialize／tools/list）にキーは不要です。必要なのは normalize_catalog の呼び出し時だけです。

手順をひとつずつ進めたい場合は、docs/quickstart.md で、キーの取得、クライアントごとの 設定、curl による接続確認までを網羅した手順をご覧ください。

npm クライアント

MCP の JSON-RPC 呼び出しを自分で実装するのではなく、型付き関数を使いたいですか？ npm で公開中の @acjlabs/catalog-attribute-normalizer-client は、normalize_catalog ツールの呼び出しをラップします。

npm install @acjlabs/catalog-attribute-normalizer-client

import { createCatalogNormalizerClient } from "@acjlabs/catalog-attribute-normalizer-client";

const client = createCatalogNormalizerClient({
  baseUrl: "https://catalog-normalizer.acjlabs.com",
  apiKey: "...",
});
const results = await client.normalizeCatalog(products, ["google", "shopify"]);

カテゴリー分類器だけでは不十分な理由

カテゴリー分類 API で分かるのは、商品が「何であるか」です。しかし、情報源ごとに異なる表記を 統一するという、より複雑な問題である「属性」の標準化には対応しません。この幅広い課題に取り組むベンダーは、 エンタープライズ向けの営業が中心です。デモの申し込み、年間契約、セルフサービスの登録なし、公開価格なしとなっています。比較の全容をご覧いただくか、 「商品データのクリーンアップ」が実際には2つの異なる問題である理由 （正規化と分類の違い、それぞれの失敗の仕方）をご覧ください。

ソースの提供状況とサポート

このリポジトリでは、ホスト型サービスのドキュメントを公開しています。サービスの実装はオープンソースではありません。バグ報告や機能リクエストは、このリポジトリの Issues で歓迎しています。また、[email protected] までご連絡いただくこともできます。