🚀 Kontent.ai MCP Server
Kontent.ai MCP Server 藉助人工智能驅動的工具，變革您的內容運營方式。您可以在喜愛的支持 AI 的編輯器中，通過自然語言對話來創建、管理和探索結構化內容。該服務器實現了模型上下文協議，可將您的 Kontent.ai 項目與 Claude、Cursor 和 VS Code 等 AI 工具相連接，使 AI 模型能夠理解您的內容結構，並通過自然語言指令執行操作。
🚀 快速開始
🔑 前提條件
在使用 MCP 服務器之前，您需要完成以下準備工作：
- Kontent.ai 賬戶：如果您還沒有賬戶，請 註冊。
- 項目：創建一個項目 以供使用。
- 管理 API 密鑰：創建一個管理 API 密鑰，並賦予其適當的權限。
- 環境 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 管理 API 的補丁操作指南。
內容類型管理
- get-type-mapi – 通過管理 API 按內部 ID 獲取 Kontent.ai 內容類型。
- list-content-types-mapi – 通過管理 API 獲取所有 Kontent.ai 內容類型。
- add-content-type-mapi – 通過管理 API 添加新的 Kontent.ai 內容類型。
- patch-content-type-mapi – 使用補丁操作（移動、添加、移除、替換）按代號更新現有的 Kontent.ai 內容類型。
- delete-content-type-mapi – 按代號刪除 Kontent.ai 內容類型。
內容類型片段管理
- get-type-snippet-mapi – 通過管理 API 按內部 ID 獲取 Kontent.ai 內容類型片段。
- list-content-type-snippets-mapi – 通過管理 API 獲取所有 Kontent.ai 內容類型片段。
- add-content-type-snippet-mapi – 通過管理 API 添加新的 Kontent.ai 內容類型片段。
- patch-type-snippet-mapi – 使用補丁操作（移動、添加、移除、替換）按內部 ID 更新現有的 Kontent.ai 內容類型片段。
- delete-type-snippet-mapi – 按代號刪除 Kontent.ai 內容類型片段。
分類法管理
- get-taxonomy-group-mapi – 通過管理 API 按內部 ID 獲取 Kontent.ai 分類法組。
- list-taxonomy-groups-mapi – 通過管理 API 獲取所有 Kontent.ai 分類法組。
- add-taxonomy-group-mapi – 通過管理 API 添加新的 Kontent.ai 分類法組。
- patch-taxonomy-group-mapi – 通過管理 API 使用補丁操作（添加、移動、移除、替換）更新 Kontent.ai 分類法組。
- delete-taxonomy-group-mapi – 按內部 ID 刪除 Kontent.ai 分類法組。
內容項管理
- get-item-mapi – 通過管理 API 按內部 ID 獲取 Kontent.ai 項。
- get-latest-variant-mapi – 通過管理 API 獲取 Kontent.ai 語言變體的最新版本。
- get-published-variant-mapi – 通過管理 API 獲取 Kontent.ai 語言變體的已發佈版本。
- list-variants-item-mapi – 通過管理 API 列出內容項的所有 Kontent.ai 語言變體。
- list-variants-collection-mapi – 通過管理 API 按集合列出 Kontent.ai 語言變體（分頁）。
- list-variants-type-mapi – 通過管理 API 按內容類型列出 Kontent.ai 語言變體（分頁）。
- list-variants-components-type-mapi – 通過管理 API 列出包含特定內容類型組件的 Kontent.ai 語言變體（分頁）。
- list-variants-space-mapi – 通過管理 API 按空間列出 Kontent.ai 語言變體（分頁）。
- add-content-item-mapi – 通過管理 API 添加新的 Kontent.ai 內容項。此操作僅創建內容項結構，不會向語言變體添加內容。請使用 upsert-language-variant-mapi 向項添加內容。
- update-content-item-mapi – 通過管理 API 按內部 ID 更新現有的 Kontent.ai 內容項。內容項必須已經存在，此工具不會創建新項。
- delete-content-item-mapi – 通過管理 API 按內部 ID 刪除 Kontent.ai 內容項。
- upsert-language-variant-mapi – 通過管理 API 創建或更新 Kontent.ai 內容項的語言變體。元素值必須滿足內容類型中定義的限制和指南。更新時，僅修改提供的元素。
- create-variant-version-mapi – 通過管理 API 創建 Kontent.ai 語言變體的新版本。此操作會為現有語言變體創建新版本，適用於內容版本控制和從已發佈內容創建新草稿。
- delete-language-variant-mapi – 通過管理 API 刪除 Kontent.ai 語言變體。
- filter-variants-mapi – 使用管理 API 過濾內容項的 Kontent.ai 語言變體。用於精確關鍵字匹配和在內容中查找特定術語。支持完整的過濾功能（內容類型、工作流步驟、分類法等），並可選擇包含變體的完整內容。返回帶延續令牌的分頁結果，用於獲取後續頁面。
- search-variants-mapi – 由人工智能驅動的語義搜索，用於按特定語言變體中的含義和概念查找內容。適用於不知道精確關鍵字的概念性搜索。過濾選項有限（僅變體 ID）。
資產管理
- get-asset-mapi – 通過管理 API 按內部 ID 獲取特定的 Kontent.ai 資產。
- list-assets-mapi – 通過管理 API 獲取所有 Kontent.ai 資產。
- update-asset-mapi – 通過管理 API 按內部 ID 更新 Kontent.ai 資產。
資產文件夾管理
- list-asset-folders-mapi – 列出所有 Kontent.ai 資產文件夾。
- patch-asset-folders-mapi – 使用補丁操作（添加新文件夾、重命名、刪除文件夾）修改 Kontent.ai 資產文件夾。
語言管理
- list-languages-mapi – 通過管理 API 獲取所有 Kontent.ai 語言。
- add-language-mapi – 通過管理 API 添加新的 Kontent.ai 語言。
- patch-language-mapi – 通過管理 API 使用替換操作更新 Kontent.ai 語言。
集合管理
- list-collections-mapi – 通過管理 API 獲取所有 Kontent.ai 集合。集合為您環境中的內容項設置邊界，並有助於按團隊、品牌或項目組織內容。
- patch-collections-mapi – 使用補丁操作（添加新集合、移動、刪除空集合、重命名）更新 Kontent.ai 集合。
空間管理
- list-spaces-mapi – 通過管理 API 獲取所有 Kontent.ai 空間。
- add-space-mapi – 向環境中添加 Kontent.ai 空間。
- patch-space-mapi – 使用替換操作修補 Kontent.ai 空間。
- delete-space-mapi – 刪除 Kontent.ai 空間。
工作流管理
- list-workflows-mapi – 通過管理 API 獲取所有 Kontent.ai 工作流。工作流定義了內容生命週期階段及其之間的轉換。
- change-variant-workflow-step-mapi – 更改 Kontent.ai 中語言變體的工作流步驟。此操作將語言變體移動到工作流中的不同步驟，實現內容生命週期管理，如將內容從草稿移動到審核、從審核移動到發佈等。
- publish-variant-mapi – 在 Kontent.ai 中發佈或安排發佈內容項的語言變體。此操作可以立即發佈變體，也可以安排在特定的未來日期和時間發佈，並可選擇指定時區。
- unpublish-variant-mapi – 在 Kontent.ai 中取消發佈或安排取消發佈內容項的語言變體。此操作可以立即取消發佈變體（使其無法通過交付 API 使用），也可以安排在特定的未來日期和時間取消發佈，並可選擇指定時區。
⚙️ 配置
服務器支持兩種配置模式：
單租戶模式（默認）
對於單租戶模式，需要配置環境變量：
| 變量 |
描述 |
是否必需 |
| KONTENT_API_KEY |
您的 Kontent.ai 管理 API 密鑰 |
✅ |
| KONTENT_ENVIRONMENT_ID |
您的環境 ID |
✅ |
| PORT |
HTTP 傳輸的端口（默認為 3001） |
❌ |
| appInsightsConnectionString |
用於遙測的應用程序洞察連接字符串 |
❌ |
| projectLocation |
用於遙測跟蹤的項目位置標識符 |
❌ |
| manageApiUrl |
自定義管理 API 基本 URL（用於預覽環境） |
❌ |
多租戶模式
對於多租戶模式（僅適用於可流式傳輸的 HTTP），服務器接受以下參數：
- 環境 ID 作為 URL 路徑參數：
/{environmentId}/mcp
- API 密鑰 通過授權標頭中的承載令牌：
Authorization: Bearer <api-key>
此模式允許單個服務器實例安全地處理多個 Kontent.ai 環境的請求，而無需環境變量。
🔧 響應優化
MCP 服務器實現了自動令牌優化，以降低人工智能模型成本並提高性能：
令牌減少策略
服務器會自動從響應中移除空值或默認值，以減少令牌使用量，包括：
- 空值和未定義值
- 空字符串 (
"")
- 空數組 (
[])
- 空對象 (
{})
- 富文本佔位符 (
"<p><br/></p>")
- 移除空值後僅包含 ID 的元素
對人工智能代理的影響
對於人工智能實現很重要：在使用此 MCP 服務器的響應時：
- 缺失的屬性表示默認值，而非缺失數據。
- 變體中缺失的元素具有其特定類型的默認值：
- 文本元素：
""（空字符串）
- 富文本：
"<p><br/></p>"（空佔位符）
- 數字/日期：
null
- 自定義元素：
null（值和可搜索值）
- 數組（資產、分類法等）：
[]
- 創建/更新內容時，請始終發送完整數據。
🚀 傳輸選項
📟 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 傳輸，首先啟動服務器：
npx @kontent-ai/mcp-server@latest shttp
單租戶模式
在 .env 文件中設置環境變量，或者確保進程可以訪問這些變量：
KONTENT_API_KEY=<management-api-key>
KONTENT_ENVIRONMENT_ID=<environment-id>
PORT=3001 # 可選，默認為 3001
然後在您的 MCP 客戶端中進行如下配置：
{
"kontent-ai-http": {
"url": "http://localhost:3001/mcp"
}
}
多租戶模式
無需環境變量。服務器使用 URL 路徑參數和承載身份驗證接受多個環境的請求。
VS Code
在您的工作區中創建一個 `.vscode/mcp.json` 文件：
```json
{
"servers": {
"kontent-ai-multi": {
"uri": "http://localhost:3001//mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}
```
如需通過輸入提示進行安全配置，請使用以下配置：
```json
{
"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}"
}
}
}
}
```
Claude Desktop
更新您的 Claude Desktop 配置文件：
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**：`~/.config/Claude/claude_desktop_config.json`
使用 `mcp-remote` 作為代理添加身份驗證標頭：
```json
{
"mcpServers": {
"kontent-ai-multi": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:3001//mcp",
"--header",
"Authorization: Bearer "
]
}
}
}
```
Claude Code
使用 CLI 添加服務器：
```bash
claude mcp add --transport http kontent-ai-multi \
"http://localhost:3001//mcp" \
--header "Authorization: Bearer "
```
> **注意**：您也可以在 Claude Code 設置 JSON 中使用 `url` 和 `headers` 屬性進行配置。
⚠️ 重要提示
請將 <environment-id> 替換為您的 Kontent.ai 環境 ID（GUID），將 <management-api-key> 替換為您的管理 API 密鑰。
💻 開發
🛠 本地安裝
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server
npm ci
npm run build
npm run start:stdio
npm run start:shttp
npm run dev:stdio
npm run dev:shttp
📂 項目結構
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
這將提供一個 Web 界面，用於檢查和測試可用工具。
📦 發佈流程
要發佈新版本，請按以下步驟操作：
- 使用
npm version [patch|minor|major] 提升版本號，這將更新 package.json、package-lock.json 並同步到 server.json。
- 將提交推送到您的分支並創建拉取請求。
- 合併拉取請求。
- 使用版本號作為名稱和標籤創建一個新的 GitHub 版本，並使用自動生成的發佈說明。
- 發佈版本將觸發一個自動化工作流，將其發佈到 npm 和 GitHub MCP 註冊表。
📄 許可證
本項目採用 MIT 許可證。
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%23061b40;%20}%20.st1%20{%20fill:%20%23306af1;%20}%20.st2%20{%20fill:%20%235ce5cf;%20}%20%3c/style%3e%3c/defs%3e%3cg%3e%3cpath%20class='st0'%20d='M55,10.5h9v3h-9v9h12V7.5h-12v3ZM64,19.5h-6v-3h6v3Z'/%3e%3cpolygon%20class='st0'%20points='69%2016.5%2078%2016.5%2078%2019.5%2069%2019.5%2069%2022.5%2081%2022.5%2081%2013.5%2072%2013.5%2072%2010.5%2081%2010.5%2081%207.5%2069%207.5%2069%2016.5'/%3e%3cpolygon%20class='st0'%20points='95%2010.5%2095%207.5%2083%207.5%2083%2022.5%2095%2022.5%2095%2019.5%2086%2019.5%2086%2016.5%2095%2016.5%2095%2013.5%2086%2013.5%2086%2010.5%2095%2010.5'/%3e%3cpath%20class='st0'%20d='M40,1.5v21h11.6l1.4-1.4v-7.6h0c0,0-1.4-1.5-1.4-1.5l1.4-1.4V2.9l-1.4-1.4h-11.6ZM50,19.5h-7v-6h7v6ZM50,10.5h-7v-6h7v6Z'/%3e%3c/g%3e%3cpath%20class='st1'%20d='M23.1,24L14.7,4.8l-4.9,11.2h3.8l-1.8,4H3.3L12.1,0H2C.9,0,0,.9,0,2v20c0,1.1.9,2,2,2h21.1Z'/%3e%3cpath%20class='st2'%20d='M34,0h-16.8l10.6,24h6.2c1.1,0,2-.9,2-2V2C36,.9,35.1,0,34,0ZM32.5,20h-4V4h4v16Z'/%3e%3c/svg%3e)
%20--%3e%3cdefs%3e%3cstyle%3e%20.st0%20{%20fill:%20%230080ff;%20}%20%3c/style%3e%3c/defs%3e%3cpath%20class='st0'%20d='M16.2,11.1c.4.5.4,1.2,0,1.8l-4.7,7.1h-3.8l5.3-8L7.6,4h3.8l4.7,7.1Z'/%3e%3c/svg%3e)
