@cloudbase/cloudbase-mcp 2.29.0 → 2.30.1

package/dist/index.js

@@ -51,6 +51,7 @@ const zod_1 = __webpack_require__(2971);
 const auth_js_1 = __webpack_require__(7291);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const logger_js_1 = __webpack_require__(3039);
+const site_map_js_1 = __webpack_require__(8107);
 const tool_result_js_1 = __webpack_require__(9835);
 const gateway_access_urls_js_1 = __webpack_require__(2435);
 const env_setup_js_1 = __webpack_require__(6978);
@@ -533,6 +534,45 @@ async function fetchAvailableEnvCandidates(cloudBaseOptions, server) {
         return [];
     }
 }
+async function fetchAccountEnvCandidates(cloudBaseOptions) {
+    try {
+        return await (0, cloudbase_manager_js_1.listAvailableEnvCandidates)({
+            cloudBaseOptions,
+            ignorePinnedEnvId: true,
+        });
+    }
+    catch {
+        return [];
+    }
+}
+function isApiKeyCredentialMode() {
+    return Boolean((0, auth_js_1.getCloudBaseApiKeyFromEnv)() && process.env.CLOUDBASE_ENV_ID);
+}
+function getCredentialScope() {
+    return isApiKeyCredentialMode() ? "single_env" : "account";
+}
+function buildCredentialBoundaryPayload(cloudBaseOptions) {
+    const credentialScope = getCredentialScope();
+    const currentRegion = (0, site_map_js_1.resolveSiteAndRegion)(cloudBaseOptions ?? {}).region;
+    const pinnedEnvId = process.env.CLOUDBASE_ENV_ID || cloudBaseOptions?.envId || null;
+    const scopeNote = credentialScope === "single_env"
+        ? `当前为环境级 API Key 登录（单环境权限）。只能访问已绑定的 envId${pinnedEnvId ? ` ${pinnedEnvId}` : ""}，看不到账号下其他环境或其他地域。这是凭据权限边界，不是环境不存在。`
+        : `当前为账号级登录。DescribeEnvs 按地域查询；未传 region 时使用当前地域 ${currentRegion}。其他地域请用 queryEnv(action="list", region="ap-singapore")，或 CLI: tcb env list -r ap-singapore。`;
+    return {
+        credential_scope: credentialScope,
+        current_region: currentRegion,
+        scope_note: scopeNote,
+    };
+}
+function applyBoundEnvRegion(server, region) {
+    if (!region) {
+        return;
+    }
+    process.env.TCB_REGION = region;
+    if (server.cloudBaseOptions) {
+        server.cloudBaseOptions.region = region;
+    }
+}
 const CODEBUDDY_AUTH_ACTIONS = ["status", "set_env", "login_by_api_key"];
 const DEFAULT_AUTH_ACTIONS = [
     "status",
@@ -763,7 +803,10 @@ async function prepareAuthEnvironment(params) {
 }
 function buildEnvQueryListResult(params) {
     const envList = Array.isArray(params.result?.EnvList) ? params.result.EnvList : [];
-    const shouldRestrictToCurrentEnv = params.hasEnvId && !params.filters.alias && !params.filters.envId;
+    const shouldRestrictToCurrentEnv = params.hasEnvId &&
+        !params.filters.alias &&
+        !params.filters.envId &&
+        !params.filters.region;
     const baseList = shouldRestrictToCurrentEnv
         ? envList.filter((env) => env.EnvId === params.cloudBaseOptions?.envId)
         : envList;
@@ -780,6 +823,11 @@ function buildEnvQueryListResult(params) {
             reason: "action=list with envId only returns a concise summary. Use action=info to fetch detailed environment information such as full resource metadata and additional environment details.",
         }
         : undefined;
+    const credentialBoundary = buildCredentialBoundaryPayload(params.cloudBaseOptions);
+    const queryRegion = params.filters.region || credentialBoundary.current_region;
+    const currentEnvOnlyNote = shouldRestrictToCurrentEnv && credentialBoundary.credential_scope === "account"
+        ? `已绑定环境，list 默认只返回当前环境。要查看其他地域请传 region（例如 region="ap-singapore"），或使用 CLI: tcb env list -r ap-singapore。`
+        : undefined;
     return {
         EnvList: paginated.items.map((env) => selectEnvFields(env, params.filters.fields)),
         TotalCount: paginated.total,
@@ -790,9 +838,13 @@ function buildEnvQueryListResult(params) {
             alias: params.filters.alias ?? null,
             aliasExact: params.filters.aliasExact ?? null,
             envId: params.filters.envId ?? null,
+            region: params.filters.region ?? null,
             fields: params.filters.fields ?? [...DEFAULT_ENV_FIELDS],
             currentEnvOnly: shouldRestrictToCurrentEnv,
         },
+        ...credentialBoundary,
+        query_region: queryRegion,
+        ...(currentEnvOnlyNote ? { scope_note: currentEnvOnlyNote } : {}),
         ...(exactEnvIdSummaryHint
             ? {
                 RecommendedNextAction: exactEnvIdSummaryHint,
@@ -1498,13 +1550,14 @@ function registerEnvTools(server) {
         requireEnvId: options?.requireEnvId ?? true,
         mcpServer: server,
     });
-    const getManagerForEnvQuery = (targetEnvId, requireEnvId = true) => (0, cloudbase_manager_js_1.getCloudBaseManager)({
-        cloudBaseOptions: targetEnvId && targetEnvId !== cloudBaseOptions?.envId
-            ? {
-                ...cloudBaseOptions,
-                envId: targetEnvId,
-            }
-            : cloudBaseOptions,
+    const getManagerForEnvQuery = (targetEnvId, requireEnvId = true, region) => (0, cloudbase_manager_js_1.getCloudBaseManager)({
+        cloudBaseOptions: {
+            ...cloudBaseOptions,
+            ...(targetEnvId && targetEnvId !== cloudBaseOptions?.envId
+                ? { envId: targetEnvId }
+                : {}),
+            ...(region ? { region } : {}),
+        },
         requireEnvId,
         mcpServer: server,
     });
@@ -1516,7 +1569,7 @@ function registerEnvTools(server) {
     if (server.ide !== 'wxide') {
         server.registerTool?.("auth", {
             title: "CloudBase 开发阶段登录与环境",
-            description: "CloudBase（腾讯云开发）开发阶段登录与环境绑定。登录后即可访问云资源；环境(env)是云函数、数据库、静态托管等资源的隔离单元，绑定环境后其他 MCP 工具才能操作该环境。支持：查询状态、发起登录、API Key登录、绑定环境(set_env)、退出登录。",
+            description: "CloudBase（腾讯云开发）开发阶段登录与环境绑定。登录后即可访问云资源；环境(env)是云函数、数据库、静态托管等资源的隔离单元，绑定环境后其他 MCP 工具才能操作该环境。支持：查询状态、发起登录、API Key登录、绑定环境(set_env)、退出登录。auth(status) 会返回 credential_scope（account=账号级 / single_env=环境级 API Key）与当前 region；环境级 API Key 只能看到绑定的 envId，查不到其他地域环境是权限边界而非环境不存在。",
             inputSchema: {
                 action: zod_1.z
                     .enum(authActionEnum)
@@ -1630,13 +1683,7 @@ function registerEnvTools(server) {
                             ? "PENDING"
                             : "REQUIRED";
                     let envPreparation;
-                    const message = authStatus === "READY"
-                        ? undefined
-                        : authStatus === "PENDING"
-                            ? "设备码授权进行中，请完成浏览器授权后再次调用 auth(action=\"status\")"
-                            : isCodeBuddyIde(server)
-                                ? "当前未登录。CodeBuddy 暂不支持在 tool 内发起认证，请在外部完成认证后再次调用 auth(action=\"status\")。"
-                                : "当前未登录，请先执行 auth(action=\"start_auth\")";
+                    const credentialBoundary = buildCredentialBoundaryPayload(cloudBaseOptions);
                     if (authStatus === "READY" && loginState) {
                         envPreparation = await prepareAuthEnvironment({
                             server,
@@ -1644,11 +1691,21 @@ function registerEnvTools(server) {
                             loginState,
                         });
                     }
+                    const statusMessage = authStatus === "READY"
+                        ? envPreparation?.message
+                            ? `${envPreparation.message} ${credentialBoundary.scope_note}`
+                            : credentialBoundary.scope_note
+                        : authStatus === "PENDING"
+                            ? "设备码授权进行中，请完成浏览器授权后再次调用 auth(action=\"status\")"
+                            : isCodeBuddyIde(server)
+                                ? "当前未登录。CodeBuddy 暂不支持在 tool 内发起认证，请在外部完成认证后再次调用 auth(action=\"status\")。"
+                                : "当前未登录，请先执行 auth(action=\"start_auth\")";
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         ok: true,
                         code: "STATUS",
                         auth_status: authStatus,
                         ...(isApiKeyMode ? { auth_mode: "api_key" } : {}),
+                        ...credentialBoundary,
                         auth_config: authConfigSummary,
                         ...(envPreparation
                             ? buildAuthEnvSetupPayload(envPreparation)
@@ -1660,7 +1717,7 @@ function registerEnvTools(server) {
                         auth_challenge: authFlowState.status === "PENDING"
                             ? (0, auth_js_1.buildDeviceAuthChallengePayload)(authFlowState.authChallenge)
                             : undefined,
-                        message,
+                        message: statusMessage,
                         next_step: authStatus === "REQUIRED"
                             ? buildAuthRequiredNextStep(server)
                             : authStatus === "PENDING"
@@ -1958,32 +2015,63 @@ function registerEnvTools(server) {
                             next_step: buildAuthRequiredNextStep(server),
                         });
                     }
-                    const envCandidates = await fetchAvailableEnvCandidates(cloudBaseOptions, server);
+                    const credentialBoundary = buildCredentialBoundaryPayload(cloudBaseOptions);
+                    const envCandidates = isApiKeyCredentialMode()
+                        ? await fetchAvailableEnvCandidates(cloudBaseOptions, server)
+                        : await fetchAccountEnvCandidates(cloudBaseOptions);
                     if (!envId) {
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "INVALID_ARGS",
                             message: "action=set_env 时必须提供 envId",
+                            ...credentialBoundary,
                             ...buildEnvCandidatePayload(envCandidates),
                             next_step: buildSetEnvNextStep(envCandidates),
                         });
                     }
-                    const target = envCandidates.find((item) => item.envId === envId);
-                    if (envCandidates.length > 0 && !target) {
+                    if (isApiKeyCredentialMode()) {
+                        const pinnedEnvId = process.env.CLOUDBASE_ENV_ID;
+                        if (pinnedEnvId && envId !== pinnedEnvId) {
+                            return (0, tool_result_js_1.buildJsonToolResult)({
+                                ok: false,
+                                code: "CREDENTIAL_SCOPE_LIMITED",
+                                message: `当前为环境级 API Key 登录，只能绑定已授权环境 ${pinnedEnvId}，不能切换到 ${envId}。这是凭据权限边界，不是目标环境不存在。`,
+                                ...credentialBoundary,
+                                current_env_id: pinnedEnvId,
+                                ...buildEnvCandidatePayload(envCandidates),
+                            });
+                        }
+                        await cloudbase_manager_js_1.envManager.setEnvId(envId);
                         return (0, tool_result_js_1.buildJsonToolResult)({
-                            ok: false,
-                            code: "INVALID_ARGS",
-                            message: `未找到环境: ${envId}`,
-                            ...buildEnvCandidatePayload(envCandidates),
-                            next_step: buildSetEnvNextStep(envCandidates),
+                            ok: true,
+                            code: "ENV_READY",
+                            message: `环境设置成功，当前环境: ${envId}`,
+                            current_env_id: envId,
+                            ...credentialBoundary,
+                        });
+                    }
+                    let target = envCandidates.find((item) => item.envId === envId);
+                    if (!target) {
+                        target = await (0, cloudbase_manager_js_1.resolveEnvCandidateByEnvId)({
+                            envId,
+                            cloudBaseOptions,
+                            loginState,
                         });
                     }
                     await cloudbase_manager_js_1.envManager.setEnvId(envId);
+                    applyBoundEnvRegion(server, target?.region);
+                    const regionHint = target?.region
+                        ? `，地域: ${target.region}`
+                        : target
+                            ? ""
+                            : "。未在当前探测地域中确认该 envId，已按唯一 ID 直绑；若后续接口仍指向错误地域，请设置 TCB_REGION 或 queryEnv(action=\"list\", region=...)";
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         ok: true,
                         code: "ENV_READY",
-                        message: `环境设置成功，当前环境: ${envId}`,
+                        message: `环境设置成功，当前环境: ${envId}${regionHint}`,
+                        ...credentialBoundary,
                         current_env_id: envId,
+                        current_region: target?.region || credentialBoundary.current_region,
                     });
                 }
                 if (action === "logout") {
@@ -2090,23 +2178,20 @@ function registerEnvTools(server) {
         });
     } // end: wxide guard for auth tool
     // queryEnv - 环境查询（合并 listEnvs + getEnvInfo + getEnvAuthDomains + usage + metrics）
-    const queryEnvHandler = async ({ action, alias, aliasExact, envId, limit, offset, fields, type, startDate, endDate, needUsageDetails, metricName, startTime, endTime, period, resourceID, subresourceID, }) => {
+    const queryEnvHandler = async ({ action, alias, aliasExact, envId, region, limit, offset, fields, type, startDate, endDate, needUsageDetails, metricName, startTime, endTime, period, resourceID, subresourceID, }) => {
         try {
             let result;
             switch (action) {
                 case "list":
                     try {
-                        const cloudbaseList = await (0, cloudbase_manager_js_1.getCloudBaseManager)({
-                            cloudBaseOptions,
-                            requireEnvId: true,
-                            mcpServer: server, // Pass server for IDE detection
-                        });
-                        // 当环境变量设置了 CLOUDBASE_ENV_ID 时（如 API Key 模式），
-                        // 避免调用 DescribeEnvs（临时密钥可能不支持该接口），
-                        // 改为通过 DescribeEnvInfo 获取单环境信息
-                        // 注意：requestFn 模式（如微信 IDE）使用 DescribeEnvs，不走此分支
+                        const cloudbaseList = await getManagerForEnvQuery(undefined, false, region);
+                        // API Key / env-var pin: skip DescribeEnvs (STS often cannot list).
+                        // Account-level sessions that only pinned CLOUDBASE_ENV_ID via set_env
+                        // can still pass region/alias/envId to list other environments.
                         const envIdFromEnv = !cloudBaseOptions?.requestFn && process.env.CLOUDBASE_ENV_ID;
-                        if (envIdFromEnv) {
+                        const shouldPinToEnvVar = Boolean(envIdFromEnv &&
+                            (isApiKeyCredentialMode() || (!region && !alias && !envId)));
+                        if (shouldPinToEnvVar && envIdFromEnv) {
                             try {
                                 const envInfo = await cloudbaseList.env.describeEnvInfo({ EnvId: envIdFromEnv });
                                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, envInfo);
@@ -2160,11 +2245,7 @@ function registerEnvTools(server) {
                         (0, logger_js_1.debug)("获取环境列表时出错，尝试降级到 listEnvs():", error instanceof Error ? error : new Error(String(error)));
                         // Fallback to original method on error
                         try {
-                            const cloudbaseList = await (0, cloudbase_manager_js_1.getCloudBaseManager)({
-                                cloudBaseOptions,
-                                requireEnvId: true,
-                                mcpServer: server, // Pass server for IDE detection
-                            });
+                            const cloudbaseList = await getManagerForEnvQuery(undefined, false, region);
                             result = await cloudbaseList.env.listEnvs();
                             (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                         }
@@ -2193,6 +2274,7 @@ function registerEnvTools(server) {
                             alias,
                             aliasExact,
                             envId,
+                            region,
                             limit,
                             offset,
                             fields,
@@ -2372,17 +2454,21 @@ function registerEnvTools(server) {
     // Register primary tool name (queryEnv)
     const queryEnvToolSchema = {
         title: "CloudBase 环境查询",
-        description: "查询 CloudBase 环境相关信息，支持查询环境列表、指定环境详情、安全域名、资源用量与监控指标。（曾用名：envQuery、listEnvs、getEnvInfo、getEnvAuthDomains）当 action=list 时，会按 DescribeEnvs 语义做列表/筛选，标准返回字段为 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，并支持通过 fields 白名单裁剪这些字段；aliasExact=true 时会按别名精确筛选，避免把前缀相近的环境误当作候选；即使传入 envId，action=list 也只返回摘要，不会返回完整资源明细或 expiry。如需查询某个已知 EnvId 对应环境的详细信息（包括资源字段和计费信息），必须使用 action=info 并传入目标环境的 envId 参数。action=info 会在可用时补充 BillingInfo（如 ExpireTime、PayMode、IsAutoRenew 等计费字段）。\n\n📊 action=usage 对齐 tcb env usage/info：透传 Manager SDK describeEnvAccountCircle + describeCreditsUsageDetail，返回计费周期与各模块资源点用量（FLEXDB/SCF/COS 等）。envId 必填；type 可选过滤模块；未传 startDate/endDate 时自动使用当前计费周期。\n\n📈 action=metrics 对齐 TCB DescribeCurveData（manager.monitor.describeCurveData，不是云监控 GetMonitorData）：查询环境/网关 QPS、云函数调用与错误、数据库 CPU/内存/磁盘、云托管 CPU/QPS 等时序。envId 与 metricName 必填；startTime/endTime 格式 YYYY-MM-DD HH:mm:ss，须成对传入，不传则默认最近 24 小时；period 仅 300/3600/86400。GatewayTraceEnvQPS 未传 resourceID 时自动填环境级 all|:|all|:|all|:|all；云托管 Tke* 指标必须传服务名 resourceID。禁止用 callCloudApi 猜测监控 Action。\n\n🔍 action=info 还会派生三个用于后端选型的字段：\n- `EnvInfo.RuntimeMode`：'postgresql' 或 'nosql'，表示新业务建议默认使用的后端（PG 已开通时为 postgresql，否则为 nosql）。\n- `EnvInfo.RuntimeBackends`：`{postgresql, nosql, mysql}` 三个布尔值，描述当前环境实际并存的后端。\n- `EnvInfo.RuntimeModeHints`：每个后端对应的 API/工具/skill 提示。\n\n🌐 action=info 还会在不改写 `StaticStorages[].StaticDomain`（云 API 名义域名）的前提下，投影网关路由 Enable 状态：`StaticStorages[].staticDomainRouteEnabled` 与 `EnvInfo.staticDomainRouteEnabled`（与 queryHosting websiteConfig 同源）。`false` 表示默认静态域名根路由已禁用（访问会返回 GATEWAY_ROUTE_DISABLED），勿把名义域名当成可达 URL。\n\nAI 在写业务/权限/存储代码前必须先看这三项：PG 模式下新业务推荐 `app.rdb()` + RLS（`managePgDatabase action=execute` 跑 `CREATE POLICY`）+ pgstore；已存在的 NoSQL 集合 / 旧 storage / `managePermissions(resourceType=\"noSqlDatabase\")` 在 PG 环境下仍然有效。真正不适用的是 MySQL：当 `RuntimeBackends.mysql === false` 时，`manageMysqlDatabase` / `queryMysqlDatabase` / `relational-database-mcp-cloudbase` skill 都不该使用。",
+        description: "查询 CloudBase 环境相关信息，支持查询环境列表、指定环境详情、安全域名、资源用量与监控指标。（曾用名：envQuery、listEnvs、getEnvInfo、getEnvAuthDomains）当 action=list 时，会按 DescribeEnvs 语义做列表/筛选，标准返回字段为 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，并支持通过 fields 白名单裁剪这些字段；aliasExact=true 时会按别名精确筛选，避免把前缀相近的环境误当作候选；即使传入 envId，action=list 也只返回摘要，不会返回完整资源明细或 expiry。账号级登录可传 region（ap-shanghai/ap-guangzhou/ap-singapore）查询对应地域，对齐 CLI `tcb env list -r <region>`；环境级 API Key 只能看到绑定的 envId，返回 credential_scope=single_env，不要误判为环境不存在。如需查询某个已知 EnvId 对应环境的详细信息（包括资源字段和计费信息），必须使用 action=info 并传入目标环境的 envId 参数。action=info 会在可用时补充 BillingInfo（如 ExpireTime、PayMode、IsAutoRenew 等计费字段）。\n\n📊 action=usage 对齐 tcb env usage/info：透传 Manager SDK describeEnvAccountCircle + describeCreditsUsageDetail，返回计费周期与各模块资源点用量（FLEXDB/SCF/COS 等）。envId 必填；type 可选过滤模块；未传 startDate/endDate 时自动使用当前计费周期。\n\n📈 action=metrics 对齐 TCB DescribeCurveData（manager.monitor.describeCurveData，不是云监控 GetMonitorData）：查询环境/网关 QPS、云函数调用与错误、数据库 CPU/内存/磁盘、云托管 CPU/QPS 等时序。envId 与 metricName 必填；startTime/endTime 格式 YYYY-MM-DD HH:mm:ss，须成对传入，不传则默认最近 24 小时；period 仅 300/3600/86400。GatewayTraceEnvQPS 未传 resourceID 时自动填环境级 all|:|all|:|all|:|all；云托管 Tke* 指标必须传服务名 resourceID。禁止用 callCloudApi 猜测监控 Action。\n\n🔍 action=info 还会派生三个用于后端选型的字段：\n- `EnvInfo.RuntimeMode`：'postgresql' 或 'nosql'，表示新业务建议默认使用的后端（PG 已开通时为 postgresql，否则为 nosql）。\n- `EnvInfo.RuntimeBackends`：`{postgresql, nosql, mysql}` 三个布尔值，描述当前环境实际并存的后端。\n- `EnvInfo.RuntimeModeHints`：每个后端对应的 API/工具/skill 提示。\n\n🌐 action=info 还会在不改写 `StaticStorages[].StaticDomain`（云 API 名义域名）的前提下，投影网关路由 Enable 状态：`StaticStorages[].staticDomainRouteEnabled` 与 `EnvInfo.staticDomainRouteEnabled`（与 queryHosting websiteConfig 同源）。`false` 表示默认静态域名根路由已禁用（访问会返回 GATEWAY_ROUTE_DISABLED），勿把名义域名当成可达 URL。\n\nAI 在写业务/权限/存储代码前必须先看这三项：PG 模式下新业务推荐 `app.rdb()` + RLS（`managePgDatabase action=execute` 跑 `CREATE POLICY`）+ pgstore；已存在的 NoSQL 集合 / 旧 storage / `managePermissions(resourceType=\"noSqlDatabase\")` 在 PG 环境下仍然有效。真正不适用的是 MySQL：当 `RuntimeBackends.mysql === false` 时，`manageMysqlDatabase` / `queryMysqlDatabase` / `relational-database-mcp-cloudbase` skill 都不该使用。",
         inputSchema: {
             action: zod_1.z
                 .enum(["list", "info", "domains", "usage", "metrics"])
-                .describe("查询类型：list=环境列表/摘要筛选（按 DescribeEnvs 语义筛选，支持通过 envId 筛选，返回 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，不支持 expiry），info=指定环境的详细信息（必须传入 envId，返回资源字段和计费信息），domains=安全域名列表，usage=环境资源用量（必须传入 envId，对齐 tcb env usage/info），metrics=环境监控时序（必须传入 envId 与 metricName，对齐 TCB DescribeCurveData）"),
+                .describe("查询类型：list=环境列表/摘要筛选（按 DescribeEnvs 语义筛选，支持通过 envId / region 筛选，返回 EnvId、Alias、Status、EnvType、Region、PackageId、PackageName、IsDefault，不支持 expiry），info=指定环境的详细信息（必须传入 envId，返回资源字段和计费信息），domains=安全域名列表，usage=环境资源用量（必须传入 envId，对齐 tcb env usage/info），metrics=环境监控时序（必须传入 envId 与 metricName，对齐 TCB DescribeCurveData）"),
             alias: zod_1.z.string().optional().describe("按环境别名筛选。action=list 时可选"),
             aliasExact: zod_1.z.boolean().optional().describe("按环境别名精确筛选。action=list 时可选；与 alias 配合使用"),
             envId: zod_1.z
                 .string()
                 .optional()
                 .describe("环境 ID。action=list 时可选（仅按 DescribeEnvs 语义做筛选，仍返回摘要）；action=info / action=usage / action=metrics 时必填。"),
+            region: zod_1.z
+                .enum(site_map_js_1.TCB_QUERY_REGIONS)
+                .optional()
+                .describe("查询地域。仅 action=list 时有效。账号级凭据会把该值透传到 DescribeEnvs（X-TC-Region），例如 ap-singapore。环境级 API Key 无法用此参数看到其他环境。等价 CLI：tcb env list -r <region> --json。"),
             limit: zod_1.z.number().int().positive().optional().describe("返回数量上限。action=list 时可选"),
             offset: zod_1.z.number().int().min(0).optional().describe("分页偏移。action=list 时可选"),
             fields: zod_1.z
@@ -2946,6 +3032,7 @@ function registerEnvTools(server) {
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.CAM_AUTH_ERROR_PATTERN = void 0;
 exports.assertTcbCloudRunActionAllowed = assertTcbCloudRunActionAllowed;
+exports.resolveCloudApiRegionAndParams = resolveCloudApiRegionAndParams;
 exports.removeEmptyStringParams = removeEmptyStringParams;
 exports.buildCamAuthGuidance = buildCamAuthGuidance;
 exports.isCamAuthError = isCamAuthError;
@@ -2995,6 +3082,20 @@ function assertTcbCloudRunActionAllowed(service, action) {
         throw new Error(`[${service}/${action}] 已禁用：${TCB_CLOUDRUN_FORBIDDEN_HINT}`);
     }
 }
+function resolveCloudApiRegionAndParams(args) {
+    const raw = { ...(args.params ?? {}) };
+    const nestedRegion = typeof raw.Region === "string" && raw.Region.trim()
+        ? raw.Region.trim()
+        : typeof raw.region === "string" && raw.region.trim()
+            ? raw.region.trim()
+            : undefined;
+    delete raw.Region;
+    delete raw.region;
+    const region = (typeof args.region === "string" && args.region.trim()
+        ? args.region.trim()
+        : undefined) || nestedRegion;
+    return { region, params: raw };
+}
 function levenshteinDistance(left, right) {
     const rows = left.length + 1;
     const cols = right.length + 1;
@@ -3111,6 +3212,9 @@ function buildCapiErrorMessage(service, action, error) {
         }
         suggestions.push(buildCapiDocGuidance(service));
     }
+    if (/parameter\s+`?Region`?\s+is not recognized/i.test(baseMessage)) {
+        suggestions.push("Region 不是 Action body 参数。请使用 callCloudApi 顶层参数 region（例如 region=\"ap-singapore\"），对应 X-TC-Region。");
+    }
     if (hasParameterError) {
         suggestions.push("请求参数名与 API 定义不一致，请核对参数字段（区分大小写）并移除未支持字段。");
         if (service === "tcb" && tcbEntry) {
@@ -3168,7 +3272,6 @@ function buildCapiErrorMessage(service, action, error) {
 function registerCapiTools(server) {
     const cloudBaseOptions = server.cloudBaseOptions;
     const logger = server.logger;
-    const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions });
     server.registerTool?.("callCloudApi", {
         title: "调用云API",
         description: `通用的云 API 调用工具，主要用于 CloudBase / 腾讯云管控面与依赖资源相关 API 调用。调用前请先确认 service、Action 与 Param，避免猜测 Action 名称。如果你的目标是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请不要优先使用 callCloudApi，而应优先查看对应 OpenAPI / Swagger。现有 OpenAPI / Swagger 能力不是通用的管控面 Action 集合；管控面 API 请优先参考 CloudBase API 概览 ${CLOUDBASE_CONTROL_PLANE_DOC_URL} 与云开发依赖资源接口指引 ${CLOUDBASE_DEPENDENCY_API_DOC_URL}。对于 tcb service，常用 Action 分类如下：
@@ -3181,6 +3284,8 @@ function registerCapiTools(server) {
 
 ⚠️ 云托管（CloudBase Run）统一走 tcbr service（CreateCloudRunEnv / CreateCloudRunServer / DescribeEnvBaseInfo / DescribeCloudRunEnvs，version="2022-02-17"），tcb 旧小租户接口 CreateCloudBaseRunResource 等已被禁用；部署请用 manageCloudRun。查询单个环境基础信息/是否已开通云托管用 DescribeEnvBaseInfo（EnvId 必填），查询环境列表及资源信息用 DescribeCloudRunEnvs（EnvId 可选过滤）。
 
+⚠️ Region 必须作为本工具顶层参数 \`region\` 传入（对应 X-TC-Region / 地域 endpoint），不要放进 params。params 里的 Region 会被剥离并当作顶层 region 使用。
+
 销毁环境时，常见做法是至少带上 \`EnvId\` 和 \`BypassCheck: true\`，如果环境已经处于隔离期再按文档补 \`IsForce: true\`。`,
         inputSchema: {
             service: zod_1.z
@@ -3197,7 +3302,11 @@ function registerCapiTools(server) {
             params: zod_1.z
                 .record(zod_1.z.any())
                 .optional()
-                .describe("Action 对应的参数对象，键名需与官方 API 定义一致。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：`{ \"service\": \"tcb\", \"action\": \"DestroyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"BypassCheck\": true } }`，如果环境已经处于隔离期，可再补 `IsForce: true`；更新环境别名则可用 `{ \"service\": \"tcb\", \"action\": \"ModifyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"Alias\": \"demo\" } }`。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode=\"openapi\")，而不是优先使用 callCloudApi。"),
+                .describe("Action 对应的参数对象，键名需与官方 API 定义一致。某些 Action 需要携带 EnvId 等信息；如不确定参数结构，请先查官方文档。tcb 示例：`{ \"service\": \"tcb\", \"action\": \"DestroyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"BypassCheck\": true } }`，如果环境已经处于隔离期，可再补 `IsForce: true`；更新环境别名则可用 `{ \"service\": \"tcb\", \"action\": \"ModifyEnv\", \"params\": { \"EnvId\": \"env-xxx\", \"Alias\": \"demo\" } }`。不要把 Region 放进 params（会报 The parameter Region is not recognized）；跨地域请用顶层 region，例如 `{ \"service\": \"tcb\", \"action\": \"DescribeEnvs\", \"region\": \"ap-singapore\" }`。若你的场景是通过 HTTP 协议直接集成 auth/functions/cloudrun/storage/mysqldb 等 CloudBase 业务 API，请优先使用 OpenAPI / Swagger 或 searchKnowledgeBase(mode=\"openapi\")，而不是优先使用 callCloudApi。"),
+            region: zod_1.z
+                .string()
+                .optional()
+                .describe("云 API 地域（X-TC-Region）。例如 ap-shanghai、ap-guangzhou、ap-singapore。DescribeEnvs 等接口按地域查询，跨地域必须传此顶层参数，不要写入 params.Region。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -3206,12 +3315,17 @@ function registerCapiTools(server) {
             openWorldHint: true,
             category: CATEGORY,
         },
-    }, async ({ service, action, params, version, }) => {
+    }, async ({ service, action, params, version, region, }) => {
         if (!ALLOWED_SERVICES.includes(service)) {
             throw new Error(`Service ${service} is not allowed. Allowed services: ${ALLOWED_SERVICES.join(", ")}`);
         }
         assertTcbCloudRunActionAllowed(service, action);
-        const cloudbase = await getManager();
+        const { region: resolvedRegion, params: bodyParams } = resolveCloudApiRegionAndParams({ region, params });
+        const cloudbase = await (0, cloudbase_manager_js_1.getCloudBaseManager)({
+            cloudBaseOptions: resolvedRegion
+                ? { ...cloudBaseOptions, region: resolvedRegion }
+                : cloudBaseOptions,
+        });
         if (['1', 'true'].includes(process.env.CLOUDBASE_EVALUATE_MODE ?? '')) {
             if (service === 'lowcode') {
                 throw new Error(`${service}/${action} Cloud API is not exposed or does not exist. Please use another API.`);
@@ -3242,7 +3356,7 @@ function registerCapiTools(server) {
         }
         let result;
         try {
-            const cleanedParams = params ? removeEmptyStringParams(params) : {};
+            const cleanedParams = removeEmptyStringParams(bodyParams);
             result = await cloudbase.commonService(service, version).call({
                 Action: action,
                 Param: cleanedParams,
@@ -3360,7 +3474,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || ( true ? "2.29.0" : 0)}
+- MCP 版本：${process.env.npm_package_version || ( true ? "2.30.1" : 0)}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -3441,7 +3555,7 @@ function createWrappedHandler(name, handler, server) {
                 requestId: (typeof error === 'object' && error && 'requestId' in error) ? error.requestId : '',
                 ide: server.ide || process.env.INTEGRATION_IDE || ''
             });
-            const mcpVersion =  true ? "2.29.0" : 0;
+            const mcpVersion =  true ? "2.30.1" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -5300,6 +5414,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.envManager = void 0;
 exports.listAvailableEnvCandidates = listAvailableEnvCandidates;
+exports.resolveEnvCandidateByEnvId = resolveEnvCandidateByEnvId;
 exports.getEnvId = getEnvId;
 exports.resetCloudBaseManagerCache = resetCloudBaseManagerCache;
 exports.getCachedEnvId = getCachedEnvId;
@@ -5343,31 +5458,39 @@ function createManagerFromLoginState(loginState, region) {
     });
 }
 async function listAvailableEnvCandidates(options) {
-    const { cloudBaseOptions, loginState: providedLoginState } = options ?? {};
-    // 优先使用显式传入的 envId
-    if (cloudBaseOptions?.envId) {
-        return [{
-                envId: cloudBaseOptions.envId,
-            }];
-    }
-    // 当环境变量设置了 CLOUDBASE_ENV_ID 且没有显式 credentials 时，直接返回（避免调 DescribeEnvs）
-    // 有显式 credentials 时需要重新查询，因为可能是不同账号
-    const hasExplicitCredentials = !!(cloudBaseOptions?.secretId && cloudBaseOptions?.secretKey);
-    if (process.env.CLOUDBASE_ENV_ID && !hasExplicitCredentials) {
-        return [{
-                envId: process.env.CLOUDBASE_ENV_ID,
-            }];
+    const { cloudBaseOptions, loginState: providedLoginState, region: regionOverride, ignorePinnedEnvId, } = options ?? {};
+    if (!ignorePinnedEnvId) {
+        // Prefer an explicit envId pin (bound session / API Key).
+        if (cloudBaseOptions?.envId) {
+            return [{
+                    envId: cloudBaseOptions.envId,
+                    region: cloudBaseOptions.region,
+                }];
+        }
+        // When CLOUDBASE_ENV_ID is set and credentials are not explicit, skip DescribeEnvs.
+        const hasExplicitCredentials = !!(cloudBaseOptions?.secretId && cloudBaseOptions?.secretKey);
+        if (process.env.CLOUDBASE_ENV_ID && !hasExplicitCredentials) {
+            return [{
+                    envId: process.env.CLOUDBASE_ENV_ID,
+                }];
+        }
     }
+    const region = (0, site_map_js_1.resolveSiteAndRegion)({
+        ...(cloudBaseOptions ?? {}),
+        ...(regionOverride ? { region: regionOverride } : {}),
+    }).region;
     let cloudbase;
     if (cloudBaseOptions?.secretId && cloudBaseOptions?.secretKey) {
-        cloudbase = createCloudBaseManagerWithOptions(cloudBaseOptions);
+        cloudbase = createCloudBaseManagerWithOptions({
+            ...cloudBaseOptions,
+            region,
+        });
     }
     else {
         const loginState = providedLoginState ?? await (0, auth_js_1.peekLoginState)();
         if (!loginState?.secretId || !loginState?.secretKey) {
             return [];
         }
-        const region = (0, site_map_js_1.resolveSiteAndRegion)(cloudBaseOptions ?? {}).region;
         cloudbase = createManagerFromLoginState(loginState, region);
     }
     try {
@@ -5392,6 +5515,40 @@ async function listAvailableEnvCandidates(options) {
         }
     }
 }
+/**
+ * Look up an envId across known TCB regions. Used by set_env so a Singapore
+ * env can be bound even when the current session region is ap-shanghai.
+ */
+async function resolveEnvCandidateByEnvId(options) {
+    const { envId, cloudBaseOptions, loginState } = options;
+    const seenRegions = new Set();
+    const regionsToProbe = [
+        (0, site_map_js_1.resolveSiteAndRegion)({
+            ...(cloudBaseOptions ?? {}),
+        }).region,
+        ...site_map_js_1.TCB_QUERY_REGIONS,
+    ];
+    for (const region of regionsToProbe) {
+        if (seenRegions.has(region)) {
+            continue;
+        }
+        seenRegions.add(region);
+        const candidates = await listAvailableEnvCandidates({
+            cloudBaseOptions,
+            loginState,
+            region,
+            ignorePinnedEnvId: true,
+        });
+        const matched = candidates.find((item) => item.envId === envId);
+        if (matched) {
+            return {
+                ...matched,
+                region: matched.region || region,
+            };
+        }
+    }
+    return undefined;
+}
 function throwAuthRequiredError() {
     (0, tool_result_js_1.throwToolPayloadError)({
         ok: false,
@@ -13283,7 +13440,7 @@ class TelemetryReporter {
         const arch = os_1.default.arch(); // 系统架构
         // Build-time injected version; guard for vitest / non-webpack runtimes.
         const mcpVersion = process.env.npm_package_version ||
-            ( true ? "2.29.0" : 0);
+            ( true ? "2.30.1" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -19190,7 +19347,7 @@ function registerSetupTools(server) {
     server.registerTool("downloadTemplate", {
         title: "下载项目模板",
         description: `自动下载并部署CloudBase项目模板。
-**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.29.0" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**Note**: Call this tool when the user requests to create a new project using a CloudBase template.\n\n支持的模板:\n- react: React + CloudBase 全栈应用模板\n- vue: Vue + CloudBase 全栈应用模板\n- miniprogram: 微信小程序 + 云开发模板  \n- uniapp: UniApp + CloudBase 跨端应用模板\n- rules: 只包含AI编辑器配置文件（包含Cursor、WindSurf、CodeBuddy等所有主流编辑器配置），适合在已有项目中补充AI编辑器配置\n\n支持的IDE类型:\n- all: 下载所有IDE配置\n- cursor: Cursor AI编辑器\n- 其他IDE类型见下方列表\n\n注意：如果未传入 ide 参数且无法从环境变量检测到 IDE，将提示错误并要求传入 ide 参数\n- windsurf: WindSurf AI编辑器\n- codebuddy: CodeBuddy AI编辑器\n- claude-code: Claude Code AI编辑器\n- cline: Cline AI编辑器\n- gemini-cli: Gemini CLI\n- opencode: OpenCode AI编辑器\n- qwen-code: 通义灵码\n- baidu-comate: 百度Comate\n- openai-codex-cli: OpenAI Codex CLI\n- augment-code: Augment Code\n- github-copilot: GitHub Copilot\n- roocode: RooCode AI编辑器\n- tongyi-lingma: 通义灵码\n- trae: Trae AI编辑器\n- qoder: Qoder AI编辑器\n- antigravity: Google Antigravity AI编辑器\n- vscode: Visual Studio Code\n- kiro: Kiro AI编辑器\n- aider: Aider AI编辑器\n\n特别说明：\n- rules 模板会自动包含当前 mcp 版本号信息（版本号：${ true ? "2.30.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -21827,7 +21984,7 @@ module.exports = __WEBPACK_EXTERNAL_MODULE_fs_promises_f8dae9d1__;
 
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
-exports.SITE_IDS = exports.SITE_REGION_MAP = void 0;
+exports.TCB_QUERY_REGIONS = exports.SITE_IDS = exports.SITE_REGION_MAP = void 0;
 exports.isSiteId = isSiteId;
 exports.normalizeSite = normalizeSite;
 exports.getSite = getSite;
@@ -21855,6 +22012,12 @@ exports.SITE_REGION_MAP = {
     },
 };
 exports.SITE_IDS = Object.keys(exports.SITE_REGION_MAP);
+/** Regions accepted by envQuery(list) / cross-region DescribeEnvs probes. */
+exports.TCB_QUERY_REGIONS = [
+    "ap-shanghai",
+    "ap-guangzhou",
+    "ap-singapore",
+];
 function isSiteId(value) {
     return value === "domestic" || value === "intl";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/cloudbase-mcp",
-  "version": "2.29.0",
+  "version": "2.30.1",
   "mcpName": "io.github.TencentCloudBase/cloudbase-mcp",
   "packageManager": "pnpm@10.8.0",
   "description": "CloudBase MCP Server — operate Tencent CloudBase (database, auth, functions, storage, hosting) from AI coding tools via the Model Context Protocol. Part of CloudBase AI Toolkit.",

package/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.TencentCloudBase/cloudbase-mcp",
   "title": "CloudBase",
   "description": "CloudBase MCP: DB, functions, storage, hosting via @cloudbase/cloudbase-mcp",
-  "version": "2.29.0",
+  "version": "2.30.1",
   "websiteUrl": "https://github.com/TencentCloudBase/CloudBase-AI-Toolkit",
   "repository": {
     "url": "https://github.com/TencentCloudBase/CloudBase-AI-Toolkit",
@@ -25,7 +25,7 @@
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@cloudbase/cloudbase-mcp",
-      "version": "2.29.0",
+      "version": "2.30.1",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"