@cloudbase/cloudbase-mcp 2.23.11 → 2.24.1

package/dist/index.d.ts

@@ -330,6 +330,13 @@ declare interface LoginState {
 
 export declare function logout(): Promise<void>;
 
+/** MCP initialize clientInfo fields available after handshake via Server.getClientVersion(). */
+declare type McpClientInfo = {
+    name?: string;
+    version?: string;
+    title?: string;
+};
+
 export { McpServer }
 
 /** 各插件的可选配置 */
@@ -357,6 +364,7 @@ export declare const reportToolCall: (params: {
     inputParams?: any;
     cloudBaseOptions?: CloudBaseOptions;
     ide?: string;
+    mcpClientInfo?: McpClientInfo;
 }) => Promise<void>;
 
 export declare const reportToolkitLifecycle: (params: {
@@ -366,6 +374,7 @@ export declare const reportToolkitLifecycle: (params: {
     error?: string;
     cloudBaseOptions?: CloudBaseOptions;
     ide?: string;
+    mcpClientInfo?: McpClientInfo;
 }) => Promise<void>;
 
 export declare function resetCloudBaseManagerCache(): void;

package/dist/index.js

@@ -30,6 +30,8 @@ import * as __WEBPACK_EXTERNAL_MODULE_winston__ from "winston";
 
 
 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.registerEnvTools = registerEnvTools;
 const toolbox_1 = __webpack_require__(2090);
@@ -39,6 +41,26 @@ const cloudbase_manager_js_1 = __webpack_require__(3431);
 const logger_js_1 = __webpack_require__(3039);
 const tool_result_js_1 = __webpack_require__(9835);
 const env_setup_js_1 = __webpack_require__(6978);
+/**
+ * Resources accepted by CreateEnv. Matches Cloud API / Manager SDK contract.
+ * `postgresql` enables CloudBase PostgreSQL (PG mode) when supported by the package.
+ */
+exports.CREATE_ENV_RESOURCE_VALUES = [
+    "flexdb",
+    "storage",
+    "function",
+    "postgresql",
+];
+/** Default Resources when callers omit the field (schema promises "all four"). */
+exports.DEFAULT_CREATE_ENV_RESOURCES = [
+    ...exports.CREATE_ENV_RESOURCE_VALUES,
+];
+function resolveCreateEnvResources(resources) {
+    if (Array.isArray(resources) && resources.length > 0) {
+        return [...resources];
+    }
+    return [...exports.DEFAULT_CREATE_ENV_RESOURCES];
+}
 /**
  * Simplify environment list data by keeping only essential fields for AI assistant
  * This reduces token consumption when returning environment lists via MCP tools
@@ -804,7 +826,13 @@ function resolveToolAuthOptions(server, overrides) {
 function registerEnvTools(server) {
     // 获取 cloudBaseOptions，如果没有则为 undefined
     const cloudBaseOptions = server.cloudBaseOptions;
-    const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions, mcpServer: server });
+    // Default: env-scoped tools need a bound envId (domains / domain management use SDK this.envId).
+    // manageEnv create/listPackages are account-level — use requireEnvId: false there only.
+    const getManager = (options) => (0, cloudbase_manager_js_1.getCloudBaseManager)({
+        cloudBaseOptions,
+        requireEnvId: options?.requireEnvId ?? true,
+        mcpServer: server,
+    });
     const getManagerForEnvQuery = (targetEnvId, requireEnvId = true) => (0, cloudbase_manager_js_1.getCloudBaseManager)({
         cloudBaseOptions: targetEnvId && targetEnvId !== cloudBaseOptions?.envId
             ? {
@@ -1685,14 +1713,10 @@ function registerEnvTools(server) {
                 .string()
                 .optional()
                 .describe("套餐 ID（action=create/modifyPlan 时必填）。可选值如 baas_personal(个人版)、baas_pf_standard(标准版)、baas_pf_enterprise(企业版)"),
-            region: zod_1.z
-                .string()
-                .optional()
-                .describe("环境地域（action=create 时可选）。默认 ap-shanghai，可选 ap-guangzhou、ap-beijing 等"),
             resources: zod_1.z
-                .array(zod_1.z.enum(["flexdb", "storage", "function", "postgresql"]))
+                .array(zod_1.z.enum(exports.CREATE_ENV_RESOURCE_VALUES))
                 .optional()
-                .describe("启用的资源类型（action=create 时可选）。默认启用全部四项：flexdb(文档数据库)、storage(存储)、function(云函数)、postgresql(PostgreSQL 数据库)"),
+                .describe("启用的资源类型（action=create 时可选）。省略时默认全部四项：flexdb(文档数据库)、storage(存储)、function(云函数)、postgresql(PostgreSQL)。CreateEnv 要求 Resources 非空，MCP 会始终下发该字段。"),
             duration: zod_1.z
                 .number()
                 .int()
@@ -1720,17 +1744,19 @@ function registerEnvTools(server) {
         const action = rawArgs.action ?? "";
         const alias = normalizeOptionalToolString(rawArgs.alias);
         const packageId = normalizeOptionalToolString(rawArgs.packageId);
-        const region = normalizeOptionalToolString(rawArgs.region) ?? "ap-shanghai";
-        const resources = rawArgs.resources;
+        const resolvedResources = resolveCreateEnvResources(rawArgs.resources);
         const duration = rawArgs.duration ?? 1;
         const envId = normalizeOptionalToolString(rawArgs.envId);
         const confirmed = rawArgs.confirm === "yes";
         try {
-            const cloudbase = await getManager();
+            const cloudbase = await getManager({ requireEnvId: false });
             switch (action) {
                 case "listPackages": {
-                    // 查询可选套餐列表（新购场景）
-                    const result = await cloudbase.env.describeBaasPackageList({ TargetAction: "new" });
+                    // Query packages for new purchase. Source aligns with billing-side Baas package APIs.
+                    const result = await cloudbase.env.describeBaasPackageList({
+                        TargetAction: "new",
+                        Source: "qcloud",
+                    });
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         ok: true,
@@ -1740,12 +1766,13 @@ function registerEnvTools(server) {
                     });
                 }
                 case "create": {
-                    // 创建环境需要 confirm
+                    // CreateEnv (Manager SDK / Cloud API) accepts Alias, PackageId, Resources, Period, etc.
+                    // It does NOT accept Region — region is determined by account/package, not this call.
                     if (!confirmed) {
                         return (0, tool_result_js_1.buildJsonToolResult)({
                             ok: false,
                             code: "CONFIRM_REQUIRED",
-                            message: `创建环境需要您确认。请确认以下配置信息后传入 confirm="yes"：\n别名: ${alias}\n套餐: ${packageId}\n地域: ${region}\n资源类型: ${resources?.join(", ") ?? "flexdb, storage, function, postgresql"}\n时长: ${duration} 个月`,
+                            message: `创建环境需要您确认。请确认以下配置信息后传入 confirm="yes"：\n别名: ${alias}\n套餐: ${packageId}\n资源类型: ${resolvedResources.join(", ")}\n时长: ${duration} 个月\n说明: CreateEnv 不接受 Region；环境地域由账号与套餐侧决定。`,
                             next_step: {
                                 tool: "manageEnv",
                                 action: "create",
@@ -1762,12 +1789,9 @@ function registerEnvTools(server) {
                     const createParams = {
                         Alias: alias,
                         PackageId: packageId,
-                        Region: region,
+                        Resources: resolvedResources,
                         Period: duration,
                     };
-                    if (resources && resources.length > 0) {
-                        createParams.Resources = resources;
-                    }
                     const result = await cloudbase.env.createEnv(createParams);
                     (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                     return (0, tool_result_js_1.buildJsonToolResult)({
@@ -1775,6 +1799,7 @@ function registerEnvTools(server) {
                         code: "ENV_CREATED",
                         message: `环境创建成功！新环境 ID: ${result.EnvId}。环境初始化可能需要几分钟，请通过 queryEnv(action="info", envId="${result.EnvId}") 轮询直到 Status 为正常。`,
                         envId: result.EnvId,
+                        resources: resolvedResources,
                     });
                 }
                 case "modifyPlan": {
@@ -1852,11 +1877,19 @@ function registerEnvTools(server) {
             if (toolPayloadResult) {
                 return toolPayloadResult;
             }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            if (action === "listPackages" && /billTags/i.test(errorMessage)) {
+                return (0, tool_result_js_1.buildJsonToolResult)({
+                    ok: false,
+                    code: "PACKAGE_LIST_FAILED",
+                    message: `查询套餐列表失败（计费标签 BillTags）：${errorMessage}。可改用控制台查看套餐，或直接使用已知 packageId（如 baas_personal）调用 manageEnv(action="create")。`,
+                });
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: `环境管理操作失败: ${error instanceof Error ? error.message : String(error)}`,
+                        text: `环境管理操作失败: ${errorMessage}`,
                     },
                 ],
             };
@@ -2200,7 +2233,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.23.11" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.24.1" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -2281,7 +2314,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.23.11" : 0;
+            const mcpVersion =  true ? "2.24.1" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -2318,7 +2351,8 @@ function createWrappedHandler(name, handler, server) {
                     error: errorMessage,
                     inputParams: sanitizeArgs(args), // 添加入参上报
                     cloudBaseOptions: cloudBaseOptions, // 传递 CloudBase 配置（可能已更新）
-                    ide: server.ide || process.env.INTEGRATION_IDE // 传递集成IDE信息
+                    ide: server.ide || process.env.INTEGRATION_IDE, // 传递集成IDE信息
+                    mcpClientInfo: (0, telemetry_js_1.readMcpClientInfoFromServer)(server),
                 }).catch(err => {
                     // 静默处理上报错误，不影响主要功能
                     (0, logger_js_1.debug)('遥测上报失败', { toolName: name, error: err instanceof Error ? err.message : String(err) });
@@ -9886,6 +9920,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.reportToolkitLifecycle = exports.reportToolCall = exports.telemetryReporter = void 0;
+exports.extractMcpClientInfo = extractMcpClientInfo;
+exports.readMcpClientInfoFromServer = readMcpClientInfoFromServer;
 const crypto_1 = __importDefault(__webpack_require__(7823));
 const http_1 = __importDefault(__webpack_require__(3782));
 const https_1 = __importDefault(__webpack_require__(3871));
@@ -9937,7 +9973,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.23.11" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.24.1" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -10119,6 +10155,49 @@ function resolveEnvId(cloudBaseOptions) {
     }
     return { envId, envIdSource };
 }
+/**
+ * Normalize SDK Implementation / clientInfo into telemetry-safe fields.
+ */
+function extractMcpClientInfo(clientVersion) {
+    if (!clientVersion || typeof clientVersion !== "object") {
+        return {};
+    }
+    const info = clientVersion;
+    const name = typeof info.name === "string" ? info.name.trim() : "";
+    const version = typeof info.version === "string" ? info.version.trim() : "";
+    const title = typeof info.title === "string" ? info.title.trim() : "";
+    return {
+        ...(name ? { name } : {}),
+        ...(version ? { version } : {}),
+        ...(title ? { title } : {}),
+    };
+}
+/**
+ * Read MCP clientInfo from an McpServer after initialize.
+ * Returns empty object when handshake has not completed or the accessor is unavailable.
+ */
+function readMcpClientInfoFromServer(server) {
+    try {
+        return extractMcpClientInfo(server?.server?.getClientVersion?.());
+    }
+    catch {
+        return {};
+    }
+}
+function appendMcpClientInfoFields(eventData, clientInfo) {
+    if (!clientInfo) {
+        return;
+    }
+    if (clientInfo.name) {
+        eventData.mcpClientName = clientInfo.name;
+    }
+    if (clientInfo.version) {
+        eventData.mcpClientVersion = clientInfo.version;
+    }
+    if (clientInfo.title) {
+        eventData.mcpClientTitle = clientInfo.title;
+    }
+}
 // 便捷方法
 const reportToolCall = async (params) => {
     const { nodeVersion, osType, osRelease, arch, mcpVersion } = exports.telemetryReporter.getUserAgent();
@@ -10163,6 +10242,7 @@ const reportToolCall = async (params) => {
     if (params.ide) {
         eventData.ide = params.ide;
     }
+    appendMcpClientInfoFields(eventData, params.mcpClientInfo);
     // Debug: 打印最终上报参数
     (0, logger_js_1.debug)('[telemetry] 工具调用上报参数', {
         toolName: params.toolName,
@@ -10205,6 +10285,7 @@ const reportToolkitLifecycle = async (params) => {
     if (params.ide) {
         eventData.ide = params.ide;
     }
+    appendMcpClientInfoFields(eventData, params.mcpClientInfo);
     // Debug: 打印最终上报参数
     (0, logger_js_1.debug)('[telemetry] 生命周期事件上报参数', {
         event: params.event,
@@ -11778,6 +11859,38 @@ function classifySqlRisk(sql) {
         requiresConfirm: true,
     };
 }
+/**
+ * Schema DDL that must go through applyMigration by default.
+ * Includes CREATE/ALTER/COMMENT (schema_change) and DROP/TRUNCATE / destructive ALTER.
+ * Excludes DML DELETE and security_change (GRANT/POLICY), which may still use execute.
+ */
+function isSchemaDdlRisk(risk, sql) {
+    if (risk === "schema_change") {
+        return true;
+    }
+    if (risk !== "destructive") {
+        return false;
+    }
+    const verb = getSqlVerb(stripLeadingSqlComments(sql));
+    return ["DROP", "TRUNCATE", "ALTER"].includes(verb);
+}
+function buildLocalMigrationFileHint(version, name) {
+    return `migrations/${version}_${name}.sql`;
+}
+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.";
+function requireExplicitMigrationVersion(args, actionLabel) {
+    const version = args.migrationVersion?.trim();
+    if (!version) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "MIGRATION_VERSION_REQUIRED",
+            message: `Provide migrationVersion when action=${actionLabel}. ${MIGRATION_VERSION_REQUIRED_MESSAGE}`,
+        });
+    }
+    return version;
+}
 function quoteIdentifier(identifier) {
     return `"${identifier.replace(/"/g, '""')}"`;
 }
@@ -12142,12 +12255,6 @@ async function executeManagerPGSql(context, sql, cloudBaseOptions) {
     }
     throw new Error("Current @cloudbase/manager-node runtime does not expose database.executePGSql or commonService fallback. Upgrade to @cloudbase/manager-node >= 5.4.0.");
 }
-/** Generate a 14-digit migration version (YYYYMMDDHHMMSS) from current time */
-function generateMigrationVersion() {
-    const d = new Date();
-    const p = (n) => String(n).padStart(2, "0");
-    return `${d.getFullYear()}${p(d.getMonth() + 1)}${p(d.getDate())}${p(d.getHours())}${p(d.getMinutes())}${p(d.getSeconds())}`;
-}
 /** Call a CloudBase PG migration API via commonService fallback */
 async function callPgMigrationApi(context, action, params, cloudBaseOptions) {
     const manager = await (0, cloudbase_manager_js_1.getCloudBaseManager)({
@@ -12390,6 +12497,34 @@ async function handleExecuteSql(args, context, deps) {
         });
     }
     const classification = classifySqlRisk(args.sql);
+    if (isSchemaDdlRisk(classification.risk, args.sql) && args.allowDdlViaExecute !== true) {
+        return buildPgToolResult({
+            success: false,
+            errorCode: "DDL_USE_APPLY_MIGRATION",
+            message: "Schema DDL (CREATE/ALTER/DROP/TRUNCATE/...) must use applyMigration with an explicit migrationVersion, " +
+                "not execute. Write local migrations/<version>_<name>.sql first, then call applyMigration. " +
+                "Set allowDdlViaExecute=true only for exceptional one-off ops that intentionally bypass migration history.",
+            data: {
+                classification,
+                localFileHintPattern: "migrations/<migrationVersion>_<migrationName>.sql",
+            },
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "planMigration", "Preview the schema change as a versioned migration (provide migrationVersion + migrationName).", {
+                    action: "planMigration",
+                    migrationName: "describe_your_change",
+                    migrationVersion: "YYYYMMDDHHMMSS",
+                    sql: args.sql,
+                }),
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Apply the schema change via PushPGUserMigrations with the same explicit migrationVersion.", {
+                    action: "applyMigration",
+                    migrationName: "describe_your_change",
+                    migrationVersion: "YYYYMMDDHHMMSS",
+                    sql: args.sql,
+                    confirm: true,
+                }),
+            ],
+        });
+    }
     if (!classification.readOnly && !args.confirm) {
         return buildPgToolResult({
             success: false,
@@ -12399,7 +12534,12 @@ async function handleExecuteSql(args, context, deps) {
                 classification,
             },
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "execute", "Re-issue with confirm=true to actually run the SQL.", { action: "execute", sql: args.sql, confirm: true }),
+                buildNextAction(MANAGE_PG_DATABASE, "execute", "Re-issue with confirm=true to actually run the SQL.", {
+                    action: "execute",
+                    sql: args.sql,
+                    confirm: true,
+                    ...(args.allowDdlViaExecute === true ? { allowDdlViaExecute: true } : {}),
+                }),
                 buildNextAction(QUERY_PG_DATABASE, "metadata", "Inspect table size and shape before destructive changes.", { action: "metadata", limit: 20 }),
             ],
         });
@@ -12416,8 +12556,15 @@ async function handleExecuteSql(args, context, deps) {
                 .slice(0, 5)
                 .map((row) => serializeValue(row)),
             targetTable: targetTable ?? null,
+            ...(args.allowDdlViaExecute === true && isSchemaDdlRisk(classification.risk, args.sql)
+                ? {
+                    warning: "DDL executed via allowDdlViaExecute bypasses migration history. Prefer applyMigration for reproducible schema changes.",
+                }
+                : {}),
         },
-        message: "Write SQL executed successfully.",
+        message: args.allowDdlViaExecute === true && isSchemaDdlRisk(classification.risk, args.sql)
+            ? "Write SQL executed successfully (DDL via allowDdlViaExecute; migration history was bypassed)."
+            : "Write SQL executed successfully.",
         nextActions: classification.risk === "schema_change" && targetTable
             ? [
                 buildNextAction(QUERY_PG_DATABASE, "schema", "Inspect the table schema, columns, indexes, and RLS policies after schema changes.", {
@@ -12445,6 +12592,43 @@ async function handleDryRun(args) {
         });
     }
     const classification = classifySqlRisk(args.sql);
+    const schemaDdl = isSchemaDdlRisk(classification.risk, args.sql);
+    if (classification.readOnly) {
+        return buildPgToolResult({
+            success: true,
+            data: {
+                classification,
+                wouldExecute: false,
+                sqlPreview: args.sql.trim().slice(0, 500),
+            },
+            message: "SQL dry run completed. This statement is read-only; use queryPgDatabase(action=sql) to execute it.",
+            nextActions: [
+                buildNextAction(QUERY_PG_DATABASE, "sql", "Execute the read-only SQL through queryPgDatabase.", { action: "sql", sql: args.sql, limit: 20 }),
+            ],
+        });
+    }
+    if (schemaDdl) {
+        return buildPgToolResult({
+            success: true,
+            data: {
+                classification,
+                wouldExecute: false,
+                sqlPreview: args.sql.trim().slice(0, 500),
+                preferredAction: "applyMigration",
+                localFileHintPattern: "migrations/<migrationVersion>_<migrationName>.sql",
+            },
+            message: "SQL dry run completed. Schema DDL should use applyMigration with an explicit migrationVersion, not execute.",
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Apply schema DDL via versioned migration (provide migrationVersion + migrationName + confirm=true).", {
+                    action: "applyMigration",
+                    migrationName: "describe_your_change",
+                    migrationVersion: "YYYYMMDDHHMMSS",
+                    sql: args.sql,
+                    confirm: true,
+                }),
+            ],
+        });
+    }
     return buildPgToolResult({
         success: true,
         data: {
@@ -12452,15 +12636,9 @@ async function handleDryRun(args) {
             wouldExecute: false,
             sqlPreview: args.sql.trim().slice(0, 500),
         },
-        message: classification.readOnly
-            ? "SQL dry run completed. This statement is read-only; use queryPgDatabase(action=sql) to execute it."
-            : "SQL dry run completed. Write SQL requires managePgDatabase(action=execute, confirm=true).",
+        message: "SQL dry run completed. Write SQL requires managePgDatabase(action=execute, confirm=true).",
         nextActions: [
-            buildNextAction(classification.readOnly ? QUERY_PG_DATABASE : MANAGE_PG_DATABASE, classification.readOnly ? "sql" : "execute", classification.readOnly
-                ? "Execute the read-only SQL through queryPgDatabase."
-                : "Execute the write SQL only after explicit confirmation.", classification.readOnly
-                ? { action: "sql", sql: args.sql, limit: 20 }
-                : { action: "execute", sql: args.sql, confirm: true }),
+            buildNextAction(MANAGE_PG_DATABASE, "execute", "Execute the write SQL only after explicit confirmation.", { action: "execute", sql: args.sql, confirm: true }),
         ],
     });
 }
