capawesome-mcp

Capawesome MCP Server

将 MCP 客户端连接到托管的 Capawesome MCP 服务，以随时搜索最新文档并管理 Capawesome Cloud。

该服务由 Capawesome 托管——无需安装，也无需保持更新：

https://mcp.capawesome.io/mcp

它提供两类功能：

• 文档 — 搜索和阅读最新的 Capawesome 文档与博客。无需令牌。其内容始终比随技能附带的任何参考文件更新。
• Capawesome Cloud — 管理应用、构建、部署、渠道、设备、环境、证书和作业。需要 API 令牌。

前置条件

1. MCP 客户端：Claude Code、Claude Desktop、Cursor、VS Code，或任何实现了 Model Context Protocol 的其他客户端。
2. 仅使用 Capawesome Cloud 工具时：Capawesome Cloud 账户和 API 令牌。

Agent 行为

• 逐步引导。 一次引导用户完成一个步骤。切勿一次提出多个无关问题。
• 先自动检测，再提问。 先根据项目和环境检测 MCP 客户端，再询问用户使用的是哪一个。
• 除非用户需要 Cloud 工具，否则绝不索要令牌。 文档工具无需身份验证。只有用户需要管理 Capawesome Cloud 时，才开始令牌流程。
• 绝不将令牌写入由 Git 跟踪的文件。 请参阅处理令牌。

操作流程

步骤 1：确定需要哪些工具集

询问用户需要以下哪一项，并且只注册所选工具集：

1. 仅文档 — 搜索和阅读 Capawesome 文档。无需令牌。使用 ?toolsets=docs（未提供查询参数时的默认值）。
2. 文档和 Capawesome Cloud — 完整功能集。需要令牌。大多数配置都需要此选项。使用 ?toolsets=all。
3. 特定子集 — 阅读 references/toolsets.md，选择与用户任务相匹配的工具集。工具越少，占用的上下文就越少，客户端也更容易选对工具。

如果用户不确定，建议选择选项 2。

另外，询问用户是否要将服务设为只读。添加 ?readonly=true 后，只会注册只读工具，因此无法创建、更改或删除任何内容。建议在共享、无人值守或 CI 环境中启用此选项。

步骤 2：创建 API 令牌

如果用户在步骤 1 中选择了仅文档，请跳过此步骤。

1. 告知用户打开 Capawesome Cloud Console 并创建 API 令牌。
2. 提醒用户令牌仅显示一次，必须立即复制。
3. 等待用户确认已获取令牌后再继续。

令牌代表创建它的账户执行操作，因此该服务能够在该账户所属的组织和应用中执行该账户有权执行的任何操作。请求会通过与 Capawesome CLI 相同的 Cloud API，因此适用相同的权限、网络限制和速率限制。

步骤 3：检测 MCP 客户端

按以下顺序检查项目以检测客户端，而不是直接询问：

1. 项目根目录中存在 .mcp.json 或 .claude/ → Claude Code
2. 项目根目录中存在 .cursor/mcp.json 或 .cursor/ → Cursor
3. 项目根目录中存在 .vscode/ → VS Code

如果以上都不存在，或者有多个匹配项，请询问用户要配置哪个客户端。

第 4 步：添加服务

阅读 references/client-setup.md，并应用其中适用于已检测到的客户端的部分。根据第 1 步的选择构建服务 URL：

选择	URL
仅文档	https://mcp.capawesome.io/mcp
文档和 Capawesome Cloud	https://mcp.capawesome.io/mcp?toolsets=all
仅 Capawesome Cloud	https://mcp.capawesome.io/mcp?toolsets=cloud
特定工具集	https://mcp.capawesome.io/mcp?toolsets=docs,cloud-apps,cloud-app-builds
只读	追加 &readonly=true；如果没有其他参数，则追加 ?readonly=true

在命令行传入 URL 时，务必将其括起来，否则 shell 会将查询参数解释为命令。

