MCP-сервер Grips Intelligence (v2)

Сервер протокола Model Context Protocol (MCP), который предоставляет API данных электронной коммерции Grips Intelligence любому MCP-клиенту — Claude Desktop, Cowork, Claude Code и т. д.

v2 — это полная переработка v1 с защищенной обработкой данных, внедренной с самого начала. Она исправляет класс ошибок ".map is not a function", для устранения которых в v1.x требовался патч времени выполнения — теперь при работе с малоизвестными или неизвестными доменами сервер возвращает корректный ответ "нет данных" вместо аварийного завершения вызова инструмента.

Что внутри

Все инструменты по умолчанию выводят данные в формате markdown для удобства чтения. Передайте format: "json" для получения ответа в формате, пригодном для машинной обработки.

Установка

npm install

Скрипт prepare автоматически собирает dist/ при выполнении npm install.

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

Укажите свой API-ключ Grips в конфигурации сервера MCP-клиента. Для Claude Desktop это файл ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "grips": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/grips-mcp-server-v2/dist/index.js"
      ],
      "env": {
        "GRIPS_API_KEY": "your-api-key-here",
        "GRIPS_DEFAULT_COUNTRY": "US"
      }
    }
  }
}

Обязательные переменные окружения:

• GRIPS_API_KEY — ваш токен API Grips (отправляется в заголовке grips-api-key).

Опциональные переменные окружения:

• GRIPS_DEFAULT_COUNTRY — US, GB или DE. По умолчанию используется US, если значение не задано или неверно.

После редактирования конфигурации полностью закройте Claude Desktop (Cmd+Q — не просто закрытие окна) и откройте снова.

Отличия от v1

v1 аварийно завершался при получении ответа API определенной формы: когда Grips возвращал данные по домену с малым покрытием или неизвестному домену, поле timeseries приходило как {} вместо null, undefined или []. В коде использовалось (data.timeseries ?? []).map(...), что защищает только от null/undefined, но не от {}. Результат: "data.timeseries ?? []).map is not a function".

v2 пропускает каждое поле полезной нагрузки через toArray<T>() (для массивов) или toObject<T>() (для ответов в виде словаря, таких как эндпоинт устройств) перед использованием. Любое значение, не являющееся массивом или объектом, заменяется на безопасное пустое значение по умолчанию, и инструмент возвращает корректный ответ "нет данных" вместо выброса исключения.

Другие изменения:

• Нормализация дат стала согласованной (каждая дата приводится к YYYY-MM-DD в UTC) во всех инструментах, поэтому строки не смещаются между днями в часовых поясах, отличных от UTC.

• Форматировщики валют / целых чисел / процентов отображают — для отсутствующих значений вместо $NaN или 0.00%.

• Сообщения об ошибках теперь включают полезные подсказки — 401 → "проверьте свой API-ключ", 429 → "превышен лимит запросов, сузьте временной интервал" и т. д.

• Изоляция ошибок по доменам в grips_compare_domains — ошибка одного домена при сравнении восьми больше не ломает остальные семь.

• Ограничение по количеству символов — ответы обрезаются примерно на 200 КБ с видимым уведомлением, чтобы выгрузки по нескольким доменам не переполняли контекстное окно.

Разработка

npm run dev    # watch mode, rebuilds on change
npm run build  # one-shot build to dist/

Тестирование из командной строки

Проверьте, что сервер запускается без ошибок (он завершит работу при получении EOF из stdin):

GRIPS_API_KEY=your-key node dist/index.js < /dev/null

Вы должны увидеть [grips-mcp] grips-mcp-server v2.0.0 ready (default country: US). в stderr и отсутствие аварийного завершения.

Для интерактивного тестирования используйте @modelcontextprotocol/inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Справочник API

Grips документирует свою публичную схему по адресу https://gripsintelligence.com/knowledge-base/api. Запросы, используемые этим сервером, скопированы дословно с этой страницы.

Поддерживаемые страны на текущий момент: US, GB, DE. Все остальные вызовут ошибку API.

Лицензия

Частная — не для внешнего распространения.