capawesome-mcp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Capawesome MCP Server

Connect an MCP client to the hosted Capawesome MCP server for always-current documentation search and Capawesome Cloud management.

The server is hosted by Capawesome — there is nothing to install and nothing to keep up to date:

https://mcp.capawesome.io/mcp

It serves two things:

Documentation — search and read the current Capawesome documentation and blog. No token required. This is always more up to date than any reference file bundled with a skill.
Capawesome Cloud — manage apps, builds, deployments, channels, devices, environments, certificates, and jobs. Requires an API token.

将MCP客户端连接至托管的Capawesome MCP服务器，以获取实时更新的文档搜索功能和Capawesome Cloud管理权限。

该服务器由Capawesome托管——无需安装任何内容，也无需进行版本更新：

https://mcp.capawesome.io/mcp

它提供两项核心服务：

文档服务——搜索和查阅最新的Capawesome文档及博客。无需令牌。此服务的内容始终比技能包中捆绑的任何参考文件更及时。
Capawesome Cloud服务——管理应用、构建、部署、渠道、设备、环境、证书和任务。需要API令牌。

Prerequisites

前提条件

An MCP client: Claude Code, Claude Desktop, Cursor, VS Code, or any other client that implements the Model Context Protocol.
For Capawesome Cloud tools only: a Capawesome Cloud account and an API token.

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

Agent Behavior

Agent行为规范

Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
Auto-detect before asking. Detect the MCP client from the project and environment before asking the user which one they use.
Never ask for a token unless Cloud tools are wanted. The documentation tools work without authentication. Only start the token flow when the user wants Capawesome Cloud management.
Never write a token into a file that is tracked by Git. See Handling Tokens.

分步指导：引导用户逐步完成流程，切勿同时提出多个无关问题。
先自动检测再询问：先从项目和环境中检测MCP客户端，再询问用户使用的客户端类型。
仅在需要Cloud工具时请求令牌：文档工具无需认证即可使用。仅当用户需要Capawesome Cloud管理功能时，才启动令牌流程。
切勿将令牌写入Git追踪的文件：详见令牌处理。

Procedures

操作流程

Step 1: Determine Which Toolsets Are Needed

步骤1：确定所需工具集

Ask the user which of the following they want, and register only that:

Documentation only — search and read the Capawesome documentation. No token needed. Use
```
?toolsets=docs
```
(the default when no query parameter is given).
Documentation and Capawesome Cloud — the full surface. Requires a token. Use
```
?toolsets=all
```
. This is what most setups want.
A specific subset — read
```
references/toolsets.md
```
and pick the toolsets matching the user's task. Fewer tools take up less context and make the client pick the right tool more often.

If the user is unsure, recommend option 2.

Additionally, ask whether the server should be read-only. Appending

?readonly=true

registers read-only tools only, so nothing can be created, changed, or deleted. Recommend it for shared, unattended, or CI setups.

询问用户需要以下哪一项功能，并仅注册对应工具集：

仅文档服务——搜索和查阅Capawesome文档。无需令牌。使用
```
?toolsets=docs
```
（未提供查询参数时的默认值）。
文档服务+Capawesome Cloud服务——完整功能。需要令牌。使用
```
?toolsets=all
```
。这是大多数场景的推荐选项。
特定子集——查阅
```
references/toolsets.md
```
并选择与用户任务匹配的工具集。工具越少，占用的上下文越少，客户端也能更精准地选择合适工具。

若用户不确定，推荐选项2。

此外，询问用户是否要将服务器设置为只读模式。追加

?readonly=true

将仅注册只读工具，无法创建、修改或删除任何内容。推荐在共享、无人值守或CI环境中使用此模式。

Step 2: Create an API Token

步骤2：创建API令牌

Skip this step if the user chose documentation only in Step 1.

Tell the user to open the Capawesome Cloud Console and create an API token.
Warn the user that the token is shown only once and must be copied immediately.
Wait for the user to confirm they have the token before continuing.

