catalog-mcp

一个 MCP 服务器，可将任何 JSON 目录转化为 AI 代理的查询工具。

指向一个目录 URL 或文件——库存清单、产品列表、feedmerge 发布的 catalog.json——任何 MCP 客户端（Claude Desktop、Claude Code，任何支持该协议的工具）都能获得对记录的结构化过滤、分组、排序和模式发现功能。

需要 Node 18+。两个运行时依赖：MCP SDK 和 zod。

为什么

代理不擅长处理大型 JSON 文件，但擅长使用工具。将一个 2 MB 的目录交给代理，它会截断、略读或编造记录；交给它带过滤语法的 catalog_query，它每次都能正确回答“具有这两个功能且价格低于 3 万美元的最便宜记录”，只读取匹配的记录。

这个仓库是我在生产环境中运行的 MCP 服务器的通用版本：一个销售楼层 AI 助手每天通过这些工具（相同的过滤语义、相同的空价格规则、相同的 TTL 缓存）查询实时库存目录数百次。它所属的流水线是：

vendor feed  ->  feedmerge  ->  catalog.json  ->  catalog-mcp  ->  any agent
             (guarded sync)   (versioned)      (query tools)

我针对自己的公开库存清单运行此工具；下面的示例使用一个中性目录，以便该仓库独立运行。

快速开始

git clone https://github.com/stevyf93II/catalog-mcp.git
cd catalog-mcp
npm install
npm test                                          # engine, loader, and stdio end-to-end tests

# serve the example catalog
node src/server.js --file examples/telescopes.json --key sku

将其接入 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "my-catalog": {
      "command": "node",
      "args": ["/path/to/catalog-mcp/src/server.js"],
      "env": {
        "CATALOG_URL": "https://example.com/catalog.json",
        "CATALOG_KEY": "sku"
      }
    }
  }
}

然后向代理提问，例如“目录中有哪些类型，每种类型的低价是多少？”，观察它自行组合 catalog_schema、catalog_count_by 和 catalog_top。

工具

所有工具均为只读且幂等，并在其 MCP 注释中声明。

过滤语法

一个小的规范，由 query、count_by 和 top 使用：

{
  "eq":       { "type": "reflector", "goto": true },
  "min":      { "aperture_mm": 150 },
  "max":      { "price": 1000 },
  "has":      { "features": ["Parabolic Mirror", "Cooling Fan"] },
  "contains": { "name": "dobsonian" }
}

• eq —— 对任何值（包括布尔值和 null）进行严格相等比较。

• min / max —— 数值边界。在边界字段中没有实数的记录将被排除。此规则至关重要：在生产目录中，缺失价格意味着“询价”，而“显示 3 万美元以下的单位”绝不能显示价格未知的单位。

• has —— 数组成员；列出的每个值都必须存在。

• contains —— 对字符串字段进行不区分大小写的子串搜索；字段 "*" 搜索记录中的每个字符串字段。

条件之间是 AND 关系。未知的顶级键会报错并列出有效键，因为静默忽略的过滤器会导致代理自信地报告错误答案。

排序会将缺少排序字段的记录推到最后，无论升序还是降序——“按价格排序”会先显示有价格的记录，而不是一堆空值。

配置

当未设置 CATALOG_RECORDS_PATH 时，加载器会使用文档根（如果它是数组），或者使用唯一的顶级对象数组（如果恰好有一个）（{ "meta": ..., "items": [...] } 即可工作）。如果文档不明确，它会拒绝并列出候选键。

刷新失败时，服务器会提供最后的好数据而不是报错——代理在任务进行中，使用五分钟前的记录比抛出异常要好——而 catalog_stats 会报告缓存年龄，因此过时性永远不会被隐藏。

非目标

• 不是数据库。目录是只读的，驻留在内存中；如果您的数据无法舒适地放入 JSON 文件，您需要一个真正的存储。

• 不支持写入。这里没有任何内容会修改目录——那是同步流水线的工作（参见 feedmerge）。

• 没有查询语言。五个过滤键覆盖了代理实际会问的内容；更复杂的功能应放在代码中，而不是工具模式中。

许可证

MIT