Total CMS

Total CMS 桌面扩展（MCPB）

一个Claude Desktop 扩展， 可将 Claude 连接到任意 Total CMS 网站内置的 MCP 服务。只需安装一次，Claude 就可以搜索文档、浏览内容，并且 （使用 API 密钥时）直接管理你的 Total CMS 网站。

这是一个本地桥接程序，而不是托管式连接器：它会在你的设备上运行一个小型 Node 进程，通过 HTTPS 将 MCP 流量代理到你网站的 /mcp 端点。这样它就可以为经过身份验证的访问添加自定义 X-API-Key 标头——Claude Desktop 内置的远程 连接器无法为声明支持可选身份验证的服务执行此操作。

隐私政策

此扩展不会收集、传输或存储任何自身数据。它会从你的设备直接向你配置的 Total CMS MCP 端点建立 HTTPS 连接（默认值：https://totalcms.co/mcp，即官方 Total CMS 文档网站），并在 Claude Desktop 与该端点之间中继 MCP 协议消息。你的可选 API 密钥会存储在操作系统的安全 凭据存储区中（通过 Claude Desktop 的 sensitive: true 配置处理），并且 只会作为 X-API-Key 请求标头发送到你配置的网站—— 绝不会记录，也不会发送到其他任何地方。

有关 Total CMS 产品和 totalcms.co 本身的隐私政策，请参阅 **https://totalcms.co/privacy**。

设置

零配置：询问有关 Total CMS 本身的问题

只需安装扩展。默认情况下，它会连接到 https://totalcms.co/mcp，即 官方 Total CMS 文档服务，因此 Claude 可以立即回答诸如“如何在 Total CMS 中设置 Webhook？”或“Total CMS 支持哪些架构 字段？”之类的问题，无需进行任何配置。

连接到你自己的网站

1. 在 Total CMS 管理后台中，前往 Settings -> MCP，复制网站的 MCP 端点 URL（格式类似 https://yoursite.com/mcp；如果你将 Total CMS 安装在子路径中，URL 也会包含 子路径）。
2. 在 Claude Desktop 的 Total CMS 扩展设置中，将该 URL 粘贴到 Total CMS MCP endpoint。
3. 重新安装/重新连接。Claude 现在可以浏览和搜索你网站上公开的 集合。

经过身份验证的访问

1. 在网站的 Settings → API Keys 中创建 Total CMS API 密钥。该密钥的 Scopes 允许执行什么操作，Claude 就能执行什么操作：
   • 完整管理员访问权限： 所有端点（*）以及所有 HTTP 方法。
   • 有限访问权限： 将 /mcp 添加到密钥的路径中，并添加它应当访问的集合， 例如 /api/collections/blog。仅添加 /mcp 可以访问 端点，但无法访问任何内容。密钥的 HTTP 方法决定其可用工具： 仅允许 GET 的密钥只能进行只读连接。只有当集合的 MCP 访问权限设置为API keys或更高时， 有限权限密钥才能访问该集合。请参阅 通过 MCP 使用密钥。
2. 将密钥粘贴到扩展设置中的 API key (optional) 字段。 密钥会存储在操作系统的密钥链中，而不是以明文形式保存。
3. Claude 现在除了可以访问公开内容外，还可以访问该密钥允许的内容。 如果使用具有架构管理权限的完整管理员密钥，还可以访问模板、网站 信息并清除缓存。将此字段留空，Claude 就只能进行公开的匿名访问。

其他 MCP 客户端

该桥接程序是一个纯 stdio MCP 服务，因此任何能启动本地服务的客户端（Cursor、VS Code、Windsurf 等）都可以通过 Node 18 或更高版本运行它。支持带自定义标头的远程服务的客户端可以跳过桥接程序，直接连接到你的网站的 /mcp 端点。

1. 从最新版本下载 totalcms.mcpb。这是一个 zip 压缩包：解压到任意位置即可。里面的 server/index.js 是独立文件，无需运行 npm install。

2. 将其添加到客户端的 MCP 配置中：

   {
     "mcpServers": {
       "totalcms": {
         "command": "node",
         "args": ["/path/to/totalcms/server/index.js"],
         "env": {
           "MCP_URL": "https://yoursite.com/mcp",
           "API_KEY": ""
         }
       }
     }
   }
   

   将 MCP_URL 留空即可使用 Total CMS 文档服务；将 API_KEY 留空即可匿名公开访问。

