@cloudbase/cloudbase-mcp 2.23.11 → 2.24.0

package/dist/index.cjs

@@ -136879,7 +136879,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.0" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -160486,6 +160486,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, '""')}"`;
 }
@@ -160850,12 +160882,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)({
@@ -161098,6 +161124,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,
@@ -161107,7 +161161,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 }),
             ],
         });
@@ -161124,8 +161183,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.", {
@@ -161153,6 +161219,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: {
@@ -161160,15 +161263,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 }),
         ],
     });
 }
@@ -161187,7 +161284,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,
@@ -161202,10 +161304,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 } : {}),
+                }),
             ],
         });
     }
@@ -161239,7 +161353,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,
@@ -161259,8 +161378,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) {
@@ -161535,11 +161662,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()
@@ -161577,7 +161704,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()
@@ -161619,6 +161746,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,
@@ -161632,6 +161763,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);
                 }
@@ -196778,7 +196917,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.0" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -196859,7 +196998,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.0" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -212872,7 +213011,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.0" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])