Kontent.ai

Server MCP Kontent.ai

Ubah operasi konten Anda dengan alat bertenaga AI untuk Kontent.ai. Buat, kelola, dan jelajahi konten terstruktur Anda melalui percakapan bahasa alami di editor berkemampuan AI favorit Anda.

Server MCP Kontent.ai mengimplementasikan Model Context Protocol untuk menghubungkan proyek Kontent.ai Anda dengan alat AI seperti Claude, Cursor, dan VS Code. Ini memungkinkan model AI memahami struktur konten Anda dan melakukan operasi melalui instruksi bahasa alami.

✨ Fitur Utama

• 🚀 Prototipe cepat: Ubah diagram Anda menjadi model konten langsung dalam hitungan detik
• 📈 Visualisasi Data: Visualisasikan model konten Anda dalam format apa pun yang Anda inginkan

Daftar Isi

• ✨ Fitur Utama
• 🔌 Memulai Cepat
• 🛠️ Alat yang Tersedia
• ⚙️ Konfigurasi
• 🔒 Keamanan
• 🚀 Opsi Transport
• 💻 Pengembangan
  • 🛠 Instalasi Lokal
  • 📂 Struktur Proyek
  • 🔍 Debugging
  • 📦 Proses Rilis
• Lisensi

🔌 Memulai Cepat

🔑 Prasyarat

Sebelum Anda dapat menggunakan server MCP, Anda memerlukan:

1. Akun Kontent.ai - Daftar jika Anda belum memiliki akun.
2. Proyek - Buat proyek untuk digunakan.
3. Kunci API Manajemen - Buat kunci dengan izin yang sesuai.
4. ID Lingkungan - Dapatkan ID lingkungan Anda.

🛠 Opsi Pengaturan

Anda dapat menjalankan Server MCP Kontent.ai dengan npx:

Transport STDIO

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

Transport HTTP Streamable

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

🛠️ Alat yang Tersedia

Panduan Operasi Patch

• get-patch-guide – 🚨 DIPERLUKAN sebelum operasi patch apa pun. Dapatkan panduan operasi patch untuk Kontent.ai berdasarkan jenis entitas

Manajemen Tipe Konten

• get-content-type – Dapatkan tipe konten Kontent.ai berdasarkan ID
• list-content-types – Dapatkan semua tipe konten Kontent.ai
• list-content-type-usages – Daftar di mana tipe konten Kontent.ai digunakan
• create-content-type – Buat tipe konten Kontent.ai baru
• patch-content-type – Perbarui tipe konten Kontent.ai yang ada berdasarkan codename menggunakan operasi patch (move, addInto, remove, replace)
• delete-content-type – Hapus tipe konten Kontent.ai berdasarkan ID

Manajemen Cuplikan Tipe Konten

• get-content-type-snippet – Dapatkan cuplikan tipe konten Kontent.ai berdasarkan ID
• list-content-type-snippets – Dapatkan semua cuplikan tipe konten Kontent.ai
• create-content-type-snippet – Buat cuplikan tipe konten Kontent.ai baru
• patch-content-type-snippet – Perbarui cuplikan tipe konten Kontent.ai yang ada berdasarkan ID menggunakan operasi patch (move, addInto, remove, replace)
• delete-content-type-snippet – Hapus cuplikan tipe konten Kontent.ai berdasarkan ID

Manajemen Taksonomi

• get-taxonomy-group – Dapatkan grup taksonomi Kontent.ai berdasarkan ID
• list-taxonomy-groups – Dapatkan semua grup taksonomi Kontent.ai
• create-taxonomy-group – Buat grup taksonomi Kontent.ai baru
• patch-taxonomy-group – Perbarui grup taksonomi Kontent.ai menggunakan operasi patch (addInto, move, remove, replace)
• delete-taxonomy-group – Hapus grup taksonomi Kontent.ai berdasarkan ID

Manajemen Item Konten

