Kontent.ai

Kontent.ai MCP Sunucusu

İçerik operasyonlarınızı Kontent.ai için yapay zeka destekli araçlarla dönüştürün. Yapılandırılmış içeriğinizi favori yapay zeka destekli düzenleyicinizde doğal dil konuşmalarıyla oluşturun, yönetin ve keşfedin.

Kontent.ai MCP Sunucusu, Kontent.ai projelerinizi Claude, Cursor ve VS Code gibi yapay zeka araçlarına bağlamak için Model Context Protocol'ü uygular. Yapay zeka modellerinin içerik yapınızı anlamasını ve doğal dil talimatlarıyla işlemler gerçekleştirmesini sağlar.

✨ Temel Özellikler

• 🚀 Hızlı prototipleme: Diyagramlarınızı saniyeler içinde canlı içerik modellerine dönüştürün
• 📈 Veri Görselleştirme: İçerik modelinizi istediğiniz formatta görselleştirin

İçindekiler

• ✨ Temel Özellikler
• 🔌 Hızlı Başlangıç
• 🛠️ Mevcut Araçlar
• ⚙️ Yapılandırma
• 🔒 Güvenlik
• 🚀 Taşıma Seçenekleri
• 💻 Geliştirme
  • 🛠 Yerel Kurulum
  • 📂 Proje Yapısı
  • 🔍 Hata Ayıklama
  • 📦 Yayın Süreci
• Lisans

🔌 Hızlı Başlangıç

🔑 Ön Koşullar

MCP sunucusunu kullanmadan önce şunlara ihtiyacınız var:

1. Kontent.ai hesabı - Hesabınız yoksa kaydolun.
2. Bir proje - Üzerinde çalışmak için bir proje oluşturun.
3. Yönetim API anahtarı - Uygun izinlerle bir anahtar oluşturun.
4. Ortam kimliği - Ortam kimliğinizi alın.

🛠 Kurulum Seçenekleri

Kontent.ai MCP Sunucusunu npx ile çalıştırabilirsiniz:

STDIO Taşıma

npx @kontent-ai/mcp-server@latest stdio

Streamable HTTP Taşıma

npx @kontent-ai/mcp-server@latest shttp

🛠️ Mevcut Araçlar

Yama İşlemleri Kılavuzu

• get-patch-guide – 🚨 Herhangi bir yama işleminden ÖNCE gereklidir. Varlık türüne göre Kontent.ai yama işlemleri kılavuzunu alın

İçerik Türü Yönetimi

• get-content-type – Kimliğe göre Kontent.ai içerik türünü alın
• list-content-types – Tüm Kontent.ai içerik türlerini alın
• create-content-type – Yeni Kontent.ai içerik türü oluşturun
• patch-content-type – Yama işlemlerini kullanarak (move, addInto, remove, replace) kod adına göre mevcut Kontent.ai içerik türünü güncelleyin
• delete-content-type – Kimliğe göre Kontent.ai içerik türünü silin

İçerik Türü Parçacığı Yönetimi

• get-content-type-snippet – Kimliğe göre Kontent.ai içerik türü parçacığını alın
• list-content-type-snippets – Tüm Kontent.ai içerik türü parçacıklarını alın
• create-content-type-snippet – Yeni Kontent.ai içerik türü parçacığı oluşturun
• patch-content-type-snippet – Yama işlemlerini kullanarak (move, addInto, remove, replace) kimliğe göre mevcut Kontent.ai içerik türü parçacığını güncelleyin
• delete-content-type-snippet – Kimliğe göre Kontent.ai içerik türü parçacığını silin

Taksonomi Yönetimi

• get-taxonomy-group – Kimliğe göre Kontent.ai taksonomi grubunu alın
• list-taxonomy-groups – Tüm Kontent.ai taksonomi gruplarını alın
• create-taxonomy-group – Yeni Kontent.ai taksonomi grubu oluşturun
• patch-taxonomy-group – Yama işlemlerini kullanarak (addInto, move, remove, replace) Kontent.ai taksonomi grubunu güncelleyin
• delete-taxonomy-group – Kimliğe göre Kontent.ai taksonomi grubunu silin

İçerik Öğesi Yönetimi