@@ -12479,7 +12657,12 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
             message: "Provide migrationName (lowercase letters, digits and underscores, starting with a letter) when action=planMigration.",
         });
     }
-    const version = args.migrationVersion?.trim() || generateMigrationVersion();
+    const versionOrError = requireExplicitMigrationVersion(args, "planMigration");
+    if (typeof versionOrError !== "string") {
+        return versionOrError;
+    }
+    const version = versionOrError;
+    const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
     const migration = {
         Version: version,
         Name: args.migrationName,
@@ -12494,10 +12677,22 @@ async function handlePlanMigration(args, context, deps, cloudBaseOptions) {
         }, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
-            data: result,
-            message: "Migration plan generated via PreviewPGUserMigrations.",
+            data: {
+                migrationVersion: version,
+                migrationName: args.migrationName,
+                localFileHint,
+                apiResult: result,
+            },
+            message: `Migration plan generated via PreviewPGUserMigrations. Reuse migrationVersion=${version} on applyMigration. Ensure local file ${localFileHint} exists and matches.`,
             nextActions: [
-                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration to execute.", { action: "applyMigration", migrationName: args.migrationName, sql: args.sql, confirm: true, ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}) }),
+                buildNextAction(MANAGE_PG_DATABASE, "applyMigration", "Review the plan above. If it looks correct, call applyMigration with the same migrationVersion.", {
+                    action: "applyMigration",
+                    migrationName: args.migrationName,
+                    migrationVersion: version,
+                    sql: args.sql,
+                    confirm: true,
+                    ...(args.rollbackSql ? { rollbackSql: args.rollbackSql } : {}),
+                }),
             ],
         });
     }
