Kontent.ai

Kontent.ai MCP 伺服器

透過專為 Kontent.ai 打造的 AI 工具，轉變您的內容營運方式。在您最喜愛的 AI 編輯器中，透過自然語言對話來建立、管理及探索您的結構化內容。

Kontent.ai MCP Server 實作了 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 Server：

STDIO 傳輸

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

Streamable 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 – 使用修補操作（move、addInto、remove、replace）依 codename 更新現有的 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 – 使用修補操作（move、addInto、remove、replace）依 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 – 使用修補操作（addInto、move、remove、replace）更新 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 內容項目變體。元素值必須符合內容類型中定義的限制與規範。僅傳送您想要變更的元素 — 省略的元素保持不變。對於包含元件的富文本元素，請提交完整的元素（值加上完整的 components 陣列，包括未變更的元件）
• 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 – 使用 replace 操作更新 Kontent.ai 語言（僅可修改啟用中的語言 — 若要啟用／停用，請使用 Kontent.ai 網頁 UI）

集合管理

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

空間管理

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

角色管理

• list-roles – 取得所有 Kontent.ai 角色。需要 Enterprise 或 Flex 方案，且具備「Manage custom roles」權限

工作流程管理

• 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 使用），或排程在指定的未來日期與時間取消發佈，並可指定時區
• cancel-scheduled-publishing-content-item-variant – 取消 Kontent.ai 中內容項目變體的排程發佈。此操作會將已排程發佈的變體回復至先前的工作流程步驟，允許進一步編輯

⚙️ 組態設定

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

單租戶模式（STDIO）

透過環境變數設定認證：

多租戶模式（Streamable HTTP）

對於 Streamable HTTP 傳輸，認證會隨每個請求提供：

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

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

🔒 安全性

間接提示注入

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

• 使用最小權限的 Management API 金鑰。 伺服器會以提供給它的任何金鑰運作。使用唯讀金鑰時，遭劫持代理程式的破壞性呼叫只會在 API 邊界失敗——這是最強的控制，因為無論模型行為如何，它都有效。
• 保持人類參與監督。 每個工具都帶有 MCP 註釋——讀取為 readOnlyHint、僅限建立的工具是累加性的，而覆寫或移除資料的工具為 destructiveHint——符合規範的用戶端會以此自動核准讀取，並在破壞性呼叫前提示。請搭配此類用戶端執行伺服器，並避免以具寫入權限的金鑰進行無頭自動核准設定。
• 如果您的用戶端支援，請新增用戶端閘道。 某些用戶端（例如 Claude Code hooks）可讓您在破壞性工具執行前確定性地提示，與模型無關。這是在本機設定的；伺服器無法強制執行。

這些是提示，而非保證。請將安全性問題私下回報至 security@kontent.ai。

🚀 傳輸選項

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

🌊 Streamable HTTP 傳輸（多租戶）

Streamable 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 inspector：

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

或在執行中的 streamable HTTP 伺服器上使用 MCP inspector：

npx @modelcontextprotocol/inspector

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

📦 發行流程

若要發行新版本：

1. 使用 npm version [patch|minor|major] 提升版本號 - 這會更新 package.json、package-lock.json，並同步至 server.json
2. 將提交推送到您的分支並建立 pull request
3. 合併 pull request
4. 使用版本號作為名稱和標籤建立新的 GitHub release，並使用自動產生的發行說明
5. 發行發布會觸發自動化工作流程，發布至 npm 和 GitHub MCP registry

授權

MIT