@cloudbase/cloudbase-mcp 2.25.9 → 2.26.0

package/dist/index.js

@@ -33,6 +33,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.DEFAULT_CREATE_ENV_RESOURCES = exports.CREATE_ENV_RESOURCE_VALUES = void 0;
 exports.resolveCreateEnvResources = resolveCreateEnvResources;
 exports.simplifyEnvList = simplifyEnvList;
+exports.isUsableNoSqlDatabaseEntry = isUsableNoSqlDatabaseEntry;
 exports.registerEnvTools = registerEnvTools;
 const toolbox_1 = __webpack_require__(2090);
 const zod_1 = __webpack_require__(2971);
@@ -40,6 +41,7 @@ const auth_js_1 = __webpack_require__(7291);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const logger_js_1 = __webpack_require__(3039);
 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);
 /**
  * Resources accepted by CreateEnv. Matches Cloud API / Manager SDK contract.
@@ -597,19 +599,21 @@ async function enrichEnvInfoWithBilling(params) {
  * CloudBase environment can have any combination of:
  * - PostgreSQL (CloudBase PG / pgstore): signaled by `EnvInfo.PostgreSQL[]`
  *   non-empty and/or `EnvInfo.Meta` containing `postgresql=enable`.
- * - NoSQL document database + the matching legacy COS-style bucket:
- *   signaled by `EnvInfo.Databases[]` (with InstanceId / RUNNING) and the
- *   bucket exposed in `EnvInfo.Storages[]`.
+ * - NoSQL document database (flexdb): signaled ONLY by a usable entry in
+ *   `EnvInfo.Databases[]`. The usable signal is a non-empty `InstanceId`
+ *   (FlexDB Tag, typically `tnt-...` — same value `getDatabaseInstanceId`
+ *   / ListTables `Tag` consume) with `Status` missing or `RUNNING`.
+ *   Cloud storage (`EnvInfo.Storages[]` / CreateEnv `storage`) is unrelated
+ *   and must never flip `RuntimeBackends.nosql`.
  * - MySQL: signaled by a non-empty `EnvInfo.MysqlInstances[]` (or similar
  *   field, name varies). In a pure PG environment this is absent.
  *
- * In particular: a CloudBase PG environment commonly STILL has the NoSQL
- * Database + Storage running in parallel. NoSQL is therefore "co-present"
- * — its collection APIs, NoSQL `securityRule`s, and the legacy
- * `app.uploadFile()` upload flow remain valid for collections / files
- * that already live there. The thing that is NOT a substitute for the new
- * PG surface is using NoSQL collections to model a brand-new business
- * table that the task explicitly puts in PG.
+ * In particular: a CloudBase PG environment commonly STILL has flexdb
+ * provisioned in parallel (`Databases[].InstanceId = tnt-...`). NoSQL is
+ * therefore "co-present" — its collection APIs and NoSQL `securityRule`s
+ * remain valid for collections that already live there. The thing that is
+ * NOT a substitute for the new PG surface is using NoSQL collections to
+ * model a brand-new business table that the task explicitly puts in PG.
  *
  * What this enrichment does:
  * - Adds `EnvInfo.RuntimeMode = "postgresql" | "nosql"` based on whether
@@ -617,11 +621,29 @@ async function enrichEnvInfoWithBilling(params) {
  *   business data when set to "postgresql".
  * - Adds `EnvInfo.RuntimeBackends`, a structured snapshot of which
  *   backends are actually available (postgresql / nosql / mysql), so the
- *   agent does not have to re-read `Databases`/`Storages`/`PostgreSQL`.
+ *   agent does not have to re-read `Databases`/`PostgreSQL`.
  * - Adds `EnvInfo.RuntimeModeHints` summarizing which API/tool to prefer
  *   for new code, including an explicit `MysqlNotAvailable` line when
  *   MySQL is absent — that one IS a hard "do not use" signal.
  */
