catalog-mcp

MCP-сервер, который превращает любой JSON-каталог в инструменты запросов для AI-агентов.

Укажите URL или файл каталога — фид инвентаря, список товаров, catalog.json, который публикует feedmerge — и любой MCP-клиент (Claude Desktop, Claude Code, всё, что говорит по протоколу) получит структурированную фильтрацию, группировку, ранжирование и обнаружение схемы по вашим записям.

Node 18+. Две зависимости времени выполнения: MCP SDK и zod.

Зачем

Агенты плохо работают с большими JSON-файлами, но хорошо — с инструментами. Отдайте агенту каталог на 2 МБ — он урежет, пролистает или выдумает записи; дайте ему catalog_query с грамматикой фильтра — и он каждый раз правильно ответит «самая дешёвая запись до 30 000 $ с этими двумя характеристиками», читая только совпадающие записи.

Этот репозиторий — обобщённая версия 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 — числовые границы. Запись без действительного числа в ограниченном поле исключается. Это правило критически важно: в производственном каталоге отсутствующая цена означает «уточняйте цену», и «покажи единицы до 30 000 $» никогда не должна выдать единицу, чья цена неизвестна.

• has — принадлежность массиву; каждое перечисленное значение должно присутствовать.

• contains — регистронезависимая подстрока в строковом поле; поле "*" ищет по всем строковым полям записи.

Условия объединяются по И. Неизвестный ключ верхнего уровня — это ошибка, которая перечисляет допустимые ключи, потому что молча игнорируемый фильтр — это как агент уверенно сообщает неверные ответы.

Сортировка помещает записи без поля сортировки в конец в обоих направлениях — «сортировать по цене» сначала показывает записи с ценой, а не стену из null.

Конфигурация

Когда CATALOG_RECORDS_PATH не задан, загрузчик использует корень документа, если это массив, или единственный массив объектов верхнего уровня, если он ровно один ({ "meta": ..., "items": [...] } просто работает). Если документ неоднозначен, он отказывается и перечисляет возможные ключи.

При неудачном обновлении сервер отдаёт последние хорошие данные вместо ошибки — агенту, находящемуся в середине задачи, лучше работать с пятиминутными записями, чем с исключением — и catalog_stats сообщает возраст кэша, так что устаревание никогда не скрывается.

Нецели

• Не база данных. Каталог доступен только для чтения и хранится в памяти; если ваши данные не помещаются комфортно в JSON-файл, вам нужна настоящая СУБД.

• Нет записи. Ничто здесь не изменяет каталог — это задача конвейера синхронизации (см. feedmerge).

• Нет языка запросов. Пять ключей фильтра покрывают то, что агенты действительно спрашивают; всё более сложное должно быть в коде, а не в схеме инструмента.

Лицензия

MIT