Ghost MCP Server

Это форк MFYDev/ghost-mcp, который теперь поддерживается и улучшается @hithereiamaliff.

Этот сервер протокола контекста моделей (MCP) предоставляет мощный и гибкий способ управления вашим экземпляром Ghost CMS с использованием интерфейсов больших языковых моделей (LLM). Он предлагает полный и безопасный доступ к административным функциям вашего блога, позволяя автоматизировать и оптимизировать рабочие процессы управления контентом.

Возможности

• Надежная интеграция с API: Использует прямые аутентифицированные вызовы axios для всех операций Admin API, обеспечивая стабильное и надежное соединение, не зависящее от внешних библиотек.

• Комплексный доступ к сущностям: Управление публикациями, пользователями, участниками, уровнями подписки, предложениями и новостными рассылками.

• Улучшенная обработка ошибок: Предоставляет подробные коды состояния и тела ответов.

• Современный транспорт: Исключительно использует потоковый HTTP-транспорт, вся устаревшая логика STDIO удалена.

• Диагностические инструменты: Включает инструменты для устранения неполадок подключения к API и конфигурации.

• Поддержка нескольких арендаторов: Использует mcp-key-service, поэтому публичные/общие развертывания никогда не раскрывают необработанные учетные данные Ghost в URL-адресах MCP.

• Аналитика Firebase: Облачное хранилище аналитики с использованием Firebase Realtime Database и локальным резервным копированием файлов.

• Готовность к развертыванию на VPS: Поддержка Docker, Nginx и автоматического развертывания через GitHub Actions.

Установка и использование

Этот MCP-сервер доступен через два метода развертывания:

Метод 1: Пакет NPM (рекомендуется для клиентов MCP)

Установите напрямую из npm:

npm install -g mcp-ghostcms

Или используйте с npx (установка не требуется):

npx mcp-ghostcms

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

Для использования с клиентами MCP, такими как Claude Desktop, добавьте следующее в ваш claude_desktop_config.json:

{
  "mcpServers": {
      "mcp-ghostcms": {
        "command": "npx",
        "args": ["-y", "mcp-ghostcms"],
        "env": {
            "GHOST_API_URL": "https://yourghostbloginstance.com",
            "GHOST_ADMIN_API_KEY": "your_admin_api_key",
            "GHOST_API_VERSION": "v6.0"
        }
      }
    }
}

Метод 2: Облачная платформа Smithery

Разверните и запустите на облачной платформе Smithery:

Или для локальной разработки со Smithery:

git clone <this-repo>
cd ghost-mcp
npm install
npm run dev

Это запустит сервер на порту 8080 и откроет Smithery Playground в вашем браузере.

Метод 3: Самостоятельно размещенный VPS с сервисом ключей MCP

Для публичных/общих развертываний этот MCP-сервер может быть размещен на собственном VPS и разрешает учетные данные Ghost через mcp-key-service. Пользователи один раз регистрируют URL своего сайта Ghost и ключ администратора, получают ключ usr_XXXXXXXX, и в URL-адресе MCP отображается только этот пользовательский ключ.

Формат URL-адреса MCP

https://your-domain.com/ghostcms/mcp/usr_YOUR_USER_KEY

Альтернативная форма с параметрами запроса:

https://your-domain.com/ghostcms/mcp?api_key=usr_YOUR_USER_KEY

Пример использования с Claude Desktop

Добавьте в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "ghost-myblog": {
      "type": "streamable-http",
      "url": "https://mcp.yourdomain.com/ghostcms/mcp/usr_YOUR_USER_KEY"
    }
  }
}

Живая демонстрация

Публичный экземпляр доступен по адресу:

https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY

Примечание: Сначала зарегистрируйте свои учетные данные Ghost на mcpkeys.techmavie.digital, чтобы получить ключ usr_.

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

Этот MCP-сервер требует следующей конфигурации:

• GHOST_API_URL: URL вашего сайта Ghost (только домен, без пути), например, https://yourghostbloginstance.com

• GHOST_ADMIN_API_KEY: Ваш ключ Ghost Admin API в формате id:secret (из Ghost Admin → Settings → Integrations).

• GHOST_API_VERSION: Версия Ghost API (v5.0 для Ghost 5.x, v6.0 для Ghost 6.x).

• GHOST_CONTENT_API_KEY (необязательно): Ваш ключ Ghost Content API для операций только для чтения.

Для размещенного HTTP-режима настройте KEY_SERVICE_URL и KEY_SERVICE_TOKEN на сервере и установите MCP_API_KEY, если вы хотите защитить конечные точки аналитики заголовком X-API-Key.

Доступные ресурсы

