Contentful MCP Server

Uyarı

Bu topluluk tarafından yönetilen bir sunucudur! Contentful resmi bir sunucu yayınlamıştır ve bunu burada bulabilirsiniz

Contentful'un Content Management API'si ile entegre olan ve kapsamlı içerik yönetimi yetenekleri sağlayan bir MCP server uygulaması.

• Lütfen dikkat edin *; eğer kodu ilgilendirmiyorsa ve bu MCP'yi Claude Desktop'ta (veya MCP server'ları kullanabilen başka herhangi bir araçta) kullanmak istiyorsanız, bu repo'yu klonlamanıza gerek yoktur. Claude desktop'ta kurmak yeterlidir. Kurulum talimatları için "Claude Desktop ile Kullanım" bölümüne bakınız.

Özellikler

• İçerik Yönetimi: Girdiler ve varlıklar için tam CRUD işlemleri
• Yorum Yönetimi: Girdilerde yorumlar oluşturun, alın ve yönetin; düz metin ve zengin metin formatları ile başlık konuşmaları desteği
• Alan Yönetimi: Alanları ve ortamları oluşturun, güncelleyin ve yönetin
• İçerik Türleri: İçerik türü tanımlarını yönetin
• Yerelleştirme: Birden fazla dil desteği
• Yayın: İçerik yayın akışını kontrol edin
• Toplu İşlemler: Birden fazla girdi ve varlık arasında toplu yayın, yayından kaldırma ve doğrulama gerçekleştirin
• Akıllı Sayfalama: Liste işlemleri bağlam penceresi taşmasını önlemek için istek başına maksimum 3 öğe döndürür; yerleşik sayfalama desteğiyle

Sayfalama

LLM'lerde bağlam penceresi taşmasını önlemek için, liste işlemleri (search_entries ve list_assets gibi) istek başına 3 öğeyle sınırlandırılmıştır. Her yanıt içerir:

• Mevcut toplam öğe sayısı
• Mevcut sayfa öğeleri (maks 3)
• Kalan öğe sayısı
• Sonraki sayfa için Skip değeri
• LLM'yi daha fazla öğe almayı teklif etmeye yönlendiren mesaj

Bu sayfalama sistemi, LLM'nin bağlam penceresi limitlerini korurken büyük veri setlerini verimli bir şekilde işlemesine olanak sağlar.

Toplu İşlemler

Toplu işlemler özelliği, birden fazla içerik öğesinin eşzamanlı yönetimini sağlar:

• Asenkron İşleme: İşlemler asenkron olarak çalışır ve durum güncellemeleri sağlar
• Verimli İçerik Yönetimi: Tek bir API çağrısında birden fazla girdi veya varlığı işleyin
• Durum İzleme: Başarı ve başarısızlık sayılarıyla ilerlemeyi izleyin
• Kaynak Optimizasyonu: API çağrılarını azaltın ve toplu işlemler için performansı artırın

Bu toplu işlem araçları, içerik geçişleri, kitlesel güncellemeler veya toplu yayın iş akışları için idealdir.

Araçlar

Girdi Yönetimi

• search_entries: Sorgu parametrelerini kullanarak girdileri arayın
• create_entry: Yeni girdiler oluşturun
• get_entry: Mevcut girdileri alın
• update_entry: Girdi alanlarını güncelleyin
• delete_entry: Girdileri silin
• publish_entry: Girdileri yayınlayın
• unpublish_entry: Girdilerin yayınını kaldırın

Yorum Yönetimi

• get_comments: Durum filtresiyle (aktif, çözüldü, tümü) bir girdinin yorumlarını alın
• create_comment: Girdilerde yeni yorumlar oluşturun; düz metin ve zengin metin formatları desteğiyle. Mevcut yorumlara yanıt vermek için parent yorum ID'si sağlayarak başlık konuşmaları destekleyin
• get_single_comment: ID'ye göre bir girdinin belirli bir yorumunu alın
• delete_comment: Bir girdiden belirli bir yorumu silin
• update_comment: Mevcut yorumları yeni body içeriği veya durum değişiklikleriyle güncelleyin

Başlık Konuşmaları

Yorumlar yapılandırılmış konuşmaları etkinleştirmek ve 512 karakterlik limiti aşmak için başlık işlevini destekler:

• Yorumlara Yanıt Verin: Mevcut bir yoruma yanıt vermek için create_comment'de parent parametresini kullanın
• Başlık Konuşmaları: Belirli yorumlara yanıt vererek konuşma ağaçları oluşturun
• Genişletilmiş Tartışmalar: Başlık yanıtları oluşturarak 512 karakterlik limiti aşın ve daha uzun mesajları sürdürün
• Konuşma Bağlamı: İlgili yorumları başlık içinde organize ederek tartışmalarda bağlam koruyun

Örnek kullanım:

1. Ana yorum oluşturun: create_comment ile entryId, body ve status
2. Bu yoruma yanıt verin: create_comment ile entryId, body, status ve parent (yanıt verdiğiniz yorum ID'si)
3. Başlığı devam ettirin: Başlığın herhangi bir yorumuna yanıt verin ve onun ID'sini parent olarak kullanın

Toplu İşlemler

• bulk_publish: Birden fazla girdiy ve varlığı tek bir işlemde yayınlayın. Varlık dizisini (girdiler ve varlıklar) kabul eder ve yayınlarını toplu olarak işler.
• bulk_unpublish: Birden fazla girdiy ve varlığın yayınını tek bir işlemde kaldırın. bulk_publish'e benzer ancak içeriği delivery API'sinden kaldırır.
• bulk_validate: Birden fazla girdiy içerik tutarlılığı, referansları ve gerekli alanlar açısından doğrulayın. İçeriği değiştirmeden doğrulama sonuçlarını döndürün.

Varlık Yönetimi

• list_assets: Varlıkları sayfalama ile listeleyin (sayfa başına 3 öğe)
• upload_asset: Meta verilerle yeni varlıklar yükleyin
• get_asset: Varlık ayrıntılarını ve bilgisini alın
• update_asset: Varlık metaverilerini ve dosyalarını güncelleyin
• delete_asset: Varlıkları alandan silin
• publish_asset: Varlıkları delivery API'sine yayınlayın
• unpublish_asset: Varlıkların yayınını delivery API'sinden kaldırın

Alan & Ortam Yönetimi

• list_spaces: Mevcut alanları listeleyin
• get_space: Alan ayrıntılarını alın
• list_environments: Bir alandaki ortamları listeleyin
• create_environment: Yeni ortam oluşturun
• delete_environment: Ortamı silin

İçerik Türü Yönetimi

• list_content_types: Mevcut içerik türlerini listeleyin
• get_content_type: İçerik türü ayrıntılarını alın
• create_content_type: Yeni içerik türü oluşturun
• update_content_type: İçerik türünü güncelleyin
• delete_content_type: İçerik türünü silin
• publish_content_type: Bir içerik türünü yayınlayın

Geliştirme Araçları

MCP Inspector

Proje, geliştirme ve hata ayıklamaya yardımcı olan bir MCP Inspector aracı içerir:

• İnceleme Modu: npm run inspect çalıştırarak inspector'u başlatın, http://localhost:5173 adresine giderek inspector'u açabilirsiniz
• Watch Modu: Dosyalar değiştiğinde inspector'u otomatik olarak yeniden başlatmak için npm run inspect:watch kullanın
• Görsel Arayüz: Inspector, MCP araçlarını test etmek ve hata ayıklamak için web arayüzü sağlar
• Gerçek Zamanlı Test: Araçları deneyin ve yanıtlarını anında görün
• Toplu İşlem Testi: İlerleme ve sonuçlar hakkında görsel geri bildirimle toplu işlemleri test edin ve izleyin

Proje ayrıca her değişiklikte MCP server'ı yeniden derleyip yükleyen npm run dev komutu içerir.

Yapılandırma

Ön Koşullar

1. Contentful adresinde bir Contentful hesabı oluşturun
2. Hesap ayarlarınızdan bir Content Management API token'ı oluşturun

Ortam Değişkenleri

Bu değişkenler argüman olarak da ayarlanabilir

• CONTENTFUL_HOST / --host: Contentful Management API Endpoint'i (varsayılan: https://api.contentful.com)
• CONTENTFUL_MANAGEMENT_ACCESS_TOKEN / --management-token: Content Management API token'ınız
• ENABLE_HTTP_SERVER / --http: HTTP/SSE modunu etkinleştirmek için "true" olarak ayarlayın
• HTTP_PORT / --port: HTTP server'ı için port (varsayılan: 3000)
• HTTP_HOST / --http-host: HTTP server'ı için host (varsayılan: localhost)
• DISABLE_AI_ACTIONS: Başlangıçta AI Actions'u getirmeyi devre dışı bırakmak için "true" olarak ayarlayın (bu özelliğe erişiminiz yoksa yararlıdır)

Alan ve Ortam Kapsamı

LLM'nin yalnızca tanımlı alan/ortam ID'leri üzerinde işlemler yapmasını sağlamak için spaceId ve EnvironmentId'yi kapsamaya alabilirsiniz. Bu, belirli alanlar içinde çalışması gereken ajanları desteklemek için tasarlanmıştır. Hem SPACE_ID hem de ENVIRONMENT_ID ortam değişkenleri ayarlanırsa, araçlar bu değerlerin gerekli olduğunu bildirmez ve handler'lar CMA işlemleri yapmak için ortam değişkenlerini kullanır. Alan handler'larındaki araçlara da erişimi kaybedersiniz, çünkü bu araçlar alanlar arasında çalışır. --space-id ve --environment-id argümanlarını kullanarak SPACE_ID ve ENVIRONMENT_ID'yi de ekleyebilirsiniz

App Identity Kullanımı

Management token'ı sağlamak yerine, kimlik doğrulamasını işlemek için App Identity de kullanabilirsiniz. MCP server'ı çağırırken bir Contentful Uygulaması kurup yüklemeniz ve aşağıdaki parametreleri ayarlamanız gerekir:

• --app-id = Apptoken sağlayan app Id
• --private-key = Kullanıcı arayüzünde oluşturduğunuz ve app_id ile bağlı olan private key
• --space-id = Uygulamanın kurulu olduğu spaceId
• --environment-id = Uygulamanın kurulu olduğu environmentId (alan içinde)

Bu değerlerle, MCP server'ı tanımlı alan/ortam-id'de içerik işlemler yapması için geçici bir AppToken isteyecektir. Bu, özellikle bu MCP server'ını MCP client'ı olarak hareket eden backend sistemlerde (sohbet ajanları gibi) kullanırken yararlıdır

Claude Desktop ile Kullanım

Bu MCP'yi kullanmak için bu repo'yu klonlamanıza gerek yoktur, claude_desktop_config.json'unuza basitçe ekleyebilirsiniz:

~/Library/Application Support/Claude/claude_desktop_config.json dosyasını düzenleyin veya oluşturun ve aşağıdaki satırları ekleyin:

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": ["-y", "@ivotoby/contentful-management-mcp-server"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA token>"
      }
    }
  }
}

