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

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

Daftar Isi

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

🔌 Mulai 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 dikerjakan.
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 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 nama kode 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, yang dipublikasikan
• get-published-content-item-variant-version – Ambil versi yang dipublikasikan dari varian item konten Kontent.ai. Gunakan ketika versi draf yang lebih baru ada tetapi Anda memerlukan konten yang saat ini dipublikasikan (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 dengan menetapkan pengguna saat ini sebagai kontributor. Nilai elemen harus memenuhi batasan dan panduan 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 dari suatu item konten. Nilai elemen harus memenuhi batasan dan panduan yang ditentukan dalam tipe konten. Kirim hanya elemen yang ingin Anda ubah — elemen yang dihilangkan tidak akan disentuh. Untuk elemen rich-text dengan komponen, kirimkan elemen lengkap (nilai plus array komponen lengkap, termasuk komponen yang tidak disentuh)
• 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 dipublikasikan
• delete-content-item-variant – Hapus varian item konten Kontent.ai
• bulk-get-content-item-variants – Dapatkan item konten Kontent.ai secara massal 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 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 UI web Kontent.ai)

Manajemen Koleksi

• list-collections – Dapatkan semua koleksi Kontent.ai. Koleksi menetapkan batasan 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 menentukan tahapan siklus hidup konten dan transisi di antaranya
• 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 dipublikasikan, dll.
• publish-content-item-variant – Publikasikan atau jadwalkan varian item konten dari suatu item konten di Kontent.ai. Operasi ini dapat langsung mempublikasikan varian atau menjadwalkannya untuk publikasi pada tanggal dan waktu tertentu di masa mendatang dengan spesifikasi zona waktu opsional
• unpublish-content-item-variant – Batalkan publikasi atau jadwalkan pembatalan publikasi varian item konten dari suatu item konten di Kontent.ai. Operasi ini dapat langsung membatalkan publikasi varian (membuatnya tidak tersedia melalui API Pengiriman) atau menjadwalkannya untuk pembatalan publikasi pada tanggal dan waktu tertentu di masa mendatang dengan spesifikasi zona waktu opsional

⚙️ 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 disediakan 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.

🔒 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 ke panggilan alat yang merusak (hapus / batalkan publikasi / timpa) atau membocorkan draf yang tidak 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 sesuai dengan kunci yang diberikan. Dengan kunci hanya-baca, panggilan destruktif dari agen yang dibajak akan langsung gagal di batas API — kontrol terkuat, karena berlaku terlepas dari perilaku model.
• Libatkan manusia dalam proses. Setiap alat membawa anotasi MCP — pembacaan bersifat readOnlyHint, alat khusus-pembuatan bersifat aditif, dan alat yang menimpa atau menghapus data bersifat destructiveHint — yang digunakan klien yang patuh untuk menyetujui pembacaan secara otomatis dan meminta konfirmasi sebelum panggilan destruktif. Jalankan server dengan klien semacam itu dan hindari pengaturan persetujuan otomatis tanpa pengawasan terhadap kunci yang mampu menulis.
• Tambahkan gerbang sisi klien jika klien Anda mendukungnya. Beberapa klien (misalnya, Claude Code hooks) memungkinkan Anda meminta konfirmasi secara deterministik sebelum alat destruktif berjalan, terlepas dari model. Ini dikonfigurasi secara lokal; server tidak dapat menegakkannya.

Ini adalah petunjuk, bukan jaminan. Laporkan masalah keamanan secara pribadi ke [email protected].

🚀 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 menyediakan kredensial melalui parameter jalur URL dan autentikasi Bearer.

Pertama, jalankan 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 pelemparan kesalahan generik
  • server.ts - Pengaturan server utama dan pendaftaran alat
  • bin.ts - Titik masuk tunggal yang menangani kedua jenis transport

🔍 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 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 komit 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 dihasilkan otomatis
5. Menerbitkan rilis memicu alur kerja otomatis yang menerbitkan ke npm dan registri MCP GitHub

Lisensi

MIT