Следующие ресурсы Ghost CMS доступны через этот MCP-сервер:

• Публикации (Posts): Статьи и контент, опубликованные на вашем сайте Ghost.

• Участники (Members): Зарегистрированные пользователи и подписчики вашего сайта.

• Новостные рассылки (Newsletters): Рассылки по электронной почте, управляемые и отправляемые через Ghost.

• Предложения (Offers): Рекламные предложения и скидки для участников.

• Приглашения (Invites): Приглашения для новых пользователей или сотрудников присоединиться к вашему сайту Ghost.

• Роли (Roles): Роли пользователей и разрешения в административной панели Ghost.

• Теги (Tags): Организационные теги для публикаций и контента.

• Уровни подписки (Tiers): Уровни подписки и планы для участников.

• Пользователи (Users): Пользователи-администраторы и учетные записи сотрудников.

• Вебхуки (Webhooks): Автоматизированные уведомления о событиях для внешних сервисов.

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

Этот MCP-сервер предоставляет широкий спектр инструментов для управления вашей Ghost CMS. Эти инструменты предоставляются через протокол контекста моделей и позволяют выполнять полный спектр операций CRUD (создание, чтение, обновление, удаление) с ресурсами вашего блога. Ниже приведен обзор доступного набора инструментов:

Публикации

• Просмотр публикаций: Список публикаций с дополнительными фильтрами, пагинацией и сортировкой.

• Чтение публикации: Получение публикации по ID или слагу.

• Добавление публикации: Создание новой публикации с заголовком, контентом и статусом.

• Редактирование публикации: Обновление существующей публикации по ID.

• Удаление публикации: Удаление публикации по ID.

Участники

• Просмотр участников: Список участников с фильтрами и пагинацией.

• Чтение участника: Получение участника по ID или электронной почте.

• Добавление участника: Создание нового участника.

• Редактирование участника: Обновление данных участника.

• Удаление участника: Удаление участника.

Новостные рассылки

• Просмотр рассылок: Список новостных рассылок.

• Чтение рассылки: Получение рассылки по ID.

• Добавление рассылки: Создание новой рассылки.

• Редактирование рассылки: Обновление данных рассылки.

• Удаление рассылки: Удаление рассылки.

Предложения

• Просмотр предложений: Список предложений.

• Чтение предложения: Получение предложения по ID.

• Добавление предложения: Создание нового предложения.

• Редактирование предложения: Обновление данных предложения.

• Удаление предложения: Удаление предложения.

Приглашения

• Просмотр приглашений: Список приглашений.

• Добавление приглашения: Создание нового приглашения.

• Удаление приглашения: Удаление приглашения.

Роли

• Просмотр ролей: Список ролей.

• Чтение роли: Получение роли по ID.

Теги

• Просмотр тегов: Список тегов.

• Чтение тега: Получение тега по ID или слагу.

• Добавление тега: Создание нового тега.

• Редактирование тега: Обновление данных тега.

• Удаление тега: Удаление тега.

Уровни подписки

• Просмотр уровней: Список уровней подписки.

• Чтение уровня: Получение уровня по ID.

• Добавление уровня: Создание нового уровня.

• Редактирование уровня: Обновление данных уровня.

• Удаление уровня: Удаление уровня.

Пользователи

• Просмотр пользователей: Список пользователей.

• Чтение пользователя: Получение пользователя по ID или слагу.

• Редактирование пользователя: Обновление данных пользователя.

• Удаление пользователя: Удаление пользователя.

Вебхуки

• Просмотр вебхуков: Список вебхуков.

• Добавление вебхука: Создание нового вебхука.

• Удаление вебхука: Удаление вебхука.

Каждый инструмент доступен через протокол MCP и может быть вызван из совместимых клиентов. Подробные схемы параметров и использование см. в исходном коде в src/tools/.

Обработка ошибок и диагностика

Этот форк включает улучшенную обработку ошибок, которая предоставляет подробную информацию о сбоях API:

• Коды состояния HTTP фиксируются и сообщаются

• Полные тела ответов включены в сообщения об ошибках

• Конфигурация среды выполнения регистрируется при запуске

• Доступны диагностические инструменты для устранения проблем с подключением:

  • admin_site_ping: Проверяет, доступна ли конечная точка Ghost Admin API

  • config_echo: Показывает текущую конфигурацию Ghost API (с замаскированным ключом)

Эти улучшения значительно упрощают диагностику распространенных проблем, таких как:

• Неверный формат URL API

• Отсутствующие или неправильно сформированные ключи Admin API

• Несоответствие версий API

• Проблемы с конфигурацией сети/прокси

Разработка

Настройка

