Catalog Attribute Normalizer

商品目录属性规范化器

以分类体系为依据的商品目录属性规范化器——经真实的 Google Product Taxonomy 验证，因此能识别通用大模型臆造的看似合理却错误的类别 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 为 "canonicalized" 时，表示该值来自你为该商品提供的 raw_attributes 输入（仅执行确定性清理，不进行回忆推断）；为 "extracted" 时，表示模型根据标题或描述推断出该值，且该值不在你的输入中——应将 "extracted" 值视为建议，与低置信度的 category_paths 条目一样谨慎对待。

属性从设计上就可靠——规范化输入中已有的值，而非回忆推断。类别分类以检索结果为依据，而非从记忆中回忆：系统会从真实、最新的 Google 和 Shopify 分类体系文件中检索候选项，并将其作为建议提供给模型，因此 leaf_id 几乎总是对应一个实际存在的节点——在包含 12 件商品的评估集中，每件商品均针对 Google 和 Shopify 分类体系进行核验：24 次核验中有 22 次（91.7%）路径和叶节点 ID 完全匹配。但仍应将 confidence 和值为 null 的 leaf_id 视为“值得快速检查”，而非保证——只有当路径经真实分类体系文件独立验证后，才会返回 leaf_id，因此此处的 null 是诚实的“请检查”信号，绝非捏造的 ID。Amazon 没有可用于检索候选项的完整公开分类体系参考文件，因此仍是尽力而为（从记忆中回忆），而非以检索结果为依据。

定价

目前可自行注册使用免费套餐；付费方案即将开放。

• 免费版 — 每月 500 件商品，无需信用卡。目前可自行注册使用。
• 按量付费 (即将开放) — 每件商品 $0.01，无最低消费。
• Pro (即将开放) — 每月 $29，含 5,000 件商品（折合每件约 $0.0058）。

现在就想使用付费方案？ 登记意向，我们会优先为你开通。

**计费单位说明：**按商品计数，不按调用次数计数。一次 normalize_catalog 调用若包含 40 件商品，就会使用每月配额中的 40 件；批量处理只是为了方便，并不打折。批次采用全有或全无的方式——如果批次数量超过剩余配额，整个调用都会被拒绝并返回 402（响应正文会列出 required 和 remaining），不会对任何商品进行分类，因此你绝不会为看似完整的部分结果付费。完全失败的调用不收费。

获取密钥

MCP 服务已在 https://catalog-normalizer.acjlabs.com/mcp 上线（备用地址 https://acjlabs-catalog-normalizer.acjlabs.workers.dev/mcp 指向同一部署，且仍可正常使用，因此现有配置无需更改）。免费套餐密钥可自行申请——向 /v1/signup 发送 POST 请求，并附上 { "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 调用？ @acjlabs/catalog-attribute-normalizer-client （已在 npm 上线）封装了 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 会告诉你产品是什么，但不会解决更棘手的问题：统一不同来源中写法各异的属性。真正处理这一更广泛问题的供应商通常采用企业销售模式——需要申请演示、签订年度合同，既不能自行注册，也没有公开定价。请参阅完整对比，或阅读为什么“清理产品数据”实际上是两个不同的问题（规范化与分类，以及二者为何会以不同方式失败）。

源代码可用性与支持

本仓库托管的是该托管服务的文档。服务实现不开源。欢迎在本仓库的 Issues 中提交 Bug 报告和功能请求；也可以通过 [email protected] 联系我们。