+/** Exported for unit tests / live-fixture checks against FlexDB InstanceId. */
+function isUsableNoSqlDatabaseEntry(db) {
+    if (!db || typeof db !== "object") {
+        return false;
+    }
+    const entry = db;
+    const instanceId = typeof entry.InstanceId === "string" ? entry.InstanceId.trim() : "";
+    // Empty InstanceId means no flexdb tenant — same failure mode as
+    // getDatabaseInstanceId() throwing "无法获取数据库实例ID".
+    if (!instanceId) {
+        return false;
+    }
+    // Some API versions omit Status; when present, only RUNNING counts as usable.
+    if (entry.Status != null && String(entry.Status).toUpperCase() !== "RUNNING") {
+        return false;
+    }
+    return true;
+}
 async function enrichEnvInfoWithRuntimeMode(result, manager) {
     const envInfo = result?.EnvInfo;
     if (!envInfo || typeof envInfo !== "object") {
@@ -634,14 +656,12 @@ async function enrichEnvInfoWithRuntimeMode(result, manager) {
         /^postgre[_]?sql$/i.test(item.Key) &&
         String(item.Value).toLowerCase() === "enable");
     const hasPostgresql = pgList.length > 0 || metaPostgresEnabled;
-    // NoSQL document DB shows up under Databases[]; the matching legacy bucket
-    // shows up under Storages[]. Treat NoSQL as available when either side is
-    // non-empty (an old env may keep one without the other).
+    // NoSQL = flexdb tenant id on Databases[].InstanceId (typically tnt-...).
+    // Aligns with getDatabaseInstanceId() / ListTables Tag. Storage is unrelated.
     const databasesList = Array.isArray(envInfo.Databases)
         ? envInfo.Databases
         : [];
-    const storagesList = Array.isArray(envInfo.Storages) ? envInfo.Storages : [];
-    const hasNoSql = databasesList.length > 0 || storagesList.length > 0;
+    const hasNoSql = databasesList.some(isUsableNoSqlDatabaseEntry);
     // MySQL field name has been seen as MysqlInstances / MySQLInstances /
     // MySQL across API versions; check any of them.
     const mysqlList = (() => {
@@ -688,8 +708,8 @@ async function enrichEnvInfoWithRuntimeMode(result, manager) {
             Permissions: "PG table permissions use Row-Level Security. Run `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` and `CREATE POLICY` via `managePgDatabase(action=\"execute\", confirm=true)`. `managePermissions(resourceType=\"noSqlDatabase\", securityRule=...)` only governs NoSQL collection rules and has NO effect on PG tables — keep using it for the NoSQL collections that already exist here.",
             Storage: "PG-mode browser uploads should use `app.storage.from().upload(<bucket>/<key>, file)` against an explicitly-created `pgstore` bucket (same model as Supabase Storage; the v3 SDK does not auto-create one). `EnvInfo.Storages[]` here is the legacy NoSQL bucket — it is still usable for the legacy `app.uploadFile()` flow but is NOT a valid pgstore target.",
             CoexistingNoSQL: hasNoSql
-                ? "This env also has the legacy NoSQL Database + Storage running. Existing collections, existing `app.uploadFile()` calls, existing `managePermissions(resourceType=\"noSqlDatabase\")` rules all remain valid for legacy data."
-                : "No legacy NoSQL Database/Storage observed in this env.",
+                ? "This env also has a usable NoSQL (flexdb) InstanceId in EnvInfo.Databases[] (FlexDB Tag, typically tnt-...). Existing collections and `managePermissions(resourceType=\"noSqlDatabase\")` rules remain valid for that data."
+                : "No usable NoSQL (flexdb) InstanceId in EnvInfo.Databases[] — do not assume app.database() / NoSQL MCP tools work. Cloud storage does not imply flexdb.",
             MysqlNotAvailable: hasMysql
                 ? "MySQL instance(s) detected — see EnvInfo.MysqlInstances."
                 : "No MySQL instance is provisioned for this env. Do NOT use `manageMysqlDatabase` / `queryMysqlDatabase` (those are MySQL-specific) and do NOT read the `relational-database-mcp-cloudbase` skill — that family targets MySQL, not CloudBase PG.",
@@ -774,6 +794,89 @@ async function enrichEnvInfoWithMissingFields(manager, result, envId) {
         return result;
     }
 }
+/**
+ * Project gateway Route.Enable onto envQuery(info) without mutating StaticDomain.
+ *
+ * StaticStorages[].StaticDomain stays the cloud-API nominal hostname.
+ * Sibling field staticDomainRouteEnabled (and EnvInfo-level mirrors for the
+ * primary store) tell callers whether the default hosting domain route is
+ * actually reachable (Enable !== false). Matches queryHosting websiteConfig.
+ */
+async function enrichEnvInfoWithStaticDomainRouteEnabled(manager, result, envId) {
+    const envInfo = result?.EnvInfo;
+    if (!envInfo || typeof envInfo !== "object") {
+        return result;
+    }
+    const staticStorages = Array.isArray(envInfo.StaticStorages)
+        ? envInfo.StaticStorages
+        : null;
+    if (!staticStorages || staticStorages.length === 0) {
+        return result;
+    }
+    if (typeof manager?.env?.describeHttpServiceRoute !== "function") {
+        return result;
+    }
+    const resolvedEnvId = (typeof envId === "string" && envId.trim()) ||
+        (typeof envInfo.EnvId === "string" && envInfo.EnvId.trim()) ||
+        undefined;
+    if (!resolvedEnvId) {
+        return result;
+    }
+    try {
+        const routeResult = await manager.env.describeHttpServiceRoute({
+            EnvId: resolvedEnvId,
+            Limit: 1000,
+        });
+        const routes = (0, gateway_access_urls_js_1.flattenHttpServiceRoutes)(routeResult);
+        let primaryRouteEnabled = null;
+        const enrichedStorages = staticStorages.map((store, index) => {
+            if (!store || typeof store !== "object" || Array.isArray(store)) {
+                return store;
+            }
+            const record = store;
+            const domain = typeof record.StaticDomain === "string" ? record.StaticDomain : "";
+            if (!domain) {
+                return store;
+            }
+            const reachable = (0, gateway_access_urls_js_1.isDomainPathReachableViaGateway)(routes, domain, "/");
+            if (index === 0) {
+                primaryRouteEnabled = reachable;
+            }
+            return {
+                ...record,
+                staticDomainRouteEnabled: reachable,
+            };
+        });
+        const enrichment = {
+            StaticStorages: enrichedStorages,
+        };
+        if (primaryRouteEnabled !== null) {
+            enrichment.staticDomainRouteEnabled = primaryRouteEnabled;
+            enrichment.accessUrlReachable = primaryRouteEnabled !== false;
+            if (primaryRouteEnabled === false) {
+                const primaryDomain = typeof enrichedStorages[0]
+                    ?.StaticDomain === "string"
+                    ? String(enrichedStorages[0].StaticDomain)
+                    : "";
+                enrichment.routeDisabled = true;
+                if (primaryDomain) {
+                    enrichment.disabledAccessUrls = [`https://${primaryDomain}/`];
+                }
+            }
+        }
+        return {
+            ...result,
+            EnvInfo: {
+                ...envInfo,
+                ...enrichment,
+            },
+        };
+    }
+    catch {
+        // Gateway route lookup is best-effort enrichment only.
+        return result;
+    }
+}
 function normalizeOptionalToolString(value) {
     return typeof value === "string" && value.trim().length > 0
         ? value.trim()
@@ -1255,8 +1358,9 @@ function registerEnvTools(server) {
                 if (action === "status") {
                     const loginState = await (0, auth_js_1.peekLoginState)();
                     const authFlowState = await (0, auth_js_1.getAuthProgressState)();
-                    // 判断是否为 API Key 模式
-                    const isApiKeyMode = !!(process.env.CLOUDBASE_API_KEY && process.env.CLOUDBASE_ENV_ID);
+                    // Detect API Key mode (CLOUDBASE_API_KEY preferred, CLOUDBASE_APIKEY fallback)
+                    const apiKeyFromEnv = (0, auth_js_1.getCloudBaseApiKeyFromEnv)();
+                    const isApiKeyMode = !!(apiKeyFromEnv && process.env.CLOUDBASE_ENV_ID);
                     const authStatus = loginState
                         ? "READY"
                         : authFlowState.status === "PENDING"
@@ -1304,8 +1408,9 @@ function registerEnvTools(server) {
                     });
                 }
                 if (action === "start_auth") {
-                    // API Key 模式：尝试换取临时密钥
-                    if (process.env.CLOUDBASE_API_KEY && process.env.CLOUDBASE_ENV_ID) {
+                    // API Key mode: exchange for temporary credentials
+                    const apiKeyFromEnv = (0, auth_js_1.getCloudBaseApiKeyFromEnv)();
+                    if (apiKeyFromEnv && process.env.CLOUDBASE_ENV_ID) {
                         try {
                             const existingLoginState = await (0, auth_js_1.peekLoginState)();
                             if (existingLoginState) {
@@ -1319,22 +1424,21 @@ function registerEnvTools(server) {
                             }
                         }
                         catch (e) {
-                            // peekLoginState 内部异常，记录后 fall through
+                            // peekLoginState threw; log and fall through to diagnostic
                             (0, logger_js_1.debug)("start_auth: peekLoginState threw", { error: e instanceof Error ? e.message : String(e) });
                         }
-                        // API Key 换取失败：返回详细诊断信息
-                        // 尝试获取更详细的错误信息
+                        // API Key exchange failed: return diagnostic details
                         let diagMessage = "当前配置了 API Key 认证模式，但换取临时密钥失败。";
                         const endpoint = process.env.CLOUDBASE_API_ENDPOINT || `https://${process.env.CLOUDBASE_ENV_ID}.ap-shanghai.tcb-api.tencentcloudapi.com`;
                         diagMessage += `\n\n诊断信息：`;
                         diagMessage += `\n- CLOUDBASE_ENV_ID: ${process.env.CLOUDBASE_ENV_ID}`;
-                        diagMessage += `\n- CLOUDBASE_API_KEY: ${process.env.CLOUDBASE_API_KEY.slice(0, 20)}...（已截断）`;
+                        diagMessage += `\n- CLOUDBASE_API_KEY: ${apiKeyFromEnv.slice(0, 20)}...（已截断）`;
                         diagMessage += `\n- Endpoint: ${endpoint}`;
                         diagMessage += `\n\n可能原因：`;
                         diagMessage += `\n1. API Key 已过期或被删除`;
                         diagMessage += `\n2. Endpoint 不可达（网络/DNS 问题）`;
                         diagMessage += `\n3. CLOUDBASE_ENV_ID 与 API Key 所属环境不匹配`;
-                        diagMessage += `\n\n建议：检查 MCP 配置中的 CLOUDBASE_API_KEY 和 CLOUDBASE_ENV_ID 环境变量是否正确。`;
+                        diagMessage += `\n\n建议：检查 MCP 配置中的 CLOUDBASE_API_KEY（或兼容的 CLOUDBASE_APIKEY）和 CLOUDBASE_ENV_ID 环境变量是否正确。`;
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "API_KEY_AUTH_FAILED",
@@ -1620,12 +1724,12 @@ function registerEnvTools(server) {
                     });
                 }
                 if (action === "logout") {
-                    // API Key 模式下不允许 logout
-                    if (process.env.CLOUDBASE_API_KEY && process.env.CLOUDBASE_ENV_ID) {
+                    // Disallow logout in API Key mode
+                    if ((0, auth_js_1.getCloudBaseApiKeyFromEnv)() && process.env.CLOUDBASE_ENV_ID) {
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "LOGOUT_NOT_ALLOWED",
-                            message: "当前使用 API Key 认证模式，不支持退出登录。如需切换认证方式，请移除 CLOUDBASE_API_KEY 环境变量后重启。",
+                            message: "当前使用 API Key 认证模式，不支持退出登录。如需切换认证方式，请移除 CLOUDBASE_API_KEY（或兼容的 CLOUDBASE_APIKEY）环境变量后重启。",
                             auth_mode: "api_key",
                         });
                     }
@@ -1847,6 +1951,8 @@ function registerEnvTools(server) {
                     if (envId) {
                         result = await enrichEnvInfoWithMissingFields(cloudbaseInfo, result, envId);
                     }
+                    // Project gateway Route.Enable next to StaticDomain (do not rewrite StaticDomain).
+                    result = await enrichEnvInfoWithStaticDomainRouteEnabled(cloudbaseInfo, result, envId);
                     result = await enrichEnvInfoWithRuntimeMode(result, cloudbaseInfo);
                     break;
                 case "domains":
@@ -1915,7 +2021,7 @@ 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=info 还会派生三个用于后端选型的字段：\n- `EnvInfo.RuntimeMode`：'postgresql' 或 'nosql'，表示新业务建议默认使用的后端（PG 已开通时为 postgresql，否则为 nosql）。\n- `EnvInfo.RuntimeBackends`：`{postgresql, nosql, mysql}` 三个布尔值，描述当前环境实际并存的后端。\n- `EnvInfo.RuntimeModeHints`：每个后端对应的 API/工具/skill 提示。\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。如需查询某个已知 EnvId 对应环境的详细信息（包括资源字段和计费信息），必须使用 action=info 并传入目标环境的 envId 参数。action=info 会在可用时补充 BillingInfo（如 ExpireTime、PayMode、IsAutoRenew 等计费字段）。\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"])
@@ -2718,6 +2824,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.applyCategoryAnnotationMeta = applyCategoryAnnotationMeta;
 exports.wrapServerWithTelemetry = wrapServerWithTelemetry;
 const os_1 = __importDefault(__webpack_require__(8116));
 const cloudbase_manager_js_1 = __webpack_require__(3431);
@@ -2725,6 +2832,30 @@ const cloud_mode_js_1 = __webpack_require__(9684);
 const logger_js_1 = __webpack_require__(3039);
 const telemetry_js_1 = __webpack_require__(5880);
 const tool_result_js_1 = __webpack_require__(9835);
+/**
+ * Mirror annotations.category into _meta.category.
+ *
+ * MCP SDK Client >=1.26 parses tools/list with a stripping ToolAnnotationsSchema,
+ * which drops unknown annotation keys. `_meta` remains available to clients, while
+ * the server wire payload still includes annotations.category for non-SDK hosts.
+ */
+function applyCategoryAnnotationMeta(config) {
+    const category = config?.annotations?.category;
+    if (typeof category !== "string" || category.length === 0) {
+        return config;
+    }
+    const existingMeta = config._meta && typeof config._meta === "object" ? config._meta : undefined;
+    if (existingMeta && existingMeta.category === category) {
+        return config;
+    }
+    return {
+        ...config,
+        _meta: {
+            ...existingMeta,
+            category,
+        },
+    };
+}
 /**
  * 生成 GitHub Issue 创建链接
  * @param toolName 工具名称
@@ -2772,7 +2903,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.9" || 0}
+- MCP 版本：${process.env.npm_package_version || ( true ? "2.26.0" : 0)}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -2853,7 +2984,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.25.9" : 0;
+            const mcpVersion =  true ? "2.26.0" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -2950,7 +3081,7 @@ function wrapServerWithTelemetry(server) {
         // Use the wrapped handler, passing the server instance
         const wrappedHandler = createWrappedHandler(toolName, handler, server);
         // Call the original registerTool method
-        return originalRegisterTool(toolName, toolConfig, wrappedHandler);
+        return originalRegisterTool(toolName, applyCategoryAnnotationMeta(toolConfig ?? {}), wrappedHandler);
     };
 }
 /**
@@ -3189,14 +3320,15 @@ async function createCloudBaseMcpServer(options) {
     server.toolDefs = [];
     const originalRegisterTool = server.registerTool.bind(server);
     server.registerTool = ((name, meta, handler) => {
+        const toolMeta = (0, tool_wrapper_js_1.applyCategoryAnnotationMeta)(meta ?? {});
         // 同步记录到 toolDefs
         server.toolDefs.push({
             name,
-            description: meta?.description ?? meta?.title ?? '',
-            inputSchema: meta?.inputSchema ?? {},
+            description: toolMeta?.description ?? toolMeta?.title ?? '',
+            inputSchema: toolMeta?.inputSchema ?? {},
             handler,
         });
-        return originalRegisterTool(name, meta, async (args) => {
+        return originalRegisterTool(name, toolMeta, async (args) => {
             try {
                 return await handler(args);
             }
@@ -3454,12 +3586,19 @@ module.exports = __WEBPACK_EXTERNAL_MODULE__modelcontextprotocol_sdk_types_js_70
 
 
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.isGatewayRouteEnabled = isGatewayRouteEnabled;
+exports.isDomainPathReachableViaGateway = isDomainPathReachableViaGateway;
 exports.rankGatewayAccessUrls = rankGatewayAccessUrls;
 exports.flattenHttpServiceRoutes = flattenHttpServiceRoutes;
 exports.filterRoutesByUpstream = filterRoutesByUpstream;
 exports.toAccessUrlEnvelope = toAccessUrlEnvelope;
 exports.resolveGatewayAccessUrls = resolveGatewayAccessUrls;
+exports.resolveAllGatewayRoutes = resolveAllGatewayRoutes;
 exports.preferGatewayOrFallback = preferGatewayOrFallback;
+/** Route is reachable unless Enable is explicitly false. */
+function isGatewayRouteEnabled(route) {
+    return route.Enable !== false;
+}
 function normalizeAccessPath(path) {
     if (!path) {
         return "/";
@@ -3469,13 +3608,63 @@ function normalizeAccessPath(path) {
 function buildHttpsUrl(domain, path) {
     return `https://${domain}${normalizeAccessPath(path)}`;
 }
+function extractHostname(urlOrHost) {
+    const trimmed = urlOrHost.trim();
+    if (!trimmed) {
+        return "";
+    }
+    try {
+        if (trimmed.includes("://")) {
+            return new URL(trimmed).hostname.toLowerCase();
+        }
+    }
+    catch {
+        // Fall through to treat as bare hostname.
+    }
+    return trimmed.replace(/\/.*$/, "").toLowerCase();
+}
+/**
+ * Whether a hostname has an enabled covering gateway route for the given path.
+ * Longest matching Path prefix wins. Missing route info → unknown (null).
+ */
+function isDomainPathReachableViaGateway(routes, domainOrUrl, requestPath) {
+    const hostname = extractHostname(domainOrUrl);
+    if (!hostname) {
+        return null;
+    }
+    const normalizedRequest = normalizeAccessPath(requestPath);
+    const domainRoutes = routes.filter((route) => Boolean(route.Domain) &&
+        route.Domain.toLowerCase() === hostname);
+    if (domainRoutes.length === 0) {
+        return null;
+    }
+    const covering = domainRoutes
+        .map((route) => ({
+        route,
+        path: normalizeAccessPath(route.Path),
+    }))
+        .filter(({ path }) => {
+        if (path === "/") {
+            return true;
+        }
+        return (normalizedRequest === path ||
+            normalizedRequest.startsWith(path.endsWith("/") ? path : `${path}/`));
+    })
+        .sort((a, b) => b.path.length - a.path.length);
+    if (covering.length === 0) {
+        return null;
+    }
+    return isGatewayRouteEnabled(covering[0].route);
+}
 /**
  * Rank gateway route URLs: custom domains (IsDefault !== true) before default domain.
- * Stable within each group; dedupe by full URL.
+ * By default skips Enable === false routes. Stable within each group; dedupe by full URL.
  */
-function rankGatewayAccessUrls(routes) {
+function rankGatewayAccessUrls(routes, options) {
+    const includeDisabled = options?.includeDisabled === true;
     const mapped = routes
         .filter((route) => Boolean(route.Domain))
+        .filter((route) => includeDisabled || isGatewayRouteEnabled(route))
         .map((route) => {
         const path = normalizeAccessPath(route.Path);
         const isDefault = route.IsDefault === true;
@@ -3484,6 +3673,7 @@ function rankGatewayAccessUrls(routes) {
             domain: route.Domain,
             path,
             isDefault,
+            enabled: isGatewayRouteEnabled(route),
             source: (isDefault
                 ? "gateway.default"
                 : "gateway.custom"),
@@ -3511,6 +3701,7 @@ function flattenHttpServiceRoutes(result) {
         Domain: domainItem.Domain ?? "",
         IsDefault: domainItem.IsDefault,
         Path: typeof route.Path === "string" ? route.Path : undefined,
+        Enable: typeof route.Enable === "boolean" ? route.Enable : undefined,
         UpstreamResourceType: typeof route.UpstreamResourceType === "string"
             ? route.UpstreamResourceType
             : undefined,
@@ -3533,64 +3724,116 @@ function filterRoutesByUpstream(routes, input) {
             types.includes(String(route.UpstreamResourceType)));
     });
 }
-function toAccessUrlEnvelope(ranked) {
-    if (ranked.length === 0) {
-        return { accessUrls: [], routes: [] };
+function toAccessUrlEnvelope(ranked, disabledAccessUrls = []) {
+    const enabled = ranked.filter((item) => item.enabled);
+    if (enabled.length === 0) {
+        return {
+            accessUrls: [],
+            routes: [],
+            disabledAccessUrls,
+        };
     }
     return {
-        accessUrl: ranked[0].url,
-        accessUrls: ranked.map((item) => item.url),
-        accessUrlSource: ranked[0].source,
-        routes: ranked,
+        accessUrl: enabled[0].url,
+        accessUrls: enabled.map((item) => item.url),
+        accessUrlSource: enabled[0].source,
+        routes: enabled,
+        disabledAccessUrls,
     };
 }
+async function loadHttpServiceRoutes(getManager, envId) {
+    const manager = await getManager();
+    const result = await manager.env.describeHttpServiceRoute({
+        EnvId: envId,
+        Limit: 1000,
+    });
+    return flattenHttpServiceRoutes(result);
+}
 /**
  * Best-effort lookup of gateway access URLs for an upstream resource.
  * Never throws — returns empty lists on failure.
+ * Disabled routes (Enable === false) are excluded from accessUrl(s).
  */
 async function resolveGatewayAccessUrls(input) {
     try {
-        const manager = await input.getManager();
-        const result = await manager.env.describeHttpServiceRoute({
-            EnvId: input.envId,
-            Limit: 1000,
-        });
-        const flattened = flattenHttpServiceRoutes(result);
+        const flattened = await loadHttpServiceRoutes(input.getManager, input.envId);
         const matched = filterRoutesByUpstream(flattened, {
             upstreamResourceName: input.upstreamResourceName,
             upstreamResourceTypes: input.upstreamResourceTypes,
         });
-        return toAccessUrlEnvelope(rankGatewayAccessUrls(matched));
+        const disabledAccessUrls = rankGatewayAccessUrls(matched, {
+            includeDisabled: true,
+        })
+            .filter((item) => !item.enabled)
+            .map((item) => item.url);
+        return toAccessUrlEnvelope(rankGatewayAccessUrls(matched), disabledAccessUrls);
+    }
+    catch {
+        return { accessUrls: [], routes: [], disabledAccessUrls: [] };
+    }
+}
+/**
+ * Load all flattened HTTP service routes (best-effort). Used by hosting to
+ * judge whether the static-domain fallback itself is gateway-disabled.
+ */
+async function resolveAllGatewayRoutes(input) {
+    try {
+        return await loadHttpServiceRoutes(input.getManager, input.envId);
     }
     catch {
-        return { accessUrls: [], routes: [] };
+        return [];
     }
 }
 /**
  * Merge ranked gateway URLs with a resource-native fallback URL.
  * Gateway custom/default always win over the fallback when present.
+ * Unreachable fallbacks are omitted from accessUrl(s) and listed under
+ * disabledAccessUrls instead.
  */
 function preferGatewayOrFallback(input) {
+    const disabledAccessUrls = [
+        ...(input.gateway.disabledAccessUrls ?? []),
+    ];
+    const fallbackReachable = input.fallbackReachable !== false;
     if (input.gateway.accessUrl) {
         const urls = [...input.gateway.accessUrls];
         if (input.fallbackUrl &&
+            fallbackReachable &&
             !urls.includes(input.fallbackUrl)) {
             urls.push(input.fallbackUrl);
         }
+        else if (input.fallbackUrl &&
+            !fallbackReachable &&
+            !disabledAccessUrls.includes(input.fallbackUrl)) {
+            disabledAccessUrls.push(input.fallbackUrl);
+        }
         return {
             accessUrl: input.gateway.accessUrl,
             accessUrls: urls,
             accessUrlSource: input.gateway.accessUrlSource,
+            accessUrlReachable: true,
+            disabledAccessUrls,
         };
     }
-    if (input.fallbackUrl) {
+    if (input.fallbackUrl && fallbackReachable) {
         return {
             accessUrl: input.fallbackUrl,
             accessUrls: [input.fallbackUrl],
             accessUrlSource: input.fallbackSource,
+            accessUrlReachable: true,
+            disabledAccessUrls,
         };
     }
-    return { accessUrls: [] };
+    if (input.fallbackUrl && !fallbackReachable) {
+        if (!disabledAccessUrls.includes(input.fallbackUrl)) {
+            disabledAccessUrls.push(input.fallbackUrl);
+        }
+    }
+    return {
+        accessUrls: [],
+        accessUrlReachable: false,
+        disabledAccessUrls,
+    };
 }
 
 
@@ -7847,6 +8090,8 @@ const MANAGE_GATEWAY_ACTIONS = [
     "createRoute",
     "updateRoute",
     "deleteRoute",
+    "enableRoute",
+    "disableRoute",
     "bindCustomDomain",
     "deleteCustomDomain",
     "enableService",
@@ -7919,6 +8164,7 @@ function registerGatewayTools(server) {
             Domain: route.Domain,
             Path: route.Path,
             IsDefault: route.IsDefault,
+            Enable: typeof route.Enable === "boolean" ? route.Enable : undefined,
             UpstreamResourceType: route.UpstreamResourceType,
             UpstreamResourceName: route.UpstreamResourceName,
         }));
@@ -7929,16 +8175,26 @@ function registerGatewayTools(server) {
             Domain: route.Domain,
             Path: route.Path,
             IsDefault: route.IsDefault,
+            Enable: typeof route.Enable === "boolean" ? route.Enable : undefined,
             UpstreamResourceType: route.UpstreamResourceType,
             UpstreamResourceName: route.UpstreamResourceName,
         }));
-        const envelope = (0, gateway_access_urls_js_1.toAccessUrlEnvelope)((0, gateway_access_urls_js_1.rankGatewayAccessUrls)(candidates));
+        const disabledAccessUrls = (0, gateway_access_urls_js_1.rankGatewayAccessUrls)(candidates, {
+            includeDisabled: true,
+        })
+            .filter((item) => !item.enabled)
+            .map((item) => item.url);
+        const envelope = (0, gateway_access_urls_js_1.toAccessUrlEnvelope)((0, gateway_access_urls_js_1.rankGatewayAccessUrls)(candidates), disabledAccessUrls);
         return {
             ...(envelope.accessUrl ? { accessUrl: envelope.accessUrl } : {}),
             accessUrls: envelope.accessUrls,
             ...(envelope.accessUrlSource
                 ? { accessUrlSource: envelope.accessUrlSource }
                 : {}),
+            accessUrlReachable: Boolean(envelope.accessUrl),
+            ...(disabledAccessUrls.length > 0
+                ? { disabledAccessUrls, routeDisabled: true }
+                : {}),
         };
     };
     const pickUsableDefaultDomain = (domains) => {
@@ -8028,6 +8284,15 @@ function registerGatewayTools(server) {
             : input.enablePathTransmission !== undefined
                 ? input.enablePathTransmission
                 : undefined;
+        // Route enable: prefer route.enable. For updateRoute only, top-level
+        // enable also maps to Route.Enable (enableService/authSwitch use the
+        // same field name but different actions).
+        const routeEnable = input.route?.enable !== undefined
+            ? input.route.enable
+            : input.action === "updateRoute" &&
+                typeof input.enable === "boolean"
+                ? input.enable
+                : undefined;
         const route = {
             Path: path,
             UpstreamResourceType: upstreamResourceType,
@@ -8037,6 +8302,9 @@ function registerGatewayTools(server) {
         if (enablePathTransmission !== undefined) {
             route.EnablePathTransmission = enablePathTransmission;
         }
+        if (routeEnable !== undefined) {
+            route.Enable = routeEnable;
+        }
         return {
             EnvId: await resolveEnvId(),
             Domain: {
@@ -8050,9 +8318,46 @@ function registerGatewayTools(server) {
                 upstreamResourceName,
                 enableAuth,
                 enablePathTransmission,
+                enable: routeEnable,
             },
         };
     };
+    const resolveExistingRouteForToggle = async (input) => {
+        const routePath = input.routePath ?? input.path;
+        if (!routePath) {
+            throw new Error("action=enableRoute/disableRoute 时必须提供 path 或 route.path（例如 \"/\" 或 \"/api\"）");
+        }
+        const normalizedPath = normalizeAccessPath(routePath);
+        const preferredDomain = input.domain;
+        const result = await listHttpServiceRoutes(preferredDomain ? { domain: preferredDomain } : undefined);
+        const upstreamName = input.routeServiceName ?? input.targetName;
+        const matches = flattenRoutes(result).filter((item) => {
+            if (preferredDomain &&
+                item.Domain !== preferredDomain) {
+                return false;
+            }
+            if (normalizeAccessPath(String(item.Path ?? "")) !== normalizedPath) {
+                return false;
+            }
+            if (upstreamName && item.UpstreamResourceName !== upstreamName) {
+                return false;
+            }
+            return true;
+        });
+        if (matches.length === 0) {
+            throw new Error(`未找到路径 ${normalizedPath} 的路由` +
+                (preferredDomain ? `（域名 ${preferredDomain}）` : "") +
+                (upstreamName ? `（上游 ${upstreamName}）` : "") +
+                "。请先用 queryGateway(action=\"listRoutes\") 确认 Domain / Path，再调用 enableRoute/disableRoute。" +
+                "关闭静态托管默认域名（*.tcloudbaseapp.com）时，请显式传 domain=该 STATIC_STORE IsDefault 域名，并通常 path=\"/\"。");
+        }
+        if (matches.length > 1) {
+            const domains = [...new Set(matches.map((item) => item.Domain))];
+            throw new Error(`路径 ${normalizedPath} 匹配到 ${matches.length} 条路由（域名：${domains.join(", ")}）。` +
+                "请补充 domain（必要时再加 targetName/route.serviceName）精确定位后再 enableRoute/disableRoute。");
+        }
+        return matches[0];
+    };
     const routeMutationNextActions = (targetName) => [
         {
             tool: "queryGateway",
@@ -8256,6 +8561,10 @@ function registerGatewayTools(server) {
                     Domain: payload.Domain,
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const routeEnabled = payload.resolved.enable !== false;
+                const accessUrl = routeEnabled
+                    ? `https://${payload.resolved.domain}${payload.resolved.path}`
+                    : undefined;
                 return buildEnvelope({
                     action: input.action,
                     model: "httpServiceRoute",
@@ -8265,13 +8574,31 @@ function registerGatewayTools(server) {
                     upstreamResourceName: payload.resolved.upstreamResourceName,
                     auth: payload.resolved.enableAuth ?? null,
                     enablePathTransmission: payload.resolved.enablePathTransmission ?? null,
-                    accessUrl: `https://${payload.resolved.domain}${payload.resolved.path}`,
-                    accessUrls: [`https://${payload.resolved.domain}${payload.resolved.path}`],
+                    enable: payload.resolved.enable ?? null,
+                    ...(accessUrl
+                        ? {
+                            accessUrl,
+                            accessUrls: [accessUrl],
+                            accessUrlReachable: true,
+                        }
+                        : {
+                            accessUrls: [],
+                            accessUrlReachable: false,
+                            routeDisabled: true,
+                            disabledAccessUrls: [
+                                `https://${payload.resolved.domain}${payload.resolved.path}`,
+                            ],
+                        }),
                     accessUrlSource: input.domain && input.domain === payload.resolved.domain
                         ? "gateway.custom"
                         : "gateway.default",
                     raw: result,
                 }, `HTTP 路由更新成功（${payload.resolved.domain}${payload.resolved.path}` +
+                    (payload.resolved.enable === false
+                        ? "，路由已禁用 Enable=false"
+                        : payload.resolved.enable === true
+                            ? "，路由已启用 Enable=true"
+                            : "") +
                     (payload.resolved.enablePathTransmission === true
                         ? "，路径透传=开启"
                         : payload.resolved.enablePathTransmission === false
@@ -8279,6 +8606,102 @@ function registerGatewayTools(server) {
                             : "") +
                     `）`, routeMutationNextActions(payload.resolved.upstreamResourceName));
             }
+            case "enableRoute":
+            case "disableRoute": {
+                const enable = input.action === "enableRoute";
+                const existing = await resolveExistingRouteForToggle({
+                    path: input.path,
+                    routePath: input.route?.path,
+                    domain: input.domain,
+                    targetName: input.targetName,
+                    routeServiceName: input.route?.serviceName,
+                });
+                const upstreamResourceType = resolveUpstreamResourceType({
+                    upstreamResourceType: input.upstreamResourceType ??
+                        existing.UpstreamResourceType,
+                    routeUpstreamResourceType: input.route?.upstreamResourceType,
+                });
+                const upstreamResourceName = input.route?.serviceName ??
+                    input.targetName ??
+                    String(existing.UpstreamResourceName ?? "");
+                if (!upstreamResourceName) {
+                    throw new Error(`action=${input.action} 无法解析上游资源名；请用 queryGateway(listRoutes) 确认后传入 targetName 或 route.serviceName。`);
+                }
+                const normalizedPath = normalizeAccessPath(String(existing.Path ?? input.route?.path ?? input.path ?? "/"));
+                const domain = existing.Domain;
+                const enableAuth = input.route?.auth !== undefined
+                    ? input.route.auth
+                    : input.auth !== undefined
+                        ? input.auth
+                        : existing.EnableAuth;
+                const enablePathTransmission = input.route?.enablePathTransmission !== undefined
+                    ? input.route.enablePathTransmission
+                    : input.enablePathTransmission !== undefined
+                        ? input.enablePathTransmission
+                        : existing.EnablePathTransmission;
+                const route = {
+                    Path: normalizedPath,
+                    UpstreamResourceType: upstreamResourceType,
+                    UpstreamResourceName: upstreamResourceName,
+                    Enable: enable,
+                };
+                if (enableAuth !== undefined) {
+                    route.EnableAuth = enableAuth;
+                }
+                if (enablePathTransmission !== undefined) {
+                    route.EnablePathTransmission = enablePathTransmission;
+                }
+                const cloudbase = await getManager();
+                const result = await cloudbase.env.modifyHttpServiceRoute({
+                    EnvId: await resolveEnvId(),
+                    Domain: {
+                        Domain: domain,
+                        Routes: [route],
+                    },
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const verb = enable ? "启用" : "禁用";
+                const accessUrl = enable
+                    ? `https://${domain}${normalizedPath}`
+                    : undefined;
+                return buildEnvelope({
+                    action: input.action,
+                    model: "httpServiceRoute",
+                    domain,
+                    path: normalizedPath,
+                    upstreamResourceType,
+                    upstreamResourceName,
+                    enable,
+                    auth: enableAuth ?? null,
+                    enablePathTransmission: enablePathTransmission ?? null,
+                    ...(accessUrl
+                        ? {
+                            accessUrl,
+                            accessUrls: [accessUrl],
+                            accessUrlReachable: true,
+                        }
+                        : {
+                            accessUrls: [],
+                            accessUrlReachable: false,
+                            routeDisabled: true,
+                            disabledAccessUrls: [`https://${domain}${normalizedPath}`],
+                        }),
+                    accessUrlSource: existing.IsDefault
+                        ? "gateway.default"
+                        : "gateway.custom",
+                    raw: result,
+                }, `HTTP 路由已${verb}（${domain}${normalizedPath}，Enable=${enable}）。` +
+                    (enable
+                        ? "启用后通常数秒到约 30 秒内可访问；请用 queryGateway(getRoute) 或探测 accessUrl 确认。"
+                        : "禁用后该路径将不可公网访问（GATEWAY_ROUTE_DISABLED）；关闭静态托管默认域名（*.tcloudbaseapp.com）时，请确认 DomainType=STATIC_STORE 且 IsDefault=true。") +
+                    " 底层对应 tcb ModifyHTTPServiceRoute（不是 ModifyGatewayRoute）。", [
+                    {
+                        tool: "queryGateway",
+                        action: "getRoute",
+                        reason: `复核路由 Enable=${enable} 是否已生效`,
+                    },
+                ]);
+            }
             case "deleteRoute": {
                 const routePath = input.route?.path ?? input.path;
                 if (!routePath) {
@@ -8486,8 +8909,11 @@ function registerGatewayTools(server) {
     }, async (input) => withEnvelope(() => handleQueryGateway(input)));
     server.registerTool?.("manageGateway", {
         title: "管理 CloudBase 网关",
-        description: "CloudBase HTTP 网关统一写入口（Domain/Route）。createRoute/updateRoute/deleteRoute 把域名下的 path 转到上游；未传 domain 时用 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（形如 *.{region}.app.tcloudbase.com），不会使用静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）。" +
+        description: "CloudBase HTTP 网关统一写入口（Domain/Route）。createRoute/updateRoute/deleteRoute 把域名下的 path 转到上游；" +
+            "enableRoute/disableRoute 启用或禁用已有路由（底层 ModifyHTTPServiceRoute 的 Routes[].Enable，不是 ModifyGatewayRoute）。" +
+            "未传 domain 时用 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（形如 *.{region}.app.tcloudbase.com），不会使用静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）。" +
             "这是网关默认域上的路径路由，不是 STATIC_STORE 上游绑定；STATIC_STORE 上游必须显式传 upstreamResourceType=STATIC_STORE。" +
+            "关闭静态托管默认域名（*.tcloudbaseapp.com）：先 queryGateway(listRoutes) 找到 DomainType=STATIC_STORE 且 IsDefault=true 的 domain，再 manageGateway(action=\"disableRoute\", domain=该域名, path=\"/\")；勿用 manageHosting。" +
             "创建后可用 queryGateway(action=\"listRoutes\") 核对 Domain / DomainType / Path / UpstreamResourceType。" +
             "上游类型只用一个参数 upstreamResourceType（也可写在 route.upstreamResourceType，route 优先）：" +
             "WEB_SCF=HTTP云函数，SCF=Event云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器；" +
@@ -8500,9 +8926,12 @@ function registerGatewayTools(server) {
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_GATEWAY_ACTIONS)
-                .describe("写操作：createRoute/updateRoute/deleteRoute 管理路由；bindCustomDomain/deleteCustomDomain 管理自定义域名；" +
+                .describe("写操作：createRoute/updateRoute/deleteRoute 管理路由；enableRoute/disableRoute 启用或禁用已有路由（需 path，建议显式传 domain）；" +
+                "bindCustomDomain/deleteCustomDomain 管理自定义域名；" +
                 "enableService/authSwitch 开关 HTTP 网关总开关与访问鉴权（需配合 enable 参数）。" +
-                "createRoute/updateRoute 必须提供 upstreamResourceType。" +
+                "createRoute/updateRoute 必须提供 upstreamResourceType；enableRoute/disableRoute 会先 listRoutes 定位已有路由，通常不必重填上游。" +
+                "updateRoute 也可传 enable/route.enable 直接改 Routes[].Enable。" +
+                "关闭 *.tcloudbaseapp.com 默认静态托管域：disableRoute + domain=该 STATIC_STORE IsDefault 域名 + path=\"/\"。" +
                 "已有自定义域名时优先 createRoute(domain=已有域名) 实现访问，不必再次 bindCustomDomain / 传入 certificateId；" +
                 "bindCustomDomain 仅用于首次绑定新域名（需 certificateId；可选 accessType=DIRECT|CDN|CUSTOM，CUSTOM 需 customCname；普通场景用默认 DIRECT）。" +
                 "接入说明：https://docs.cloudbase.net/service/custom-domain"),
@@ -8551,16 +8980,25 @@ function registerGatewayTools(server) {
                     .boolean()
                     .optional()
                     .describe("同顶层 enablePathTransmission。route 内设置时优先于顶层。"),
+                enable: zod_1.z
+                    .boolean()
+                    .optional()
+                    .describe("路由级开关（Routes[].Enable / Route.Enable）。createRoute/updateRoute 可用：" +
+                    "enable=false 禁用该 Domain+Path（访问返回 GATEWAY_ROUTE_DISABLED）；" +
+                    "enable=true 重新启用。updateRoute 也可用顶层 enable 表达同一语义；" +
+                    "也可用专用 action enableRoute/disableRoute。route.enable 优先于顶层 enable。"),
             })
                 .optional()
                 .describe("路由对象（可选写法）。例：云函数 {upstreamResourceType:\"WEB_SCF\",serviceName:\"fn\",path:\"/api\"}；" +
                 "云托管 {upstreamResourceType:\"CBR\",serviceName:\"svc\",path:\"/api\"}；" +
-                "静态托管 {upstreamResourceType:\"STATIC_STORE\",serviceName:\"staticstore\",path:\"/\"}。"),
+                "静态托管 {upstreamResourceType:\"STATIC_STORE\",serviceName:\"staticstore\",path:\"/\"}；" +
+                "禁用路由 {path:\"/\",enable:false}（配合 updateRoute，或直接用 disableRoute）。"),
             domain: zod_1.z
                 .string()
                 .optional()
                 .describe("域名。省略时自动使用环境 DomainType=HTTPSERVICE 的 IsDefault 默认 HTTP 域名（*.{region}.app.tcloudbase.com），不会回退到静态托管 CDN 域名（*.tcloudbaseapp.com，DomainType=STATIC_STORE）；也不是 STATIC_STORE 上游绑定。" +
                 "可用 queryGateway(action=\"listRoutes\") 核对实际 Domain / DomainType。" +
+                "enableRoute/disableRoute 操作 *.tcloudbaseapp.com 时必须显式传入该域名。" +
                 "已有自定义域名时请显式传入该域名并 createRoute/updateRoute/deleteRoute，即可实现自定义域名访问且无需证书 ID；" +
                 "仅 bindCustomDomain 时表示要新绑定的域名。"),
             certificateId: zod_1.z
@@ -8583,9 +9021,11 @@ function registerGatewayTools(server) {
             enable: zod_1.z
                 .boolean()
                 .optional()
-                .describe("开关目标状态（enableService / authSwitch 必填）：enable=true 开启，enable=false 关闭。" +
-                "bindCustomDomain 可选：enable=false 表示绑定后禁用域名（默认启用）。" +
-                "省略或非布尔值会返回参数错误。"),
+                .describe("开关目标状态：enableService / authSwitch 必填（true 开启 / false 关闭）；" +
+                "bindCustomDomain 可选：enable=false 表示绑定后禁用域名（默认启用）；" +
+                "updateRoute 可选：映射到 Routes[].Enable（也可用 route.enable，route 优先；" +
+                "也可用专用 action enableRoute/disableRoute）。" +
+                "省略或非布尔值在 enableService/authSwitch 会返回参数错误。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -11208,8 +11648,9 @@ class TelemetryReporter {
         const osRelease = os_1.default.release(); // 操作系统版本
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
-        // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.25.9" || 0;
+        // Build-time injected version; guard for vitest / non-webpack runtimes.
+        const mcpVersion = process.env.npm_package_version ||
+            ( true ? "2.26.0" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -16744,7 +17185,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.25.9" : 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.26.0" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -18018,16 +18459,19 @@ function isDirectoryUploadTarget(localPath, cloudPath) {
         return true;
     return path_1.default.posix.extname(normalizedCloudPath) === '';
 }
-function buildHostingAccessUrl(staticDomain, cloudPath, localPath) {
-    if (!staticDomain)
-        return '';
+function hostingAccessPathname(cloudPath, localPath) {
     const normalizedCloudPath = (cloudPath ?? '').trim().replace(/^\/+|\/+$/g, '');
     const isDirectory = isDirectoryUploadTarget(localPath, cloudPath);
     if (!normalizedCloudPath) {
-        return `https://${staticDomain}/`;
+        return '/';
     }
     const pathname = isDirectory ? `${normalizedCloudPath}/` : normalizedCloudPath;
-    return `https://${staticDomain}/${pathname}`;
+    return `/${pathname}`;
+}
+function buildHostingAccessUrl(staticDomain, cloudPath, localPath) {
+    if (!staticDomain)
+        return '';
+    return `https://${staticDomain}${hostingAccessPathname(cloudPath, localPath)}`;
 }
 function buildUploadErrorMessage(error, localPath) {
     const baseMessage = error instanceof Error ? error.message : String(error);
@@ -18208,7 +18652,7 @@ function buildDomainMutationResult(params) {
         message: `静态托管域名${actionLabel}请求已提交。域名配置、证书校验和边缘侧传播通常需要 30 秒到 10 分钟，请继续调用 queryHosting(action="domainStatus") 确认最终结果。`,
     };
 }
-async function getHostingWebsiteConfig(cloudbase, logger) {
+async function getHostingWebsiteConfig(cloudbase, logger, cloudBaseOptions) {
     const websiteConfig = await cloudbase.hosting.getWebsiteConfig();
     (0, cloudbase_manager_js_1.logCloudBaseResult)(logger, websiteConfig);
     const hostingResult = {
@@ -18225,6 +18669,27 @@ async function getHostingWebsiteConfig(cloudbase, logger) {
     catch {
         // Ignore enrichment failures and return the website config as-is.
     }
+    try {
+        const cdnDomain = typeof hostingResult.CdnDomain === 'string' ? hostingResult.CdnDomain : '';
+        if (cdnDomain && typeof cloudbase.env?.describeHttpServiceRoute === 'function') {
+            const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+            const routeResult = await cloudbase.env.describeHttpServiceRoute({
+                EnvId: envId,
+                Limit: 1000,
+            });
+            const routes = (0, gateway_access_urls_js_1.flattenHttpServiceRoutes)(routeResult);
+            const reachable = (0, gateway_access_urls_js_1.isDomainPathReachableViaGateway)(routes, cdnDomain, '/');
+            hostingResult.staticDomainRouteEnabled = reachable;
+            hostingResult.accessUrlReachable = reachable !== false;
+            if (reachable === false) {
+                hostingResult.routeDisabled = true;
+                hostingResult.disabledAccessUrls = [`https://${cdnDomain}/`];
+            }
+        }
+    }
+    catch {
+        // Gateway route lookup is best-effort enrichment only.
+    }
     return hostingResult;
 }
 async function resolveHostingStaticDomain(cloudbase, logger) {
@@ -18308,7 +18773,7 @@ function registerHostingTools(server) {
             const cloudbase = await getManager();
             switch (input.action) {
                 case 'websiteConfig': {
-                    const websiteConfig = await getHostingWebsiteConfig(cloudbase, server.logger);
+                    const websiteConfig = await getHostingWebsiteConfig(cloudbase, server.logger, cloudBaseOptions);
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         success: true,
                         data: {
@@ -18434,7 +18899,7 @@ function registerHostingTools(server) {
     });
     server.registerTool('manageHosting', {
         title: '管理 CloudBase 静态托管',
-        description: '管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。',
+        description: '管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 本工具没有关闭默认域名（*.tcloudbaseapp.com）的 action；要禁用该默认公网域名，请用 manageGateway(action="disableRoute", domain=该 STATIC_STORE IsDefault 域名, path="/")（底层 ModifyHTTPServiceRoute，不是 ModifyGatewayRoute）。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。',
         inputSchema: manageHostingInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -18474,7 +18939,24 @@ function registerHostingTools(server) {
                     const cdnFromStore = (store.CdnDomain ?? store.StaticDomain);
                     const staticDomain = cdnFromStore || await resolveHostingStaticDomain(cloudbase, server.logger);
                     const fallbackAccessUrl = buildHostingAccessUrl(staticDomain, input.cloudPath, input.localPath);
+                    const accessPathname = hostingAccessPathname(input.cloudPath, input.localPath);
                     const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+                    const getGatewayManager = async () => {
+                        const manager = await getManager();
+                        if (!manager) {
+                            throw new Error("cloudbase manager unavailable");
+                        }
+                        return manager;
+                    };
+                    const allGatewayRoutes = await (0, gateway_access_urls_js_1.resolveAllGatewayRoutes)({
+                        envId,
+                        getManager: getGatewayManager,
+                    });
+                    const staticDomainRouteEnabled = staticDomain
+                        ? (0, gateway_access_urls_js_1.isDomainPathReachableViaGateway)(allGatewayRoutes, staticDomain, accessPathname)
+                        : null;
+                    // null = no matching gateway route info → keep legacy fallback.
+                    const fallbackReachable = staticDomainRouteEnabled !== false;
                     const gatewayCandidates = Array.from(new Set([
                         store.StaticStoreName,
                         store.Name,
@@ -18484,34 +18966,38 @@ function registerHostingTools(server) {
                     ]
                         .map((item) => (typeof item === "string" ? item.trim() : ""))
                         .filter(Boolean)));
-                    let accessUrl = fallbackAccessUrl;
+                    let accessUrl = fallbackReachable ? fallbackAccessUrl : "";
                     let accessUrls = accessUrl ? [accessUrl] : [];
                     let accessUrlSource = accessUrl
                         ? "hosting.staticDomain"
                         : undefined;
+                    let accessUrlReachable = Boolean(accessUrl);
+                    let disabledAccessUrls = [];
+                    if (fallbackAccessUrl && !fallbackReachable) {
+                        disabledAccessUrls.push(fallbackAccessUrl);
+                    }
                     for (const upstreamName of gatewayCandidates) {
                         const gateway = await (0, gateway_access_urls_js_1.resolveGatewayAccessUrls)({
                             envId,
                             upstreamResourceName: upstreamName,
                             upstreamResourceTypes: ["STATIC_STORE"],
-                            getManager: async () => {
-                                const manager = await getManager();
-                                if (!manager) {
-                                    throw new Error("cloudbase manager unavailable");
-                                }
-                                return manager;
-                            },
+                            getManager: getGatewayManager,
                         });
                         const preferred = (0, gateway_access_urls_js_1.preferGatewayOrFallback)({
                             gateway,
                             fallbackUrl: fallbackAccessUrl || undefined,
                             fallbackSource: "hosting.staticDomain",
+                            fallbackReachable,
                         });
-                        if (preferred.accessUrl) {
-                            accessUrl = preferred.accessUrl;
+                        if (preferred.accessUrl || preferred.disabledAccessUrls.length > 0) {
+                            accessUrl = preferred.accessUrl ?? "";
                             accessUrls = preferred.accessUrls;
                             accessUrlSource = preferred.accessUrlSource;
-                            break;
+                            accessUrlReachable = preferred.accessUrlReachable;
+                            disabledAccessUrls = preferred.disabledAccessUrls;
+                            if (preferred.accessUrl) {
+                                break;
+                            }
                         }
                     }
                     try {
@@ -18527,18 +19013,31 @@ function registerHostingTools(server) {
                                 projectName = path_1.default.basename(input.localPath);
                             }
                         }
-                        await (0, notification_js_1.sendDeployNotification)(server, {
-                            deployType: 'hosting',
-                            url: accessUrl,
-                            projectId: envId,
-                            projectName,
-                            consoleUrl: `https://tcb.cloud.tencent.com/dev?envId=${envId}#/static-hosting`,
-                        });
+                        // sendDeployNotification requires a concrete url; skip when no reachable accessUrl
+                        if (accessUrl) {
+                            await (0, notification_js_1.sendDeployNotification)(server, {
+                                deployType: 'hosting',
+                                url: accessUrl,
+                                projectId: envId,
+                                projectName,
+                                consoleUrl: `https://tcb.cloud.tencent.com/dev?envId=${envId}#/static-hosting`,
+                            });
+                        }
                     }
                     catch {
                         // Notification failure should not block uploads.
                     }
                     const uploadPrefix = input.cloudPath ?? input.files?.[0]?.cloudPath ?? '';
+                    const routeDisabled = staticDomainRouteEnabled === false;
+                    let message = '静态托管文件上传成功。若需要校验上传结果，请继续调用 queryHosting(action="findFiles") 或 queryHosting(action="listFiles")。';
+                    if (routeDisabled && accessUrlReachable) {
+                        message =
+                            '静态托管文件上传成功。默认静态托管域名的网关路由已禁用（访问会返回 GATEWAY_ROUTE_DISABLED），已改用其他可达域名作为 accessUrl。可用 manageGateway(action="updateRoute", route.enable=true) 重新启用默认域路由。';
+                    }
+                    else if (routeDisabled && !accessUrlReachable) {
+                        message =
+                            '静态托管文件上传成功，但默认静态托管域名的网关路由已禁用（GATEWAY_ROUTE_DISABLED），当前没有可达的 accessUrl。请用 manageGateway(action="updateRoute", domain="<静态域名>", path="/", upstreamResourceType="STATIC_STORE", targetName="staticstore", route.enable=true) 启用路由，或改用已启用的自定义域名 / CloudBase Sites 域名访问。';
+                    }
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         success: true,
                         data: {
@@ -18548,13 +19047,19 @@ function registerHostingTools(server) {
                             files: input.files ?? [],
                             ignore: input.ignore,
                             staticDomain,
-                            accessUrl,
+                            staticDomainRouteEnabled,
+                            accessUrl: accessUrl || undefined,
                             accessUrls,
                             accessUrlSource,
+                            accessUrlReachable,
+                            ...(disabledAccessUrls.length > 0
+                                ? { disabledAccessUrls }
+                                : {}),
+                            ...(routeDisabled ? { routeDisabled: true } : {}),
                             result,
                             nextActions: uploadPrefix ? [buildFindFilesNextStep(uploadPrefix.replace(/^\/+/, ''))] : undefined,
                         },
-                        message: '静态托管文件上传成功。若需要校验上传结果，请继续调用 queryHosting(action="findFiles") 或 queryHosting(action="listFiles")。',
+                        message,
                     });
                 }
                 case 'delete': {
@@ -18757,6 +19262,7 @@ function registerHostingTools(server) {
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.buildVerificationUriComplete = buildVerificationUriComplete;
 exports.buildDeviceAuthChallengePayload = buildDeviceAuthChallengePayload;
+exports.getCloudBaseApiKeyFromEnv = getCloudBaseApiKeyFromEnv;
 exports.getAuthProgressStateSync = getAuthProgressStateSync;
 exports.getAuthProgressState = getAuthProgressState;
 exports.resolveAuthOptions = resolveAuthOptions;
@@ -18858,16 +19364,24 @@ function updateAuthProgressState(partial) {
     });
     return getAuthProgressStateSync();
 }
+/**
+ * Resolve CloudBase API Key from env.
+ * Prefer CLOUDBASE_API_KEY; fall back to CLOUDBASE_APIKEY (js-sdk / node-sdk convention).
+ */
+function getCloudBaseApiKeyFromEnv() {
+    return process.env.CLOUDBASE_API_KEY || process.env.CLOUDBASE_APIKEY || undefined;
+}
 function normalizeLoginStateFromEnvVars(options) {
     if (options?.ignoreEnvVars) {
         return null;
     }
-    // 优先检查 CloudBase API Key（优先级高于 TENCENTCLOUD_*）
-    const { CLOUDBASE_API_KEY, CLOUDBASE_ENV_ID: CLOUDBASE_ENV, } = process.env;
-    if (CLOUDBASE_API_KEY && CLOUDBASE_ENV) {
+    // Prefer CloudBase API Key over TENCENTCLOUD_*
+    const apiKey = getCloudBaseApiKeyFromEnv();
+    const CLOUDBASE_ENV = process.env.CLOUDBASE_ENV_ID;
+    if (apiKey && CLOUDBASE_ENV) {
         return {
             _type: 'api_key',
-            apiKey: CLOUDBASE_API_KEY,
+            apiKey,
             envId: CLOUDBASE_ENV,
         };
     }
@@ -19039,7 +19553,7 @@ async function peekLoginState(options) {
 }
 async function ensureLogin(options) {
     (0, logger_js_1.debug)("TENCENTCLOUD_SECRETID", { hasSecretId: !!process.env.TENCENTCLOUD_SECRETID });
-    (0, logger_js_1.debug)("CLOUDBASE_API_KEY", { hasApiKey: !!process.env.CLOUDBASE_API_KEY });
+    (0, logger_js_1.debug)("CLOUDBASE_API_KEY", { hasApiKey: !!getCloudBaseApiKeyFromEnv() });
     const loginState = await peekLoginState({
         ignoreEnvVars: options?.ignoreEnvVars,
     });