1. Клонируйте репозиторий

2. Установите зависимости: npm install

3. Создайте файл .env с вашей конфигурацией Ghost:

   GHOST_API_URL=https://yourghostbloginstance.com
   GHOST_ADMIN_API_KEY=your_admin_api_key
   GHOST_API_VERSION=v6.0

4. Соберите проект: npm run build

5. Запустите сервер разработки: npm run dev

Устранение неполадок

Если вы столкнулись с ошибками аутентификации или "Resource not found":

1. Убедитесь, что ваш ключ Ghost Admin API имеет правильный формат id:secret.

2. Убедитесь, что ваш GHOST_API_URL является правильным доменом для вашего экземпляра Ghost.

3. Используйте инструмент admin_site_ping, чтобы убедиться, что конечная точка Admin API доступна.

4. Проверьте журналы сервера на предмет используемой конфигурации.

Требования к потоковому HTTP MCP

Этот сервер реализует потоковый HTTP-транспорт MCP с надлежащим управлением сеансами и обработкой заголовка Accept. Сервер автоматически внедряет text/event-stream в заголовки Accept и создает изолированные экземпляры транспорта для каждого запроса, чтобы предотвратить конфликты сеансов.

Тестирование конечной точки с правильной инициализацией MCP:

# Test MCP initialization (proper way to test)
curl -s -X POST \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  "https://mcp.techmavie.digital/ghostcms/mcp/usr_YOUR_USER_KEY"

# Expected response (SSE format):
# event: message
# data: {"result":{"protocolVersion":"2024-11-05","capabilities":{...},"serverInfo":{...}},"jsonrpc":"2.0","id":1}

Примечание: Простые запросы GET/POST без инициализации MCP вернут ошибки протокола, такие как "Bad Request: Server not initialized" — это ожидаемое поведение. Конечная точка требует правильного рукопожатия протокола MCP.

Для клиентов MCP (Claude Desktop, Claude iOS, Claude Code):

• Клиенты MCP автоматически обрабатывают протокол инициализации и управление сеансами

• Убедитесь, что ваш URL-адрес MCP правильно отформатирован в конфигурации вашего клиента

• Для Claude iOS используйте функцию Connectors с полным URL-адресом MCP, используя ваш ключ usr_

• Для Claude Code добавьте сервер в настройки MCP с типом streamable-http

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

• Сервер создает новый экземпляр транспорта для каждого HTTP-запроса (шаблон без сохранения состояния)

• Каждое клиентское соединение автоматически получает уникальный идентификатор сеанса

• Несколько клиентов могут подключаться одновременно без конфликтов сеансов

• Сеансы автоматически очищаются после отправки ответов

Распространенные ошибки и решения:

Развертывание на VPS

Этот MCP-сервер включает полную поддержку развертывания на собственном VPS с использованием Docker, Nginx и автоматического развертывания через GitHub Actions.

Архитектура

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Claude/MCP     │────▶│  Nginx Proxy    │────▶│  Docker         │
│  Client         │     │  /ghostcms/     │     │  Container      │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                                                ┌─────────────────┐
                                                │  Ghost CMS      │
                                                │  Admin API      │
                                                └─────────────────┘

Файлы развертывания

Репозиторий включает:

• Dockerfile - Конфигурация контейнера с Node.js 20-alpine

• docker-compose.yml - Оркестрация Docker с томами для аналитики и учетных данных Firebase

• deploy/nginx-mcp.conf - Конфигурация обратного прокси-сервера Nginx

• .github/workflows/deploy-vps.yml - Рабочий процесс автоматического развертывания GitHub Actions

Быстрое развертывание

# On your VPS
cd /opt/mcp-servers
git clone https://github.com/hithereiamaliff/mcp-ghostcms.git ghostcms
cd ghostcms

# Build and start
docker compose up -d --build

# Check logs
docker compose logs -f

Конечные точки

Аналитика Firebase

Этот MCP-сервер использует Firebase Realtime Database для облачного хранения аналитики с локальным резервным копированием файлов в качестве резервного варианта.

Возможности

• Двойное хранилище: Firebase (основное) + локальный файл (резервная копия)

• Постоянство: Данные сохраняются после пересборки контейнеров и развертываний

• В реальном времени: Обновления каждые 60 секунд

• Панель управления: Визуальная аналитика по адресу /analytics/dashboard

Отслеживаемые данные

• Общее количество запросов и вызовов инструментов

• Запросы по методам (GET, POST и т.д.)

• Запросы по конечным точкам

• Статистика использования инструментов

• IP-адреса клиентов и агенты пользователей

• Почасовые тренды запросов

• Активность недавних вызовов инструментов

На