Eğer MCP Client'ınız ortam değişkenleri ayarlamayı desteklemiyorsa, yönetim token'ını şu şekilde bir argüman olarak da ayarlayabilirsiniz:

{
  "mcpServers": {
    "contentful": {
      "command": "npx",
      "args": [
        "-y",
        "@ivotoby/contentful-management-mcp-server",
        "--management-token",
        "<your token>",
        "--host",
        "http://api.contentful.com"
      ]
    }
  }
}

Smithery Üzerinden Kurulum

Contentful Management Server'ı Claude Desktop'a otomatik olarak Smithery üzerinden kurmak için:

npx -y @smithery/cli install @ivotoby/contentful-management-mcp-server --client claude

Claude Desktop ile Geliştirme ve Kullanım

Katkıda bulunmak ve Claude'un katkılarınızla ne yaptığını test etmek istiyorsanız;

• npm run dev çalıştırın, bu her değişiklikte MCP server'ını yeniden derleyen watcher'ı başlatacaktır
• claude_desktop_config.json'u projeye doğrudan referans gösterecek şekilde güncelleyin, örneğin;

{
  "mcpServers": {
    "contentful": {
      "command": "node",
      "args": ["/Users/ivo/workspace/contentful-mcp/bin/mcp-server.js"],
      "env": {
        "CONTENTFUL_MANAGEMENT_ACCESS_TOKEN": "<Your CMA Token>"
      }
    }
  }
}

