Kontent.ai

Kontent.ai MCP 伺服器

使用 Kontent.ai 的 AI 驅動工具來轉變您的內容作業。透過您喜愛的 AI 編輯器中的自然語言對話，建立、管理並探索您的結構化內容。

Kontent.ai MCP 伺服器實作了模型上下文協定 (Model Context Protocol)，將您的 Kontent.ai 專案與 Claude、Cursor 和 VS Code 等 AI 工具連接起來。它讓 AI 模型能夠理解您的內容結構，並透過自然語言指令執行操作。

✨ 主要功能

• 🚀 快速原型製作：在幾秒鐘內將您的圖表轉換為即時的內容模型
• 📈 資料視覺化：以任何您想要的格式視覺化您的內容模型

目錄

• ✨ 主要功能
• 🔌 快速入門
• 🛠️ 可用工具
• ⚙️ 設定
• 🔒 安全性
• 🚀 傳輸選項
• 💻 開發
  • 🛠 本機安裝
  • 📂 專案結構
  • 🔍 除錯
  • 📦 發佈流程
• 授權

🔌 快速入門

🔑 先決條件

在使用 MCP 伺服器之前，您需要：

1. 一個 Kontent.ai 帳戶 - 如果您還沒有帳戶，請註冊。
2. 一個專案 - 建立一個專案來進行操作。
3. Management API 金鑰 - 建立一個金鑰並賦予適當的權限。
4. 環境 ID - 取得您的環境 ID。

🛠 設定選項

您可以使用 npx 來執行 Kontent.ai MCP 伺服器：

STDIO 傳輸

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

可串流的 HTTP 傳輸

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

🛠️ 可用工具

修補操作指南

• get-patch-guide – 🚨 在任何修補操作之前必須執行。依實體類型取得 Kontent.ai 的修補操作指南

內容類型管理

• get-content-type – 依 ID 取得 Kontent.ai 內容類型
• list-content-types – 取得所有 Kontent.ai 內容類型
• create-content-type – 建立新的 Kontent.ai 內容類型
• patch-content-type – 使用修補操作（移動、新增至、移除、取代）依代號更新現有的 Kontent.ai 內容類型
• delete-content-type – 依 ID 刪除 Kontent.ai 內容類型

內容類型片段管理

• get-content-type-snippet – 依 ID 取得 Kontent.ai 內容類型片段
• list-content-type-snippets – 取得所有 Kontent.ai 內容類型片段
• create-content-type-snippet – 建立新的 Kontent.ai 內容類型片段
• patch-content-type-snippet – 使用修補操作（移動、新增至、移除、取代）依 ID 更新現有的 Kontent.ai 內容類型片段
• delete-content-type-snippet – 依 ID 刪除 Kontent.ai 內容類型片段

分類管理

• get-taxonomy-group – 依 ID 取得 Kontent.ai 分類群組
• list-taxonomy-groups – 取得所有 Kontent.ai 分類群組
• create-taxonomy-group – 建立新的 Kontent.ai 分類群組
• patch-taxonomy-group – 使用修補操作（新增至、移動、移除、取代）更新 Kontent.ai 分類群組
• delete-taxonomy-group – 依 ID 刪除 Kontent.ai 分類群組

內容項目管理

