@cloudbase/cloudbase-mcp 2.25.3 → 2.25.5

package/dist/index.js

@@ -2772,7 +2772,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.3" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.25.5" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -2853,7 +2853,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.3" : 0;
+            const mcpVersion =  true ? "2.25.5" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -7840,6 +7840,7 @@ const QUERY_GATEWAY_ACTIONS = [
     "listRoutes",
     "getRoute",
     "listCustomDomains",
+    "getPrivilege",
 ];
 const MANAGE_GATEWAY_ACTIONS = [
     "createRoute",
@@ -7847,6 +7848,8 @@ const MANAGE_GATEWAY_ACTIONS = [
     "deleteRoute",
     "bindCustomDomain",
     "deleteCustomDomain",
+    "enableService",
+    "authSwitch",
 ];
 /** DomainType of the environment default HTTP service (gateway) domain. */
 const HTTP_SERVICE_DOMAIN_TYPE = "HTTPSERVICE";
@@ -7943,6 +7946,32 @@ function registerGatewayTools(server) {
             candidates.find((item) => item.Enable !== false) ??
             candidates[0]);
     };
+    const getGatewayPrivilege = async () => {
+        const cloudbase = await getManager();
+        const result = await cloudbase
+            .commonService("tcb", "2018-06-08")
+            .call({
+            Action: "DescribeCloudBaseGWPrivilege",
+            Param: {
+                ServiceId: await resolveEnvId(),
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+        return result ?? {};
+    };
+    const buildPrivilegeDescription = (privilege) => {
+        const serviceStatus = privilege.EnableService === undefined
+            ? "未知"
+            : privilege.EnableService === true
+                ? "已开启"
+                : "未开启";
+        const authStatus = privilege.EnableAuth === undefined
+            ? "未知"
+            : privilege.EnableAuth === true
+                ? "已开启"
+                : "未开启";
+        return `HTTP 网关${serviceStatus}，访问鉴权${authStatus}`;
+    };
     const resolveDefaultHttpDomain = async () => {
         // Match console DescribeHTTPServiceRoute usage: filter DomainType=HTTPSERVICE.
         // Envs often also expose an IsDefault STATIC_STORE domain (*.tcloudbaseapp.com);
@@ -8115,6 +8144,28 @@ function registerGatewayTools(server) {
                     },
                 ]);
             }
+            case "getPrivilege": {
+                const privilege = await getGatewayPrivilege();
+                const enableService = privilege.EnableService === true;
+                const enableAuth = privilege.EnableAuth === true;
+                return buildEnvelope({
+                    action: input.action,
+                    enableService,
+                    enableAuth,
+                    raw: privilege,
+                }, buildPrivilegeDescription(privilege) +
+                    (enableService
+                        ? ""
+                        : "；若路由创建成功但访问报 HTTPSERVICE_NONACTIVATED（403），请先开启 HTTP 网关"), enableService
+                    ? undefined
+                    : [
+                        {
+                            tool: "manageGateway",
+                            action: "enableService",
+                            reason: "开启 HTTP 网关总开关（EnableService），开启后路由即可通过默认域访问",
+                        },
+                    ]);
+            }
             default:
                 throw new Error(`不支持的操作类型: ${input.action}`);
         }
@@ -8145,6 +8196,28 @@ function registerGatewayTools(server) {
                     throw err;
                 }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                // 探测 HTTP 网关总开关：未开启时提示 HTTPSERVICE_NONACTIVATED 风险并引导开启。
