Kontent.ai

Kontent.ai MCP 服务器

借助面向 Kontent.ai 的 AI 驱动工具，革新您的内容运营。在您喜爱的 AI 编辑器中，通过自然语言对话创建、管理和探索结构化内容。

Kontent.ai MCP 服务器实现了模型上下文协议，将您的 Kontent.ai 项目与 Claude、Cursor 和 VS Code 等 AI 工具连接起来。它使 AI 模型能够理解您的内容结构，并通过自然语言指令执行操作。

✨ 核心功能

• 🚀 快速原型设计：在几秒钟内将图表转化为实时内容模型
• 📈 数据可视化：以您想要的任何格式可视化内容模型

目录

• ✨ 核心功能
• 🔌 快速入门
• 🛠️ 可用工具
• ⚙️ 配置
• 🔒 安全
• 🚀 传输选项
• 💻 开发
  • 🛠 本地安装
  • 📂 项目结构
  • 🔍 调试
  • 📦 发布流程
• 许可证

🔌 快速入门

🔑 先决条件

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

1. 一个 Kontent.ai 账户 - 如果您还没有账户，请注册。
2. 一个项目 - 创建一个项目以进行操作。
3. 管理 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 Web 界面）

集合管理

• 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

这将提供一个用于检查和测试可用工具的 Web 界面。

📦 发布流程

发布新版本：

1. 使用 npm version [patch|minor|major] 提升版本号——这将更新 package.json、package-lock.json，并同步到 server.json
2. 将提交推送到您的分支并创建拉取请求
3. 合并拉取请求
4. 创建一个新的 GitHub 发布，使用版本号作为名称和标签，并使用自动生成的发布说明
5. 发布该版本将触发自动化工作流，发布到 npm 和 GitHub MCP 注册表

许可证

MIT