catalog-mcp

あらゆるJSONカタログをAIエージェント向けのクエリツールに変えるMCPサーバー。

カタログのURLまたはファイルを指定するだけで（在庫フィード、商品リスト、feedmergeが公開するcatalog.jsonなど）、あらゆるMCPクライアント（Claude Desktop、Claude Code、プロトコルに対応したもの）が、レコードに対して構造化フィルタリング、グループ化、ランキング、スキーマ発見を行えるようになります。

Node 18以上。実行時の依存関係は2つ：MCP SDKとzod。

なぜ必要か

エージェントは大きなJSONファイルを扱うのが苦手で、ツールを使うのが得意です。エージェントに2MBのカタログを渡すと、レコードを切り詰めたり、スキミングしたり、幻覚を起こしたりします。しかし、フィルター文法を備えたcatalog_queryを渡せば、「$30,000未満でこれら2つの特徴を持つ最も安いレコード」という質問に、毎回正しく、条件に合うレコードだけを読んで答えます。

このリポジトリは、私が本番環境で稼働させているMCPサーバーの一般化版です。ある販売フロアのAIアシスタントが、まさにこれらのツール（同じフィルターセマンティクス、同じnull価格ルール、同じTTLキャッシュ）を使って、1日に何百回もライブの在庫カタログをクエリしています。そのパイプラインは以下の通りです：

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で使われる、1つの小さな仕様：

{
  "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 — 数値の範囲。対象フィールドに実数がないレコードは除外されます。このルールは重要です。本番カタログでは、価格がないことは「価格はお問い合わせください」を意味し、「$30,000未満のユニットを表示」というクエリは、価格が不明なユニットを決して表面化してはいけません。

• has — 配列のメンバーシップ。リストされた値がすべて存在しなければなりません。

• contains — 文字列フィールドに対する大文字小文字を区別しない部分文字列検索。フィールド"*"はレコード内のすべての文字列フィールドを検索します。

条件はANDで結合されます。未知のトップレベルキーは、有効なキーを列挙するエラーになります。なぜなら、フィルターが黙って無視されると、エージェントが自信満々に間違った答えを報告するからです。

並べ替えは、ソートフィールドがないレコードを両方向で末尾に追いやります。「価格順に並べる」と、価格のあるレコードが最初に表示され、nullの壁が表示されることはありません。

設定

CATALOG_RECORDS_PATHが設定されていない場合、ローダーはドキュメントルートが配列であればそれを使用し、そうでなければオブジェクトのトップレベル配列が1つだけあればそれを使用します（{ "meta": ..., "items": [...] }はそのまま動作します）。ドキュメントが曖昧な場合は拒否し、候補となるキーを列挙します。

リフレッシュに失敗した場合、サーバーはエラーにする代わりに最後に正常に読み込んだデータを提供します。タスク中のエージェントは、例外よりも5分前のレコードの方が良いからです。また、catalog_statsはキャッシュの経過時間を報告するため、古さが隠されることはありません。

非目標

• データベースではありません。カタログは読み取り専用でメモリ上に存在します。データがJSONファイルに快適に収まらない場合は、本物のストアが必要です。

• 書き込みはありません。ここでカタログを変更することはありません。それは同期パイプラインの役割です（feedmergeを参照）。

• クエリ言語はありません。5つのフィルターキーでエージェントが実際に尋ねる質問はカバーできます。それ以上凝ったものは、ツールスキーマではなくコードに属します。

ライセンス

MIT