🚀 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)
