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

Streamable HTTP 傳輸

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

🛠️ 可用工具

Patch 操作指南

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

內容類型管理

• get-content-type – 依 ID 取得 Kontent.ai 內容類型
• list-content-types – 取得所有 Kontent.ai 內容類型
• list-content-type-usages – 列出 Kontent.ai 內容類型的使用位置
• create-content-type – 建立新的 Kontent.ai 內容類型
• patch-content-type – 使用 patch 操作（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 – 使用 patch 操作（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 – 使用 patch 操作（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 – 使用 patch 操作修改 Kontent.ai 資產資料夾（addInto 新增資料夾、rename 變更名稱、remove 刪除資料夾）

語言管理

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

集合管理

• list-collections – 取得所有 Kontent.ai 集合。集合為您環境中的內容項目設定界限，並協助依團隊、品牌或專案組織內容
• patch-collections – 使用 patch 操作更新 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 方案並具備「管理自訂角色」權限

工作流程管理

• 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 token：Authorization: Bearer <api-key>

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

KONTENT_API_KEY 和 KONTENT_ENVIRONMENT_ID 在此傳輸上會被忽略，即使它們恰好設定在伺服器的環境中。每個請求必須攜帶自己的憑證；未攜帶憑證的請求會被拒絕，而不是使用伺服器的憑證來服務。

🔒 安全性

間接提示注入

此伺服器傳回的內容（例如編輯者撰寫的元素）可能包含文字，被連接的 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>"
      }
    }
}

🌊 可串流 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 - 通用錯誤拋出工具
  • app.ts - 用於可串流 HTTP 傳輸的 Express 應用程式工廠
  • 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

或在執行中的可串流 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. 發布 release 會觸發自動化工作流程，發布至 npm 和 GitHub MCP registry

授權

MIT