Journey / SameUp CMS MCP Server

Dies ist ein Model Context Protocol (MCP)-Server, der für Journey / SameUp CMS entwickelt wurde. Er ermöglicht KI-Assistenten (Claude Desktop, Cursor, Antigravity usw.), direkt mit der CMS-REST-API zu kommunizieren und Komponenten- und Seitenverwaltung durchzuführen.

Funktionen

• Modernes TypeScript & MCP SDK: Typsichere Tools basierend auf @modelcontextprotocol/sdk und zod.

• Automatische Authentifizierung: Meldet sich automatisch bei der CMS-API an (/api/v1/login), speichert das zurückgegebene Auth-Cookie (at) und erneuert es automatisch bei Ablauf.

• Lokale Entwicklungskompatibilität: Toleriert automatisch selbstsignierte SSL-Zertifikate (CMS_IGNORE_SSL=true).

Installation & Ausführung

1. Abhängigkeiten installieren

pnpm install

2. Umgebungsvariablen (.env)

Konfigurieren Sie die Datei .env im Stammverzeichnis:

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. Kompilieren und Starten

# Projeyi derle
pnpm run build

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

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

Verfügbare MCP-Tools

1. list_components

Listet alle auf SameUp CMS definierten aktiven Komponenten auf (Custom, SingleLine, Markdown, Photo, Dropdown usw.).

Parameter:

• search (string, optional): Filtert nach Komponententitel oder Slug (z. B. "banner", "markdown").

• type (string, optional): Filtert nach Komponententyp (z. B. "Custom", "SingleLine", "Markdown").

• includeDetails (boolean, optional, Standard: false): Wenn true angegeben wird, werden auch die Unterfelder (children) von Custom-Komponenten abgerufen.

2. get_component_detail

Ruft alle Eigenschaften einer bestimmten Komponente anhand ihrer ID oder ihres Slugs ab, und falls es sich um einen Custom-Typ handelt, auch die untergeordneten Kindkomponenten (children) hierarchisch.

Parameter:

• id (number, optional): Die numerische ID der Komponente (z. B. 1, 25).

• slug (string, optional): Der Slug-Name der Komponente (z. B. "announcements", "app-banner"). (Hinweis: Mindestens eines der Felder id oder slug muss angegeben werden).

3. create_component

Definiert eine neue Komponentenvorlage im CMS. Mit einem einzigen Aufruf können sowohl eine Custom-Hauptkomponente als auch die darunter liegenden children-Felder erstellt werden.

Parameter:

• title (string, erforderlich): Der Name der Komponente (z. B. "Hero Banner", "Feature Card").

• slug (string, erforderlich): Eindeutiger Slug, der mit dem Frontend übereinstimmt (z. B. "hero-banner", "feature-card").

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

• canBeRepeated (boolean, optional, Standard: false): Ist es eine wiederholbare Liste?

• reusable (boolean, optional, Standard: true): Ist es wiederverwendbar?

• data (string, optional): Standarddaten/-text.

• parentId (number, optional): Die ID der übergeordneten Komponente, falls sie unter einer vorhandenen Hauptkomponente hinzugefügt werden soll.

• children (array, optional): Liste der Unterfelder für Custom-Komponenten (title, slug, componentType, canBeRepeated, reusable, data).

IDE-/MCP-Client-Konfiguration

Konfiguration für Claude Desktop / Cursor / Antigravity

Sie können den folgenden Block zu Ihrer Datei mcp_config.json oder claude_desktop_config.json hinzufügen:

{
  "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"
      }
    }
  }
}