contentful-mcp

Контентный MCP-сервер

Реализация сервера MCP, которая интегрируется с API управления контентом Contentful, предоставляя комплексные возможности управления контентом.

• Обратите внимание *; если вас не интересует код, а вы просто хотите использовать этот MCP в Claude Desktop (или любом другом инструменте, который может использовать серверы MCP), вам не нужно клонировать этот репозиторий, вы можете просто настроить его в Claude Desktop, инструкции по его установке см. в разделе «Использование с Claude Desktop».

Функции

• Управление контентом : полный цикл операций CRUD для записей и активов
• Управление пространством : создание, обновление и управление пространствами и средами.
• Типы контента : управление определениями типов контента
• Локализация : Поддержка нескольких локалей
• Публикация : управление процессом публикации контента
• Массовые операции : выполнение массовой публикации, отмены публикации и проверки нескольких записей и активов.
• Умная пагинация : операции со списками возвращают максимум 3 элемента на запрос, чтобы предотвратить переполнение контекстного окна, со встроенной поддержкой пагинации.

Пагинация

Чтобы предотвратить переполнение контекстного окна в LLM, операции со списками (например, search_entries и list_assets) ограничены 3 элементами на запрос. Каждый ответ включает:

• Общее количество доступных предметов
• Текущая страница элементов (макс. 3)
• Количество оставшихся предметов
• Пропустить значение для следующей страницы
• Сообщение, побуждающее LLM предложить извлечь больше элементов

Эта система пагинации позволяет LLM эффективно обрабатывать большие наборы данных, сохраняя при этом ограничения контекстного окна.

Массовые операции

Функция массовых операций обеспечивает эффективное управление несколькими элементами контента одновременно:

• Асинхронная обработка : операции выполняются асинхронно и предоставляют обновления статуса.
• Эффективное управление контентом : обработка нескольких записей или активов за один вызов API
• Отслеживание статуса : отслеживайте прогресс с помощью счетчиков успешных и неудачных операций.
• Оптимизация ресурсов : сокращение числа вызовов API и повышение производительности пакетных операций.

Эти инструменты для массовых операций идеально подходят для миграции контента, массовых обновлений или пакетных публикаций.

Инструменты

Управление входом

• search_entries : Поиск записей с использованием параметров запроса
• create_entry : Создать новые записи
• get_entry : Извлечь существующие записи
• update_entry : Обновить поля ввода
• delete_entry : Удалить записи
• publish_entry : Публикация записей
• unpublish_entry : Отменить публикацию записей

Массовые операции

• bulk_publish : Публикация нескольких записей и активов за одну операцию. Принимает массив сущностей (записей и активов) и обрабатывает их публикацию как пакет.
• bulk_unpublish : Отменить публикацию нескольких записей и активов за одну операцию. Аналогично bulk_publish, но удаляет контент из API доставки.
• bulk_validate : Проверка нескольких записей на предмет согласованности содержимого, ссылок и обязательных полей. Возвращает результаты проверки без изменения содержимого.

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

• list_assets : Список активов с разбивкой на страницы (3 элемента на странице)
• upload_asset : Загрузить новые активы с метаданными
• get_asset : Получить сведения и информацию об активах
• update_asset : Обновление метаданных и файлов активов
• delete_asset : Удалить активы из пространства
• publish_asset : публикация ресурсов в API доставки
• unpublish_asset : Отменить публикацию ресурсов из API доставки

Управление пространством и окружающей средой

• list_spaces : Список доступных пространств
• get_space : Получить сведения о пространстве
• list_environments : Список сред в пространстве
• create_environment : Создать новую среду
• delete_environment : Удалить среду

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

• list_content_types : Список доступных типов контента
• get_content_type : Получить сведения о типе контента
• create_content_type : Создать новый тип контента
• update_content_type : Обновить тип контента
• delete_content_type : Удалить тип контента
• publish_content_type : Опубликовать тип контента

Инструменты разработки

Инспектор МКП

Проект включает в себя инструмент MCP Inspector, который помогает в разработке и отладке:

• Режим проверки : запустите npm run inspect , чтобы запустить инспектор. Вы можете открыть инспектор, перейдя по адресу http://localhost:5173.
• Режим наблюдения : используйте npm run inspect:watch для автоматического перезапуска инспектора при изменении файлов.
• Визуальный интерфейс : инспектор предоставляет веб-интерфейс для тестирования и отладки инструментов MCP.
• Тестирование в реальном времени : попробуйте инструменты и сразу же увидите результаты.
• Тестирование массовых операций : тестирование и мониторинг массовых операций с визуальной обратной связью о ходе выполнения и результатах.

Проект также содержит команду npm run dev , которая перестраивает и перезагружает сервер MCP при каждом изменении.

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

Предпосылки

