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. Sebuah proyek - Buat proyek untuk digunakan.
3. Kunci Management API - Buat kunci dengan izin yang sesuai.
4. Environment ID - Dapatkan environment ID 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 tipe entitas

Manajemen Tipe Konten

• get-content-type – Dapatkan tipe konten Kontent.ai berdasarkan ID
• list-content-types – Dapatkan semua tipe konten Kontent.ai
• 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 — draft jika ada, jika tidak, yang sudah diterbitkan
• get-published-content-item-variant-version – Ambil versi yang sudah diterbitkan dari varian item konten Kontent.ai. Gunakan saat ada versi draft yang lebih baru 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 wadahnya, 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 dengan 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 akan diinisialisasi kosong
• update-content-item-variant – Perbarui varian item konten Kontent.ai dari sebuah 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 berubah. Untuk elemen rich-text dengan komponen, kirimkan elemen lengkap (nilai plus array komponen lengkap, termasuk komponen yang tidak diubah)
• 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 versioning konten dan membuat draft baru dari konten yang sudah diterbitkan
• delete-content-item-variant – Hapus varian item konten Kontent.ai
• bulk-get-content-item-variants – Ambil massal item konten Kontent.ai beserta 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 dengan paginasi beserta continuation token
• search-content-item-variants – Pencarian semantik bertenaga AI untuk menemukan konten berdasarkan makna dan konsep dalam varian item konten tertentu. Gunakan untuk: pencarian konseptual saat Anda tidak mengetahui kata kunci yang tepat. Opsi pemfilteran terbatas (hanya variant ID)

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 yang 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 web UI Kontent.ai)

Manajemen Koleksi

• list-collections – Dapatkan semua koleksi Kontent.ai. Koleksi menetapkan batasan untuk item konten di lingkungan Anda dan membantu mengorganisir 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 "Manage custom roles"

Manajemen Alur Kerja

• list-workflows – Dapatkan semua alur kerja Kontent.ai. Alur kerja menentukan tahapan siklus hidup konten dan transisi di antara tahapan tersebut
• create-workflow – Buat alur kerja Kontent.ai baru dengan langkah, transisi, cakupan, dan izin peran khusus
• 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 sedang 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 draft ke review, review ke published, dll.
• publish-content-item-variant – Terbitkan atau jadwalkan varian item konten dari sebuah item konten di Kontent.ai. Operasi ini dapat langsung menerbitkan varian tersebut atau menjadwalkannya untuk diterbitkan 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 sebuah item konten di Kontent.ai. Operasi ini dapat langsung membatalkan penerbitan varian tersebut (menjadikannya 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 transport-nya:

Mode Single-Tenant (STDIO)

Konfigurasikan kredensial melalui variabel lingkungan:

Mode Multi-Tenant (HTTP Streamable)

Untuk transport HTTP Streamable, kredensial diberikan per permintaan:

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

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

🔒 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 — injeksi prompt tidak langsung. Agen yang dibajak dapat diarahkan untuk melakukan panggilan alat yang merusak (delete / unpublish / overwrite) atau membocorkan draft yang belum diterbitkan. 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 API Management dengan hak istimewa paling rendah. Server bertindak dengan kunci apa pun yang diberikan. Dengan kunci hanya-baca, panggilan destruktif dari agen yang dibajak akan gagal di batas API — kontrol terkuat, karena tetap berlaku terlepas dari perilaku model.
• Pertahankan keterlibatan manusia. Setiap alat memiliki anotasi MCP — pembacaan adalah readOnlyHint, alat khusus pembuatan bersifat aditif, dan alat yang menimpa atau menghapus data adalah destructiveHint — yang digunakan oleh klien yang sesuai untuk menyetujui pembacaan secara otomatis dan meminta konfirmasi sebelum panggilan destruktif. Jalankan server dengan klien seperti itu dan hindari pengaturan auto-approve tanpa kepala 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 destruktif dijalankan, terlepas dari model. Ini dikonfigurasi secara lokal; server tidak dapat memaksakannya.

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

🚀 Opsi Transportasi

📟 Transportasi STDIO

Untuk menjalankan server dengan transportasi STDIO, konfigurasi 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>"
      }
    }
}

🌊 Transportasi HTTP Streamable (Multi-Tenant)

Transportasi HTTP Streamable melayani beberapa lingkungan Kontent.ai dari satu instance server. Setiap permintaan menyediakan 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>"

[!IMPORTANT] 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 lemparan kesalahan generik
  • server.ts - Pengaturan server utama dan pendaftaran alat
  • bin.ts - Titik masuk tunggal yang menangani kedua jenis transportasi

🔍 Debugging

Untuk debugging, Anda dapat menggunakan inspektur MCP:

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

Atau gunakan inspektur MCP pada server HTTP streamable yang 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 komit ke cabang Anda dan buat permintaan tarik
3. Gabungkan permintaan tarik
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