JinDaGe - mcp-server MCP Details

article

README

🚀 Kontent.ai MCP Server

Kontent.ai MCP Server 借助人工智能驱动的工具，变革您的内容运营方式。您可以在喜爱的支持 AI 的编辑器中，通过自然语言对话来创建、管理和探索结构化内容。该服务器实现了模型上下文协议，可将您的 Kontent.ai 项目与 Claude、Cursor 和 VS Code 等 AI 工具相连接，使 AI 模型能够理解您的内容结构，并通过自然语言指令执行操作。

🚀 快速开始

🔑 前提条件

在使用 MCP 服务器之前，您需要完成以下准备工作：

Kontent.ai 账户：如果您还没有账户，请注册。
项目：创建一个项目以供使用。
管理 API 密钥：创建一个管理 API 密钥，并赋予其适当的权限。
环境 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 管理 API 的补丁操作指南。

内容类型管理

get-type-mapi – 通过管理 API 按内部 ID 获取 Kontent.ai 内容类型。
list-content-types-mapi – 通过管理 API 获取所有 Kontent.ai 内容类型。
add-content-type-mapi – 通过管理 API 添加新的 Kontent.ai 内容类型。
patch-content-type-mapi – 使用补丁操作（移动、添加、移除、替换）按代号更新现有的 Kontent.ai 内容类型。
delete-content-type-mapi – 按代号删除 Kontent.ai 内容类型。

内容类型片段管理

get-type-snippet-mapi – 通过管理 API 按内部 ID 获取 Kontent.ai 内容类型片段。
list-content-type-snippets-mapi – 通过管理 API 获取所有 Kontent.ai 内容类型片段。
add-content-type-snippet-mapi – 通过管理 API 添加新的 Kontent.ai 内容类型片段。
patch-type-snippet-mapi – 使用补丁操作（移动、添加、移除、替换）按内部 ID 更新现有的 Kontent.ai 内容类型片段。
delete-type-snippet-mapi – 按代号删除 Kontent.ai 内容类型片段。

分类法管理

get-taxonomy-group-mapi – 通过管理 API 按内部 ID 获取 Kontent.ai 分类法组。
list-taxonomy-groups-mapi – 通过管理 API 获取所有 Kontent.ai 分类法组。
add-taxonomy-group-mapi – 通过管理 API 添加新的 Kontent.ai 分类法组。
patch-taxonomy-group-mapi – 通过管理 API 使用补丁操作（添加、移动、移除、替换）更新 Kontent.ai 分类法组。
delete-taxonomy-group-mapi – 按内部 ID 删除 Kontent.ai 分类法组。

内容项管理

get-item-mapi – 通过管理 API 按内部 ID 获取 Kontent.ai 项。
get-latest-variant-mapi – 通过管理 API 获取 Kontent.ai 语言变体的最新版本。
get-published-variant-mapi – 通过管理 API 获取 Kontent.ai 语言变体的已发布版本。
list-variants-item-mapi – 通过管理 API 列出内容项的所有 Kontent.ai 语言变体。
list-variants-collection-mapi – 通过管理 API 按集合列出 Kontent.ai 语言变体（分页）。
list-variants-type-mapi – 通过管理 API 按内容类型列出 Kontent.ai 语言变体（分页）。
list-variants-components-type-mapi – 通过管理 API 列出包含特定内容类型组件的 Kontent.ai 语言变体（分页）。
list-variants-space-mapi – 通过管理 API 按空间列出 Kontent.ai 语言变体（分页）。
add-content-item-mapi – 通过管理 API 添加新的 Kontent.ai 内容项。此操作仅创建内容项结构，不会向语言变体添加内容。请使用 upsert-language-variant-mapi 向项添加内容。
update-content-item-mapi – 通过管理 API 按内部 ID 更新现有的 Kontent.ai 内容项。内容项必须已经存在，此工具不会创建新项。
delete-content-item-mapi – 通过管理 API 按内部 ID 删除 Kontent.ai 内容项。
upsert-language-variant-mapi – 通过管理 API 创建或更新 Kontent.ai 内容项的语言变体。元素值必须满足内容类型中定义的限制和指南。更新时，仅修改提供的元素。
create-variant-version-mapi – 通过管理 API 创建 Kontent.ai 语言变体的新版本。此操作会为现有语言变体创建新版本，适用于内容版本控制和从已发布内容创建新草稿。
delete-language-variant-mapi – 通过管理 API 删除 Kontent.ai 语言变体。
filter-variants-mapi – 使用管理 API 过滤内容项的 Kontent.ai 语言变体。用于精确关键字匹配和在内容中查找特定术语。支持完整的过滤功能（内容类型、工作流步骤、分类法等），并可选择包含变体的完整内容。返回带延续令牌的分页结果，用于获取后续页面。
search-variants-mapi – 由人工智能驱动的语义搜索，用于按特定语言变体中的含义和概念查找内容。适用于不知道精确关键字的概念性搜索。过滤选项有限（仅变体 ID）。

