Kontent.ai

Kontent.ai MCP Server

利用面向 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 – 使用替换操作更新 Kontent.ai 语言（只能修改活动语言 — 要激活/停用，请使用 Kontent.ai Web UI）

集合管理

• 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 使用），也可以计划在未来的特定日期和时间取消发布，并可指定时区
• 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

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

📦 发布流程

如需发布新版本：

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

License

MIT