Kontent.ai

Kontent.ai MCP Server

Преобразите свои операции с контентом с помощью инструментов на базе ИИ для Kontent.ai. Создавайте, управляйте и исследуйте структурированный контент через общение на естественном языке в вашем любимом редакторе с поддержкой ИИ.

Kontent.ai MCP Server реализует Model Context Protocol для соединения ваших проектов Kontent.ai с инструментами ИИ, такими как Claude, Cursor и VS Code. Он позволяет моделям ИИ понимать структуру вашего контента и выполнять операции с помощью инструкций на естественном языке.

✨ Ключевые возможности

• 🚀 Быстрое прототипирование: Превращайте ваши диаграммы в живые модели контента за секунды
• 📈 Визуализация данных: Визуализируйте модель контента в любом нужном вам формате

Содержание

• ✨ Ключевые возможности
• 🔌 Быстрый старт
• 🛠️ Доступные инструменты
• ⚙️ Конфигурация
• 🔒 Безопасность
• 🚀 Варианты транспорта
• 💻 Разработка
  • 🛠 Локальная установка
  • 📂 Структура проекта
  • 🔍 Отладка
  • 📦 Процесс выпуска
• Лицензия

🔌 Быстрый старт

🔑 Необходимые условия

Прежде чем использовать MCP-сервер, вам потребуется:

1. Учётная запись Kontent.ai — Зарегистрируйтесь, если у вас её нет.
2. Проект — Создайте проект для работы.
3. Ключ Management API — Создайте ключ с соответствующими разрешениями.
4. Идентификатор окружения — Получите идентификатор окружения.

🛠 Варианты настройки

Вы можете запустить Kontent.ai MCP Server с помощью npx:

Транспорт STDIO

npx @kontent-ai/mcp-server@latest stdio

Потоковый HTTP-транспорт

npx @kontent-ai/mcp-server@latest shttp

🛠️ Доступные инструменты

Руководство по операциям Patch

• get-patch-guide – 🚨 ОБЯЗАТЕЛЬНО перед любой операцией patch. Получить руководство по операциям patch для Kontent.ai по типу сущности

Управление типами контента

• get-content-type – Получить тип контента Kontent.ai по ID
• list-content-types – Получить все типы контента Kontent.ai
• create-content-type – Создать новый тип контента Kontent.ai
• patch-content-type – Обновить существующий тип контента Kontent.ai по кодовому имени с помощью операций patch (move, addInto, remove, replace)
• delete-content-type – Удалить тип контента Kontent.ai по ID

Управление фрагментами типов контента

• get-content-type-snippet – Получить фрагмент типа контента Kontent.ai по ID
• list-content-type-snippets – Получить все фрагменты типов контента Kontent.ai
• create-content-type-snippet – Создать новый фрагмент типа контента Kontent.ai
• patch-content-type-snippet – Обновить существующий фрагмент типа контента Kontent.ai по ID с помощью операций patch (move, addInto, remove, replace)
• delete-content-type-snippet – Удалить фрагмент типа контента Kontent.ai по ID

Управление таксономией

• get-taxonomy-group – Получить группу таксономии Kontent.ai по ID
• list-taxonomy-groups – Получить все группы таксономии Kontent.ai
• create-taxonomy-group – Создать новую группу таксономии Kontent.ai
• patch-taxonomy-group – Обновить группу таксономии Kontent.ai с помощью операций patch (addInto, move, remove, replace)
• delete-taxonomy-group – Удалить группу таксономии Kontent.ai по ID

Управление элементами контента

• get-content-item – Получить элемент контента Kontent.ai по ID
• get-content-item-variant – Получить вариант элемента контента Kontent.ai (языковую версию/перевод). Возвращает текущую версию — черновик, если он существует, иначе опубликованную
• get-published-content-item-variant-version – Получить опубликованную версию варианта элемента контента Kontent.ai. Используйте, когда существует более новая версия черновика, но вам нужно текущее опубликованное (живое) содержимое
• get-content-item-translations – Получить все переводы элемента контента Kontent.ai — каждую языковую версию (вариант) конкретного элемента контента
• list-content-item-variants – Список, фильтрация, поиск элементов контента Kontent.ai с вариантами элементов контента (языковыми версиями/переводами)
• create-content-item – Создать новый элемент контента Kontent.ai (создаёт только контейнер, используйте create-content-item-variant для добавления языковых версий/переводов)
• update-content-item – Обновить существующий элемент контента Kontent.ai по ID. Элемент контента должен уже существовать — этот инструмент не создаёт новые элементы
• delete-content-item – Удалить элемент контента Kontent.ai по ID
• create-content-item-variant – Создать вариант элемента контента Kontent.ai, назначив текущего пользователя участником. Значения элементов должны соответствовать ограничениям и рекомендациям, определённым в типе контента. Отправляйте только те элементы, которые хотите задать; пропущенные инициализируются пустыми
• update-content-item-variant – Обновить вариант элемента контента Kontent.ai. Значения элементов должны соответствовать ограничениям и рекомендациям, определённым в типе контента. Отправляйте только те элементы, которые хотите изменить — пропущенные элементы остаются без изменений. Для элементов форматированного текста с компонентами отправляйте полный элемент (значение плюс полный массив components, включая компоненты, которые остаются без изменений)
• create-new-content-item-variant-version – Создать новую версию варианта элемента контента Kontent.ai. Эта операция создаёт новую версию существующего варианта элемента контента, что полезно для версионирования контента и создания новых черновиков из опубликованного контента
• delete-content-item-variant – Удалить вариант элемента контента Kontent.ai
• bulk-get-content-item-variants – Массовое получение элементов контента Kontent.ai с их вариантами по парам ссылок на элемент и язык. Используйте после list-content-item-variants для получения полных данных контента для конкретных пар элемент+язык. Элементы без варианта на запрошенном языке возвращают элемент без свойства variant. Возвращает постраничные результаты с токеном продолжения
• search-content-item-variants – Семантический поиск на базе ИИ для нахождения контента по смыслу и концепциям в конкретном варианте элемента контента. Используйте для: концептуального поиска, когда вы не знаете точных ключевых слов. Ограниченные возможности фильтрации (только ID варианта)