A token acts on behalf of the account that created it, so the server can do whatever that account can do across its organizations and apps. Requests go through the same Cloud API as the Capawesome CLI, which means the same permissions, network restrictions, and rate limits apply.

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

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

令牌代表创建它的账户执行操作，因此服务器可在该账户的所有组织和应用中执行账户权限范围内的任何操作。请求通过与Capawesome CLI相同的Cloud API进行，这意味着适用相同的权限、网络限制和速率限制。

Step 3: Detect the MCP Client

步骤3：检测MCP客户端

Detect the client instead of asking, by checking the project in this order:

```
.mcp.json
```
or
```
.claude/
```
in the project root → Claude Code
```
.cursor/mcp.json
```
or
```
.cursor/
```
in the project root → Cursor
```
.vscode/
```
in the project root → VS Code

If none of these exist, or if more than one matches, ask the user which client to configure.

优先通过以下顺序检查项目来检测客户端，而非直接询问用户：

项目根目录下存在
```
.mcp.json
```
或
```
.claude/
```
→ Claude Code
项目根目录下存在
```
.cursor/mcp.json
```
或
```
.cursor/
```
→ Cursor
项目根目录下存在
```
.vscode/
```
→ VS Code

若以上均不存在，或存在多个匹配项，则询问用户要配置哪个客户端。

Step 4: Add the Server

步骤4：添加服务器

Read

references/client-setup.md

and apply the section for the detected client. Build the server URL from the choices made in Step 1:

Choice	URL
Documentation only	`https://mcp.capawesome.io/mcp`
Documentation and Capawesome Cloud	`https://mcp.capawesome.io/mcp?toolsets=all`
Capawesome Cloud only	`https://mcp.capawesome.io/mcp?toolsets=cloud`
Specific toolsets	`https://mcp.capawesome.io/mcp?toolsets=docs,cloud-apps,cloud-app-builds`
Read-only	Append `&readonly=true` , or `?readonly=true` when there is no other parameter

Always quote the URL when passing it on the command line, otherwise the shell interprets the query parameters.

Omit the

Authorization

header entirely for a documentation-only setup.

查阅

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

头。

Step 5: Restart the Client and Verify

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

Tell the user to restart their MCP client so it picks up the new server.
Verify the documentation tools by asking the client to run
```
search_docs
```
with a query such as
```
live update rollback
```
.
If Cloud tools were registered, verify them by asking the client to run
```
cloud_get_current_user
```
. It returns the account the token belongs to.
If either call fails, go to Error Handling.

告知用户重启MCP客户端以加载新服务器配置。
通过让客户端执行
```
search_docs
```
命令（例如查询
```
live update rollback
```
）来验证文档工具是否正常工作。
若已注册Cloud工具，通过让客户端执行
```
cloud_get_current_user
```
命令来验证。该命令会返回令牌所属的账户信息。
若任一命令失败，请前往错误处理部分。

Step 6: Use the Server

步骤6：使用服务器

Once connected, prefer the MCP tools over bundled reference files and over model knowledge whenever the topic is Capawesome:

search_docs
— search the documentation and blog by keyword. Start here; snippets are short by design.
get_doc_page
— read a full page as Markdown, using a URL from
```
search_docs
```
. Read the whole page before writing code against a plugin API, a CLI command, or a Cloud workflow — search snippets regularly omit required configuration steps.
list_blog_posts
— list the most recent blog posts, for announcements and release notes.
cloud_*
— manage Capawesome Cloud. Read
```
references/toolsets.md
```
for the toolset each tool belongs to.

连接成功后，当涉及Capawesome相关主题时，优先使用MCP工具而非捆绑的参考文件或模型知识库：