资产管理

get-asset-mapi – 通过管理 API 按内部 ID 获取特定的 Kontent.ai 资产。
list-assets-mapi – 通过管理 API 获取所有 Kontent.ai 资产。
update-asset-mapi – 通过管理 API 按内部 ID 更新 Kontent.ai 资产。

资产文件夹管理

list-asset-folders-mapi – 列出所有 Kontent.ai 资产文件夹。
patch-asset-folders-mapi – 使用补丁操作（添加新文件夹、重命名、删除文件夹）修改 Kontent.ai 资产文件夹。

语言管理

list-languages-mapi – 通过管理 API 获取所有 Kontent.ai 语言。
add-language-mapi – 通过管理 API 添加新的 Kontent.ai 语言。
patch-language-mapi – 通过管理 API 使用替换操作更新 Kontent.ai 语言。

集合管理

list-collections-mapi – 通过管理 API 获取所有 Kontent.ai 集合。集合为您环境中的内容项设置边界，并有助于按团队、品牌或项目组织内容。
patch-collections-mapi – 使用补丁操作（添加新集合、移动、删除空集合、重命名）更新 Kontent.ai 集合。

空间管理

list-spaces-mapi – 通过管理 API 获取所有 Kontent.ai 空间。
add-space-mapi – 向环境中添加 Kontent.ai 空间。
patch-space-mapi – 使用替换操作修补 Kontent.ai 空间。
delete-space-mapi – 删除 Kontent.ai 空间。

工作流管理

list-workflows-mapi – 通过管理 API 获取所有 Kontent.ai 工作流。工作流定义了内容生命周期阶段及其之间的转换。
change-variant-workflow-step-mapi – 更改 Kontent.ai 中语言变体的工作流步骤。此操作将语言变体移动到工作流中的不同步骤，实现内容生命周期管理，如将内容从草稿移动到审核、从审核移动到发布等。
publish-variant-mapi – 在 Kontent.ai 中发布或安排发布内容项的语言变体。此操作可以立即发布变体，也可以安排在特定的未来日期和时间发布，并可选择指定时区。
unpublish-variant-mapi – 在 Kontent.ai 中取消发布或安排取消发布内容项的语言变体。此操作可以立即取消发布变体（使其无法通过交付 API 使用），也可以安排在特定的未来日期和时间取消发布，并可选择指定时区。

⚙️ 配置

服务器支持两种配置模式：

单租户模式（默认）

对于单租户模式，需要配置环境变量： | 变量 | 描述 | 是否必需 | |------|------|----------| | KONTENT_API_KEY | 您的 Kontent.ai 管理 API 密钥 | ✅ | | KONTENT_ENVIRONMENT_ID | 您的环境 ID | ✅ | | PORT | HTTP 传输的端口（默认为 3001） | ❌ | | appInsightsConnectionString | 用于遥测的应用程序洞察连接字符串 | ❌ | | projectLocation | 用于遥测跟踪的项目位置标识符 | ❌ | | manageApiUrl | 自定义管理 API 基本 URL（用于预览环境） | ❌ |

多租户模式

对于多租户模式（仅适用于可流式传输的 HTTP），服务器接受以下参数：

环境 ID 作为 URL 路径参数：/{environmentId}/mcp
API 密钥 通过授权标头中的承载令牌：Authorization: Bearer <api-key>