+                // 探测失败不阻断路由创建结果，仅追加弱提示。
+                let privilegeHint = "";
+                let privilegeNextActions = [];
+                try {
+                    const privilege = await getGatewayPrivilege();
+                    if (privilege.EnableService !== true) {
+                        privilegeHint =
+                            "⚠️ HTTP 网关总开关未开启，路由创建成功后访问仍将返回 HTTPSERVICE_NONACTIVATED（403）；请先调用 manageGateway(action=\"enableService\", enable=true) 开启，再等待 30 秒到 3 分钟访问。";
+                        privilegeNextActions = [
+                            {
+                                tool: "manageGateway",
+                                action: "enableService",
+                                reason: "开启 HTTP 网关总开关（EnableService），否则访问路由会报 HTTPSERVICE_NONACTIVATED（403）",
+                            },
+                        ];
+                    }
+                }
+                catch {
+                    privilegeHint =
+                        "（无法确认 HTTP 网关开关状态；若访问报 HTTPSERVICE_NONACTIVATED，请用 queryGateway(action=\"getPrivilege\") 查询后用 manageGateway(action=\"enableService\") 开启）";
+                }
                 return buildEnvelope({
                     action: input.action,
                     model: "httpServiceRoute",
@@ -8167,7 +8240,12 @@ function registerGatewayTools(server) {
                         : payload.resolved.enablePathTransmission === false
                             ? "；路径透传关闭（网关会剥掉触发路径前缀后再转发给后端）"
                             : "；路径透传未显式设置（平台默认 false，会剥掉触发路径前缀）") +
-                    `。注意：路由配置传播通常需要等待 30 秒到 3 分钟，请勿立即访问。该操作只创建网关入口，不会自动放开上游权限；若上游是云函数且需要匿名或浏览器直接访问，请继续检查函数资源权限。`, routeMutationNextActions(payload.resolved.upstreamResourceName));
+                    `。注意：路由配置传播通常需要等待 30 秒到 3 分钟，请勿立即访问。该操作只创建网关入口，不会自动放开上游权限；若上游是云函数且需要匿名或浏览器直接访问，请继续检查函数资源权限。` +
+                    (privilegeHint ? ` ${privilegeHint}` : ""), [
+                    ...privilegeNextActions,
+                    ...(routeMutationNextActions(payload.resolved.upstreamResourceName) ??
+                        []),
+                ]);
             }
             case "updateRoute": {
                 const cloudbase = await getManager();
@@ -8226,12 +8304,28 @@ function registerGatewayTools(server) {
                 if (!input.domain || !input.certificateId) {
                     throw new Error("action=bindCustomDomain 时必须提供 domain 和 certificateId");
                 }
+                const accessType = input.accessType ?? "DIRECT";
+                if (accessType === "CUSTOM" && !input.customCname) {
+                    throw new Error("action=bindCustomDomain 且 accessType=CUSTOM 时必须提供 customCname（自有 CDN/WAF 的回源/回填地址，不是 DNS 解析目标）。" +
+                        "说明：https://docs.cloudbase.net/service/custom-domain");
+                }
+                if (accessType !== "CUSTOM" && input.customCname) {
+                    throw new Error("customCname 仅在 accessType=CUSTOM 时可用；普通绑定用默认 DIRECT，不要传 customCname。" +
+                        "说明：https://docs.cloudbase.net/service/custom-domain");
+                }
                 const cloudbase = await getManager();
                 const result = await cloudbase.env.bindCustomDomain({
                     EnvId: await resolveEnvId(),
                     Domain: {
                         Domain: input.domain,
                         CertId: input.certificateId,
+                        AccessType: accessType,
+                        ...(input.enable !== undefined
+                            ? { Enable: input.enable }
+                            : {}),
+                        ...(input.customCname
+                            ? { CustomCname: input.customCname }
+                            : {}),
                     },
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
@@ -8239,24 +8333,118 @@ function registerGatewayTools(server) {
                     action: input.action,
                     domain: input.domain,
                     certificateId: input.certificateId,
+                    accessType,
+                    ...(input.customCname
+                        ? { customCname: input.customCname }
+                        : {}),
+                    ...(input.enable !== undefined
+                        ? { enable: input.enable }
+                        : {}),
                     raw: result,
-                }, "自定义域名绑定成功");
+                }, `自定义域名绑定成功（${accessType}）`, [
+                    {
+                        tool: "manageGateway",
+                        action: "createRoute",
+                        reason: "绑定后需 createRoute 添加访问路径，并完成 DNS CNAME 解析后才可访问",
+                    },
+                ]);
             }
             case "deleteCustomDomain": {
                 if (!input.domain) {
                     throw new Error("action=deleteCustomDomain 时必须提供 domain");
                 }
                 const cloudbase = await getManager();
-                const result = await cloudbase.env.deleteCustomDomain({
-                    EnvId: await resolveEnvId(),
-                    Domain: input.domain,
+                try {
+                    const result = await cloudbase.env.deleteCustomDomain({
+                        EnvId: await resolveEnvId(),
+                        Domain: input.domain,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                    return buildEnvelope({
+                        action: input.action,
+                        domain: input.domain,
+                        raw: result,
+                    }, "自定义域名删除成功");
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    // SDK 在域名下仍有路由绑定时抛错，需先删路由再删域名
+                    if (/route binding/i.test(message)) {
+                        return {
+                            success: false,
+                            data: { action: input.action, domain: input.domain },
+                            message: `域名 ${input.domain} 下仍有路由绑定，需先删除路由再删除域名。` +
+                                `原始错误：${message}`,
+                            nextActions: [
+                                {
+                                    tool: "queryGateway",
+                                    action: "listRoutes",
+                                    reason: "查看该域名下的路由，确认需要删除的路径",
+                                },
+                                {
+                                    tool: "manageGateway",
+                                    action: "deleteRoute",
+                                    reason: "先删除该域名下的全部路由（逐个 deleteRoute），再重试 deleteCustomDomain",
+                                },
+                            ],
+                        };
+                    }
+                    throw error;
+                }
+            }
+            case "enableService": {
+                if (typeof input.enable !== "boolean") {
+                    throw new Error('action=enableService 时必须提供 enable 参数（boolean），如 enable=true 开启 HTTP 网关总开关、enable=false 关闭；禁止省略或传非布尔值。');
+                }
+                const cloudbase = await getManager();
+                const result = await cloudbase.access.switchAuth(input.enable);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const serviceText = input.enable ? "开启" : "关闭";
+                return buildEnvelope({
+                    action: input.action,
+                    enable: input.enable,
+                    raw: result,
+                }, `HTTP 网关总开关${serviceText}成功`, [
+                    {
+                        tool: "queryGateway",
+                        action: "getPrivilege",
+                        reason: "复核 HTTP 网关总开关与访问鉴权状态",
+                    },
+                ]);
+            }
+            case "authSwitch": {
+                if (typeof input.enable !== "boolean") {
+                    throw new Error('action=authSwitch 时必须提供 enable 参数（boolean），如 enable=true 开启访问鉴权、enable=false 关闭；禁止省略或传非布尔值。');
+                }
+                const cloudbase = await getManager();
+                const result = await cloudbase
+                    .commonService("tcb", "2018-06-08")
+                    .call({
+                    Action: "ModifyCloudBaseGWPrivilege",
+                    Param: {
+                        ServiceId: await resolveEnvId(),
+                        EnableService: input.enable,
+                        Options: [
+                            {
+                                Key: "authswitch",
+                                Value: input.enable ? "true" : "false",
+                            },
+                        ],
+                    },
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const serviceText = input.enable ? "开启" : "关闭";
                 return buildEnvelope({
                     action: input.action,
-                    domain: input.domain,
+                    enable: input.enable,
                     raw: result,
-                }, "自定义域名删除成功");
+                }, `HTTP 访问服务鉴权${serviceText}成功`, [
+                    {
+                        tool: "queryGateway",
+                        action: "getPrivilege",
+                        reason: "复核 HTTP 网关总开关与访问鉴权状态",
+                    },
+                ]);
             }
             default:
                 throw new Error(`不支持的操作类型: ${input.action}`);
@@ -8266,12 +8454,14 @@ function registerGatewayTools(server) {
         title: "查询 CloudBase 网关",
         description: "CloudBase HTTP 网关统一只读入口（Domain/Route）。查询域名下路径路由及其上游：" +
             "WEB_SCF/SCF=云函数，CBR=云托管，STATIC_STORE=静态托管，LH=轻量应用服务器。" +
-            "主键为 Domain + Path；listRoutes / getRoute / listCustomDomains。" +
+            "主键为 Domain + Path；listRoutes / getRoute / listCustomDomains / getPrivilege。" +
+            "getPrivilege 查询 HTTP 网关总开关（enableService）与访问鉴权（enableAuth）状态。" +
             "实现自定义域名访问前，先 listCustomDomains：若已有自定义域名，优先 createRoute 挂路由（无需证书 ID）；仅在没有可用自定义域名时才 bindCustomDomain。",
         inputSchema: {
             action: zod_1.z
                 .enum(QUERY_GATEWAY_ACTIONS)
-                .describe("只读操作类型：listRoutes、getRoute、listCustomDomains。" +
+                .describe("只读操作类型：listRoutes、getRoute、listCustomDomains、getPrivilege。" +
+                "getPrivilege 无需其他参数，直接返回 HTTP 网关总开关与访问鉴权状态。" +
                 "自定义域名访问场景先 listCustomDomains 确认是否已有域名可复用。"),
             targetName: zod_1.z
                 .string()
@@ -8304,14 +8494,17 @@ function registerGatewayTools(server) {
             "createRoute 只建网关入口，不改上游权限。" +
             "enablePathTransmission：默认 false 剥触发路径前缀；true 透传完整路径（CBR 多路由、WEB_SCF 自管子路径常需 true；STATIC_STORE 自定义触发路径映射站点根通常 false）。" +
             "⚠️ 自定义域名访问：若环境已有自定义域名（先 queryGateway listCustomDomains），优先 createRoute 并显式传入该 domain，无需 certificateId；" +
-            "仅首次绑定全新自定义域名时用 bindCustomDomain（需 certificateId）。CORS/安全域名用 envDomainManagement。",
+            "仅首次绑定全新自定义域名时用 bindCustomDomain（需 certificateId）。CORS/安全域名用 envDomainManagement。" +
+            "enableService/authSwitch：HTTP 网关总开关与访问鉴权开关；createRoute 后若访问报 HTTPSERVICE_NONACTIVATED，通常是总开关未开启（用 queryGateway getPrivilege 查询、enableService 开启）。",
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_GATEWAY_ACTIONS)
-                .describe("写操作：createRoute/updateRoute/deleteRoute 管理路由；bindCustomDomain/deleteCustomDomain 管理自定义域名。" +
+                .describe("写操作：createRoute/updateRoute/deleteRoute 管理路由；bindCustomDomain/deleteCustomDomain 管理自定义域名；" +
+                "enableService/authSwitch 开关 HTTP 网关总开关与访问鉴权（需配合 enable 参数）。" +
                 "createRoute/updateRoute 必须提供 upstreamResourceType。" +
                 "已有自定义域名时优先 createRoute(domain=已有域名) 实现访问，不必再次 bindCustomDomain / 传入 certificateId；" +
-                "bindCustomDomain 仅用于首次绑定新域名。"),
+                "bindCustomDomain 仅用于首次绑定新域名（需 certificateId；可选 accessType=DIRECT|CDN|CUSTOM，CUSTOM 需 customCname；普通场景用默认 DIRECT）。" +
+                "接入说明：https://docs.cloudbase.net/service/custom-domain"),
             targetName: zod_1.z
                 .string()
                 .optional()
@@ -8374,6 +8567,24 @@ function registerGatewayTools(server) {
                 .optional()
                 .describe("证书 ID。仅首次 bindCustomDomain 必填。" +
                 "在已有自定义域名上 createRoute / updateRoute / deleteRoute 不需要 certificateId。"),
+            accessType: zod_1.z
+                .enum(["DIRECT", "CDN", "CUSTOM"])
+                .optional()
+                .describe("绑定类型（仅 bindCustomDomain，默认 DIRECT）。" +
+                "DIRECT=直连（普通绑域名用这个）；CDN=云开发 CDN；CUSTOM=自有 CDN/WAF（需 customCname）。" +
+                "详见 https://docs.cloudbase.net/service/custom-domain"),
+            customCname: zod_1.z
+                .string()
+                .optional()
+                .describe("自有 CDN/WAF 的回源/回填地址（仅 bindCustomDomain 且 accessType=CUSTOM）。" +
+                "不是 DNS 里用户域名要解析到的那个 CNAME；DIRECT/CDN 不要传。" +
+                "详见 https://docs.cloudbase.net/service/custom-domain"),
+            enable: zod_1.z
+                .boolean()
+                .optional()
+                .describe("开关目标状态（enableService / authSwitch 必填）：enable=true 开启，enable=false 关闭。" +
+                "bindCustomDomain 可选：enable=false 表示绑定后禁用域名（默认启用）。" +
+                "省略或非布尔值会返回参数错误。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -10410,6 +10621,22 @@ function buildLoginConfigNextStep(loginMethods) {
         },
     };
 }
+/**
+ * 短信验证码默认通道提示：开启 phone 登录后即可用云开发默认短信通道收发验证码，
+ * 不需要配置短信签名/模板/自定义 Provider。仅当需要自定义模板、签名或更换短信服务商时，
+ * 才需要配置 SmsVerificationConfig / 自定义短信通道。
+ */
+function buildSmsHint(loginMethods) {
+    if (!loginMethods.phone) {
+        return undefined;
+    }
+    return {
+        defaultChannelReady: true,
+        message: "短信验证码登录已开启，可直接使用云开发默认短信通道收发验证码，无需配置短信签名/模板/自定义 Provider。" +
+            "前端调用 auth.getVerification({ phone_number }) 发送验证码、auth.signInWithSms({ verificationInfo, verificationCode, phoneNum }) 登录。" +
+            "仅当需要自定义短信模板/签名或更换短信服务商时，才需要配置 SmsVerificationConfig 或接入自定义短信通道。",
+    };
+}
 function extractProviders(value) {
     const payload = normalizePlainObject(value, "providersResult");
     const providers = payload?.Providers ?? payload?.ProviderList ?? payload?.Data ?? [];
@@ -10590,12 +10817,14 @@ function registerAppAuthTools(server) {
                 const loginMethods = buildLoginMethods(result);
                 const nextStep = buildLoginConfigNextStep(loginMethods);
                 const webSdkHint = buildWebSdkHint(loginMethods);
+                const smsHint = buildSmsHint(loginMethods);
                 return buildSupabaseLikeAuthResponse({
                     success: true,
                     envId,
                     loginMethods,
                     ...(nextStep ? { next_step: nextStep } : {}),
                     ...(webSdkHint ? { webSdkHint } : {}),
+                    ...(smsHint ? { smsHint } : {}),
                 });
             }
             case "listProviders": {
@@ -10671,7 +10900,7 @@ function registerAppAuthTools(server) {
     }));
     server.registerTool?.("manageAppAuth", {
         title: "管理 CloudBase 应用认证配置",
-        description: "CloudBase 应用侧认证配置写入口。用于修改登录方式、provider、client 配置，确保 publishable key，以及创建或删除 API key、自定义登录密钥。⚠️ 本工具为管理端配置工具，不执行用户登录。当任务要求编写客户端登录代码时（例如「用 JS SDK 登录」），应先通过本工具完成配置（如启用 usernamePassword、获取 publishable key），再在项目代码中编写 @cloudbase/js-sdk 客户端登录代码（如 auth.signInWithPassword()），而非使用本工具完成登录。若前端要接受普通用户名样式标识符，应先执行 action=patchLoginStrategy 并传入 patch={ usernamePassword: true }，再实现对应前端登录逻辑。⚠️ action=createApiKey 返回体中的 created 字段表示是否真正新建：created=false 说明复用了环境中已存在的 key，此时 keyName/expireIn 入参不会生效，返回的 keyName/expireAt 均为服务端真实值，并会附带 warnings，切勿把它当作临时凭证分发。",
+        description: "CloudBase 应用侧认证配置写入口。用于修改登录方式、provider、client 配置，确保 publishable key，以及创建或删除 API key、自定义登录密钥。⚠️ 本工具为管理端配置工具，不执行用户登录。当任务要求编写客户端登录代码时（例如「用 JS SDK 登录」），应先通过本工具完成配置（如启用 usernamePassword、获取 publishable key），再在项目代码中编写 @cloudbase/js-sdk 客户端登录代码（如 auth.signInWithPassword()），而非使用本工具完成登录。若前端要接受普通用户名样式标识符，应先执行 action=patchLoginStrategy 并传入 patch={ usernamePassword: true }，再实现对应前端登录逻辑。⚠️ 短信验证码登录（patch={ phone: true }）使用云开发默认短信通道，开启后即可收发验证码，不需要配置短信签名/模板/自定义 Provider；仅当需要自定义模板/签名或更换短信服务商时才需配置 SmsVerificationConfig 或自定义短信通道。⚠️ action=createApiKey 返回体中的 created 字段表示是否真正新建：created=false 说明复用了环境中已存在的 key，此时 keyName/expireIn 入参不会生效，返回的 keyName/expireAt 均为服务端真实值，并会附带 warnings，切勿把它当作临时凭证分发。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_APP_AUTH_ACTIONS),
             patch: zod_1.z
@@ -10737,12 +10966,14 @@ function registerAppAuthTools(server) {
                 const loginMethods = buildLoginMethods(confirmed);
                 const nextStep = buildLoginConfigNextStep(loginMethods);
                 const webSdkHint = buildWebSdkHint(loginMethods);
+                const smsHint = buildSmsHint(loginMethods);
                 return buildSupabaseLikeAuthResponse({
                     success: true,
                     envId,
                     loginMethods,
                     ...(nextStep ? { next_step: nextStep } : {}),
                     ...(webSdkHint ? { webSdkHint } : {}),
+                    ...(smsHint ? { smsHint } : {}),
                 });
             }
             case "addProvider": {
@@ -10977,7 +11208,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.25.3" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.25.5" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -11489,7 +11720,7 @@ const TRIGGER_SCHEMA = zod_1.z.object({
 const CREATE_FUNCTION_SCHEMA = zod_1.z.object({
     name: zod_1.z.string().describe("函数名称"),
     type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("函数类型"),
-    protocolType: zod_1.z.enum(["HTTP", "WS"]).optional().describe("HTTP 云函数协议类型"),
+    protocolType: zod_1.z.enum(["WS"]).optional().describe("HTTP 函数访问协议，当前仅支持 WebSockets，取值为 WS（配合 protocolParams.wsParams 使用）。普通 HTTP 函数不要传此字段；传其他值（如 HTTP）会报 InvalidParameterValue.ProtocolType。"),
     protocolParams: zod_1.z
         .object({
         wsParams: zod_1.z
@@ -12987,6 +13218,14 @@ function collectMigrationVersions(value, found = new Set()) {
 /** Brief retries before concluding a pushed migration never landed (Push can be async). */
 const MIGRATION_VERIFY_ATTEMPTS = 4;
 const MIGRATION_VERIFY_DELAY_MS = 1500;
+/** Page size when hydrating remote migration history into a Push/Preview payload. */
+const MIGRATION_LIST_PAGE_SIZE = 100;
+/**
+ * PushPGUserMigrations is async: poll DescribeTaskResult until Succeed/Failed.
+ * Aligns with CLI `tcb db pg migration up` and Manager SDK docs.
+ */
+const MIGRATION_TASK_POLL_INTERVAL_MS = 1500;
+const MIGRATION_TASK_MAX_WAIT_MS = 90_000;
 /**
  * Confirm a pushed migration version is present in the remote migration history.
  *
@@ -13020,6 +13259,99 @@ async function verifyMigrationApplied(context, version, cloudBaseOptions) {
     }
     return { applied: null, error: lastError };
 }
+function extractMigrationSummaries(history) {
+    const raw = history.Migrations;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const summaries = [];
+    for (const item of raw) {
+        if (!item || typeof item !== "object") {
+            continue;
+        }
+        const row = item;
+        const version = typeof row.Version === "string" ? row.Version.trim() : "";
+        const name = typeof row.Name === "string" ? row.Name.trim() : "";
+        if (version) {
+            summaries.push({ Version: version, Name: name || version });
+        }
+    }
+    return summaries;
+}
+/**
+ * List every remote migration summary (paginated). Required before Push/Preview:
+ * submitting only the pending migration while remote history exists yields
+ * Executable=false with Conflicts reason remote_history_not_found_locally, and the
+ * async task fails with "migration plan is not executable".
+ */
+async function listAllRemoteMigrationSummaries(context, cloudBaseOptions) {
+    const summaries = [];
+    let offset = 0;
+    let latestVersion = "";
+    let total = 0;
+    while (true) {
+        const page = await callPgMigrationApi(context, "ListPGUserMigrations", { Limit: MIGRATION_LIST_PAGE_SIZE, Offset: offset }, cloudBaseOptions);
+        const pageItems = extractMigrationSummaries(page);
+        summaries.push(...pageItems);
+        if (typeof page.LatestVersion === "string" && page.LatestVersion.trim()) {
+            latestVersion = page.LatestVersion.trim();
+        }
+        if (typeof page.Total === "number" && Number.isFinite(page.Total)) {
+            total = page.Total;
+        }
+        else {
+            total = summaries.length;
+        }
+        if (pageItems.length < MIGRATION_LIST_PAGE_SIZE) {
+            break;
+        }
+        offset += MIGRATION_LIST_PAGE_SIZE;
+    }
+    return { summaries, latestVersion, total };
+}
+/**
+ * Build Push/Preview Migrations = remote history Queries + the pending migration.
+ * Matches CLI behavior (submit full set; server skips already-applied versions).
+ */
+async function buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions) {
+    const { summaries, latestVersion } = await listAllRemoteMigrationSummaries(context, cloudBaseOptions);
+    const migrations = [];
+    for (const summary of summaries) {
+        if (summary.Version === pending.Version) {
+            // Caller supplies the authoritative SQL for this version.
+            continue;
+        }
+        const detail = await callPgMigrationApi(context, "DescribePGUserMigration", { MigrationVersion: summary.Version }, cloudBaseOptions);
+        const query = typeof detail.Query === "string" ? detail.Query : "";
+        if (!query.trim()) {
+            throw new Error(`DescribePGUserMigration returned empty Query for version=${summary.Version} (${summary.Name}). ` +
+                "Cannot hydrate remote history for PushPGUserMigrations.");
+        }
+        migrations.push({
+            Version: typeof detail.Version === "string" && detail.Version.trim() ? detail.Version.trim() : summary.Version,
+            Name: typeof detail.Name === "string" && detail.Name.trim() ? detail.Name.trim() : summary.Name,
+            Query: query,
+        });
+    }
+    migrations.push(pending);
+    return { migrations, remoteCount: summaries.length, latestVersion };
+}
+async function waitPgMigrationTask(context, taskId, cloudBaseOptions) {
+    const deadline = Date.now() + MIGRATION_TASK_MAX_WAIT_MS;
+    let last = { TaskId: taskId };
+    while (Date.now() <= deadline) {
+        last = (await callPgMigrationApi(context, "DescribeTaskResult", { TaskId: taskId }, cloudBaseOptions));
+        const status = String(last.Status || "").toLowerCase();
+        if (status === "succeed" || status === "failed") {
+            return last;
+        }
+        await sleep(MIGRATION_TASK_POLL_INTERVAL_MS);
+    }
+    const error = new Error(`DescribeTaskResult timed out after ${Math.floor(MIGRATION_TASK_MAX_WAIT_MS / 1000)}s ` +
+        `for TaskId=${taskId} (last Status=${last.Status || "-"}, Phase=${last.Phase || "-"}).`);
+    error.lastTask = last;
+    throw error;
+}
 const MIGRATION_VERSION_REQUIRED_MESSAGE = "migrationVersion is required (14-digit UTC timestamp YYYYMMDDHHMMSS). " +
     "Decide the version first, write local file migrations/<version>_<migrationName>.sql, " +
     "then call planMigration/applyMigration with the same migrationVersion and migrationName.";
@@ -13806,29 +14138,38 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
-    const migration = {
+    const pending = {
         Version: version,
         Name: args.migrationName,
         Query: args.sql,
     };
     if (args.rollbackSql?.trim()) {
-        migration.Rollback = args.rollbackSql;
+        pending.Rollback = args.rollbackSql;
     }
     try {
+        const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
         const result = await callPgMigrationApi(context, "PreviewPGUserMigrations", {
-            Migrations: [migration],
+            Migrations: hydrated.migrations,
         }, cloudBaseOptions);
+        const executable = result.Executable === true;
         return buildPgToolResult({
             success: true,
             data: {
                 migrationVersion: version,
                 migrationName: args.migrationName,
                 localFileHint,
+                hydratedRemoteCount: hydrated.remoteCount,
+                latestRemoteVersion: hydrated.latestVersion || null,
+                executable,
                 apiResult: result,
             },
-            message: `Migration plan generated via PreviewPGUserMigrations. Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`,
+            message: executable
+                ? `Migration plan generated via PreviewPGUserMigrations (hydrated ${hydrated.remoteCount} remote migration(s)). Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`
+                : `Migration plan is NOT executable (PreviewPGUserMigrations.Executable=false after hydrating ${hydrated.remoteCount} remote migration(s)). Inspect apiResult.Conflicts before applyMigration. Common causes: version older than latest remote (${hydrated.latestVersion || "unknown"}), or checksum mismatch.`,
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion.", {
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", executable
+                    ? "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion."
+                    : "Resolve Conflicts (often pick a migrationVersion newer than LatestVersion), then retry planMigration/applyMigration.", {
                     action: "applyMigration",
                     migrationName: args.migrationName,
                     migrationVersion: version,
@@ -13875,26 +14216,118 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
     }
     const version = versionOrError;
     const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
-    const migration = {
+    const pending = {
         Version: version,
         Name: args.migrationName,
         Query: args.sql,
     };
     if (args.rollbackSql?.trim()) {
-        migration.Rollback = args.rollbackSql;
-    }
-    const params = { Migrations: [migration] };
-    if (args.lockTimeoutMs !== undefined) {
-        params.LockTimeoutMs = args.lockTimeoutMs;
-    }
-    if (args.statementTimeoutMs !== undefined) {
-        params.StatementTimeoutMs = args.statementTimeoutMs;
+        pending.Rollback = args.rollbackSql;
     }
     try {
+        // Pushing only the pending migration while remote history exists makes the plan
+        // non-executable (remote_history_not_found_locally). Hydrate remote Queries first,
+        // matching CLI `tcb db pg migration up` (full list; server skips applied).
+        const hydrated = await buildMigrationsPayloadWithRemoteHistory(context, pending, cloudBaseOptions);
+        const preview = await callPgMigrationApi(context, "PreviewPGUserMigrations", { Migrations: hydrated.migrations }, cloudBaseOptions);
+        if (preview.Executable !== true) {
+            return buildPgToolResult({
+                success: false,
+                errorCode: "MIGRATION_NOT_EXECUTABLE",
+                data: {
+                    migrationVersion: version,
+                    migrationName: args.migrationName,
+                    localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
+                    latestRemoteVersion: hydrated.latestVersion || null,
+                    previewResult: preview,
+                    verified: false,
+                },
+                message: `PreviewPGUserMigrations reported Executable=false for migrationVersion=${version} ` +
+                    `(latest remote=${hydrated.latestVersion || "unknown"}, hydratedRemoteCount=${hydrated.remoteCount}). ` +
+                    "Push was NOT submitted. Inspect previewResult.Conflicts — common reasons: " +
+                    "local_migration_before_latest_remote (pick a newer 14-digit version) or checksum_mismatch. " +
+                    "If the schema change is urgent you may fall back to action=execute with allowDdlViaExecute=true, but that bypasses migration history.",
+                nextActions: [
+                    buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check LatestVersion and pick a migrationVersion strictly newer than it.", { action: "listMigrations", limit: 20 }),
+                    buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Re-run planMigration after adjusting migrationVersion/SQL.", {
+                        action: "planMigration",
+                        migrationName: args.migrationName,
+                        migrationVersion: version,
+                        sql: args.sql,
+                        ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                    }),
+                ],
+            });
+        }
+        const params = { Migrations: hydrated.migrations };
+        if (args.lockTimeoutMs !== undefined) {
+            params.LockTimeoutMs = args.lockTimeoutMs;
+        }
+        if (args.statementTimeoutMs !== undefined) {
+            params.StatementTimeoutMs = args.statementTimeoutMs;
+        }
         const result = await callPgMigrationApi(context, "PushPGUserMigrations", params, cloudBaseOptions);
-        // PushPGUserMigrations may return a TaskId without the migration having taken
-        // effect. Confirm against the remote history before reporting success, so callers
-        // never get a false-positive success for a silently dropped migration.
+        const taskId = typeof result.TaskId === "string" ? result.TaskId.trim() : "";
+        let taskResult = null;
+        if (taskId) {
+            try {
+                taskResult = await waitPgMigrationTask(context, taskId, cloudBaseOptions);
+            }
+            catch (error) {
+                const lastTask = error.lastTask;
+                return buildPgToolResult({
+                    success: false,
+                    errorCode: "MIGRATION_TASK_TIMEOUT",
+                    data: {
+                        migrationVersion: version,
+                        migrationName: args.migrationName,
+                        localFileHint,
+                        hydratedRemoteCount: hydrated.remoteCount,
+                        apiResult: result,
+                        taskResult: lastTask ?? { TaskId: taskId },
+                        verified: null,
+                    },
+                    message: `PushPGUserMigrations returned TaskId=${taskId}, but waiting for DescribeTaskResult timed out: ` +
+                        `${error instanceof Error ? error.message : String(error)}. ` +
+                        "The migration may still be running — check action=listMigrations before retrying or falling back to execute.",
+                    nextActions: [
+                        buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Check whether the migrationVersion eventually landed.", { action: "listMigrations", limit: 20 }),
+                    ],
+                });
+            }
+            const status = String(taskResult.Status || "").toLowerCase();
+            if (status === "failed") {
+                return buildPgToolResult({
+                    success: false,
+                    errorCode: "MIGRATION_TASK_FAILED",
+                    data: {
+                        migrationVersion: version,
+                        migrationName: args.migrationName,
+                        localFileHint,
+                        hydratedRemoteCount: hydrated.remoteCount,
+                        apiResult: result,
+                        taskResult: taskResult,
+                        verified: false,
+                    },
+                    message: `PushPGUserMigrations TaskId=${taskId} failed at phase=${taskResult.Phase || "-"}: ` +
+                        `${taskResult.Reason || "unknown reason"}. ` +
+                        "The migration did NOT take effect. Fix Conflicts/SQL (or use a newer migrationVersion), then retry applyMigration. " +
+                        "Urgent bypass: action=execute with allowDdlViaExecute=true (skips migration history).",
+                    nextActions: [
+                        buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Preview again to inspect Conflicts before retrying apply.", {
+                            action: "planMigration",
+                            migrationName: args.migrationName,
+                            migrationVersion: version,
+                            sql: args.sql,
+                            ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                        }),
+                        buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Confirm the version is still absent from remote history.", { action: "listMigrations", limit: 20 }),
+                    ],
+                });
+            }
+        }
+        // Task Succeed (or sync response without TaskId): confirm history records the version.
         const verification = await verifyMigrationApplied(context, version, cloudBaseOptions);
         if (verification.applied === false) {
             return buildPgToolResult({
@@ -13904,10 +14337,12 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationVersion: version,
                     migrationName: args.migrationName,
                     localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
                     apiResult: result,
+                    taskResult: taskResult,
                     verified: false,
                 },
-                message: `PushPGUserMigrations returned without error, but migrationVersion=${version} is not present in the remote migration history, ` +
+                message: `PushPGUserMigrations completed (TaskId=${taskId || "none"}), but migrationVersion=${version} is not present in the remote migration history, ` +
                     "so the migration did NOT take effect. Do not assume the schema change is applied. " +
                     "Re-check the SQL and migrationVersion, inspect the migration with action=migrationDetail, and retry action=applyMigration. " +
                     "If the schema change is urgent you may fall back to action=execute with allowDdlViaExecute=true, but that bypasses migration history.",
@@ -13925,7 +14360,9 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                     migrationVersion: version,
                     migrationName: args.migrationName,
                     localFileHint,
+                    hydratedRemoteCount: hydrated.remoteCount,
                     apiResult: result,
+                    taskResult: taskResult,
                     verified: null,
                 },
                 message: `PushPGUserMigrations was submitted, but verifying migrationVersion=${version} against the remote history failed: ${verification.error}. ` +
@@ -13941,10 +14378,12 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
                 migrationVersion: version,
                 migrationName: args.migrationName,
                 localFileHint,
+                hydratedRemoteCount: hydrated.remoteCount,
                 apiResult: result,
+                taskResult: taskResult,
                 verified: true,
             },
-            message: `Migrations applied via PushPGUserMigrations and verified present in the remote migration history. Ensure local file ${localFileHint} exists and matches.`,
+            message: `Migrations applied via PushPGUserMigrations (hydrated ${hydrated.remoteCount} remote migration(s)), task ${taskId ? `TaskId=${taskId} ` : ""}verified present in the remote migration history. Ensure local file ${localFileHint} exists and matches.`,
         });
     }
     catch (error) {
@@ -15459,7 +15898,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.3" : 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.25.5" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])