Umbraco-CMS-MCP-Dev

Umbraco MCP

一个适用于 Umbraco CMS 的 MCP（Model Context Protocol）服务，可解锁由 AI 驱动的内容管理功能。它全面提供对 Umbraco Management API 的访问权限，让 AI Agent 通过自然对话执行后台任务，让你不再受限于 UI，并轻松完成那些手动操作繁琐甚至无法完成的复杂、重复工作流。

简介

MCP 服务使用 Umbraco API 用户进行身份验证，确保以安全、基于权限的方式访问 Umbraco Management API。这意味着你可以通过 Umbraco 的标准用户权限系统，完全掌控 AI Agent 可以执行的操作，无需特殊的安全模型。

快速开始

1. 创建 Umbraco API 用户

首先，创建具有适当权限的 Umbraco API 用户。请参阅 Umbraco 文档中的说明。

2. 在 Claude Desktop 中安装

下载并安装 Claude Desktop 应用，然后将 MCP 服务添加到配置中：

1. 打开 Claude Desktop Settings > Developer > Edit Config
2. 将此配置添加到你的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "umbraco-mcp": {
      "command": "npx",
      "args": ["@umbraco-cms/mcp-dev@17"],
      "env": {
        "NODE_TLS_REJECT_UNAUTHORIZED": "0",
        "UMBRACO_CLIENT_ID": "your-api-user-id",
        "UMBRACO_CLIENT_SECRET": "your-api-secret",
        "UMBRACO_BASE_URL": "https://localhost:{port}",
        "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type"
      }
    }
  }
}

3. 完全重启 Claude Desktop（包括 Windows 系统托盘中的程序）

提示： 请将 @umbraco-cms/mcp-dev 固定到你站点使用的 Umbraco 主版本（例如上面的 @17，或 Umbraco 18.x 站点使用的 @18），而不是使用 @latest。工具架构对应的是该软件包自身主版本的 Management API，因此主版本不匹配时，如果工具结构已经发生变化，任务执行到一半可能会出现难以理解的失败。服务会在启动时检查所连接站点的版本，并在版本不匹配时发出警告；但固定版本可以彻底避免这种情况。

文档

如需完整的安装说明、配置选项、工具列表和使用示例，请参阅完整文档：

Umbraco MCP 文档

托管部署

Cloudflare Worker 入口（src/worker.ts）支持两种部署模式，由 @umbraco-cms/mcp-hosted 库在请求时选择：

• 单租户（默认）——Worker 针对 wrangler.toml 中配置的 UMBRACO_BASE_URL 进行身份验证。这是现有行为，无需额外配置。
• 多租户 Umbraco Cloud——在 wrangler.toml 的 [vars] 下设置 UMBRACO_CLOUD_ROUTING_ENABLED = "true"。对 /at/{alias}/... 的请求会解析 {alias} 对应的上游 Umbraco Cloud 项目，并按照 MCP 资源指示器规范签发限定于该资源的访问令牌。Worker 服务的每个 Umbraco Cloud 项目都必须注册一个 ID 为 umbraco-cms-developer-mcp-hosted 的 OpenIddict 客户端。

siteRouting 始终会接入；是否启用则由每个请求对应的环境变量控制。

使用 AI 工具参与贡献

本项目针对使用 AI 编码助手进行开发做了优化。我们提供了热门 AI 工具的指令文件，以帮助保持一致的开发模式和测试标准。

使用 rulesync

项目包含 rulesync 配置文件，可自动为 19 种以上的 AI 开发工具生成指令文件。为你偏好的 AI 工具生成配置文件：

# Generate only for Claude Code
npx rulesync generate --claudecode

# Generate only for Cursor
npx rulesync generate --cursor

# Generate only for Vs Code Copilot
npx rulesync generate --copilot

其他 AI 工具

rulesync 支持 19 种以上的 AI 开发工具，包括 GitHub Copilot、Cline、Aider 等。请查看 rulesync 仓库，了解支持工具的完整列表。

指令文件涵盖：

• MCP 开发模式和约定
• TypeScript 实现指南
• 使用构建器和辅助工具的全面测试标准
• 项目专属背景信息和架构
• 与 Umbraco Management API 集成的模式