Bu, MCP server'daki herhangi bir değişikliği Claude ile doğrudan test etmenize olanak sağlar, ancak yeni araçlar/kaynaklar eklerseniz Claude Desktop'ı yeniden başlatmanız gerekir

Taşıma Modları

MCP server'ı iki taşıma modunu destekler:

stdio Taşıması

Varsayılan taşıma modu, iletişim için standart giriş/çıkış akışlarını kullanır. Bu, Claude Desktop gibi stdio taşımasını destekleyen MCP client'ları ile entegrasyon için idealdir.

stdio modunu kullanmak için, server'ı --http bayrağı olmadan çalıştırın:

npx -y contentful-mcp --management-token YOUR_TOKEN
# veya alternatif olarak
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN

StreamableHTTP Taşıması

Server'ı ayrıca MCP protokolünde tanımlanan StreamableHTTP taşımasını da destekler. Bu mod, web tabanlı entegrasyonlar için veya server'ı bağımsız bir hizmet olarak çalıştırırken yararlıdır.

StreamableHTTP modunu kullanmak için --http bayrağıyla çalıştırın:

npx -y contentful-mcp --management-token YOUR_TOKEN --http --port 3000
# veya alternatif olarak
npx -y @ivotoby/contentful-management-mcp-server --management-token YOUR_TOKEN --http --port 3000

StreamableHTTP Ayrıntıları

• Resmi MCP StreamableHTTP taşımasını kullanır
• Standart MCP protokol işlemlerini destekler
• Durum korumak için oturum yönetimini içerir
• İnitialize/notify desenlerini uygun şekilde işler
• Standart MCP client'ları ile uyumludur
• Eski SSE taşımasının yerine modern yaklaşımı koyar

Uygulama, standart MCP protokol belirtimini takip ederek, herhangi bir MCP client'ının özel işleme ihtiyacı olmadan server'a bağlanmasına olanak sağlar.

Hata İşleme

Server, aşağıdakiler için kapsamlı hata işleme uygular:

• Kimlik doğrulama hataları
• Hız sınırlaması
• Geçersiz istekler
• Ağ sorunları
• API'ye özgü hatalar

Lisans

MIT License

İnce Baskı

Bu MCP Server, Claude'un (veya MCP kaynaklarını tüketebilen diğer ajanların) içerik, alanlar ve içerik modellerini güncellemesine ve silmesine olanak sağlar. Bu nedenle Claude'un Contentful alanlarınızla ne yapmasına izin verdiğinize dikkat edin!

Bu MCP server, Contentful tarafından resmi olarak desteklenmemektedir (henüz değil)