Journey / SameUp CMS MCP Server

Это сервер Model Context Protocol (MCP), разработанный для Journey / SameUp CMS. Он позволяет ИИ-ассистентам (Claude Desktop, Cursor, Antigravity и др.) напрямую взаимодействовать с REST API CMS для управления компонентами и страницами.

Возможности

• Современный TypeScript и MCP SDK: типобезопасные инструменты на базе @modelcontextprotocol/sdk и zod.

• Автоматическая аутентификация: автоматически выполняет вход в CMS API (/api/v1/login), сохраняет возвращаемый auth-куки (at) и автоматически обновляет его по истечении срока действия.

• Совместимость с локальной разработкой: автоматически допускает самоподписанные SSL-сертификаты (CMS_IGNORE_SSL=true).

Установка и запуск

1. Установка зависимостей

pnpm install

2. Переменные окружения (.env)

Настройте файл .env в корневом каталоге:

CMS_API_URL=https://api-journey.sameup.dev
CMS_EMAIL=your-admin-email@sameup.co
CMS_PASSWORD=your-secure-password
CMS_IGNORE_SSL=true

3. Сборка и запуск

# Projeyi derle
pnpm run build

# Doğrudan derlenmiş dosyayı çalıştır
pnpm start

# Geliştirme modu (Hot reload)
pnpm run dev

Доступные MCP-инструменты (Tools)

1. list_components

Перечисляет все активные компоненты, определенные в SameUp CMS (Custom, SingleLine, Markdown, Photo, Dropdown и т. д.).

Параметры:

• search (string, необязательный): фильтрация по заголовку компонента или slug (например: "banner", "markdown").

• type (string, необязательный): фильтрация по типу компонента (например: "Custom", "SingleLine", "Markdown").

• includeDetails (boolean, необязательный, по умолчанию: false): при значении true также возвращает дочерние поля (children) компонентов Custom.

2. get_component_detail

Возвращает все свойства конкретного компонента по его ID или Slug, а если компонент имеет тип Custom, то также иерархически возвращает его дочерние компоненты (children).

Параметры:

• id (number, необязательный): числовой ID компонента (например: 1, 25).

• slug (string, необязательный): slug-имя компонента (например: "announcements", "app-banner"). (Примечание: должно быть указано хотя бы одно из полей id или slug).

3. create_component

Определяет новый шаблон компонента в CMS. За один вызов можно создать как основной компонент Custom, так и связанные с ним поля children.

Параметры:

• title (string, обязательный): название компонента (например: "Hero Banner", "Feature Card").

• slug (string, обязательный): уникальный slug, соответствующий фронтенду (например: "hero-banner", "feature-card").

• componentType (string, обязательный): "Custom", "SingleLine", "Markdown", "Photo", "Document", "Dropdown", "Video", "Form", "FormItem", "List".

• canBeRepeated (boolean, необязательный, по умолчанию: false): является ли повторяемым списком?

• reusable (boolean, необязательный, по умолчанию: true): можно ли переиспользовать?

• data (string, необязательный): данные/текст по умолчанию.

• parentId (number, необязательный): ID родительского компонента, если добавляется в существующий основной компонент.

• children (array, необязательный): список дочерних полей для компонентов Custom (title, slug, componentType, canBeRepeated, reusable, data).

Конфигурация IDE / MCP-клиента

Конфигурация Claude Desktop / Cursor / Antigravity

Вы можете добавить следующий блок в ваш файл mcp_config.json или claude_desktop_config.json:

{
  "mcpServers": {
    "journey-cms": {
      "command": "node",
      "args": [
        "/path/to/journey-mcp/dist/index.js"
      ],
      "env": {
        "CMS_API_URL": "https://api-journey.sameup.dev",
        "CMS_EMAIL": "your-admin-email@sameup.co",
        "CMS_PASSWORD": "your-secure-password",
        "CMS_IGNORE_SSL": "true"
      }
    }
  }
}