Kontent.ai MCP Server 是 Kontent.ai 官方提供的 MCP（模型上下文协议）服务器。它通过自然语言对话，把 Kontent.ai 项目与 AI 工具连接起来，让你在常用的 AI 编辑器中创建、管理和探索结构化内容。该服务器实现 MCP 协议，使 AI 模型能够理解你的内容结构，并通过自然语言指令执行操作。
用途 该服务器面向内容运营场景，强调两点价值：一是快速原型设计，可将图表在数秒内转化为可用的内容模型；二是数据可视化，可按任意格式可视化内容模型。它将 Kontent.ai 的内容管理能力暴露为可供 AI 调用的工具集，适合希望借助 AI 助手操作 Kontent.ai 内容模型与内容的用户。
主要能力 服务器提供的工具按对象类型划分，覆盖内容管理的多个方面：
- 补丁操作指南：get-patch-guide，官方标注为任何补丁操作前必需，用于按实体类型获取补丁操作指南。
- 内容类型管理：获取、列出、列出使用位置、创建、补丁更新、删除内容类型。
- 内容类型片段管理：获取、列出、创建、补丁更新、删除内容类型片段。
- 分类法管理：获取、列出、创建、补丁更新、删除分类法组。
- 内容条目管理：获取内容条目；获取内容条目变体（语言版本/翻译），返回当前版本——存在草稿则返回草稿，否则返回已发布版本；获取已发布内容条目变体版本；获取内容条目所有翻译；列出、筛选、搜索内容条目变体；创建内容条目（仅创建容器，需用创建变体工具添加语言版本/翻译）；按 ID 更新内容条目；按 ID 删除内容条目；创建内容条目变体（将当前用户设为贡献者）；更新内容条目变体；创建新的内容条目变体版本；删除内容条目变体；批量获取内容条目变体；基于语义的 AI 搜索内容条目变体。
- 资产管理：获取指定资产、列出所有资产、按 ID 更新资产。
- 资产文件夹管理：列出资产文件夹、通过补丁操作修改资产文件夹（addInto 新增、rename 重命名、remove 删除）。
- 语言管理：列出所有语言（含活动与非活动，需检查 is_active 属性）、创建语言（始终创建为活动）、通过 replace 更新语言（仅活动语言可修改，激活/停用需使用 Kontent.ai Web UI）。
- 集合管理：列出集合、通过补丁操作更新集合（addInto 新增、move 重排、remove 删除空集合、replace 重命名）。
- 空间管理：列出、创建、补丁更新、删除空间。
- 角色管理：列出角色，需要 Enterprise 或 Flex 套餐及“Manage custom roles”权限。
- 工作流管理：列出、创建、更新、删除工作流；更改内容条目变体的工作流步骤；发布或计划发布内容条目变体；取消发布或计划取消发布内容条目变体；取消计划发布。
使用方式 使用前需要准备：Kontent.ai 账户（没有则注册）、一个项目、具备相应权限的 Management API 密钥、以及环境 ID。服务器可通过 npx 运行。
服务器支持两种模式，与传输方式对应：
- 单租户模式（STDIO）：通过环境变量配置凭据。
- 多租户模式（Streamable HTTP）：凭据按请求提供——环境 ID 作为 URL 路径参数 /{environmentId}/mcp，API 密钥通过 Authorization 请求头以 Bearer 令牌传递（Authorization: Bearer <api-key>）。此模式允许单个服务器实例处理多个 Kontent.ai 环境的请求，无需凭据环境变量。在该传输方式下，即使服务器环境中设置了 KONTENT_API_KEY 和 KONTENT_ENVIRONMENT_ID 也会被忽略；每个请求必须自带凭据，缺失凭据的请求会被拒绝，而不会使用服务器自身的凭据。
配置方面，可按客户端分别配置。VS Code 可在工作区的 .vscode/mcp.json 文件中配置（支持带输入提示的安全配置）；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 作为代理添加认证请求头；Claude Code 可通过 CLI 添加服务器，也可在设置 JSON 中使用 url 和 headers 属性配置。配置时需将 <environment-id> 替换为 Kontent.ai 环境 ID（GUID），将 <management-api-key> 替换为管理 API 密钥。Streamable HTTP 传输方式下，先启动服务器。
项目结构 源代码中，src/ 为源码，tools/ 为 MCP 工具实现，clients/ 为 Kontent.ai API 客户端设置，schemas/ 为数据校验 schema，utils/ 为工具函数（errorHandler.ts 提供 MCP 工具的标准化错误处理，throwError.ts 为通用错误抛出工具），app.ts 是 Streamable HTTP 传输的 Express 应用工厂，server.ts 为主服务器设置与工具注册，bin.ts 为处理两种传输类型的单一入口。
调试与发布 调试可使用 MCP inspector，或对运行中的 Streamable HTTP 服务器使用 MCP inspector，其提供用于检查和测试可用工具的 Web 界面。发布新版本的流程为：使用 npm version [patch|minor|major] 更新版本（会更新 package.json、package-lock.json 并同步到 server.json）；将提交推送到分支并创建拉取请求；合并拉取请求；创建新的 GitHub release，以版本号作为名称和标签并使用自动生成的发布说明；发布 release 会触发自动化工作流，将包发布到 npm 和 GitHub MCP registry。
安全与限制 官方明确提示间接提示注入风险：服务器返回的内容（例如编辑撰写的元素）可能包含被连接的 LLM 解释为指令的文本。被劫持的智能体可能被引导执行破坏性工具调用（删除、取消发布、覆盖）或泄露未发布的草稿。这是行业范围内尚未解决的问题，服务器无法通过转换返回内容可靠修复，因此采取分层防御：使用最小权限的 Management API 密钥（只读密钥可在 API 边界直接使破坏性调用失败）；保持人工在环，每个工具带有 MCP 注解——读取为 readOnlyHint，仅创建的工具为 additive，覆盖或删除数据的工具为 destructiveHint——合规客户端据此自动批准读取并在破坏性调用前提示，建议避免使用可写密钥的无头自动批准配置；如客户端支持，可添加客户端侧门控（例如 Claude Code hooks）在破坏性工具运行前确定性地提示。官方强调这些只是提示而非保证，安全问题应私下报告至 security@kontent.ai。
其他限制：语言激活/停用需在 Kontent.ai Web UI 中进行，服务器仅能修改活动语言；删除工作流前该工作流不能被任何内容条目使用，更新工作流时也不能移除正在使用的步骤；角色列表功能需要 Enterprise 或 Flex 套餐以及“Manage custom roles”权限。
