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

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

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

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

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

• get-content-type — Получить тип контента Kontent.ai по ID
• list-content-types — Получить все типы контента Kontent.ai
• list-content-type-usages — Показать, где используется тип контента Kontent.ai
• create-content-type — Создать новый тип контента Kontent.ai
• patch-content-type — Обновить существующий тип контента Kontent.ai по кодовому имени с помощью операций патча (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 с помощью операций патча (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 с помощью операций патча (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. Значения элементов должны соответствовать ограничениям и рекомендациям, определенным в типе контента. Отправляйте только те элементы, которые хотите изменить — пропущенные элементы остаются без изменений. Для элементов с форматированным текстом с компонентами отправляйте полный элемент (значение плюс полный массив компонентов, включая компоненты, которые не изменяются)
• 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 для получения полных данных контента для конкретных пар элемент+язык. Элементы без варианта на запрошенном языке возвращаются без свойства варианта. Возвращает постраничные результаты с токеном продолжения
• 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 с помощью операций патча (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 с помощью операций патча (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 с разрешением «Управление пользовательскими ролями»

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

• 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), либо запланировать снятие с публикации на конкретную будущую дату и время с возможностью указания часового пояса
• cancel-scheduled-publishing-content-item-variant — Отменить запланированную публикацию варианта элемента контента в Kontent.ai. Эта операция возвращает вариант, запланированный для публикации, на предыдущий шаг рабочего процесса, позволяя вносить дальнейшие правки

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

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

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

Настройте учетные данные через переменные среды:

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

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

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

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

KONTENT_API_KEY и KONTENT_ENVIRONMENT_ID игнорируются на этом транспорте, даже если они случайно заданы в среде сервера. Каждый запрос должен нести свои собственные учетные данные; запрос без них отклоняется, а не обслуживается с учетными данными сервера.

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

Косвенная инъекция промптов

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

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

Это подсказки, а не гарантии. Сообщайте о проблемах безопасности конфиденциально на security@kontent.ai.

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

📟 Транспорт 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-транспорт (мультитенантный)

Потоковый 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/ - Настройка клиента API Kontent.ai
  • schemas/ - Схемы валидации данных
  • utils/ - Вспомогательные функции
    • errorHandler.ts - Стандартизированная обработка ошибок для MCP-инструментов
    • throwError.ts - Утилита для выбрасывания общих ошибок
  • app.ts - Фабрика Express-приложения для потокового HTTP-транспорта
  • server.ts - Основная настройка сервера и регистрация инструментов
  • bin.ts - Единая точка входа, обрабатывающая оба типа транспорта

🔍 Отладка

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

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

Или используйте MCP-инспектор на запущенном потоковом 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 release с номером версии в качестве имени и тега, используя автоматически сгенерированные заметки о выпуске
5. Публикация релиза запускает автоматический рабочий процесс, который публикует в npm и реестр MCP GitHub

Лицензия

MIT