Kontent.ai

Kontent.ai MCP Sunucusu

Kontent.ai için yapay zeka destekli araçlarla içerik operasyonlarınızı dönüştürün. Favori yapay zeka etkin düzenleyicinizde doğal dil konuşmaları aracılığıyla yapılandırılmış içeriğinizi 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 Bağlam Protokolü'nü 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 herhangi bir formatta görselleştirin

İçindekiler

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

🔌 Hızlı Başlangıç

🔑 Ön Koşullar

MCP sunucusunu kullanabilmeniz için şunlara ihtiyacınız vardır:

1. Bir Kontent.ai hesabı - Hesabınız yoksa kaydolun.
2. Bir proje - Çalışmak için bir proje oluşturun.
3. Management API anahtarı - Uygun izinlere sahip 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 Aktarımı

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

Akışkan HTTP Aktarımı

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

🛠️ Mevcut Araçlar

Yama İşlemleri Kılavuzu

• get-patch-guide – 🚨 Herhangi bir yama işleminden önce ZORUNLUDUR. Varlık türüne göre Kontent.ai için 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 (taşı, içine ekle, kaldır, değiştir) kullanarak kod adına göre mevcut bir Kontent.ai içerik türünü güncelleyin
• delete-content-type – Kimliğe göre bir 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 (taşı, içine ekle, kaldır, değiştir) kullanarak kimliğe göre mevcut bir Kontent.ai içerik türü parçacığını güncelleyin
• delete-content-type-snippet – Kimliğe göre bir 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 (içine ekle, taşı, kaldır, değiştir) kullanarak 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ü/çevirisi) alın. Mevcut sürümü döndürür — varsa taslak, aksi takdirde yayınlanmış
• get-published-content-item-variant-version – Bir Kontent.ai içerik öğesi varyantının yayınlanmış sürümünü alın. Daha yeni bir taslak sürüm mevcut olduğunda ancak şu anda yayınlanmış (canlı) içeriğe ihtiyacınız olduğunda kullanın
• get-content-item-translations – Tüm Kontent.ai içerik öğesi çevirilerini alın — belirli bir içerik öğesinin her dil sürümü (varyantı)
• list-content-item-variants – İçerik öğesi varyantları (dil sürümleri/çevirileri) ile 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/çevirileri 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 öğeler oluşturmaz
• delete-content-item – Kimliğe göre Kontent.ai içerik öğesini silin
• create-content-item-variant – Mevcut 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şenler içeren zengin metin öğeleri için, tam öğeyi (değer artı dokunulmamış bileşenler dahil olmak üzere 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, içerik öğesi varyantlarıyla birlikte toplu olarak alın. Belirli öğe+dil çiftleri için tam içerik verilerini almak üzere list-content-item-variants işleminden sonra kullanın. İstenen dilde varyantı olmayan öğeler, varyant özelliği olmadan öğeyi döndürür. Devam belirteci ile sayfalandırılmış sonuçlar döndürür
• search-content-item-variants – Belirli bir içerik öğesi varyantında anlam ve kavramlara göre içerik bulmak için yapay zeka destekli anlamsal arama. Şunlar için kullanın: tam anahtar kelimeleri bilmediğinizde 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 içine ekle, adları değiştirmek için yeniden adlandır, klasörleri silmek için kaldır)

Dil Yönetimi

• list-languages – Tüm Kontent.ai dillerini alın (hem aktif hem de pasif olanları içerir - is_active özelliğini kontrol edin)
• create-language – Yeni Kontent.ai dili oluşturun (diller her zaman aktif olarak oluşturulur)
• patch-language – Değiştirme işlemlerini kullanarak Kontent.ai dilini güncelleyin (yalnızca aktif diller değiştirilebilir - aktifleştirmek/pasifleştirmek 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 ekibe, markaya 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 içine ekle, yeniden sıralamak için taşı, boş koleksiyonları silmek için kaldır, yeniden adlandırmak için değiştir)

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ımda olan adımlar kaldırılamaz
• delete-workflow – Kimliğe göre bir Kontent.ai iş akışını silin. İş akışı herhangi bir içerik öğesi tarafından kullanılmıyor olmalı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ğin taslaktan incelemeye, incelemeden yayınlanmışa taşınması gibi içerik yaşam döngüsü yönetimini sağlar
• publish-content-item-variant – Kontent.ai'de bir içerik öğesinin içerik öğesi varyantını yayınlayın veya zamanlayı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 zamanlayabilir
• unpublish-content-item-variant – Kontent.ai'de bir içerik öğesinin içerik öğesi varyantının yayınını kaldırın veya yayından kaldırmayı zamanlayın. Bu işlem, varyantın yayınını hemen kaldırabilir (Delivery API aracılığıyla kullanılamaz hale getirir) veya isteğe bağlı saat dilimi belirtimiyle belirli bir gelecek tarih ve saatte yayından kaldırılmak üzere zamanlayabilir