• get-content-item – Kimliğe göre Kontent.ai içerik öğesini alın
• get-content-item-variant – Kontent.ai içerik öğesi varyantını (dil sürümü/çeviri) alın. Geçerli sürümü döndürür — taslak varsa taslak, aksi takdirde yayınlanmış sürüm
• get-published-content-item-variant-version – Kontent.ai içerik öğesi varyantının yayınlanmış sürümünü alın. Daha yeni bir taslak sürüm mevcutken şu anda yayınlanmış (canlı) içeriğe ihtiyaç duyduğunuzda kullanın
• get-content-item-translations – Belirli bir içerik öğesinin tüm dil sürümlerini (varyantlarını) yani tüm Kontent.ai içerik öğesi çevirilerini alın
• list-content-item-variants – İçerik öğesi varyantlarıyla (dil sürümleri/çeviriler) birlikte Kontent.ai içerik öğelerini listeleyin, filtreleyin, arayın
• create-content-item – Yeni Kontent.ai içerik öğesi oluşturun (yalnızca kapsayıcıyı oluşturur, dil sürümleri/çeviriler eklemek için create-content-item-variant kullanın)
• update-content-item – Kimliğe göre mevcut Kontent.ai içerik öğesini güncelleyin. İçerik öğesi zaten mevcut olmalıdır - bu araç yeni öğe oluşturmaz
• delete-content-item – Kimliğe göre Kontent.ai içerik öğesini silin
• create-content-item-variant – Geçerli kullanıcıyı katkıda bulunan olarak atayarak Kontent.ai içerik öğesi varyantı oluşturun. Öğe değerleri, içerik türünde tanımlanan sınırlamaları ve yönergeleri karşılamalıdır. Yalnızca ayarlamak istediğiniz öğeleri gönderin; atlananlar boş olarak başlatılır
• update-content-item-variant – Bir içerik öğesinin Kontent.ai içerik öğesi varyantını güncelleyin. Öğe değerleri, içerik türünde tanımlanan sınırlamaları ve yönergeleri karşılamalıdır. Yalnızca değiştirmek istediğiniz öğeleri gönderin — atlanan öğelere dokunulmaz. Bileşenli zengin metin öğeleri için tam öğeyi (değer ve dokunulmadan bırakılan bileşenler dahil tam bileşenler dizisi) gönderin
• create-new-content-item-variant-version – Kontent.ai içerik öğesi varyantının yeni sürümünü oluşturun. Bu işlem, mevcut bir içerik öğesi varyantının yeni bir sürümünü oluşturur; içerik sürümleme ve yayınlanmış içerikten yeni taslaklar oluşturmak için kullanışlıdır
• delete-content-item-variant – Kontent.ai içerik öğesi varyantını silin
• bulk-get-content-item-variants – Öğe ve dil referans çiftlerine göre Kontent.ai içerik öğelerini ve içerik öğesi varyantlarını toplu olarak alın. Belirli öğe+dil çiftleri için tam içerik verilerini almak üzere list-content-item-variants sonrasında kullanın. İstenen dilde varyantı olmayan öğeler, varyant özelliği olmadan öğeyi döndürür. Devam belirteciyle sayfalanmış sonuçlar döndürür
• search-content-item-variants – Belirli bir içerik öğesi varyantında içeriği anlam ve kavramlara göre bulmak için yapay zeka destekli anlamsal arama. Şu durumlarda kullanın: kesin anahtar kelimeleri bilmediğiniz kavramsal aramalar. Sınırlı filtreleme seçenekleri (yalnızca varyant kimliği)

Varlık Yönetimi

• get-asset – Kimliğe göre belirli bir Kontent.ai varlığını alın
• list-assets – Tüm Kontent.ai varlıklarını alın
• update-asset – Kimliğe göre Kontent.ai varlığını güncelleyin

Varlık Klasörü Yönetimi

• list-asset-folders – Tüm Kontent.ai varlık klasörlerini listeleyin
• patch-asset-folders – Yama işlemlerini kullanarak Kontent.ai varlık klasörlerini değiştirin (yeni klasörler eklemek için addInto, adları değiştirmek için rename, klasörleri silmek için remove)

Dil Yönetimi

• list-languages – Tüm Kontent.ai dillerini alın (hem etkin hem de etkin olmayanları içerir - is_active özelliğini kontrol edin)
• create-language – Yeni Kontent.ai dili oluşturun (diller her zaman etkin olarak oluşturulur)
• patch-language – Değiştirme işlemlerini kullanarak Kontent.ai dilini güncelleyin (yalnızca etkin diller değiştirilebilir - etkinleştirmek/devre dışı bırakmak için Kontent.ai web arayüzünü kullanın)

Koleksiyon Yönetimi

• list-collections – Tüm Kontent.ai koleksiyonlarını alın. Koleksiyonlar, ortamınızdaki içerik öğeleri için sınırlar belirler ve içeriği ekip, marka veya projeye göre düzenlemeye yardımcı olur
• patch-collections – Yama işlemlerini kullanarak Kontent.ai koleksiyonlarını güncelleyin (yeni koleksiyonlar eklemek için addInto, yeniden sıralamak için move, boş koleksiyonları silmek için remove, yeniden adlandırmak için replace)

Alan Yönetimi

• list-spaces – Tüm Kontent.ai alanlarını alın
• create-space – Bir web sitesini veya kanalı yönetmek için yeni Kontent.ai alanı oluşturun
• patch-space – Değiştirme işlemlerini kullanarak Kontent.ai alanını yamalayın
• delete-space – Kontent.ai alanını silin