• get-content-item – Dapatkan item konten Kontent.ai berdasarkan ID
• get-content-item-variant – Ambil varian item konten Kontent.ai (versi bahasa/terjemahan). Mengembalikan versi saat ini — draf jika ada, jika tidak, versi yang diterbitkan
• get-published-content-item-variant-version – Ambil versi yang diterbitkan dari varian item konten Kontent.ai. Gunakan ketika versi draf yang lebih baru ada tetapi Anda memerlukan konten yang saat ini diterbitkan (live)
• get-content-item-translations – Dapatkan semua terjemahan item konten Kontent.ai — setiap versi bahasa (varian) dari item konten tertentu
• list-content-item-variants – Daftar, filter, cari item konten Kontent.ai dengan varian item konten (versi bahasa/terjemahan)
• create-content-item – Buat item konten Kontent.ai baru (hanya membuat wadah, gunakan create-content-item-variant untuk menambahkan versi bahasa/terjemahan)
• update-content-item – Perbarui item konten Kontent.ai yang ada berdasarkan ID. Item konten harus sudah ada - alat ini tidak akan membuat item baru
• delete-content-item – Hapus item konten Kontent.ai berdasarkan ID
• create-content-item-variant – Buat varian item konten Kontent.ai yang menetapkan pengguna saat ini sebagai kontributor. Nilai elemen harus memenuhi batasan dan pedoman yang ditentukan dalam tipe konten. Kirim hanya elemen yang ingin Anda atur; yang dihilangkan diinisialisasi kosong
• update-content-item-variant – Perbarui varian item konten Kontent.ai dari item konten. Nilai elemen harus memenuhi batasan dan pedoman yang ditentukan dalam tipe konten. Kirim hanya elemen yang ingin Anda ubah — elemen yang dihilangkan dibiarkan tidak tersentuh. Untuk elemen rich-text dengan komponen, kirim elemen lengkap (nilai plus array komponen lengkap, termasuk komponen yang tidak tersentuh)
• create-new-content-item-variant-version – Buat versi baru dari varian item konten Kontent.ai. Operasi ini membuat versi baru dari varian item konten yang ada, berguna untuk pembuatan versi konten dan membuat draf baru dari konten yang diterbitkan
• delete-content-item-variant – Hapus varian item konten Kontent.ai
• bulk-get-content-item-variants – Dapatkan massal item konten Kontent.ai dengan varian item kontennya berdasarkan pasangan referensi item dan bahasa. Gunakan setelah list-content-item-variants untuk mengambil data konten lengkap untuk pasangan item+bahasa tertentu. Item tanpa varian dalam bahasa yang diminta mengembalikan item tanpa properti varian. Mengembalikan hasil yang dipaginasi dengan token kelanjutan
• search-content-item-variants – Pencarian semantik bertenaga AI untuk menemukan konten berdasarkan makna dan konsep dalam varian item konten tertentu. Gunakan untuk: pencarian konseptual ketika Anda tidak tahu kata kunci yang tepat. Opsi pemfilteran terbatas (hanya ID varian)

Manajemen Aset

• get-asset – Dapatkan aset Kontent.ai tertentu berdasarkan ID
• list-assets – Dapatkan semua aset Kontent.ai
• update-asset – Perbarui aset Kontent.ai berdasarkan ID

Manajemen Folder Aset

• list-asset-folders – Daftar semua folder aset Kontent.ai
• patch-asset-folders – Ubah folder aset Kontent.ai menggunakan operasi patch (addInto untuk menambahkan folder baru, rename untuk mengubah nama, remove untuk menghapus folder)

Manajemen Bahasa

• list-languages – Dapatkan semua bahasa Kontent.ai (termasuk aktif dan tidak aktif - periksa properti is_active)
• create-language – Buat bahasa Kontent.ai baru (bahasa selalu dibuat sebagai aktif)
• patch-language – Perbarui bahasa Kontent.ai menggunakan operasi replace (hanya bahasa aktif yang dapat dimodifikasi - untuk mengaktifkan/menonaktifkan, gunakan UI web Kontent.ai)

Manajemen Koleksi

