Journey / SameUp CMS MCP Server

Journey / SameUp CMS için geliştirilmiş Model Context Protocol (MCP) sunucusudur. Yapay zeka asistanlarının (Claude Desktop, Cursor, Antigravity vb.) doğrudan CMS REST API'si ile konuşarak bileşen ve sayfa yönetimi yapabilmesini sağlar.

Özellikler

• Modern TypeScript & MCP SDK: @modelcontextprotocol/sdk ve zod tabanlı tip güvenli araçlar.

• Otomatik Kimlik Doğrulama: CMS API'ye (/api/v1/login) otomatik oturum açar, dönen auth cookie'yi (at) saklar ve süresi dolduğunda otomatik yeniler.

• Local Geliştirme Uyumlu: Kendinden imzalı (self-signed) SSL sertifikalarını otomatik tolere eder (CMS_IGNORE_SSL=true).

Kurulum & Çalıştırma

1. Bağımlılıkları Yükleme

pnpm install

2. Ortam Değişkenleri (.env)

Kök dizinde .env dosyasını yapılandırın:

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. Derleme ve Başlatma

# Projeyi derle
pnpm run build

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

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

Mevcut MCP Araçları (Tools)

1. list_components

SameUp CMS üzerinde tanımlı tüm aktif bileşenleri (Custom, SingleLine, Markdown, Photo, Dropdown vb.) listeler.

Parametreler:

• search (string, opsiyonel): Bileşen başlığı veya slug'ında filtreleme (örn: "banner", "markdown").

• type (string, opsiyonel): Bileşen tipine göre filtreleme (örn: "Custom", "SingleLine", "Markdown").

• includeDetails (boolean, opsiyonel, varsayılan: false): true verildiğinde Custom bileşenlerin alt alanlarını (children) da getirir.

2. get_component_detail

Belirli bir bileşenin ID veya Slug bilgisine göre tüm özelliklerini ve eğer Custom tipindeyse alt çocuk bileşenlerini (children) hiyerarşik olarak getirir.

Parametreler:

• id (number, opsiyonel): Bileşenin sayısal ID'si (örn: 1, 25).

• slug (string, opsiyonel): Bileşenin slug adı (örn: "announcements", "app-banner"). (Not: id veya slug alanlarından en az biri verilmelidir).

3. create_component

CMS üzerinde yeni bir bileşen şablonu tanımlar. Tek bir çağrıda hem Custom bir ana bileşen hem de altına bağlı children alanları oluşturulabilir.

Parametreler:

• title (string, zorunlu): Bileşenin adı (örn: "Hero Banner", "Feature Card").

• slug (string, zorunlu): Front-end ile eşleşen benzersiz slug (örn: "hero-banner", "feature-card").

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

• canBeRepeated (boolean, opsiyonel, varsayılan: false): Tekrarlanabilir liste mi?

• reusable (boolean, opsiyonel, varsayılan: true): Yeniden kullanılabilir mi?

• data (string, opsiyonel): Varsayılan veri/metin.

• parentId (number, opsiyonel): Var olan bir ana bileşenin altına eklenecekse üst bileşen ID'si.

• children (array, opsiyonel): Custom bileşenler için alt alanlar listesi (title, slug, componentType, canBeRepeated, reusable, data).

IDE / MCP İstemci Yapılandırması

Claude Desktop / Cursor / Antigravity Config

mcp_config.json veya claude_desktop_config.json dosyanıza şu bloğu ekleyebilirsiniz:

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