@@ -12531,7 +12726,12 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
             message: "PushPGUserMigrations requires confirm=true. Run with confirm=true to proceed.",
         });
     }
-    const version = args.migrationVersion?.trim() || generateMigrationVersion();
+    const versionOrError = requireExplicitMigrationVersion(args, "applyMigration");
+    if (typeof versionOrError !== "string") {
+        return versionOrError;
+    }
+    const version = versionOrError;
+    const localFileHint = buildLocalMigrationFileHint(version, args.migrationName);
     const migration = {
         Version: version,
         Name: args.migrationName,
@@ -12551,8 +12751,16 @@ async function handleApplyMigration(args, context, deps, cloudBaseOptions) {
         const result = await callPgMigrationApi(context, "PushPGUserMigrations", params, cloudBaseOptions);
         return buildPgToolResult({
             success: true,
-            data: result,
-            message: "Migrations applied via PushPGUserMigrations.",
+            data: {
+                migrationVersion: version,
+                migrationName: args.migrationName,
+                localFileHint,
+                apiResult: result,
+            },
+            message: `Migrations applied via PushPGUserMigrations. Ensure local file ${localFileHint} exists and matches.`,
+            nextActions: [
+                buildNextAction(MANAGE_PG_DATABASE, "listMigrations", "Verify the remote migration history records the same migrationVersion.", { action: "listMigrations", limit: 20 }),
+            ],
         });
     }
     catch (error) {
@@ -12827,11 +13035,11 @@ function registerPGDatabaseTools(server, providedDeps) {
     });
     server.registerTool?.(MANAGE_PG_DATABASE, {
         title: "管理 PostgreSQL 上下文或执行写入 SQL",
-        description: "管理 CloudBase PostgreSQL：执行已确认的写入 SQL 或 DDL、SQL 风险预检、迁移管理。建表、改 schema、数据结构变更优先使用 applyMigration（带版本管理与回滚），而非 execute。",
+        description: "管理 CloudBase PostgreSQL：执行已确认的写入 SQL、SQL 风险预检、迁移管理。建表/ALTER/DROP 等 schema 变更必须使用 applyMigration（显式 migrationVersion + 本地 migrations/ 留档），不要默认用 execute。execute 主要用于 DML 与 GRANT/RLS 等运维 SQL。",
         inputSchema: {
             action: zod_1.z
                 .enum(MANAGE_ACTIONS)
-                .describe("操作类型：execute=执行已确认的写入 SQL 或 DDL；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + sql）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + sql + confirm=true）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
+                .describe("操作类型：execute=执行已确认的写入 SQL（DML/GRANT/RLS；schema DDL 默认拒绝，需 allowDdlViaExecute=true）；dryRun=只分析 SQL 风险不执行；planMigration=预览迁移计划（需 migrationName + migrationVersion + sql）；applyMigration=应用迁移，建表/改 schema 首选（需 migrationName + migrationVersion + sql + confirm=true）；listMigrations=查询已应用的 Migration 列表（可传 limit/offset 分页）；migrationDetail=查看单条 Migration 详情（需 migrationVersion）；rollbackMigration=回滚最近 N 条 Migration（需 lastN + confirm=true）；repairMigration=修复 Migration 历史记录（需 migrationVersion + migrationName + repairStatus + repairReason）"),
             sql: zod_1.z
                 .string()
                 .optional()
@@ -12869,7 +13077,7 @@ function registerPGDatabaseTools(server, providedDeps) {
                 .string()
                 .regex(/^\d{14}$/)
                 .optional()
-                .describe("14 位时间戳 YYYYMMDDHHMMSS。detail/repair 必填；plan/apply 不传时自动生成。"),
+                .describe("14 位时间戳 YYYYMMDDHHMMSS。plan/apply/detail/repair 必填；禁止由服务端静默生成，避免与本地 migrations/<version>_<name>.sql 分叉。"),
             rollbackSql: zod_1.z
                 .string()
                 .optional()
@@ -12911,6 +13119,10 @@ function registerPGDatabaseTools(server, providedDeps) {
                 .string()
                 .optional()
                 .describe("repair 必填：修复原因。"),
+            allowDdlViaExecute: zod_1.z
+                .boolean()
+                .optional()
+                .describe("可选，默认 false。仅当需要故意绕过 migration history 时设为 true，才允许 schema DDL 走 execute；正常建表/改 schema 必须用 applyMigration。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -12924,6 +13136,14 @@ function registerPGDatabaseTools(server, providedDeps) {
         const cbOpts = server.cloudBaseOptions;
         switch (args.action) {
             case "execute": {
+                // Soft-block schema DDL before readiness probe so agents get migration guidance immediately.
+                if (args.sql?.trim()) {
+                    const classification = classifySqlRisk(args.sql);
+                    if (isSchemaDdlRisk(classification.risk, args.sql) &&
+                        args.allowDdlViaExecute !== true) {
+                        return handleExecuteSql(args, context, deps);
+                    }
+                }
                 try {
                     await ensurePgReadyOnce(cbOpts, deps);
                 }
@@ -14055,7 +14275,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.23.11" : 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.24.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/cloudbase-mcp",
-  "version": "2.23.11",
+  "version": "2.24.1",
   "packageManager": "pnpm@10.8.0",
   "description": "腾讯云开发 MCP Server，通过AI提示词和MCP协议+云开发，让开发更智能、更高效,当你在Cursor/ VSCode GitHub Copilot/WinSurf/CodeBuddy/Augment Code/Claude Code等AI编程工具里写代码时，它能自动帮你生成可直接部署的前后端应用+小程序，并一键发布到腾讯云开发 CloudBase。",
   "main": "./dist/index.cjs",
@@ -100,6 +100,12 @@
     "webpack-obfuscator": "^3.6.0"
   },
   "overrides": {
-    "tough-cookie": "^4.1.3"
+    "tough-cookie": "^4.1.3",
+    "js-yaml": "4.3.0",
+    "brace-expansion@1": "1.1.16",
+    "brace-expansion@2": "2.1.2",
+    "brace-expansion@3": "5.0.7",
+    "brace-expansion@4": "5.0.7",
+    "brace-expansion@5": "5.0.7"
   }
 }