Journey / SameUp CMS MCP Server

Es un servidor de Model Context Protocol (MCP) desarrollado para Journey / SameUp CMS. Permite a los asistentes de inteligencia artificial (Claude Desktop, Cursor, Antigravity, etc.) gestionar componentes y páginas hablando directamente con la API REST del CMS.

Características

• TypeScript moderno y MCP SDK: herramientas con tipado seguro basadas en @modelcontextprotocol/sdk y zod.

• Autenticación automática: inicia sesión automáticamente en la API del CMS (/api/v1/login), almacena la cookie de autenticación (at) devuelta y la renueva automáticamente cuando caduca.

• Compatible con desarrollo local: tolera automáticamente los certificados SSL autofirmados (self-signed) (CMS_IGNORE_SSL=true).

Instalación y ejecución

1. Instalación de dependencias

pnpm install

2. Variables de entorno (.env)

Configura el archivo .env en el directorio raíz:

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. Compilación y arranque

# Projeyi derle
pnpm run build

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

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

Herramientas MCP disponibles (Tools)

1. list_components

Lista todos los componentes activos definidos en SameUp CMS (Custom, SingleLine, Markdown, Photo, Dropdown, etc.).

Parámetros:

• search (string, opcional): Filtra por el título del componente o el slug (p. ej.: "banner", "markdown").

• type (string, opcional): Filtra por tipo de componente (p. ej.: "Custom", "SingleLine", "Markdown").

• includeDetails (boolean, opcional, por defecto: false): cuando se pasa true, también recupera los subcampos (children) de los componentes Custom.

2. get_component_detail

Obtiene jerárquicamente todas las propiedades de un componente concreto según su ID o slug y, si es de tipo Custom, también sus subcomponentes (children).

Parámetros:

• id (number, opcional): ID numérico del componente (p. ej.: 1, 25).

• slug (string, opcional): Nombre slug del componente (p. ej.: "announcements", "app-banner"). (Nota: debe proporcionarse al menos uno de los campos id o slug).

3. create_component

Define una nueva plantilla de componente en el CMS. En una sola llamada se puede crear tanto un componente principal Custom como sus campos children asociados.

Parámetros:

• title (string, obligatorio): Nombre del componente (p. ej.: "Hero Banner", "Feature Card").

• slug (string, obligatorio): Slug único que coincide con el front-end (p. ej.: "hero-banner", "feature-card").

• componentType (string, obligatorio): "Custom", "SingleLine", "Markdown", "Photo", "Document", "Dropdown", "Video", "Form", "FormItem", "List".

• canBeRepeated (boolean, opcional, por defecto: false): ¿Es una lista repetible?

• reusable (boolean, opcional, por defecto: true): ¿Es reutilizable?

• data (string, opcional): Datos/texto por defecto.

• parentId (number, opcional): ID del componente padre si se va a añadir bajo un componente principal existente.

• children (array, opcional): Lista de subcampos para componentes Custom (title, slug, componentType, canBeRepeated, reusable, data).

Configuración de IDE / cliente MCP

Configuración de Claude Desktop / Cursor / Antigravity

Puedes añadir el siguiente bloque a tu archivo mcp_config.json o 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"
      }
    }
  }
}