• list-collections – Dapatkan semua koleksi Kontent.ai. Koleksi menetapkan batas untuk item konten di lingkungan Anda dan membantu mengatur konten berdasarkan tim, merek, atau proyek
• patch-collections – Perbarui koleksi Kontent.ai menggunakan operasi patch (addInto untuk menambahkan koleksi baru, move untuk mengurutkan ulang, remove untuk menghapus koleksi kosong, replace untuk mengganti nama)

Manajemen Ruang

• list-spaces – Dapatkan semua ruang Kontent.ai
• create-space – Buat ruang Kontent.ai baru untuk mengelola situs web atau saluran
• patch-space – Patch ruang Kontent.ai menggunakan operasi replace
• delete-space – Hapus ruang Kontent.ai

Manajemen Peran

• list-roles – Dapatkan semua peran Kontent.ai. Memerlukan paket Enterprise atau Flex dengan izin "Kelola peran kustom"

Manajemen Alur Kerja

• list-workflows – Dapatkan semua alur kerja Kontent.ai. Alur kerja mendefinisikan tahapan siklus hidup konten dan transisi di antara mereka
• create-workflow – Buat alur kerja Kontent.ai baru dengan langkah, transisi, cakupan, dan izin peran kustom
• update-workflow – Perbarui alur kerja Kontent.ai yang ada berdasarkan ID. Ubah langkah, transisi, cakupan, dan izin peran. Tidak dapat menghapus langkah yang sedang digunakan
• delete-workflow – Hapus alur kerja Kontent.ai berdasarkan ID. Alur kerja tidak boleh digunakan oleh item konten apa pun
• change-content-item-variant-workflow-step – Ubah langkah alur kerja dari varian item konten di Kontent.ai. Operasi ini memindahkan varian item konten ke langkah yang berbeda dalam alur kerja, memungkinkan manajemen siklus hidup konten seperti memindahkan konten dari draf ke tinjauan, tinjauan ke diterbitkan, dll.
• publish-content-item-variant – Terbitkan atau jadwalkan varian item konten dari item konten di Kontent.ai. Operasi ini dapat segera menerbitkan varian atau menjadwalkannya untuk publikasi pada tanggal dan waktu tertentu di masa depan dengan spesifikasi zona waktu opsional
• unpublish-content-item-variant – Batalkan penerbitan atau jadwalkan pembatalan penerbitan varian item konten dari item konten di Kontent.ai. Operasi ini dapat segera membatalkan penerbitan varian (membuatnya tidak tersedia melalui Delivery API) atau menjadwalkannya untuk pembatalan penerbitan pada tanggal dan waktu tertentu di masa depan dengan spesifikasi zona waktu opsional
• cancel-scheduled-publishing-content-item-variant – Batalkan penerbitan terjadwal dari varian item konten di Kontent.ai. Operasi ini mengembalikan varian yang dijadwalkan untuk diterbitkan kembali ke langkah alur kerja sebelumnya, memungkinkan pengeditan lebih lanjut

⚙️ Konfigurasi

Server mendukung dua mode, masing-masing terkait dengan transportnya:

Mode Single-Tenant (STDIO)

Konfigurasikan kredensial melalui variabel lingkungan:

Mode Multi-Tenant (HTTP Streamable)

Untuk transport HTTP Streamable, kredensial diberikan per permintaan:

• ID Lingkungan sebagai parameter jalur URL: /{environmentId}/mcp
• Kunci API melalui token Bearer di header Authorization: Authorization: Bearer <api-key>

Ini memungkinkan satu instance server menangani permintaan untuk beberapa lingkungan Kontent.ai tanpa memerlukan variabel lingkungan kredensial.

KONTENT_API_KEY dan KONTENT_ENVIRONMENT_ID diabaikan pada transport ini, bahkan jika kebetulan diatur di lingkungan server. Setiap permintaan harus membawa kredensialnya sendiri; permintaan yang tidak membawanya ditolak daripada dilayani dengan kredensial server.

🔒 Keamanan

Injeksi prompt tidak langsung