若要改为从源代码构建，运行 npm install && npm run build 会生成 server/index.js。

工作原理

server/index.js 是一个小型 stdio MCP 服务，由 Claude Desktop 直接启动（无需安装 Node - MCPB 软件包包含自己的运行时处理逻辑）。它会与配置的 MCP_URL 建立可流式传输的 HTTP连接，并原样双向转发每条 JSON-RPC 消息：initialize、tools/list、tools/call、resources/*、prompts/* 以及所有通知。设置 API_KEY 后，每个发出的 HTTP 请求都会携带 X-API-Key 标头。

除非 MCP_URL 使用 https://，否则服务不会启动——不允许在网络上传输明文凭据，即使是在本地测试时也不行。

为什么不用 mcp-remote？

我们最初试用过它（完整说明请参阅 BUILD-REPORT.md）。简而言之：mcp-remote 启动时会无条件运行 OAuth 发现；收到任何 HTTP 401 响应时，都会启动基于浏览器的 OAuth 授权流程，而且没有任何选项可以禁用。Total CMS 使用普通的 API 密钥标头，而非 OAuth——错误的密钥应当向 MCP 客户端返回清晰的 401 错误，而不是让客户端卡在浏览器弹窗后，尝试对不支持 OAuth 的服务进行 OAuth 认证。因此，这个软件包采用基于 @modelcontextprotocol/sdk 的 StreamableHTTPClientTransport 和 StdioServerTransport 直接手动编写了一个小型代理。

开发

npm install
npm run build     # typecheck -> esbuild bundle -> mcpb validate -> mcpb pack

这会生成 dist/totalcms.mcpb。将该文件拖到 Claude Desktop 上即可安装。

npm run typecheck 和 npm run validate 可单独运行。

发布

npm run bump 0.3.0                  # rewrites the version in all four files
# add a "## [0.3.0] - YYYY-MM-DD" section to CHANGELOG.md
git commit -am "Release v0.3.0"
git tag v0.3.0 && git push origin master v0.3.0

推送标签即可完成整个发布流程。Release 工作流会构建软件包，将其附加到 GitHub Release，并以 io.github.totalcms/total-cms 的名称将新版本发布到 MCP Registry。

GitHub Release 说明与 CHANGELOG.md 中对应的部分一致，因此版本发布内容应写在该文件中——请在打标签前写好。若缺少对应部分，系统会发出警告，并改用自动生成的说明，而不会导致构建失败；绝不应仅仅因为没有写好说明就阻止发布。

还有两点值得注意：

• MCP Registry 与 GitHub Releases 是两个独立的系统。 从 MCP 目录安装的用户会通过 Registry 获取更新，而非从发布页面获取——只向其中一个发布会让这些用户停留在旧版本。因此，工作流会同时发布到两处，也因此绝不应手动发布版本。
• server.json 中的 fileSha256 由 CI 写入，因为 zip 文件会嵌入时间戳，CI 构建生成的哈希值与本地构建生成的哈希值永远不会相同。提交到 git 的值仅记录了最近一次本地构建；请忽略它。

通过 GitHub OIDC 向 Registry 进行身份验证，因此无需轮换密钥。若要重新发布已有的标签，或重新发布在此工作流创建之前发布的标签，请从 Actions 选项卡手动运行 Release 工作流，并提供该标签。

安全说明

• 不访问文件系统，不启动子进程，只向一个主机发出出站 HTTPS 请求（即 MCP_URL 指向的主机）。
• API 密钥从 API_KEY 环境变量中读取（由 Claude Desktop 从密钥链中存储的配置设置），绝不会写入 stdout、stderr 或任何日志。
• MCP_URL 必须使用 https://，否则进程会拒绝启动。

许可证

源代码采用 MIT 许可证。Total CMS 名称、火焰徽标和随附的 icon.png 均为商标，不受该许可授权的约束——你可以分叉代码，但重新分发的版本不得声称由 Total CMS 发布或认可。请参阅 TRADEMARKS.md。