Rol Yönetimi

• list-roles – Tüm Kontent.ai rollerini alın. "Özel rolleri yönet" iznine sahip Enterprise veya Flex planı gerektirir

İş Akışı Yönetimi

• list-workflows – Tüm Kontent.ai iş akışlarını alın. İş akışları, içerik yaşam döngüsü aşamalarını ve aralarındaki geçişleri tanımlar
• create-workflow – Özel adımlar, geçişler, kapsamlar ve rol izinleriyle yeni Kontent.ai iş akışı oluşturun
• update-workflow – Kimliğe göre mevcut bir Kontent.ai iş akışını güncelleyin. Adımları, geçişleri, kapsamları ve rol izinlerini değiştirin. Kullanımdaki adımları kaldıramazsınız
• delete-workflow – Kimliğe göre bir Kontent.ai iş akışını silin. İş akışı hiçbir içerik öğesi tarafından kullanılıyor olmamalıdır
• change-content-item-variant-workflow-step – Kontent.ai'de bir içerik öğesi varyantının iş akışı adımını değiştirin. Bu işlem, bir içerik öğesi varyantını iş akışında farklı bir adıma taşıyarak içeriği taslaktan incelemeye, incelemeden yayınlanmışa taşıma gibi içerik yaşam döngüsü yönetimini etkinleştirir
• publish-content-item-variant – Kontent.ai'de bir içerik öğesinin içerik öğesi varyantını yayınlayın veya planlayın. Bu işlem varyantı hemen yayınlayabilir veya isteğe bağlı saat dilimi belirtimiyle belirli bir gelecek tarih ve saatte yayınlanmak üzere planlayabilir
• unpublish-content-item-variant – Kontent.ai'de bir içerik öğesinin içerik öğesi varyantının yayınını kaldırın veya planlayın. Bu işlem varyantın yayınını hemen kaldırabilir (Delivery API üzerinden kullanılamaz hale getirir) veya isteğe bağlı saat dilimi belirtimiyle belirli bir gelecek tarih ve saatte yayından kaldırılmak üzere planlayabilir
• cancel-scheduled-publishing-content-item-variant – Kontent.ai'de bir içerik öğesi varyantının planlanmış yayınını iptal edin. Bu işlem, yayınlanmak üzere planlanmış bir varyantı önceki iş akışı adımına geri döndürerek daha fazla düzenleme yapılmasını sağlar

⚙️ Yapılandırma

Sunucu, her biri kendi taşımasına bağlı iki modu destekler:

Tek Kiracılı Mod (STDIO)

Kimlik bilgilerini ortam değişkenleriyle yapılandırın:

Çok Kiracılı Mod (Streamable HTTP)

Streamable HTTP taşıması için kimlik bilgileri istek başına sağlanır:

• Ortam Kimliği URL yol parametresi olarak: /{environmentId}/mcp
• API Anahtarı Authorization başlığında Bearer belirteci olarak: Authorization: Bearer <api-key>

Bu, tek bir sunucu örneğinin kimlik bilgisi ortam değişkenleri gerektirmeden birden fazla Kontent.ai ortamı için istekleri işlemesini sağlar.

🔒 Güvenlik

Dolaylı komut enjeksiyonu

Bu sunucu tarafından döndürülen içerik (örneğin, bir editör tarafından yazılan bir öğe), bağlı bir LLM'nin talimat olarak yorumlayabileceği metin içerebilir — dolaylı komut enjeksiyonu. Ele geçirilmiş bir aracı, yıkıcı araç çağrılarına (silme / yayından kaldırma / üzerine yazma) veya yayınlanmamış taslakların sızdırılmasına yönlendirilebilir. Bu, sektör genelinde çözülmemiş bir sorundur ve sunucu, döndürdüğü içeriği dönüştürerek bunu güvenilir şekilde düzeltemez, bu nedenle savunma katmanlıdır:

• En düşük ayrıcalıklı Management API anahtarı kullanın. Sunucu, kendisine verilen anahtarla çalışır. Salt okunur bir anahtarla, ele geçirilmiş bir aracının yıkıcı çağrısı API sınırında basitçe başarısız olur — bu en güçlü kontroldür, çünkü model davranışından bağımsız olarak geçerlidir.
• Bir insanı döngüde tutun. Her araç MCP ek açıklamaları taşır — okumalar readOnlyHint, yalnızca oluşturan araçlar eklemelidir ve verilerin üzerine yazan veya silen araçlar destructiveHint şeklindedir — uyumlu istemciler bunları okumaları otomatik onaylamak ve yıkıcı çağrılardan önce kullanıcıya soru sormak için kullanır. Sunucuyu böyle bir istemciyle çalıştırın ve yazma yetkisine sahip bir anahtarla başsız (headless) otomatik onay kurulumlarından kaçının.
• İstemciniz destekliyorsa istemci tarafı bir kapı (gate) ekleyin. Bazı istemciler (örneğin, Claude Code hooks) modelden bağımsız olarak, yıkıcı bir araç çalışmadan önce belirlenimci (deterministik) bir şekilde soru sormanıza olanak tanır. Bu yerel olarak yapılandırılır; bir sunucu bunu zorunlu kılamaz.