仅配置文档时，完全省略 Authorization 标头。

第 5 步：重启客户端并验证

1. 告知用户重启 MCP 客户端，以便加载新增的服务。
2. 让客户端运行 search_docs，并使用类似 live update rollback 的查询来验证文档工具。
3. 如果已注册 Cloud 工具，让客户端运行 cloud_get_current_user 来验证。它会返回令牌所属的账户。
4. 如果任一调用失败，请转到错误处理。

第 6 步：使用服务

连接后，只要主题涉及 Capawesome，就优先使用 MCP 工具，而不是捆绑的参考文件或模型知识：

• search_docs — 按关键词搜索文档和博客。请从这里开始；搜索摘要有意保持简短。
• get_doc_page — 使用 search_docs 返回的 URL，以 Markdown 格式读取完整页面。在针对插件 API、CLI 命令或 Cloud 工作流编写代码前，请阅读整个页面——搜索摘要经常会省略必需的配置步骤。
• list_blog_posts — 列出最新的博客文章，用于查看公告和发行说明。
• cloud_* — 管理 Capawesome Cloud。请阅读 references/toolsets.md，了解每个工具所属的工具集。

处理令牌

一些 Cloud 工具会接受敏感值，例如环境密钥、签名证书和应用商店凭据。传递给工具的任何内容都会成为对话的一部分，并发送给 AI 提供商，且可能出现在聊天记录或用户无法控制的日志中。

请遵守以下规则：

• 切勿提交令牌。 项目中的 .mcp.json、.cursor/mcp.json 和 claude_desktop_config.json 都由 Git 跟踪。优先选择不会将令牌写入文件的配置方式：VS Code 的 inputs 提示、环境变量或用户级配置。
• 使用 Capawesome CLI 或控制台设置生产密钥，而不是通过 MCP 工具设置。MCP 服务应用于读取数据，以及处理用户愿意在对话记录中看到的值。
• 如果令牌可能已泄露，请告知用户在 Capawesome Cloud 控制台中撤销该令牌并创建新令牌。

错误处理

• 设置后未列出服务：客户端未重启。请重启。在 Claude Code 中，运行 claude mcp list 以确认服务已注册。
• 401 Unauthorized：令牌缺失、格式错误或已撤销。请确认请求头的值为 Bearer <TOKEN>，中间包含空格，并确认该令牌仍存在于 Console 中。
• 文档工具可用，但未显示任何 cloud_* 工具：URL 缺少 ?toolsets=all（或某个 cloud-* 工具集），或者未发送 Authorization 请求头。请检查 URL 和请求头。
• 只显示读取工具：URL 包含 readonly=true。请移除它以注册写入工具。
• Shell 报告“no matches found”或丢弃查询参数：命令行中的 URL 未加引号。请用双引号括起来。
• Claude Desktop 无法连接到服务：Claude Desktop 配置文件只能启动本地命令。请按 references/client-setup.md 中的说明使用 mcp-remote。
• Cloud 工具返回 403 Forbidden：该账号没有相应组织或应用的权限，或者组织的网络限制阻止了请求。请使用 cloud_get_current_user 和 cloud_list_organizations 验证。
• 受到速率限制：此处适用与 Cloud API 相同的速率限制。请稍候片刻后重试。

相关技能

• capawesome-cloud — 用于设置原生构建、实时更新和应用商店发布。
• capawesome-cli — Capawesome CLI，可在终端和 CI/CD 中调用相同的 Cloud API。
• capacitor-plugins — 用于安装和配置 Capacitor 插件，包括此服务文档介绍的 Capawesome 插件。
• capacitor-expert — 全面的 Capacitor 参考，涵盖插件、框架集成和 Capawesome Cloud。
• capacitor-mcp — Capacitor MCP 服务，涵盖 Capacitor 本身和社区插件列表。
• ionic-framework-mcp — Ionic Framework MCP 服务，涵盖 UI 组件及其用法示例。