1. Создайте учетную запись Contentful на Contentful
2. Создайте токен API управления контентом из настроек вашего аккаунта.

Переменные среды

Эти переменные также могут быть заданы как аргументы.

• CONTENTFUL_HOST / --host : Конечная точка API управления контентом (по умолчанию https://api.contentful.com )
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token : Ваш токен API управления контентом
• ENABLE_HTTP_SERVER / --http : Установите значение «true», чтобы включить режим HTTP/SSE
• HTTP_PORT / --port : Порт для HTTP-сервера (по умолчанию: 3000)
• HTTP_HOST / --http-host : Хост для HTTP-сервера (по умолчанию: localhost)

Исследование космоса и окружающей среды

Вы можете ограничить spaceId и EnvironmentId, чтобы гарантировать, что LLM будет выполнять операции только с определенными идентификаторами пространства/среды. Это в основном необходимо для поддержки агентов, которые должны работать в определенных пространствах. Если заданы как SPACE_ID , так и ENVIRONMENT_ID env-vars, инструменты не будут сообщать о необходимости этих значений, а обработчики будут использовать переменные среды для выполнения операций CMA. Вы также потеряете доступ к инструментам в обработчике пространства, поскольку эти инструменты находятся в разных пространствах. Вы также можете добавить SPACE_ID и ENVIRONMENT_ID , используя аргументы --space-id и --environment-id

Использование идентификатора приложения

Вместо предоставления токена управления вы также можете использовать App Identity для обработки аутентификации. Вам придется настроить и установить Contentful App и задать следующие параметры при вызове MCP-сервера:

• --app-id = идентификатор приложения, предоставляющего Apptoken
• --private-key = закрытый ключ, созданный вами в пользовательском интерфейсе вашего приложения, привязанный к app_id
• --space-id = spaceId, в котором установлено приложение
• --environment-id = environmentId (внутри пространства), в котором установлено приложение.

С этими значениями сервер MCP запросит временный AppToken для выполнения операции с контентом в определенном пространстве/идентификаторе среды. Это особенно полезно при использовании этого сервера MCP в бэкэнд-системах, которые действуют как MCP-клиент (например, чат-агенты)

Использование с Claude Desktop

Вам не нужно клонировать этот репозиторий, чтобы использовать этот MCP, вы можете просто добавить его в свой claude_desktop_config.json :

Добавьте или отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json и добавьте следующие строки:

Если ваш MCPClient не поддерживает настройку переменных среды, вы также можете установить токен управления, используя следующий аргумент:

Установка через Smithery

Чтобы автоматически установить Contentful Management Server для Claude Desktop через Smithery :

Разработка и использование Claude Desktop

Если вы хотите внести свой вклад и проверить, что Клод сделает с вашим вкладом;

• запустите npm run dev , это запустит наблюдателя, который перестраивает сервер MCP при каждом изменении
• обновите claude_desktop_config.json , чтобы он напрямую ссылался на проект, т. е.:

Это позволит вам протестировать любые изменения на сервере MCP напрямую с помощью Claude. Однако если вы добавите новые инструменты/ресурсы, вам потребуется перезапустить Claude Desktop.

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

Сервер MCP поддерживает два режима транспортировки:

stdio транспорт

Режим транспорта по умолчанию использует стандартные потоки ввода/вывода для связи. Это идеально подходит для интеграции с клиентами MCP, поддерживающими транспорт stdio, такими как Claude Desktop.

Чтобы использовать режим stdio, просто запустите сервер без флага --http :

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

Сервер также поддерживает транспорт StreamableHTTP, как определено в протоколе MCP. Этот режим полезен для веб-интеграций или при запуске сервера как автономной службы.

Чтобы использовать режим StreamableHTTP, запустите с флагом --http :

Подробности о потоковом HTTP

• Использует официальный транспорт MCP StreamableHTTP
• Поддерживает стандартные операции протокола MCP
• Включает управление сеансами для поддержания состояния
• Правильно обрабатывает шаблоны инициализации/уведомления
• Совместимость со стандартными клиентами MCP
• Заменяет устаревший транспорт SSE на современный подход.

Реализация соответствует стандартной спецификации протокола MCP, позволяя любому клиенту MCP подключаться к серверу без специальной обработки.

Обработка ошибок

Сервер реализует комплексную обработку ошибок для:

• Ошибки аутентификации
• Ограничение скорости
• Недействительные запросы
• Проблемы с сетью
• Ошибки, специфичные для API

Лицензия

Лицензия Массачусетского технологического института

Мелкий шрифт

Этот MCP Server позволяет Claude (или другим агентам, которые могут потреблять ресурсы MCP) обновлять, удалять контент, пространства и модели контента. Поэтому будьте уверены, что вы позволяете Claude делать с вашими Contentful пространствами!

Этот MCP-сервер официально не поддерживается Contentful (пока)