Bunlar ipuçlarıdır, garantiler değildir. Güvenlik sorunlarını özel olarak security@kontent.ai adresine bildirin.

🚀 Taşıma Seçenekleri

📟 STDIO Taşıması

Sunucuyu STDIO taşımasıyla çalıştırmak için MCP istemcinizi şu şekilde yapılandırın:

{
  "kontent-ai-stdio": {
      "command": "npx",
      "args": ["@kontent-ai/mcp-server@latest", "stdio"],
      "env": {
        "KONTENT_API_KEY": "<management-api-key>",
        "KONTENT_ENVIRONMENT_ID": "<environment-id>"
      }
    }
}

🌊 Streamable HTTP Taşıması (Çok Kiracılı)

Streamable HTTP taşıması, tek bir sunucu örneğinden birden fazla Kontent.ai ortamına hizmet verir. Her istek, kimlik bilgilerini URL yol parametreleri ve Bearer kimlik doğrulamasıyla sağlar.

Önce sunucuyu başlatın:

npx @kontent-ai/mcp-server@latest shttp

{
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/<environment-id>/mcp",
      "headers": {
        "Authorization": "Bearer <management-api-key>"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "apiKey",
      "type": "password",
      "description": "Kontent.ai API Key"
    },
    {
      "id": "environmentId",
      "type": "text",
      "description": "Environment ID"
    }
  ],
  "servers": {
    "kontent-ai-multi": {
      "uri": "http://localhost:3001/${inputs.environmentId}/mcp",
      "headers": {
        "Authorization": "Bearer ${inputs.apiKey}"
      }
    }
  }
}

{
  "mcpServers": {
    "kontent-ai-multi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3001/<environment-id>/mcp",
        "--header",
        "Authorization: Bearer <management-api-key>"
      ]
    }
  }
}

claude mcp add --transport http kontent-ai-multi \
  "http://localhost:3001/<environment-id>/mcp" \
  --header "Authorization: Bearer <management-api-key>"

[!IMPORTANT] <environment-id> değerini Kontent.ai ortam kimliğinizle (GUID) ve <management-api-key> değerini anahtarınızla değiştirin.

💻 Geliştirme

🛠 Yerel Kurulum

# Clone the repository
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# Install dependencies
npm ci

# Build the project
npm run build

# Start the server
npm run start:stdio  # For STDIO transport
npm run start:shttp  # For Streamable HTTP transport

# Start the server with automatic reloading (no need to build first)
npm run dev:stdio  # For STDIO transport
npm run dev:shttp  # For Streamable HTTP transport

📂 Proje Yapısı

• src/ - Kaynak kodu
  • tools/ - MCP araç uygulamaları
  • clients/ - Kontent.ai API istemci kurulumu
  • schemas/ - Veri doğrulama şemaları
  • utils/ - Yardımcı işlevler
    • errorHandler.ts - MCP araçları için standartlaştırılmış hata işleme
    • throwError.ts - Genel hata fırlatma yardımcı aracı
  • server.ts - Ana sunucu kurulumu ve araç kaydı
  • bin.ts - Her iki taşıma türünü de işleyen tek giriş noktası

🔍 Hata Ayıklama

Hata ayıklama için MCP denetçisini (inspector) kullanabilirsiniz:

npx @modelcontextprotocol/inspector -e KONTENT_API_KEY=<key> -e KONTENT_ENVIRONMENT_ID=<env-id> node path/to/build/bin.js

Veya çalışan bir streamable HTTP sunucusunda MCP denetçisini kullanın:

npx @modelcontextprotocol/inspector

Bu, mevcut araçları incelemek ve test etmek için bir web arayüzü sağlar.

📦 Yayın Süreci

Yeni bir sürüm yayınlamak için:

1. npm version [patch|minor|major] kullanarak sürümü artırın — bu, package.json ve package-lock.json değerlerini günceller ve server.json ile eşitler
2. Commit'i dalınıza gönderin ve bir pull request oluşturun
3. Pull request'i birleştirin
4. Otomatik oluşturulan sürüm notlarını kullanarak sürüm numarasını hem ad hem de etiket olarak belirten yeni bir GitHub release oluşturun
5. Release'i yayınlamak, npm ve GitHub MCP kayıt defterine yayınlayan otomatik bir iş akışını tetikler

Lisans

MIT