• get-content-item – 依 ID 取得 Kontent.ai 內容項目
• get-content-item-variant – 擷取 Kontent.ai 內容項目變體（語言版本/翻譯）。傳回目前版本 — 若存在草稿則為草稿，否則為已發佈版本
• get-published-content-item-variant-version – 擷取 Kontent.ai 內容項目變體的已發佈版本。當存在較新的草稿版本，但您需要目前發佈（即時）的內容時使用
• get-content-item-translations – 取得特定內容項目的所有 Kontent.ai 內容項目翻譯 — 即每個語言版本（變體）
• list-content-item-variants – 列出、篩選、搜尋包含內容項目變體（語言版本/翻譯）的 Kontent.ai 內容項目
• create-content-item – 建立新的 Kontent.ai 內容項目（僅建立容器，使用 create-content-item-variant 來新增語言版本/翻譯）
• update-content-item – 依 ID 更新現有的 Kontent.ai 內容項目。內容項目必須已存在 — 此工具不會建立新項目
• delete-content-item – 依 ID 刪除 Kontent.ai 內容項目
• create-content-item-variant – 建立 Kontent.ai 內容項目變體，並將目前使用者指派為貢獻者。元素值必須符合內容類型中定義的限制和指南。僅傳送您要設定的元素；省略的元素會初始化為空值
• update-content-item-variant – 更新內容項目的 Kontent.ai 內容項目變體。元素值必須符合內容類型中定義的限制和指南。僅傳送您要變更的元素 — 省略的元素會保持不變。對於含有元件的富文本元素，請提交完整的元素（值加上完整的元件陣列，包括保持不變的元件）
• create-new-content-item-variant-version – 建立 Kontent.ai 內容項目變體的新版本。此操作會為現有的內容項目變體建立新版本，適用於內容版本控制以及從已發佈內容建立新草稿
• delete-content-item-variant – 刪除 Kontent.ai 內容項目變體
• bulk-get-content-item-variants – 依項目和語言參考配對，批次取得 Kontent.ai 內容項目及其內容項目變體。在 list-content-item-variants 之後使用，以擷取特定項目+語言配對的完整內容資料。在請求的語言中沒有變體的項目，會傳回不含變體屬性的項目。傳回帶有接續權杖的分頁結果
• search-content-item-variants – 由 AI 驅動的語意搜尋，用於在特定內容項目變體中依含義和概念尋找內容。適用於：當您不知道確切關鍵字時的概念性搜尋。篩選選項有限（僅限變體 ID）

資產管理

• get-asset – 依 ID 取得特定的 Kontent.ai 資產
• list-assets – 取得所有 Kontent.ai 資產
• update-asset – 依 ID 更新 Kontent.ai 資產

資產資料夾管理

• list-asset-folders – 列出所有 Kontent.ai 資產資料夾
• patch-asset-folders – 使用修補操作修改 Kontent.ai 資產資料夾（addInto 用於新增資料夾，rename 用於變更名稱，remove 用於刪除資料夾）

語言管理

• list-languages – 取得所有 Kontent.ai 語言（包含作用中和非作用中 — 請檢查 is_active 屬性）
• create-language – 建立新的 Kontent.ai 語言（語言建立時一律為作用中）
• patch-language – 使用取代操作更新 Kontent.ai 語言（僅作用中的語言可被修改 — 若要啟用/停用，請使用 Kontent.ai 網頁介面）

集合管理

• list-collections – 取得所有 Kontent.ai 集合。集合為您環境中的內容項目設定邊界，並協助依團隊、品牌或專案來組織內容
• patch-collections – 使用修補操作更新 Kontent.ai 集合（addInto 用於新增集合，move 用於重新排序，remove 用於刪除空集合，replace 用於重新命名）

空間管理

• list-spaces – 取得所有 Kontent.ai 空間
• create-space – 建立新的 Kontent.ai 空間，用於管理網站或頻道
• patch-space – 使用取代操作修補 Kontent.ai 空間
• delete-space – 刪除 Kontent.ai 空間

角色管理

• list-roles – 取得所有 Kontent.ai 角色。需要 Enterprise 或 Flex 方案並具備「管理自訂角色」權限

工作流程管理

• list-workflows – 取得所有 Kontent.ai 工作流程。工作流程定義了內容生命週期階段及其之間的轉換
• create-workflow – 建立新的 Kontent.ai 工作流程，包含自訂步驟、轉換、範圍和角色權限
• update-workflow – 依 ID 更新現有的 Kontent.ai 工作流程。修改步驟、轉換、範圍和角色權限。無法移除使用中的步驟
• delete-workflow – 依 ID 刪除 Kontent.ai 工作流程。該工作流程不得被任何內容項目使用
• change-content-item-variant-workflow-step – 變更 Kontent.ai 中內容項目變體的工作流程步驟。此操作會將內容項目變體移至工作流程中的不同步驟，從而實現內容生命週期管理，例如將內容從草稿移至審查、審查移至已發佈等
• publish-content-item-variant – 發佈或排程發佈 Kontent.ai 中內容項目的內容項目變體。此操作可以立即發佈變體，或排程在特定的未來日期和時間發佈，並可選擇指定時區
• unpublish-content-item-variant – 取消發佈或排程取消發佈 Kontent.ai 中內容項目的內容項目變體。此操作可以立即取消發佈變體（使其無法透過 Delivery API 取得），或排程在特定的未來日期和時間取消發佈，並可選擇指定時區

