@cloudbase/cloudbase-mcp 2.35.2 → 2.36.1

package/README.md

@@ -129,6 +129,12 @@ Set `TCB_SITE` (`domestic` / `intl`) to select the login/credential site, and `T
 
 In **remote mode** the site is determined by the endpoint host itself—`tcb-api.cloud.tencent.com` is the China site, `tcb-api.tencentcloud.com` is the international site—and there is no `site` query parameter to set. This holds for a China-site environment in `ap-singapore` too: keep using the China-site endpoint. Self-hosted Cloud Mode deployments can still use the `TCB_SITE` environment variable.
 
+### Experimental: MCP Apps panels (off by default)
+
+`auth`, `queryEnv` and the deploy tools can render MCP Apps panels (`ui://cloudbase/*`) in hosts that support them. This is experimental and **switched off by default**: with no environment variable set, no `ui://` resource is registered and no tool carries `_meta.ui`, so a host sees an ordinary MCP server and results stay plain JSON text.
+
+Turn it on with `CLOUDBASE_MCP_UI=on` (also accepts `1` / `true` / `yes` / `enabled`). Anything else — `off`, `0`, `false`, `no`, `disabled`, or a typo — leaves it off. Tools behave identically either way; the flag only decides whether panels are offered.
+
 ## Capabilities
 
 Typical backend work in your environment (confirm critical steps):
@@ -140,6 +146,71 @@ Typical backend work in your environment (confirm critical steps):
 
 Tool catalog: [MCP tools](../doc/mcp-tools.md) · [tools.json](../scripts/tools.json)
 
+## Confirmations before destructive calls
+
+Deleting a cloud function, a collection, the documents in one, a stored file, a CloudRun service or a MySQL instance now pauses
+the call until you answer a dialog that names the target — "about to delete the cloud function `hello` (env `env-abc`)" — instead
+of asking a bare "are you sure?". The same deletes pause when they arrive as `callCloudApi`, but only for an explicit
+`service` + `Action` pair: `DeleteFunction` on `tcb` or `scf`, `tcb.DeleteTable`, `tcb.DeleteItem`, `tcb.DestroyEnv`, `tcb.DestroyPlatformEnv`, `tcb.DestroyMySQL`,
+`tcbr.DeleteCloudRunServer`, and `tcbr.DeleteCloudRunVersions` when `IsDeleteServer` is true. A `Delete` prefix does not
+confirm other cloud APIs. Cloud storage deletes do not go through `callCloudApi`. PostgreSQL `execute` / `applyMigration` pause only when the SQL itself is `DELETE`, `DROP`, `TRUNCATE` or `ALTER … DROP`; `INSERT`, `UPDATE` and `CREATE TABLE` do not. It is built on MCP form elicitation, so it
+can only appear where the client declares that capability *and* actually asks the user.
+
+| Situation | What happens |
+| --- | --- |
+| The client asks the user | You get the dialog; the call runs only after you pick "delete" |
+| The client is in a full-access / never-ask mode | It answers on its own within a few milliseconds. That is treated as "you were not asked", and the call proceeds |
+| The client cannot render forms | No dialog, and the call proceeds — the behaviour is the same as before this change |
+| You decline, dismiss it, or answer nothing for 45s | Nothing is executed, and the result says so **without** being marked as an error, so a model does not retry the same deletion |
+
+A declined call is not a failure: the tool returns "not executed" plus what to do instead. Two environment variables change the
+handling, and neither of them bypasses authentication, permissions or read-only limits — they only decide whether the question is
+asked:
+
+| Variable | Effect |
+| --- | --- |
+| `CLOUDBASE_MCP_SKIP_ELICITATIONS` | Comma-separated. Accepts a tool name (`manageFunctions`, `callCloudApi`) or a single action (`manageFunctions.deleteFunction`, `callCloudApi.tcb.DeleteFunction`), case-sensitive, no wildcard. Unknown entries are logged and ignored rather than failing the server |
+| `CLOUDBASE_MCP_ELICIT_AUTO_APPROVE` | `allow` (default) proceeds when the client answers for itself; `block` treats that case as not confirmed |
+
+A client's own tool-approval prompt is not this confirmation: it asks "may this tool run?", not "is this the resource you want to
+delete?".
+
+### Credential-shaped arguments: one real check before writing
+
+When a call's arguments contain something shaped like a credential — a three-part JWT, or a `cb_secret_…` / `cb_publishable_…`
+key — the server asks the client for one check before writing: compare the value against your original source and confirm. The
+message deliberately carries **no plaintext**: only the total length, the segment lengths (for a JWT), and a fingerprint (the first
+12 hex characters of sha256). That is enough to notice a value that was changed while being copied or transcribed, and nothing that
+would put the secret into the conversation or into the logs.
+
+**What this is not.** We do not decide whether the credential is valid. There is no signature verification, no `certs`/JWKS lookup,
+no network request of any kind, and no server-side comparison — the server never sees the value you originally pasted, so the only
+side that can compare it is the client. This is a request for a real confirmation at write time, not a validity check.
+
+**Boundaries.** It only applies when the arguments actually contain a credential-shaped string (otherwise the call is unchanged: one
+shallow scan, no network). It only applies when the client supports interactive form elicitation; a client that cannot ask proceeds
+as before, so an unattended client is not blocked. And a check that returns within a few hundred milliseconds counts as "nobody
+looked at it": unlike the deletion confirmation — where a client answering for itself is treated as "you were not asked" and the call
+proceeds — a credential write is **not** executed, because a value nobody compared is exactly the case this guards against. When the
+guard declines, the result says "not executed" **without** being marked as an error, so a model does not retry it blindly.
+
+| Variable | Effect |
+| --- | --- |
+| `CLOUDBASE_MCP_SKIP_CREDENTIAL_GUARD` | Comma-separated. Accepts a tool name (`manageCloudRun`) or a single action (`manageCloudRun.updateConfig`), case-sensitive, no wildcard. Unknown entries are logged and ignored rather than failing the server |
+
+## Get-started panel (MCP Apps)
+
+Where the client declares the `io.modelcontextprotocol/ui` extension, `auth` also opens a small read-only panel
+(`ui://cloudbase/get-started`). It consumes the structured result that this `auth` call already returned and shows
+the connection status in plain words — location (site plus region, e.g. "Shanghai (China)"), access scope, and the
+environment ID — with a single primary action for the current state (sign in when signed out, pick an environment
+when not bound, wire up a sample project when ready). The only call the panel makes is the read-only `auth(status)`,
+fired by "Re-check"; every other action just hands a sentence to the conversation, and the raw response is folded
+into "View raw response".
+
+Clients that do not render MCP Apps are unaffected: `auth` keeps the same title, description, arguments and
+output, and `resources/list` stays empty, so nothing new appears in a resource browser.
+
 ## IDE config snippets
 
 <details>