Konten yang dikembalikan oleh server ini (misalnya, elemen yang ditulis oleh editor) dapat berisi teks yang ditafsirkan oleh LLM yang terhubung sebagai instruksi — indirect prompt injection. Agen yang dibajak dapat diarahkan untuk melakukan panggilan alat yang merusak (hapus / batalkan publikasi / timpa) atau membocorkan draf yang belum dipublikasikan. Ini adalah masalah yang belum terpecahkan di seluruh industri yang tidak dapat diperbaiki secara andal oleh server dengan mengubah konten yang dikembalikannya, sehingga pertahanan dilakukan berlapis:

• Gunakan kunci Management API dengan hak akses paling rendah. Server bertindak dengan kunci apa pun yang diberikan. Dengan kunci hanya-baca, panggilan merusak dari agen yang dibajak akan gagal di batas API — kontrol terkuat, karena tetap berlaku terlepas dari perilaku model.
• Libatkan manusia dalam proses. Setiap alat membawa anotasi MCP — pembacaan adalah readOnlyHint, alat khusus pembuatan bersifat aditif, dan alat yang menimpa atau menghapus data adalah destructiveHint — yang digunakan oleh klien yang patuh untuk menyetujui pembacaan secara otomatis dan meminta konfirmasi sebelum panggilan yang merusak. Jalankan server dengan klien seperti itu dan hindari pengaturan persetujuan otomatis tanpa pengawasan terhadap kunci yang dapat menulis.
• Tambahkan gerbang sisi klien jika klien Anda mendukungnya. Beberapa klien (misalnya, hook Claude Code) memungkinkan Anda meminta konfirmasi secara deterministik sebelum alat yang merusak dijalankan, terlepas dari model. Ini dikonfigurasi secara lokal; server tidak dapat menerapkannya.

Ini adalah petunjuk, bukan jaminan. Laporkan masalah keamanan secara pribadi ke security@kontent.ai.

🚀 Opsi Transport

📟 Transport STDIO

Untuk menjalankan server dengan transport STDIO, konfigurasikan klien MCP Anda dengan:

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

🌊 Transport HTTP Streamable (Multi-Tenant)

Transport HTTP Streamable melayani beberapa lingkungan Kontent.ai dari satu instance server. Setiap permintaan memberikan kredensial melalui parameter jalur URL dan autentikasi Bearer.

Pertama, mulai server:

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

[!PENTING] Ganti <environment-id> dengan ID lingkungan Kontent.ai Anda (GUID) dan <management-api-key> dengan kunci Anda.

💻 Pengembangan

🛠 Instalasi Lokal

# 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

📂 Struktur Proyek

• src/ - Kode sumber
  • tools/ - Implementasi alat MCP
  • clients/ - Pengaturan klien API Kontent.ai
  • schemas/ - Skema validasi data
  • utils/ - Fungsi utilitas
    • errorHandler.ts - Penanganan kesalahan terstandarisasi untuk alat MCP
    • throwError.ts - Utilitas lempar kesalahan generik
  • app.ts - Pabrik aplikasi Express untuk transport HTTP Streamable
  • server.ts - Pengaturan server utama dan pendaftaran alat
  • bin.ts - Titik masuk tunggal yang menangani kedua jenis transport

🔍 Debugging

Untuk debugging, Anda dapat menggunakan inspector MCP:

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

Atau gunakan inspector MCP pada server HTTP streamable yang sedang berjalan:

npx @modelcontextprotocol/inspector

Ini menyediakan antarmuka web untuk memeriksa dan menguji alat yang tersedia.

📦 Proses Rilis

Untuk merilis versi baru:

1. Naikkan versi menggunakan npm version [patch|minor|major] - ini memperbarui package.json, package-lock.json, dan menyinkronkan ke server.json
2. Dorong commit ke cabang Anda dan buat pull request
3. Gabungkan pull request
4. Buat rilis GitHub baru dengan nomor versi sebagai nama dan tag, menggunakan catatan rilis yang dibuat otomatis
5. Menerbitkan rilis memicu alur kerja otomatis yang menerbitkan ke npm dan registry MCP GitHub

Lisensi

MIT