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 内容类型
• list-content-type-usages – 列出 Kontent.ai 内容类型的使用位置
• create-content-type – 创建新的 Kontent.ai 内容类型
• patch-content-type – 使用补丁操作（move、addInto、remove、replace）按代号更新现有的 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 内容项变体。元素值必须满足内容类型中定义的限制和指南。仅发送您想要更改的元素 — 省略的元素保持不变。对于包含组件的富文本元素，请提交完整元素（值加上完整的组件数组，包括未更改的组件）
• 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 角色。需要企业版或灵活版计划，并具有“管理自定义角色”权限

工作流管理

• 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 中取消发布或安排取消发布内容项的内容项变体。此操作可以立即取消发布变体（使其通过交付 API 不可用），或安排在特定未来日期和时间取消发布，并可选择指定时区
• cancel-scheduled-publishing-content-item-variant – 在 Kontent.ai 中取消内容项变体的计划发布。此操作将计划发布的变体恢复到其先前的工作流步骤，从而允许进一步编辑

⚙️ 配置

服务器支持两种模式，每种模式与其传输方式相关联：

单租户模式（STDIO）

通过环境变量配置凭据：

多租户模式（可流式 HTTP）

对于可流式 HTTP 传输，凭据在每个请求中提供：

• 环境 ID 作为 URL 路径参数：/{environmentId}/mcp
• API 密钥 通过 Authorization 标头中的 Bearer 令牌：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 检查器：

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