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
  • 📦 Sürüm Süreci
• Lisans

🔌 Hızlı Başlangıç

🔑 Ön Koşullar

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

1. Bir Kontent.ai hesabı - Hesabınız yoksa kaydolun.
2. Bir proje - Ç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

Akışkan 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 GEREKLİDİR. 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
• list-content-type-usages – Bir Kontent.ai içerik türünün nerede kullanıldığını listeleyin
• 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 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 kullanarak (move, addInto, remove, replace) 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 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ış
• 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 – Belirli bir içerik öğesinin tüm Kontent.ai içerik öğesi çevirilerini alın — her dil sürümü (varyantı)
• list-content-item-variants – İçerik öğesi varyantlarıyla (dil sürümleri/çeviriler) 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 öğeler 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 gönderin (değer artı dokunulmadan bırakılan bileşenler dahil tam bileşenler dizisi)
• 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 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 anlam ve kavramlara göre içerik 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 aktif hem de aktif olmayanları 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 - 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" izniyle 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ıramazsınız
• delete-workflow – Kimliğe göre bir Kontent.ai iş akışını silin. İş akışı herhangi bir içerik öğesi tarafından kullanımda 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şır; içeriği taslaktan incelemeye, incelemeden yayınlanmışa taşıma 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ından kaldırılmasını yapın veya zamanlayın. Bu işlem varyantı hemen yayından 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
• cancel-scheduled-publishing-content-item-variant – Kontent.ai'de bir içerik öğesi varyantının zamanlanmış yayınlanmasını iptal edin. Bu işlem, yayınlanmak üzere zamanlanmış bir varyantı önceki iş akışı adımına geri döndürür ve daha fazla düzenlemeye olanak tanır

⚙️ 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 (Akışkan HTTP)

Akışkan 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 taşıyıcı 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şlemesine olanak tanır.

KONTENT_API_KEY ve KONTENT_ENVIRONMENT_ID bu taşımada, sunucunun ortamında ayarlanmış olsalar bile yok sayılır. Her istek kendi kimlik bilgilerini taşımalıdır; taşımayan, sunucununkilerle sunulmak yerine reddedilir.

🔒 Güvenlik

Dolaylı komut istemi enjeksiyonu

Bu sunucunun döndürdüğü içerik (örneğin, bir editör tarafından yazılmış bir öğe), bağlı bir LLM'nin talimat olarak yorumlayabileceği metinler içerebilir — dolaylı prompt enjeksiyonu. Ele geçirilmiş bir aracı, yıkıcı araç çağrılarına (sil / yayından kaldır / üzerine yaz) veya yayınlanmamış taslakların sızması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 çözemez; bu nedenle savunma katmanlıdır:

• En düşük yetkili Management API anahtarını kullanın. Sunucu, kendisine verilen anahtarla hareket eder. 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 — model davranışından bağımsız olduğu için en güçlü kontroldür.
• İnsanı döngüde tutun. Her araç MCP ek açıklamaları taşır — okumalar readOnlyHint, yalnızca oluşturma araçları eklemelidir ve verilerin üzerine yazan veya kaldıran araçlar destructiveHint — uyumlu istemciler bunları okumaları otomatik onaylamak ve yıkıcı çağrılardan önce soru sormak için kullanır. Sunucuyu böyle bir istemciyle çalıştırın ve yazma yetkisine sahip bir anahtara karşı başsız otomatik onay kurulumlarından kaçının.
• İstemciniz destekliyorsa istemci tarafı bir kapı ekleyin. Bazı istemciler (örneğin, Claude Code hooks), modelden bağımsız olarak yıkıcı bir araç çalışmadan önce deterministik olarak 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, garanti değildir. Güvenlik sorunlarını özel olarak security@kontent.ai adresine bildirin.

🚀 Taşıma Seçenekleri

📟 STDIO Taşıma

Sunucuyu STDIO taşıma 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 Taşıma (Çok Kiracılı)

Akışkan HTTP taşıma, tek bir sunucu örneğinden birden fazla Kontent.ai ortamına hizmet verir. Her istek, URL yol parametreleri ve Bearer kimlik doğrulaması yoluyla kimlik bilgileri 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> öğesini Kontent.ai ortam kimliğinizle (GUID) ve <management-api-key> öğesini 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ı programı
  • app.ts - Akışkan HTTP taşıma için Express uygulama fabrikası
  • 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 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 Yayınlama 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 öğelerini günceller ve server.json ile senkronize eder
2. Değişikliğ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 de etiket olarak kullanarak, otomatik oluşturulan sürüm notlarıyla yeni bir GitHub sürümü oluşturun
5. Yayınlama, npm ve GitHub MCP kayıt defterine yayınlayan otomatik bir iş akışını tetikler

Lisans

MIT