Kontent.ai MCP Server

Kontent.ai MCP 服务

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

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

✨ 主要功能

• 🚀 快速原型开发：数秒内将图表转换为实时内容模型
• 📈 数据可视化：以任意格式可视化您的内容模型

目录

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

🔌 快速入门

🔑 前提条件

使用 MCP 服务前，您需要：

1. Kontent.ai 账户 - 如果您还没有账户，请注册。
2. 项目 - 创建项目以供使用。
3. Management API 密钥 - 创建密钥，并授予适当的权限。
4. 环境 ID - 获取您的环境 ID。

🛠 设置选项

您可以使用 npx 运行 Kontent.ai MCP 服务：

STDIO 传输

npx @kontent-ai/mcp-server@latest stdio

Streamable HTTP 传输

npx @kontent-ai/mcp-server@latest shttp

🛠️ 可用工具

Patch 操作指南

• get-patch-guide – 🚨 执行任何 patch 操作前都必须使用。按实体类型获取 Kontent.ai 的 patch 操作指南

内容类型管理

• 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 – 使用 patch 操作（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 – 使用 patch 操作（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 – 使用 patch 操作（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 之后使用，以获取特定内容项和语言配对的完整内容数据。请求语言中没有变体的内容项将以不含 variant 属性的形式返回。结果分页返回，并附带续传令牌
• 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 – 使用 patch 操作修改 Kontent.ai 资源文件夹（addInto 用于添加新文件夹，rename 用于更改名称，remove 用于删除文件夹）

语言管理

• list-languages – 获取所有 Kontent.ai 语言（包括启用和未启用的语言 — 检查 is_active 属性）
• create-language – 创建新的 Kontent.ai 语言（语言始终以启用状态创建）
• patch-language – 使用 replace 操作更新 Kontent.ai 语言（只能修改启用的语言 — 如需启用或停用语言，请使用 Kontent.ai 网页界面）

集合管理

• list-collections – 获取所有 Kontent.ai 集合。集合用于划定环境中内容项的边界，并帮助按团队、品牌或项目整理内容。
• patch-collections – 使用补丁操作更新 Kontent.ai 集合（使用 addInto 添加新集合，使用 move 调整顺序，使用 remove 删除空集合，使用 replace 重命名）。

空间管理

• list-spaces – 获取所有 Kontent.ai 空间。
• create-space – 创建新的 Kontent.ai 空间，用于管理网站或渠道。
• patch-space – 使用 replace 操作修补 Kontent.ai 空间。
• delete-space – 删除 Kontent.ai 空间。

角色管理

• list-roles – 获取所有 Kontent.ai 角色。需要 Enterprise 或 Flex 计划，并具有“Manage custom roles”权限。

工作流管理

• 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 传输，每个请求都会提供凭据：

• Environment ID 作为 URL 路径参数：/{environmentId}/mcp
• API Key 通过 Authorization 标头中的 Bearer 令牌提供：Authorization: Bearer <api-key>

这样，单个服务实例就能处理来自多个 Kontent.ai 环境的请求，而无需设置凭据环境变量。

在此传输方式下，KONTENT_API_KEY 和 KONTENT_ENVIRONMENT_ID 会被忽略，即使它们恰好已在服务的环境中设置。每个请求都必须携带自己的凭据；未携带凭据的请求会被拒绝，而不会使用服务自身的凭据处理。

🔒 安全

间接提示词注入

此服务返回的内容（例如编辑人员撰写的元素）可能包含被已连接的大模型解释为指令的文本，即间接提示词注入。被劫持的 Agent 可能会被引导执行破坏性工具调用（删除／取消发布／覆盖），或泄露未发布的草稿。这是整个行业尚未解决的问题，服务无法通过转换返回的内容来可靠地消除风险，因此需要分层防御：

• 使用遵循最小权限原则的 Management API 密钥。 服务会使用提供给它的任何密钥。使用只读密钥时，被劫持的 Agent 发出的破坏性调用会直接在 API 边界处失败——这是最有力的控制措施，因为无论模型行为如何，它都能生效。
• 让人工参与处理流程。 每个工具都带有 MCP 注释——读取操作标记为 readOnlyHint，仅创建工具只会添加数据，覆盖或删除数据的工具标记为 destructiveHint——兼容的客户端会据此自动批准读取操作，并在破坏性调用前提示确认。请将服务与此类客户端搭配使用，并避免在具备写入权限的密钥下采用无头自动批准配置。
• 如果客户端支持，请添加客户端侧防护。 某些客户端（例如 Claude Code 钩子）支持在破坏性工具运行前确定性地提示确认，而不受模型影响。此配置在本地完成，服务无法强制执行。

这些只是提示，并非保证。请通过 [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>"
      }
    }
}

🌊 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>"

重要

将 <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 - 用于 Streamable 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

也可以在运行中的 Streamable 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