⚙️ 設定

伺服器支援兩種模式，每種模式都與其傳輸方式相關聯：

單一租戶模式 (STDIO)

透過環境變數設定憑證：

多租戶模式 (可串流 HTTP)

對於可串流 HTTP 傳輸，憑證會隨每個請求提供：

• 環境 ID 作為 URL 路徑參數：/{environmentId}/mcp
• API 金鑰 透過 Authorization 標頭中的 Bearer 權杖：Authorization: Bearer <api-key>

這允許單一伺服器執行個體處理多個 Kontent.ai 環境的請求，而無需設定憑證環境變數。

🔒 安全性

間接提示注入

此伺服器傳回的內容（例如，編輯器編寫的元素）可能包含被連接的 LLM 解讀為指令的文字 — 間接提示注入。被劫持的代理程式可能會被引導執行破壞性的工具呼叫（刪除 / 取消發佈 / 覆寫）或洩漏未發佈的草稿。這是一個業界普遍存在且尚未解決的問題，伺服器無法透過轉換其傳回的內容來可靠地修復，因此防禦是分層進行的：

• 使用最低權限的管理 API 金鑰。 伺服器會以所給予的金鑰權限運作。若使用唯讀金鑰，即使代理程式遭劫持，破壞性呼叫也會在 API 邊界直接失敗——這是最強的控制機制，因為無論模型行為如何，此限制都有效。
• 保持人類參與決策。 每個工具都帶有 MCP 註解——讀取操作為 readOnlyHint，僅建立工具為附加性質，而覆寫或移除資料的工具則為 destructiveHint——相容的客戶端會利用這些註解自動核准讀取，並在破壞性呼叫前提示使用者。請使用此類客戶端執行伺服器，並避免在具備寫入權限的金鑰下，採用無人類監督的自動核准設定。
• 若您的客戶端支援，請加入客戶端防護機制。 某些客戶端（例如 Claude Code hooks）可讓您在破壞性工具執行前，獨立於模型之外，以確定性方式進行提示。此設定為本機配置；伺服器無法強制執行。

以上為安全提示，並非絕對保證。請私下回報安全性問題至 [email protected]。

🚀 傳輸選項

📟 STDIO 傳輸

若要使用 STDIO 傳輸執行伺服器，請在您的 MCP 客戶端中進行以下配置：

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

🌊 可串流 HTTP 傳輸（多租戶）

可串流 HTTP 傳輸可讓單一伺服器執行個體服務多個 Kontent.ai 環境。每個請求會透過 URL 路徑參數和 Bearer 驗證提供憑證。

首先啟動伺服器：

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] 請將 <environment-id> 替換為您的 Kontent.ai 環境 ID（GUID），並將 <management-api-key> 替換為您的金鑰。

💻 開發

🛠 本機安裝

# 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

📂 專案結構

• src/ - 原始碼
  • tools/ - MCP 工具實作
  • clients/ - Kontent.ai API 客戶端設定
  • schemas/ - 資料驗證結構描述
  • utils/ - 工具函式
    • errorHandler.ts - MCP 工具的標準化錯誤處理
    • throwError.ts - 通用錯誤拋出工具
  • server.ts - 主要伺服器設定與工具註冊
  • bin.ts - 處理兩種傳輸類型的單一進入點

🔍 除錯

若要進行除錯，您可以使用 MCP 檢查器：

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

或在執行中的可串流 HTTP 伺服器上使用 MCP 檢查器：

npx @modelcontextprotocol/inspector

這會提供一個網頁介面，用於檢查和測試可用的工具。

📦 發佈流程

若要發佈新版本：

1. 使用 npm version [patch|minor|major] 提升版本號——這會更新 package.json、package-lock.json，並同步至 server.json
2. 將提交推送至您的分支並建立拉取請求
3. 合併拉取請求
4. 建立新的 GitHub 發佈，使用版本號作為名稱和標籤，並使用自動產生的發佈說明
5. 發佈發佈版本會觸發自動化工作流程，將套件發佈至 npm 和 GitHub MCP 登錄庫

授權

MIT