此模式允许单个服务器实例安全地处理多个 Kontent.ai 环境的请求，而无需环境变量。

🔧 响应优化

MCP 服务器实现了自动令牌优化，以降低人工智能模型成本并提高性能：

令牌减少策略

服务器会自动从响应中移除空值或默认值，以减少令牌使用量，包括：

空值和未定义值
空字符串 ("")
空数组 ([])
空对象 ({})
富文本占位符 (" ")
移除空值后仅包含 ID 的元素

对人工智能代理的影响

对于人工智能实现很重要：在使用此 MCP 服务器的响应时：

缺失的属性表示默认值，而非缺失数据。
变体中缺失的元素具有其特定类型的默认值：
- 文本元素：""（空字符串）
- 富文本：" "（空占位符）
- 数字/日期：null
- 自定义元素：null（值和可搜索值）
- 数组（资产、分类法等）：[]
创建/更新内容时，请始终发送完整数据。

🚀 传输选项

📟 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 传输，首先启动服务器：

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

单租户模式

在 .env 文件中设置环境变量，或者确保进程可以访问这些变量：

KONTENT_API_KEY=<management-api-key>
KONTENT_ENVIRONMENT_ID=<environment-id>
PORT=3001  # 可选，默认为 3001

然后在您的 MCP 客户端中进行如下配置：

{
  "kontent-ai-http": {
    "url": "http://localhost:3001/mcp"
  }
}

多租户模式

无需环境变量。服务器使用 URL 路径参数和承载身份验证接受多个环境的请求。

VS Code

在您的工作区中创建一个 `.vscode/mcp.json` 文件： ```json { "servers": { "kontent-ai-multi": { "uri": "http://localhost:3001//mcp", "headers": { "Authorization": "Bearer " } } } } ``` 如需通过输入提示进行安全配置，请使用以下配置： ```json { "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}" } } } } ```

Claude Desktop

更新您的 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` 作为代理添加身份验证标头： ```json { "mcpServers": { "kontent-ai-multi": { "command": "npx", "args": [ "mcp-remote", "http://localhost:3001//mcp", "--header", "Authorization: Bearer " ] } } } ```

Claude Code

使用 CLI 添加服务器： ```bash claude mcp add --transport http kontent-ai-multi \ "http://localhost:3001//mcp" \ --header "Authorization: Bearer " ``` > **注意**：您也可以在 Claude Code 设置 JSON 中使用 `url` 和 `headers` 属性进行配置。

⚠️ 重要提示

请将 <environment-id> 替换为您的 Kontent.ai 环境 ID（GUID），将 <management-api-key> 替换为您的管理 API 密钥。

💻 开发

🛠 本地安装

# 克隆仓库
git clone https://github.com/kontent-ai/mcp-server.git
cd mcp-server

# 安装依赖
npm ci

# 构建项目
npm run build

# 启动服务器
npm run start:stdio  # 对于 STDIO 传输
npm run start:shttp  # 对于可流式传输的 HTTP 传输

# 启动服务器并自动重新加载（无需先构建）
npm run dev:stdio  # 对于 STDIO 传输
npm run dev:shttp  # 对于可流式传输的 HTTP 传输

📂 项目结构

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 界面，用于检查和测试可用工具。

📦 发布流程

要发布新版本，请按以下步骤操作：

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

📄 许可证

本项目采用 MIT 许可证。

mcp-server

README

🚀 Kontent.ai MCP Server

🚀 快速开始

🔑 前提条件

🛠 安装选项

STDIO 传输

可流式传输的 HTTP 传输

✨ 主要特性

🛠️ 可用工具

补丁操作指南

内容类型管理

内容类型片段管理

分类法管理

内容项管理

资产管理

资产文件夹管理

语言管理

集合管理

空间管理

工作流管理

⚙️ 配置

单租户模式（默认）

多租户模式

🔧 响应优化

令牌减少策略

对人工智能代理的影响

🚀 传输选项

📟 STDIO 传输

🌊 可流式传输的 HTTP 传输

单租户模式

多租户模式

💻 开发

🛠 本地安装

📂 项目结构

🔍 调试

📦 发布流程

📄 许可证

Runtime guide

Hosted runtime

Local runtime / other methods