package/README.zh-CN.md

@@ -128,6 +128,49 @@ IDE 支持时优先用 Plugin；只需 MCP 配置时用本包即可。
 
 工具目录：[MCP 工具](../doc/mcp-tools.md) · [tools.json](../scripts/tools.json)
 
+## 破坏性操作的执行前确认
+
+删除云函数、集合、集合内的文档、云存储文件、云托管服务或 MySQL 实例时，调用会在执行前暂停，等你在确认框里选一次——框里写清**这次要动什么**（例如「即将删除云函数 `hello`（环境 `env-abc`）」），而不是只问一句"确定吗"。同一批删除如果改走 `callCloudApi`，也按写死的 `service` + `Action` 停下来确认：`tcb`/`scf` 的 `DeleteFunction`、`tcb.DeleteTable`、`tcb.DeleteItem`、`tcb.DestroyEnv`、`tcb.DestroyPlatformEnv`、`tcb.DestroyMySQL`、`tcbr.DeleteCloudRunServer`，以及 `tcbr.DeleteCloudRunVersions` 且 `IsDeleteServer` 为 true。不会按 `Delete` 前缀去拦其它云 API。云存储删除不走 `callCloudApi`。PostgreSQL 的 `execute` / `applyMigration` 只在语句本身是 `DELETE`、`DROP`、`TRUNCATE` 或 `ALTER … DROP` 时才停下来；`INSERT` / `UPDATE` / `CREATE TABLE` 不拦。它基于 MCP 的表单式 elicitation，所以只在**声明了该能力、并且真的会问用户**的客户端里出现。
+
+| 情况 | 行为 |
+| --- | --- |
+| 客户端会问你 | 出现确认框；只有你选了"确认删除"才执行 |
+| 客户端处于完全访问 / 不询问模式 | 它会在几毫秒内自己应答。这被当作"你没被问到"处理，调用照常执行 |
+| 客户端渲染不了表单 | 不弹窗，照常执行——与本次改动前完全一致 |
+| 你点了取消、关掉，或 45 秒没作答 | 什么都不执行，返回里写明"未执行"，且**不会被标记成错误**（避免模型把"被拒绝"当成出错然后重试同一个删除） |
+
+被拒绝不等于失败：工具返回"未执行"以及可以改用别的做法。两个环境变量可以调整这套行为，它们都**不绕过**认证、权限或只读限制，只决定"问不问"：
+
+| 变量 | 作用 |
+| --- | --- |
+| `CLOUDBASE_MCP_SKIP_ELICITATIONS` | 逗号分隔。可写工具名（`manageFunctions`、`callCloudApi`）或单个动作（`manageFunctions.deleteFunction`、`callCloudApi.tcb.DeleteFunction`）；区分大小写、无通配。无法识别的条目会记日志并忽略，不会让服务起不来 |
+| `CLOUDBASE_MCP_ELICIT_AUTO_APPROVE` | `allow`（默认）：客户端自己应答时放行；`block`：这种情况也按"未确认"处理 |
+
+客户端自己的"工具审批"框**不是**这个确认：它问的是"允不允许这个工具运行"，不是"你要删的就是这个资源吗"。
+
+### 参数里出现凭证：写入前先做一次真实核对
+
+当一次调用的参数里出现凭证形态的字符串——三段式 JWT，或 `cb_secret_…` / `cb_publishable_…` 开头的密钥——服务端会在写入前向客户端要一次核对：把这串与你手上的**原始来源**逐字比对，一致再确认。消息里**刻意不放明文**，只给总长度、分段长度（JWT）与指纹（sha256 的前 12 位十六进制）：这几样足够看出"复制或转写时被改过"，又不会把密钥带进对话或日志。
+
+**这不是什么。** 我们**不判断凭证是否有效**：没有验签，不查 `certs`/JWKS，**不发任何网络请求**，服务端也不做比对——用户最初粘进来的那份服务端永远拿不到，能做比对的只有客户端。它只是"写入前要一次真实的确认"，不是有效性校验。
+
+**边界。** 只有参数里**真的**出现凭证形态字符串时才会走到这一步（否则调用零变化：一次浅扫描、无网络）；只有客户端支持交互式表单 elicitation 时才生效，不支持干预式确认的客户端照常执行（不会把无人值守的客户端整个封死）；另外，**几百毫秒内返回的核对一律按"没人看过"处理**——与删除确认相反（那边客户端自己应答会被当作"你没被问到"而放行），凭证写入**不执行**，因为"没人比对过"正是它要挡的情况。被拦下时返回"未执行"，且**不会被标记成错误**，避免模型盲目重试。
+
+| 变量 | 作用 |
+| --- | --- |
+| `CLOUDBASE_MCP_SKIP_CREDENTIAL_GUARD` | 逗号分隔。可写工具名（`manageCloudRun`）或单个动作（`manageCloudRun.updateConfig`）；区分大小写、无通配。无法识别的条目会记日志并忽略，不会让服务起不来 |
+
+## 起步面板（MCP Apps）
+
+当客户端声明了 `io.modelcontextprotocol/ui` 扩展时，`auth` 会额外打开一个小型只读面板
+（`ui://cloudbase/get-started`）：它直接消费这次 `auth` 调用已经送回来的结构化结果，用人话展示连接状态
+——位置（站点 + 地域，如「上海（中国站）」）、可访问范围与环境 ID——并只给出一个当前该做的主行动
+（未登录给登录、已登录未绑定给选环境、已就绪给接一个示例项目）。面板唯一会发出的调用是只读的
+`auth(status)`（点「重新检查」触发），其余操作只是把一句话交给会话。原始返回折在「查看原始返回」里。
+
+不渲染 MCP Apps 的客户端不受影响：`auth` 的标题、描述、参数与输出保持不变，`resources/list` 仍为空数组，
+资源面板里不会多出任何新条目。
+
 ## IDE 配置片段
 
 <details>