@cloudbase/cloudbase-mcp 2.16.1-beta.1 → 2.16.1

package/dist/index.cjs

@@ -39846,17 +39846,34 @@ async function handleRunQuery(args, context) {
     }
     const cloudbase = await context.getManager();
     const dbContext = await resolveSqlDbContext(context.getManager, context.cloudBaseOptions, args.dbInstance);
-    const result = await callSqlControlPlane(cloudbase, "RunSql", {
-        EnvId: dbContext.envId,
-        Sql: args.sql,
-        ReadOnly: true,
-        DbInstance: {
+    let result;
+    try {
+        result = await callSqlControlPlane(cloudbase, "RunSql", {
             EnvId: dbContext.envId,
-            InstanceId: dbContext.instanceId,
-            Schema: dbContext.schema,
-        },
-    });
-    (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            Sql: args.sql,
+            ReadOnly: true,
+            DbInstance: {
+                EnvId: dbContext.envId,
+                InstanceId: dbContext.instanceId,
+                Schema: dbContext.schema,
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+    }
+    catch (error) {
+        const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+        if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+            return buildSqlToolResult({
+                success: false,
+                errorCode: "MYSQL_NOT_CREATED",
+                message: "MySQL is not provisioned yet or not found. Please provision MySQL before running queries.",
+                nextActions: [
+                    buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before querying data.", { action: "provisionMySQL", confirm: true }),
+                ],
+            });
+        }
+        throw error;
+    }
     const normalized = normalizeRunSqlResult(result);
     return buildSqlToolResult({
         success: true,
@@ -40107,16 +40124,33 @@ async function handleRunStatement(args, context) {
     }
     const cloudbase = await context.getManager();
     const dbContext = await resolveSqlDbContext(context.getManager, context.cloudBaseOptions, args.dbInstance);
-    const result = await callSqlControlPlane(cloudbase, "RunSql", {
-        EnvId: dbContext.envId,
-        Sql: args.sql,
-        DbInstance: {
+    let result;
+    try {
+        result = await callSqlControlPlane(cloudbase, "RunSql", {
             EnvId: dbContext.envId,
-            InstanceId: dbContext.instanceId,
-            Schema: dbContext.schema,
-        },
-    });
-    (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            Sql: args.sql,
+            DbInstance: {
+                EnvId: dbContext.envId,
+                InstanceId: dbContext.instanceId,
+                Schema: dbContext.schema,
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+    }
+    catch (error) {
+        const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+        if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+            return buildSqlToolResult({
+                success: false,
+                errorCode: "MYSQL_NOT_CREATED",
+                message: "MySQL is not provisioned yet or not found. Please provision MySQL before running statements.",
+                nextActions: [
+                    buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before executing statements.", { action: "provisionMySQL", confirm: true }),
+                ],
+            });
+        }
+        throw error;
+    }
     const statementType = getSqlVerb(args.sql) || "UNKNOWN";
     const normalized = normalizeRunSqlResult(result);
     return buildSqlToolResult({
@@ -40216,16 +40250,33 @@ async function handleInitializeSchema(args, context) {
     const requestIdList = [];
     for (const statement of args.statements) {
         try {
-            const result = await callSqlControlPlane(cloudbase, "RunSql", {
-                EnvId: dbContext.envId,
-                Sql: statement,
-                DbInstance: {
+            let result;
+            try {
+                result = await callSqlControlPlane(cloudbase, "RunSql", {
                     EnvId: dbContext.envId,
-                    InstanceId: dbContext.instanceId,
-                    Schema: dbContext.schema,
-                },
-            });
-            (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+                    Sql: statement,
+                    DbInstance: {
+                        EnvId: dbContext.envId,
+                        InstanceId: dbContext.instanceId,
+                        Schema: dbContext.schema,
+                    },
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            }
+            catch (error) {
+                const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+                if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+                    return buildSqlToolResult({
+                        success: false,
+                        errorCode: "MYSQL_NOT_CREATED",
+                        message: "MySQL is not provisioned yet or not found. Please provision MySQL before initializing schema.",
+                        nextActions: [
+                            buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before executing statements.", { action: "provisionMySQL", confirm: true }),
+                        ],
+                    });
+                }
+                throw error;
+            }
             const normalized = normalizeRunSqlResult(result);
             if (typeof normalized.requestId === "string") {
                 requestIdList.push(normalized.requestId);
@@ -132946,7 +132997,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.16.1-beta.1" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.16.1" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -190997,7 +191048,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.16.1-beta.1" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.16.1" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -199112,7 +199163,7 @@ function registerDatabaseTools(server) {
     // readNoSqlDatabaseStructure
     server.registerTool?.("readNoSqlDatabaseStructure", {
         title: "读取 NoSQL 数据库结构",
-        description: "读取 NoSQL 数据库结构",
+        description: "读取 NoSQL 数据库集合与索引结构，支持列出集合、查看集合详情、列出索引以及检查索引是否存在。",
         inputSchema: {
             action: zod_1.z.enum([
                 "listCollections",
@@ -199121,10 +199172,10 @@ function registerDatabaseTools(server) {
                 "listIndexes",
                 "checkIndex",
             ]).describe(`listCollections: 列出集合列表
-describeCollection: 描述集合
+describeCollection: 描述集合详情（会返回索引摘要）
 checkCollection: 检查集合是否存在
-listIndexes: 列出索引列表
-checkIndex: 检查索引是否存在`),
+listIndexes: 列出指定集合的索引列表
+checkIndex: 检查指定索引是否存在`),
             limit: zod_1.z
                 .number()
                 .optional()
@@ -199260,38 +199311,42 @@ checkIndex: 检查索引是否存在`),
     // writeNoSqlDatabaseStructure
     server.registerTool?.("writeNoSqlDatabaseStructure", {
         title: "修改 NoSQL 数据库结构",
-        description: "修改 NoSQL 数据库结构",
+        description: "修改 NoSQL 数据库结构，支持创建/删除集合，以及通过 updateCollection 的 updateOptions.CreateIndexes / updateOptions.DropIndexes 添加索引和删除索引。",
         inputSchema: {
             action: zod_1.z.enum([
                 "createCollection",
                 "updateCollection",
                 "deleteCollection",
             ]).describe(`createCollection: 创建集合
-updateCollection: 更新集合
+updateCollection: 更新集合配置；添加索引请传 updateOptions.CreateIndexes，删除索引请传 updateOptions.DropIndexes
 deleteCollection: 删除集合`),
             collectionName: zod_1.z.string().describe("集合名称"),
             updateOptions: zod_1.z
                 .object({
                 CreateIndexes: zod_1.z
                     .array(zod_1.z.object({
-                    IndexName: zod_1.z.string(),
+                    IndexName: zod_1.z.string().describe("要创建的索引名称"),
                     MgoKeySchema: zod_1.z.object({
-                        MgoIsUnique: zod_1.z.boolean(),
+                        MgoIsUnique: zod_1.z.boolean().describe("是否唯一索引"),
                         MgoIndexKeys: zod_1.z.array(zod_1.z.object({
-                            Name: zod_1.z.string(),
-                            Direction: zod_1.z.string(),
-                        })),
-                    }),
+                            Name: zod_1.z.string().describe("索引字段名"),
+                            Direction: zod_1.z
+                                .string()
+                                .describe("索引方向，通常 1 表示升序，-1 表示降序"),
+                        })).describe("索引字段列表，支持单字段或复合索引"),
+                    }).describe("待创建索引的字段与约束配置"),
                 }))
-                    .optional(),
+                    .optional()
+                    .describe("要添加的索引列表"),
                 DropIndexes: zod_1.z
                     .array(zod_1.z.object({
-                    IndexName: zod_1.z.string(),
+                    IndexName: zod_1.z.string().describe("要删除的索引名称"),
                 }))
-                    .optional(),
+                    .optional()
+                    .describe("要删除的索引列表"),
             })
                 .optional()
-                .describe("更新选项(updateCollection 时使用)"),
+                .describe("更新选项(updateCollection 时使用)。CreateIndexes 用于添加索引，DropIndexes 用于删除索引。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -205156,7 +205211,7 @@ function registerSetupTools(server) {
         title: "下载项目模板",
         description: `自动下载并部署CloudBase项目模板。⚠️ **MANDATORY FOR NEW PROJECTS** ⚠️
 
-**CRITICAL**: This tool MUST be called FIRST when starting a new project.\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.16.1-beta.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**CRITICAL**: This tool MUST be called FIRST when starting a new project.\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.16.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -222298,12 +222353,25 @@ function registerGatewayTools(server) {
                 }
                 const cloudbase = await getManager();
                 const accessPath = normalizeAccessPath(input.path || `/${input.targetName}`);
-                const result = await cloudbase.access.createAccess({
-                    name: input.targetName,
-                    path: accessPath,
-                    type: ((input.type || "Event") === "HTTP" ? 6 : 1),
-                    auth: input.auth,
-                });
+                let result;
+                try {
+                    result = await cloudbase.access.createAccess({
+                        name: input.targetName,
+                        path: accessPath,
+                        type: ((input.type || "Event") === "HTTP" ? 6 : 1),
+                        auth: input.auth,
+                    });
+                }
+                catch (err) {
+                    if (err.message && err.message.includes("An error has occurred")) {
+                        let hint = "为目标资源配置访问路由失败（后端内部错误）。请确保：1) 目标云函数已成功创建并处于 Active 状态；2) 环境默认 HTTP 域名已完成初始化；3) 该访问路径未被占用。";
+                        if (input.type === "HTTP") {
+                            hint += "此外注意：如果目标函数最初是作为 Event 函数创建的，这里 type 必须依然传 Event（或省略），传 HTTP 会导致此错误。";
+                        }
+                        throw new Error(`${hint} 原始错误：${err.message}`);
+                    }
+                    throw err;
+                }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 return buildEnvelope({
                     action: input.action,
@@ -222479,7 +222547,7 @@ function registerGatewayTools(server) {
                 .describe("目标资源类型。当前支持 function，后续可扩展"),
             targetName: zod_1.z.string().optional().describe("目标资源名称"),
             path: zod_1.z.string().optional().describe("访问路径，默认 /{targetName}"),
-            type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("函数接入类型"),
+            type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("目标函数的本身类型（非接入形式）。如果被访问的函数是 Event 型（默认），此处必须传 Event；只有当被访问函数在创建时就是 HTTP 函数时才传 HTTP。"),
             auth: zod_1.z.boolean().optional().describe("是否开启鉴权"),
             route: zod_1.z
                 .object({

package/dist/index.js

@@ -1509,7 +1509,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.16.1-beta.1" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.16.1" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -3692,7 +3692,7 @@ function registerDatabaseTools(server) {
     // readNoSqlDatabaseStructure
     server.registerTool?.("readNoSqlDatabaseStructure", {
         title: "读取 NoSQL 数据库结构",
-        description: "读取 NoSQL 数据库结构",
+        description: "读取 NoSQL 数据库集合与索引结构，支持列出集合、查看集合详情、列出索引以及检查索引是否存在。",
         inputSchema: {
             action: zod_1.z.enum([
                 "listCollections",
@@ -3701,10 +3701,10 @@ function registerDatabaseTools(server) {
                 "listIndexes",
                 "checkIndex",
             ]).describe(`listCollections: 列出集合列表
-describeCollection: 描述集合
+describeCollection: 描述集合详情（会返回索引摘要）
 checkCollection: 检查集合是否存在
-listIndexes: 列出索引列表
-checkIndex: 检查索引是否存在`),
+listIndexes: 列出指定集合的索引列表
+checkIndex: 检查指定索引是否存在`),
             limit: zod_1.z
                 .number()
                 .optional()
@@ -3840,38 +3840,42 @@ checkIndex: 检查索引是否存在`),
     // writeNoSqlDatabaseStructure
     server.registerTool?.("writeNoSqlDatabaseStructure", {
         title: "修改 NoSQL 数据库结构",
-        description: "修改 NoSQL 数据库结构",
+        description: "修改 NoSQL 数据库结构，支持创建/删除集合，以及通过 updateCollection 的 updateOptions.CreateIndexes / updateOptions.DropIndexes 添加索引和删除索引。",
         inputSchema: {
             action: zod_1.z.enum([
                 "createCollection",
                 "updateCollection",
                 "deleteCollection",
             ]).describe(`createCollection: 创建集合
-updateCollection: 更新集合
+updateCollection: 更新集合配置；添加索引请传 updateOptions.CreateIndexes，删除索引请传 updateOptions.DropIndexes
 deleteCollection: 删除集合`),
             collectionName: zod_1.z.string().describe("集合名称"),
             updateOptions: zod_1.z
                 .object({
                 CreateIndexes: zod_1.z
                     .array(zod_1.z.object({
-                    IndexName: zod_1.z.string(),
+                    IndexName: zod_1.z.string().describe("要创建的索引名称"),
                     MgoKeySchema: zod_1.z.object({
-                        MgoIsUnique: zod_1.z.boolean(),
+                        MgoIsUnique: zod_1.z.boolean().describe("是否唯一索引"),
                         MgoIndexKeys: zod_1.z.array(zod_1.z.object({
-                            Name: zod_1.z.string(),
-                            Direction: zod_1.z.string(),
-                        })),
-                    }),
+                            Name: zod_1.z.string().describe("索引字段名"),
+                            Direction: zod_1.z
+                                .string()
+                                .describe("索引方向，通常 1 表示升序，-1 表示降序"),
+                        })).describe("索引字段列表，支持单字段或复合索引"),
+                    }).describe("待创建索引的字段与约束配置"),
                 }))
-                    .optional(),
+                    .optional()
+                    .describe("要添加的索引列表"),
                 DropIndexes: zod_1.z
                     .array(zod_1.z.object({
-                    IndexName: zod_1.z.string(),
+                    IndexName: zod_1.z.string().describe("要删除的索引名称"),
                 }))
-                    .optional(),
+                    .optional()
+                    .describe("要删除的索引列表"),
             })
                 .optional()
-                .describe("更新选项(updateCollection 时使用)"),
+                .describe("更新选项(updateCollection 时使用)。CreateIndexes 用于添加索引，DropIndexes 用于删除索引。"),
         },
         annotations: {
             readOnlyHint: false,
@@ -6106,12 +6110,25 @@ function registerGatewayTools(server) {
                 }
                 const cloudbase = await getManager();
                 const accessPath = normalizeAccessPath(input.path || `/${input.targetName}`);
-                const result = await cloudbase.access.createAccess({
-                    name: input.targetName,
-                    path: accessPath,
-                    type: ((input.type || "Event") === "HTTP" ? 6 : 1),
-                    auth: input.auth,
-                });
+                let result;
+                try {
+                    result = await cloudbase.access.createAccess({
+                        name: input.targetName,
+                        path: accessPath,
+                        type: ((input.type || "Event") === "HTTP" ? 6 : 1),
+                        auth: input.auth,
+                    });
+                }
+                catch (err) {
+                    if (err.message && err.message.includes("An error has occurred")) {
+                        let hint = "为目标资源配置访问路由失败（后端内部错误）。请确保：1) 目标云函数已成功创建并处于 Active 状态；2) 环境默认 HTTP 域名已完成初始化；3) 该访问路径未被占用。";
+                        if (input.type === "HTTP") {
+                            hint += "此外注意：如果目标函数最初是作为 Event 函数创建的，这里 type 必须依然传 Event（或省略），传 HTTP 会导致此错误。";
+                        }
+                        throw new Error(`${hint} 原始错误：${err.message}`);
+                    }
+                    throw err;
+                }
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 return buildEnvelope({
                     action: input.action,
@@ -6287,7 +6304,7 @@ function registerGatewayTools(server) {
                 .describe("目标资源类型。当前支持 function，后续可扩展"),
             targetName: zod_1.z.string().optional().describe("目标资源名称"),
             path: zod_1.z.string().optional().describe("访问路径，默认 /{targetName}"),
-            type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("函数接入类型"),
+            type: zod_1.z.enum(["Event", "HTTP"]).optional().describe("目标函数的本身类型（非接入形式）。如果被访问的函数是 Event 型（默认），此处必须传 Event；只有当被访问函数在创建时就是 HTTP 函数时才传 HTTP。"),
             auth: zod_1.z.boolean().optional().describe("是否开启鉴权"),
             route: zod_1.z
                 .object({
@@ -7866,7 +7883,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.16.1-beta.1" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.16.1" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -10062,7 +10079,7 @@ function registerSetupTools(server) {
         title: "下载项目模板",
         description: `自动下载并部署CloudBase项目模板。⚠️ **MANDATORY FOR NEW PROJECTS** ⚠️
 
-**CRITICAL**: This tool MUST be called FIRST when starting a new project.\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.16.1-beta.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
+**CRITICAL**: This tool MUST be called FIRST when starting a new project.\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.16.1" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -12969,17 +12986,34 @@ async function handleRunQuery(args, context) {
     }
     const cloudbase = await context.getManager();
     const dbContext = await resolveSqlDbContext(context.getManager, context.cloudBaseOptions, args.dbInstance);
-    const result = await callSqlControlPlane(cloudbase, "RunSql", {
-        EnvId: dbContext.envId,
-        Sql: args.sql,
-        ReadOnly: true,
-        DbInstance: {
+    let result;
+    try {
+        result = await callSqlControlPlane(cloudbase, "RunSql", {
             EnvId: dbContext.envId,
-            InstanceId: dbContext.instanceId,
-            Schema: dbContext.schema,
-        },
-    });
-    (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            Sql: args.sql,
+            ReadOnly: true,
+            DbInstance: {
+                EnvId: dbContext.envId,
+                InstanceId: dbContext.instanceId,
+                Schema: dbContext.schema,
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+    }
+    catch (error) {
+        const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+        if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+            return buildSqlToolResult({
+                success: false,
+                errorCode: "MYSQL_NOT_CREATED",
+                message: "MySQL is not provisioned yet or not found. Please provision MySQL before running queries.",
+                nextActions: [
+                    buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before querying data.", { action: "provisionMySQL", confirm: true }),
+                ],
+            });
+        }
+        throw error;
+    }
     const normalized = normalizeRunSqlResult(result);
     return buildSqlToolResult({
         success: true,
@@ -13230,16 +13264,33 @@ async function handleRunStatement(args, context) {
     }
     const cloudbase = await context.getManager();
     const dbContext = await resolveSqlDbContext(context.getManager, context.cloudBaseOptions, args.dbInstance);
-    const result = await callSqlControlPlane(cloudbase, "RunSql", {
-        EnvId: dbContext.envId,
-        Sql: args.sql,
-        DbInstance: {
+    let result;
+    try {
+        result = await callSqlControlPlane(cloudbase, "RunSql", {
             EnvId: dbContext.envId,
-            InstanceId: dbContext.instanceId,
-            Schema: dbContext.schema,
-        },
-    });
-    (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            Sql: args.sql,
+            DbInstance: {
+                EnvId: dbContext.envId,
+                InstanceId: dbContext.instanceId,
+                Schema: dbContext.schema,
+            },
+        });
+        (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+    }
+    catch (error) {
+        const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+        if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+            return buildSqlToolResult({
+                success: false,
+                errorCode: "MYSQL_NOT_CREATED",
+                message: "MySQL is not provisioned yet or not found. Please provision MySQL before running statements.",
+                nextActions: [
+                    buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before executing statements.", { action: "provisionMySQL", confirm: true }),
+                ],
+            });
+        }
+        throw error;
+    }
     const statementType = getSqlVerb(args.sql) || "UNKNOWN";
     const normalized = normalizeRunSqlResult(result);
     return buildSqlToolResult({
@@ -13339,16 +13390,33 @@ async function handleInitializeSchema(args, context) {
     const requestIdList = [];
     for (const statement of args.statements) {
         try {
-            const result = await callSqlControlPlane(cloudbase, "RunSql", {
-                EnvId: dbContext.envId,
-                Sql: statement,
-                DbInstance: {
+            let result;
+            try {
+                result = await callSqlControlPlane(cloudbase, "RunSql", {
                     EnvId: dbContext.envId,
-                    InstanceId: dbContext.instanceId,
-                    Schema: dbContext.schema,
-                },
-            });
-            (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+                    Sql: statement,
+                    DbInstance: {
+                        EnvId: dbContext.envId,
+                        InstanceId: dbContext.instanceId,
+                        Schema: dbContext.schema,
+                    },
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(context.server.logger, result);
+            }
+            catch (error) {
+                const errorCode = typeof error === "object" && error && "code" in error ? error.code : "";
+                if (errorCode === "FailedOperation.DataSourceNotExist" || error.message?.includes("Database instance not found")) {
+                    return buildSqlToolResult({
+                        success: false,
+                        errorCode: "MYSQL_NOT_CREATED",
+                        message: "MySQL is not provisioned yet or not found. Please provision MySQL before initializing schema.",
+                        nextActions: [
+                            buildNextAction(MANAGE_SQL_DATABASE, "provisionMySQL", "Provision MySQL before executing statements.", { action: "provisionMySQL", confirm: true }),
+                        ],
+                    });
+                }
+                throw error;
+            }
             const normalized = normalizeRunSqlResult(result);
             if (typeof normalized.requestId === "string") {
                 requestIdList.push(normalized.requestId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/cloudbase-mcp",
-  "version": "2.16.1-beta.1",
+  "version": "2.16.1",
   "description": "腾讯云开发 MCP Server，通过AI提示词和MCP协议+云开发，让开发更智能、更高效,当你在Cursor/ VSCode GitHub Copilot/WinSurf/CodeBuddy/Augment Code/Claude Code等AI编程工具里写代码时，它能自动帮你生成可直接部署的前后端应用+小程序，并一键发布到腾讯云开发 CloudBase。",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",