Управление ресурсами

• get-asset – Получить конкретный ресурс Kontent.ai по ID
• list-assets – Получить все ресурсы Kontent.ai
• update-asset – Обновить ресурс Kontent.ai по ID

Управление папками ресурсов

• list-asset-folders – Список всех папок ресурсов Kontent.ai
• patch-asset-folders – Изменить папки ресурсов Kontent.ai с помощью операций patch (addInto для добавления новых папок, rename для изменения имён, remove для удаления папок)

Управление языками

• list-languages – Получить все языки Kontent.ai (включает как активные, так и неактивные — проверяйте свойство is_active)
• create-language – Создать новый язык Kontent.ai (языки всегда создаются активными)
• patch-language – Обновить язык Kontent.ai с помощью операций replace (можно изменять только активные языки — для активации/деактивации используйте веб-интерфейс Kontent.ai)

Управление коллекциями

• list-collections – Получить все коллекции Kontent.ai. Коллекции устанавливают границы для элементов контента в вашем окружении и помогают организовать контент по командам, брендам или проектам
• patch-collections – Обновить коллекции Kontent.ai с помощью операций patch (addInto для добавления новых коллекций, move для изменения порядка, remove для удаления пустых коллекций, replace для переименования)

Управление пространствами

• list-spaces – Получить все пространства Kontent.ai
• create-space – Создать новое пространство Kontent.ai для управления веб-сайтом или каналом
• patch-space – Изменить пространство Kontent.ai с помощью операций replace
• delete-space – Удалить пространство Kontent.ai

Управление ролями

• list-roles – Получить все роли Kontent.ai. Требуется план Enterprise или Flex с разрешением «Manage custom roles»

Управление рабочими процессами

• list-workflows – Получить все рабочие процессы Kontent.ai. Рабочие процессы определяют этапы жизненного цикла контента и переходы между ними
• create-workflow – Создать новый рабочий процесс Kontent.ai с пользовательскими шагами, переходами, областями действия и разрешениями ролей
• update-workflow – Обновить существующий рабочий процесс Kontent.ai по ID. Изменяйте шаги, переходы, области действия и разрешения ролей. Нельзя удалить шаги, которые используются
• delete-workflow – Удалить рабочий процесс Kontent.ai по ID. Рабочий процесс не должен использоваться никакими элементами контента
• change-content-item-variant-workflow-step – Изменить шаг рабочего процесса варианта элемента контента в Kontent.ai. Эта операция перемещает вариант элемента контента на другой шаг рабочего процесса, обеспечивая управление жизненным циклом контента, например перемещение контента из черновика на проверку, с проверки в опубликованные и т. д.
• publish-content-item-variant – Опубликовать или запланировать публикацию варианта элемента контента в Kontent.ai. Эта операция может либо немедленно опубликовать вариант, либо запланировать его публикацию на определённую будущую дату и время с опциональным указанием часового пояса
• unpublish-content-item-variant – Отменить публикацию или запланировать отмену публикации варианта элемента контента в Kontent.ai. Эта операция может либо немедленно отменить публикацию варианта (сделав его недоступным через Delivery API), либо запланировать отмену публикации на определённую будущую дату и время с опциональным указанием часового пояса

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

Сервер поддерживает два режима, каждый из которых привязан к своему транспорту:

Однотенантный режим (STDIO)

Настройте учётные данные через переменные окружения:

Мультитенантный режим (Потоковый HTTP)

Для потокового HTTP-транспорта учётные данные предоставляются в каждом запросе:

• Идентификатор окружения как параметр пути URL: /{environmentId}/mcp
• Ключ API через Bearer-токен в заголовке Authorization: Authorization: Bearer <api-key>

Это позволяет одному экземпляру сервера обрабатывать запросы для нескольких окружений Kontent.ai без необходимости в переменных окружения с учётными данными.

