@cloudbase/cloudbase-mcp 2.35.1 → 2.36.0

package/README.md

@@ -76,7 +76,20 @@ You need a [CloudBase environment](https://tcb.cloud.tencent.com/dev) and should
 
 Pick the endpoint matching the site your environment lives in—the two sites use separate accounts and credentials.
 
-**Local**: runs `npx @cloudbase/cloudbase-mcp@latest` on your machine—full features, including local filesystem upload and template download. Requires Node.js v18.15.0+.
+**OAuth (interactive, recommended)**: the URL is the whole configuration—your IDE opens the browser for login and consent, and you pick the environment there. No keys land in config files, and there is nothing to rotate.
+
+```json
+{
+  "mcpServers": {
+    "cloudbase": {
+      "type": "http",
+      "url": "https://tcb-api.cloud.tencent.com/mcp/v1"
+    }
+  }
+}
+```
+
+**Static credentials** (for a client without OAuth, and for CI/CD): append `env_id` and a key pair created on the same site as the endpoint.
 
 ```json
 {
@@ -93,10 +106,9 @@ Pick the endpoint matching the site your environment lives in—the two sites us
 }
 ```
 
-Remote auth takes one of two paths:
+> A static key pair stays valid until it is rotated or deleted; an OAuth session ends when you log out. Use the static form only where the browser flow is impossible—and keep it out of a repository.
 
-- **OAuth (interactive, recommended)**: add the URL only—your IDE opens the browser for login and consent, so no keys land in config files.
-- **Static credentials (CI/CD)**: add `env_id` with the `X-TencentCloud-*` headers above.
+**Local**: runs `npx @cloudbase/cloudbase-mcp@latest` on your machine—full features, including local filesystem upload and template download. Requires Node.js v18.15.0+.
 
 Remote trade-off: local-filesystem features (upload, template download) are unavailable, and the international site does not yet expose NoSQL tools.
 
@@ -117,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):
@@ -128,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>