search_docs
—— 通过关键词搜索文档和博客内容。建议从此工具开始使用；其返回的片段设计为简短精炼。
get_doc_page
—— 以Markdown格式读取完整页面内容，使用
```
search_docs
```
返回的URL。在编写插件API、CLI命令或Cloud工作流相关代码前，请完整阅读页面内容——搜索片段通常会遗漏必要的配置步骤。
list_blog_posts
—— 列出最新的博客文章，用于查看公告和发布说明。
cloud_*
—— 管理Capawesome Cloud。查阅
```
references/toolsets.md
```
了解各工具所属的工具集。

Handling Tokens

令牌处理

A few Cloud tools accept sensitive values — environment secrets, signing certificates, and app store credentials. Anything passed to a tool becomes part of the conversation and is sent to the AI provider, and it may end up in chat history or logs outside the user's control.

Apply these rules:

Never commit a token.
```
.mcp.json
```
,
```
.cursor/mcp.json
```
, and
```
claude_desktop_config.json
```
in a project are tracked by Git. Prefer a setup that keeps the token out of the file: the VS Code
```
inputs
```
prompt, an environment variable, or the user-scoped configuration.
Set production secrets with the Capawesome CLI or the Console, not through MCP tools. Use the MCP server for reading and for values the user would be fine seeing in a transcript.
If a token may have leaked, tell the user to revoke it in the Capawesome Cloud Console and create a new one.

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

请遵循以下规则：

切勿提交令牌：项目中的
```
.mcp.json
```
、
```
.cursor/mcp.json
```
和
```
claude_desktop_config.json
```
会被Git追踪。优先采用将令牌保存在文件外的配置方式：VS Code的
```
inputs
```
提示、环境变量或用户范围的配置。
使用Capawesome CLI或控制台设置生产密钥，而非通过MCP工具。仅使用MCP服务器读取信息，或处理用户可接受出现在对话记录中的值。
若令牌可能已泄露，告知用户在Capawesome Cloud控制台中吊销该令牌并创建新令牌。

Error Handling

错误处理

Server not listed after setup: The client was not restarted. Restart it. In Claude Code, run
```
claude mcp list
```
to confirm the server is registered.
401 Unauthorized
: The token is missing, malformed, or revoked. Verify the header value is
```
Bearer <TOKEN>
```
including the space, and that the token still exists in the Console.
Documentation tools work but no
cloud_*
tools appear: The URL is missing
```
?toolsets=all
```
(or a
```
cloud-*
```
toolset), or the
```
Authorization
```
header was not sent. Check the URL and the header.
Only read tools appear: The URL contains
```
readonly=true
```
. Remove it to register write tools.
Shell reports "no matches found" or drops the query parameters: The URL was not quoted on the command line. Wrap it in double quotes.
Claude Desktop cannot reach the server: The Claude Desktop config file only starts local commands. Use
```
mcp-remote
```
as shown in
```
references/client-setup.md
```
.
403 Forbidden
on Cloud tools: The account lacks permission for that organization or app, or an organization network restriction blocks the request. Verify with
```
cloud_get_current_user
```
and
```
cloud_list_organizations
```
.
Rate limited: The same rate limits as the Cloud API apply. Retry after a short wait.

设置后未列出服务器：客户端未重启。请重启客户端。在Claude Code中，运行
```
claude mcp list
```
确认服务器已注册。
401 Unauthorized
：令牌缺失、格式错误或已被吊销。验证请求头值是否为
```
Bearer <TOKEN>
```
（包含空格），并确认令牌仍存在于控制台中。
文档工具正常工作但无
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-mcp

Original

Translation

Capawesome MCP Server

Capawesome MCP Server

Prerequisites

前提条件

Agent Behavior

Agent行为规范

Procedures

操作流程

Step 1: Determine Which Toolsets Are Needed

步骤1：确定所需工具集

Step 2: Create an API Token

步骤2：创建API令牌

Step 3: Detect the MCP Client

步骤3：检测MCP客户端

Step 4: Add the Server

步骤4：添加服务器

Step 5: Restart the Client and Verify

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

Step 6: Use the Server

步骤6：使用服务器

Handling Tokens

令牌处理

Error Handling

错误处理

Related Skills

相关技能