🔒 Безопасность

Косвенная инъекция подсказок

Контент, возвращаемый этим сервером (например, элемент, написанный редактором), может содержать текст, который подключённая LLM интерпретирует как инструкции — косвенная инъекция подсказок. Захваченный агент может быть направлен на деструктивные вызовы инструментов (удаление / отмена публикации / перезапись) или на утечку неопубликованных черновиков. Это общеотраслевая, нерешённая проблема, которую сервер не может надёжно исправить путём преобразования возвращаемого контента, поэтому защита является многоуровневой:

• Используйте ключ Management API с минимальными привилегиями. Сервер действует с тем ключом, который ему предоставлен. С ключом только для чтения деструктивный вызов захваченного агента просто завершится ошибкой на границе API — это самый надёжный контроль, поскольку он действует независимо от поведения модели.
• Держите человека в курсе. Каждый инструмент несёт аннотации MCP — чтения помечены как readOnlyHint, инструменты только для создания являются аддитивными, а инструменты, которые перезаписывают или удаляют данные, помечены как destructiveHint — что позволяет совместимым клиентам автоматически одобрять чтения и запрашивать подтверждение перед деструктивными вызовами. Запускайте сервер с таким клиентом и избегайте автоматического одобрения в автономном режиме при использовании ключа с правами на запись.
• Добавьте проверку на стороне клиента, если ваш клиент это поддерживает. Некоторые клиенты (например, хуки Claude Code) позволяют детерминированно запрашивать подтверждение перед запуском деструктивного инструмента, независимо от модели. Это настраивается локально; сервер не может это принудительно обеспечить.

Это рекомендации, а не гарантии. Сообщайте о проблемах безопасности конфиденциально на [email protected].

🚀 Варианты транспорта

📟 Транспорт STDIO

Чтобы запустить сервер с транспортом STDIO, настройте ваш MCP-клиент с помощью:

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 Потоковый HTTP-транспорт (Multi-Tenant)

Потоковый HTTP-транспорт обслуживает несколько окружений Kontent.ai с одного экземпляра сервера. Каждый запрос предоставляет учётные данные через параметры пути URL и аутентификацию Bearer.

Сначала запустите сервер:

npx @kontent-ai/mcp-server@latest shttp

{
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/<environment-id>/mcp",
      "headers": {
        "Authorization": "Bearer <management-api-key>"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "apiKey",
      "type": "password",
      "description": "Kontent.ai API Key"
    },
    {
      "id": "environmentId",
      "type": "text",
      "description": "Environment ID"
    }
  ],
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/${inputs.environmentId}/mcp",
      "headers": {
        "Authorization": "Bearer ${inputs.apiKey}"
      }
    }
  }
}

{
  "mcpServers": {
    "kontent-ai-multi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/<environment-id>/mcp",
        "--header",
        "Authorization: Bearer <management-api-key>"
      ]
    }
  }
}

claude mcp add --transport http kontent-ai-multi \
  "http://localhost:3001/<environment-id>/mcp" \
  --header "Authorization: Bearer <management-api-key>"

[!IMPORTANT] Замените <environment-id> на ID вашего окружения Kontent.ai (GUID) и <management-api-key> на ваш ключ.

💻 Разработка

🛠 Локальная установка

# Clone the repository
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# Install dependencies
npm ci

# Build the project
npm run build

# Start the server
npm run start:stdio  # For STDIO transport
npm run start:shttp  # For Streamable HTTP transport

# Start the server with automatic reloading (no need to build first)
npm run dev:stdio  # For STDIO transport
npm run dev:shttp  # For Streamable HTTP transport

📂 Структура проекта

• src/ - Исходный код
  • tools/ - Реализации инструментов MCP
  • clients/ - Настройка клиента Kontent.ai API
  • schemas/ - Схемы валидации данных
  • utils/ - Вспомогательные функции
    • errorHandler.ts - Стандартизированная обработка ошибок для инструментов MCP
    • throwError.ts - Утилита для генерации общих ошибок
  • server.ts - Основная настройка сервера и регистрация инструментов
  • bin.ts - Единая точка входа, обрабатывающая оба типа транспорта

🔍 Отладка

Для отладки вы можете использовать MCP inspector:

npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js

Или используйте MCP inspector на работающем потоковом HTTP-сервере:

npx @modelcontextprotocol/inspector

Это предоставляет веб-интерфейс для проверки и тестирования доступных инструментов.

📦 Процесс выпуска

Чтобы выпустить новую версию:

1. Увеличьте версию с помощью npm version [patch|minor|major] — это обновит package.json, package-lock.json и синхронизирует с server.json
2. Отправьте коммит в вашу ветку и создайте pull request
3. Примите pull request
4. Создайте новый релиз на GitHub с номером версии в качестве имени и тега, используя автоматически сгенерированные заметки о релизе
5. Публикация релиза запускает автоматизированный рабочий процесс, который публикует пакет в npm и реестр GitHub MCP

Лицензия

MIT