⚙️ Yapılandırma

Sunucu, her biri aktarımına bağlı iki modu destekler:

Tek Kiracılı Mod (STDIO)

Kimlik bilgilerini ortam değişkenleri aracılığıyla yapılandırın:

Çok Kiracılı Mod (Akışkan HTTP)

Akışkan HTTP aktarımı için kimlik bilgileri istek başına sağlanır:

• Ortam Kimliği bir URL yol parametresi olarak: /{environmentId}/mcp
• API Anahtarı, Yetkilendirme başlığında Taşıyıcı belirteç aracılığıyla: Authorization: Bearer <api-key>

Bu, tek bir sunucu örneğinin, kimlik bilgisi ortam değişkenleri gerektirmeden birden çok Kontent.ai ortamı için istekleri işlemesine olanak tanır.

🔒 Güvenlik

Dolaylı istem 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 metinler içerebilir — dolaylı istem enjeksiyonu. Ele geçirilmiş bir ajan, 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, sunucunun döndürdüğü içeriği dönüştürerek güvenilir bir şekilde çözemeyeceği, sektör çapında, çözülmemiş bir sorundur, bu nedenle savunma katmanlıdır:

• En az ayrıcalığa sahip bir Management API anahtarı kullanın. Sunucu, kendisine verilen anahtar ne ise onunla çalışır. Salt okunur bir anahtarla, ele geçirilmiş bir aracının yıkıcı çağrısı API sınırında başarısız olur — bu, model davranışından bağımsız olarak geçerli olduğu için en güçlü kontroldür.
• Döngüde bir insan bulundurun. Her araç MCP ek açıklamaları taşır — okumalar readOnlyHint, yalnızca oluşturma araçları eklemelidir ve verilerin üzerine yazan veya veri silen araçlar destructiveHint — uyumlu istemciler bunları okumaları otomatik onaylamak ve yıkıcı çağrılardan önce sormak için kullanır. Sunucuyu böyle bir istemciyle çalıştırın ve yazma yetkisine sahip bir anahtarla başsız otomatik onaylama kurulumlarından kaçının.
• İstemciniz destekliyorsa istemci tarafı bir kapı ekleyin. Bazı istemciler (örneğin, Claude Code kancaları), modelden bağımsız olarak yıkıcı bir araç çalışmadan önce deterministik olarak sormanıza izin verir. Bu yerel olarak yapılandırılır; bir sunucu bunu zorunlu kılamaz.

Bunlar ipuçlarıdır, garanti değildir. Güvenlik sorunlarını gizli olarak [email protected] adresine bildirin.

🚀 Aktarım Seçenekleri

📟 STDIO Aktarımı

Sunucuyu STDIO aktarımı ile ç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>"
      }
    }
}

🌊 Akışkan HTTP Aktarımı (Çok Kiracılı)

Akışkan HTTP aktarımı, tek bir sunucu örneğinden birden çok Kontent.ai ortamına hizmet verir. Her istek, URL yol parametreleri ve Bearer kimlik doğrulaması aracılığıyla kimlik bilgilerini 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>"

[!ÖNEMLİ] <environment-id> yerine Kontent.ai ortam kimliğinizi (GUID) ve <management-api-key> yerine anahtarınızı yazın.

💻 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 yönetimi
    • throwError.ts - Genel hata fırlatma yardımcısı
  • server.ts - Ana sunucu kurulumu ve araç kaydı
  • bin.ts - Her iki aktarım türünü de işleyen tek giriş noktası

🔍 Hata Ayıklama

Hata ayıklama için MCP denetçisini 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 akışkan 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.

📦 Sürüm 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, package-lock.json günceller ve server.json ile senkronize eder
2. Commit'i dalınıza gönderin ve bir çekme isteği oluşturun
3. Çekme isteğini birleştirin
4. Sürüm numarasını hem ad hem etiket olarak kullanarak, otomatik oluşturulan sürüm notlarıyla yeni bir GitHub sürümü oluşturun
5. Sürümü yayınlamak, npm ve GitHub MCP kayıt defterine yayınlayan otomatik bir iş akışını tetikler

Lisans

MIT