@cloudbase/cloudbase-mcp 2.19.5 → 2.20.0

package/dist/index.d.ts

@@ -1,5 +1,4 @@
 import CloudBase from '@cloudbase/manager-node';
-import { Credential as Credential_2 } from '@cloudbase/toolbox';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
@@ -176,12 +175,7 @@ export declare interface GetFileInfoParams {
  */
 export declare function getInteractiveServerAsync(): Promise<InteractiveServer>;
 
-export declare function getLoginState(options?: EnsureLoginOptions): Promise<{
-    secretId: string;
-    secretKey: string;
-    token: string | undefined;
-    envId: string | undefined;
-} | Credential_2>;
+export declare function getLoginState(options?: EnsureLoginOptions): Promise<LoginState | null>;
 
 declare interface GetManagerOptions {
     requireEnvId?: boolean;
@@ -271,6 +265,13 @@ declare type Logger = (data: {
     [key: string]: any;
 }) => void;
 
+declare interface LoginState {
+    secretId: string;
+    secretKey: string;
+    token?: string;
+    envId?: string;
+}
+
 export declare function logout(): Promise<void>;
 
 export { McpServer }

package/dist/index.js

@@ -727,6 +727,8 @@ function registerEnvTools(server) {
             if (action === "status") {
                 const loginState = await (0, auth_js_1.peekLoginState)();
                 const authFlowState = await (0, auth_js_1.getAuthProgressState)();
+                // 判断是否为 API Key 模式
+                const isApiKeyMode = !!(process.env.CLOUDBASE_API_KEY && process.env.CLOUDBASE_ENV_ID);
                 const authStatus = loginState
                     ? "READY"
                     : authFlowState.status === "PENDING"
@@ -751,6 +753,7 @@ function registerEnvTools(server) {
                     ok: true,
                     code: "STATUS",
                     auth_status: authStatus,
+                    ...(isApiKeyMode ? { auth_mode: "api_key" } : {}),
                     auth_config: authConfigSummary,
                     ...(envPreparation
                         ? buildAuthEnvSetupPayload(envPreparation)
@@ -773,6 +776,46 @@ function registerEnvTools(server) {
                 });
             }
             if (action === "start_auth") {
+                // API Key 模式：尝试换取临时密钥
+                if (process.env.CLOUDBASE_API_KEY && process.env.CLOUDBASE_ENV_ID) {
+                    try {
+                        const existingLoginState = await (0, auth_js_1.peekLoginState)();
+                        if (existingLoginState) {
+                            return (0, tool_result_js_1.buildJsonToolResult)({
+                                ok: true,
+                                code: "AUTH_READY",
+                                message: "当前使用 API Key 认证模式，已自动完成登录，无需手动授权。",
+                                auth_mode: "api_key",
+                                envId: process.env.CLOUDBASE_ENV_ID,
+                            });
+                        }
+                    }
+                    catch (e) {
+                        // peekLoginState 内部异常，记录后 fall through
+                        (0, logger_js_1.debug)("start_auth: peekLoginState threw", { error: e instanceof Error ? e.message : String(e) });
+                    }
+                    // API Key 换取失败：返回详细诊断信息
+                    // 尝试获取更详细的错误信息
+                    let diagMessage = "当前配置了 API Key 认证模式，但换取临时密钥失败。";
+                    const endpoint = process.env.CLOUDBASE_API_ENDPOINT || `https://${process.env.CLOUDBASE_ENV_ID}.ap-shanghai.tcb-api.tencentcloudapi.com`;
+                    diagMessage += `\n\n诊断信息：`;
+                    diagMessage += `\n- CLOUDBASE_ENV_ID: ${process.env.CLOUDBASE_ENV_ID}`;
+                    diagMessage += `\n- CLOUDBASE_API_KEY: ${process.env.CLOUDBASE_API_KEY.slice(0, 20)}...（已截断）`;
+                    diagMessage += `\n- Endpoint: ${endpoint}`;
+                    diagMessage += `\n\n可能原因：`;
+                    diagMessage += `\n1. API Key 已过期或被删除`;
+                    diagMessage += `\n2. Endpoint 不可达（网络/DNS 问题）`;
+                    diagMessage += `\n3. CLOUDBASE_ENV_ID 与 API Key 所属环境不匹配`;
+                    diagMessage += `\n\n建议：检查 MCP 配置中的 CLOUDBASE_API_KEY 和 CLOUDBASE_ENV_ID 环境变量是否正确。`;
+                    return (0, tool_result_js_1.buildJsonToolResult)({
+                        ok: false,
+                        code: "API_KEY_AUTH_FAILED",
+                        message: diagMessage,
+                        auth_mode: "api_key",
+                        envId: process.env.CLOUDBASE_ENV_ID,
+                        endpoint,
+                    });
+                }
                 const region = server.cloudBaseOptions?.region || process.env.TCB_REGION;
                 const auth = toolbox_1.AuthSupervisor.getInstance({});
                 const authFlowState = await (0, auth_js_1.getAuthProgressState)();
@@ -977,6 +1020,15 @@ function registerEnvTools(server) {
                 });
             }
             if (action === "logout") {
+                // API Key 模式下不允许 logout
+                if (process.env.CLOUDBASE_API_KEY && process.env.CLOUDBASE_ENV_ID) {
+                    return (0, tool_result_js_1.buildJsonToolResult)({
+                        ok: false,
+                        code: "LOGOUT_NOT_ALLOWED",
+                        message: "当前使用 API Key 认证模式，不支持退出登录。如需切换认证方式，请移除 CLOUDBASE_API_KEY 环境变量后重启。",
+                        auth_mode: "api_key",
+                    });
+                }
                 if (confirm !== "yes") {
                     return (0, tool_result_js_1.buildJsonToolResult)({
                         ok: false,
@@ -1103,29 +1155,58 @@ function registerEnvTools(server) {
                             requireEnvId: true,
                             mcpServer: server, // Pass server for IDE detection
                         });
-                        // Use commonService to call DescribeEnvs with filter parameters
-                        // Filter parameters match the reference conditions provided by user
-                        result = await cloudbaseList.commonService("tcb", "2018-06-08").call({
-                            Action: "DescribeEnvs",
-                            Param: {
-                                EnvTypes: ["weda", "baas"], // Include weda and baas (normal) environments
-                                IsVisible: false, // Filter out invisible environments
-                                Channels: ["dcloud", "iotenable", "tem", "scene_module"], // Filter special channels
-                            },
-                        });
-                        (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-                        // Transform response format to match original listEnvs() format
-                        if (result && result.EnvList) {
-                            result = { EnvList: result.EnvList };
-                        }
-                        else if (result && result.Data && result.Data.EnvList) {
-                            result = { EnvList: result.Data.EnvList };
+                        // 当环境变量设置了 CLOUDBASE_ENV_ID 时（如 API Key 模式），
+                        // 避免调用 DescribeEnvs（临时密钥可能不支持该接口），
+                        // 改为通过 DescribeEnvInfo 获取单环境信息
+                        const envIdFromEnv = process.env.CLOUDBASE_ENV_ID;
+                        if (envIdFromEnv) {
+                            try {
+                                const envInfo = await cloudbaseList.env.describeEnvInfo({ EnvId: envIdFromEnv });
+                                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, envInfo);
+                                // DescribeEnvInfo 返回结构: { EnvInfo: { EnvBaseInfo: { EnvId, Alias, ... }, BillingInfo, ... } }
+                                // 需要提取 EnvBaseInfo 作为扁平 env 对象以匹配 DescribeEnvs 返回格式
+                                const baseInfo = envInfo?.EnvInfo?.EnvBaseInfo;
+                                if (baseInfo) {
+                                    result = { EnvList: [baseInfo] };
+                                }
+                                else if (envInfo?.EnvInfo) {
+                                    // 兼容: 如果没有 EnvBaseInfo 但有 EnvInfo，尝试直接使用
+                                    result = { EnvList: [{ EnvId: envIdFromEnv, ...envInfo.EnvInfo }] };
+                                }
+                                else {
+                                    result = { EnvList: [{ EnvId: envIdFromEnv }] };
+                                }
+                            }
+                            catch (envInfoError) {
+                                (0, logger_js_1.debug)("DescribeEnvInfo 失败，返回基础环境信息:", envInfoError instanceof Error ? envInfoError : new Error(String(envInfoError)));
+                                result = { EnvList: [{ EnvId: envIdFromEnv }] };
+                            }
                         }
                         else {
-                            // Fallback to original method if format is unexpected
-                            (0, logger_js_1.debug)("Unexpected response format, falling back to listEnvs()");
-                            result = await cloudbaseList.env.listEnvs();
+                            // Use commonService to call DescribeEnvs with filter parameters
+                            // Filter parameters match the reference conditions provided by user
+                            result = await cloudbaseList.commonService("tcb", "2018-06-08").call({
+                                Action: "DescribeEnvs",
+                                Param: {
+                                    EnvTypes: ["weda", "baas"], // Include weda and baas (normal) environments
+                                    IsVisible: false, // Filter out invisible environments
+                                    Channels: ["dcloud", "iotenable", "tem", "scene_module"], // Filter special channels
+                                },
+                            });
                             (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                            // Transform response format to match original listEnvs() format
+                            if (result && result.EnvList) {
+                                result = { EnvList: result.EnvList };
+                            }
+                            else if (result && result.Data && result.Data.EnvList) {
+                                result = { EnvList: result.Data.EnvList };
+                            }
+                            else {
+                                // Fallback to original method if format is unexpected
+                                (0, logger_js_1.debug)("Unexpected response format, falling back to listEnvs()");
+                                result = await cloudbaseList.env.listEnvs();
+                                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                            }
                         }
                     }
                     catch (error) {
@@ -1622,7 +1703,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.19.5" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.20.0" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -1670,7 +1751,7 @@ function createWrappedHandler(name, handler, server) {
             success = true;
             requestId = extractRequestIdFromToolResult(result);
             const duration = Date.now() - startTime;
-            (0, logger_js_1.debug)(`工具执行成功: ${name}`, { duration });
+            (0, logger_js_1.debug)(`工具执行成功: ${name}`, { duration, requestId: requestId || undefined });
             if (!isTestEnvironment) {
                 server.logger?.({ type: 'afterToolCall', toolName: name, args: sanitizeArgs(args), result: result, duration });
             }
@@ -1682,6 +1763,7 @@ function createWrappedHandler(name, handler, server) {
             requestId = (typeof error === 'object' && error && 'requestId' in error) ? error.requestId : '';
             (0, logger_js_1.debug)(`工具执行失败: ${name}`, {
                 error: errorMessage,
+                requestId: requestId || undefined,
                 duration: Date.now() - startTime
             });
             const isTestEnvironment =  false || process.env.VITEST === "true";
@@ -1702,8 +1784,9 @@ 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.19.5" : 0;
-            const enhancedErrorMessage = `${errorMessage}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
+            const mcpVersion =  true ? "2.20.0" : 0;
+            const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
+            const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
             const enhancedError = error instanceof Error
                 ? new Error(enhancedErrorMessage)
@@ -3325,11 +3408,20 @@ function createManagerFromLoginState(loginState, region) {
 }
 async function listAvailableEnvCandidates(options) {
     const { cloudBaseOptions, loginState: providedLoginState } = options ?? {};
+    // 优先使用显式传入的 envId
     if (cloudBaseOptions?.envId) {
         return [{
                 envId: cloudBaseOptions.envId,
             }];
     }
+    // 当环境变量设置了 CLOUDBASE_ENV_ID 且没有显式 credentials 时，直接返回（避免调 DescribeEnvs）
+    // 有显式 credentials 时需要重新查询，因为可能是不同账号
+    const hasExplicitCredentials = !!(cloudBaseOptions?.secretId && cloudBaseOptions?.secretKey);
+    if (process.env.CLOUDBASE_ENV_ID && !hasExplicitCredentials) {
+        return [{
+                envId: process.env.CLOUDBASE_ENV_ID,
+            }];
+    }
     let cloudbase;
     if (cloudBaseOptions?.secretId && cloudBaseOptions?.secretKey) {
         cloudbase = createCloudBaseManagerWithOptions(cloudBaseOptions);
@@ -3656,6 +3748,7 @@ async function getCloudBaseManager(options = {}) {
                 await throwPendingAuthError();
             }
             throwAuthRequiredError();
+            return undefined; // unreachable, helps TypeScript narrow
         }
         const { envId: loginEnvId, secretId, secretKey, token } = loginState;
         let finalEnvId = cloudBaseOptions?.envId;
@@ -4199,7 +4292,11 @@ checkIndex: 检查指定索引是否存在`),
             ]).describe(`createCollection: 创建集合
 updateCollection: 更新集合配置；添加索引请传 updateOptions.CreateIndexes，删除索引请传 updateOptions.DropIndexes
 deleteCollection: 删除集合`),
-            collectionName: zod_1.z.string().describe("集合名称"),
+            collectionName: zod_1.z
+                .string()
+                .trim()
+                .min(1, "collectionName 不能为空")
+                .describe("集合名称"),
             updateOptions: zod_1.z
                 .object({
                 CreateIndexes: zod_1.z
@@ -4323,31 +4420,40 @@ deleteCollection: 删除集合`),
             };
         }
         if (action === "deleteCollection") {
-            const result = await cloudbase.commonService("tcb", "2018-06-08").call({
-                Action: "DeleteTable",
-                Param: {
-                    EnvId: await (0, cloudbase_manager_js_1.getEnvId)(server.cloudBaseOptions),
-                    TableName: collectionName,
-                },
-            });
-            (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-            const body = withCollectionName(collectionName, {
-                success: true,
-                requestId: result.RequestId,
-                action,
-                message: result.Exists === false ? "集合不存在" : "云开发数据库集合删除成功",
-            });
-            if (result.Exists === false) {
-                body.exists = false;
-            }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify(body, null, 2),
+            try {
+                const result = await cloudbase.commonService("tcb", "2018-06-08").call({
+                    Action: "DeleteTable",
+                    Param: {
+                        EnvId: await (0, cloudbase_manager_js_1.getEnvId)(server.cloudBaseOptions),
+                        TableName: collectionName,
                     },
-                ],
-            };
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const body = withCollectionName(collectionName, {
+                    success: true,
+                    requestId: result.RequestId,
+                    action,
+                    message: result.Exists === false ? "集合不存在" : "云开发数据库集合删除成功",
+                });
+                if (result.Exists === false) {
+                    body.exists = false;
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(body, null, 2),
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/parameter invalid|invalid parameter|param(eter)?\s+invalid/i.test(message)) {
+                    throw new Error(`deleteCollection 参数校验失败，请确认 collectionName 合法且已存在。当前 collectionName=\"${collectionName}\"。原始错误：${message}`);
+                }
+                throw error;
+            }
         }
         throw new Error(`不支持的操作类型: ${action}`);
     });
@@ -6861,15 +6967,42 @@ function registerGatewayTools(server) {
             case "deleteAccess": {
                 const cloudbase = await getManager();
                 const accessPath = input.path ? normalizeAccessPath(input.path) : undefined;
+                let resolvedAccessId = input.accessId;
+                if (!resolvedAccessId) {
+                    if (!input.targetName && !accessPath) {
+                        throw new Error("action=deleteAccess 时至少需要提供 accessId，或提供 targetName/path 用于定位入口");
+                    }
+                    const accessList = await cloudbase.access.getAccessList({
+                        ...(input.targetName ? { name: input.targetName } : {}),
+                        ...(accessPath ? { path: accessPath } : {}),
+                    });
+                    const candidates = (accessList.APISet ?? []).filter((item) => {
+                        if (!accessPath) {
+                            return true;
+                        }
+                        return normalizeAccessPath(item.Path) === accessPath;
+                    });
+                    if (candidates.length === 0) {
+                        throw new Error("未找到可删除的访问入口，请确认 targetName/path 或直接传 accessId");
+                    }
+                    if (candidates.length > 1 && !accessPath) {
+                        throw new Error("匹配到多个访问入口，请补充 path 或直接传 accessId");
+                    }
+                    resolvedAccessId = candidates[0]?.APIId;
+                }
+                if (!resolvedAccessId) {
+                    throw new Error("无法解析访问入口 accessId，请改为显式传入 accessId");
+                }
                 const result = await cloudbase.access.deleteAccess({
                     ...(input.targetName ? { name: input.targetName } : {}),
-                    ...(accessPath ? { path: accessPath } : {}),
+                    apiId: resolvedAccessId,
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
                 return buildEnvelope({
                     action: input.action,
                     targetName: input.targetName ?? null,
                     path: accessPath ?? null,
+                    accessId: resolvedAccessId,
                     raw: result,
                 }, "网关访问入口删除成功");
             }
@@ -6971,6 +7104,7 @@ function registerGatewayTools(server) {
             domain: zod_1.z.string().optional().describe("自定义域名"),
             certificateId: zod_1.z.string().optional().describe("证书 ID"),
             accessName: zod_1.z.string().optional().describe("访问入口名称，保留字段"),
+            accessId: zod_1.z.string().optional().describe("访问入口 ID。deleteAccess 时可直接传入，避免参数歧义"),
         },
         annotations: {
             readOnlyHint: false,
@@ -9122,7 +9256,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.19.5" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.20.0" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -11023,10 +11157,11 @@ function registerPermissionTools(server) {
             roleId: zod_1.z.string().optional(),
             roleIds: zod_1.z.array(zod_1.z.string()).optional(),
             roleName: zod_1.z.string().optional(),
-            roleIdentity: zod_1.z.string().optional(),
+            roleIdentity: zod_1.z.string().optional().describe("角色标识符（字母/数字/_-:@.），action=createRole 时必填，用于程序化引用角色"),
             description: zod_1.z.string().optional(),
             memberUids: zod_1.z.array(zod_1.z.string()).optional(),
             policies: zod_1.z.array(zod_1.z.record(zod_1.z.any())).optional(),
+            policyIds: zod_1.z.array(zod_1.z.string()).optional().describe("策略 ID 列表（当前不支持直接按 ID 绑定，请改传 policies 详情对象）"),
             uid: zod_1.z.string().optional(),
             uids: zod_1.z.array(zod_1.z.string()).optional(),
             username: zod_1.z.string().optional(),
@@ -11040,7 +11175,7 @@ function registerPermissionTools(server) {
             openWorldHint: true,
             category: "permissions",
         },
-    }, async ({ action, resourceType, resourceId, permission, securityRule, roleId, roleIds, roleName, roleIdentity, description, memberUids, policies, uid, uids, username, password, userStatus, }) => withEnvelope(async () => {
+    }, async ({ action, resourceType, resourceId, permission, securityRule, roleId, roleIds, roleName, roleIdentity, description, memberUids, policies, policyIds, uid, uids, username, password, userStatus, }) => withEnvelope(async () => {
         const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
         const cloudbase = await getManager();
         const normalizedPolicies = normalizeRecordArray(policies, "policies");
@@ -11100,6 +11235,14 @@ function registerPermissionTools(server) {
                 if (!roleId) {
                     throw new Error(`action=${action} 时必须提供 roleId`);
                 }
+                if (action === "addRolePolicies" || action === "removeRolePolicies") {
+                    if (policyIds?.length) {
+                        throw new Error(`action=${action} 暂不支持 policyIds。请改传 policies，且每项至少包含 ResourceType 和 Resource。`);
+                    }
+                    if (!normalizedPolicies?.length) {
+                        throw new Error(`action=${action} 时必须提供 policies，且每项至少包含 ResourceType 和 Resource。`);
+                    }
+                }
                 const result = await cloudbase.permission.modifyRole({
                     roleId,
                     ...(action === "updateRole"
@@ -11669,7 +11812,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.19.5" : 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.20.0" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -13467,8 +13610,21 @@ function updateAuthProgressState(partial) {
     return getAuthProgressStateSync();
 }
 function normalizeLoginStateFromEnvVars(options) {
+    if (options?.ignoreEnvVars) {
+        return null;
+    }
+    // 优先检查 CloudBase API Key（优先级高于 TENCENTCLOUD_*）
+    const { CLOUDBASE_API_KEY, CLOUDBASE_ENV_ID: CLOUDBASE_ENV, } = process.env;
+    if (CLOUDBASE_API_KEY && CLOUDBASE_ENV) {
+        return {
+            _type: 'api_key',
+            apiKey: CLOUDBASE_API_KEY,
+            envId: CLOUDBASE_ENV,
+        };
+    }
+    // 然后检查腾讯云密钥环境变量
     const { TENCENTCLOUD_SECRETID, TENCENTCLOUD_SECRETKEY, TENCENTCLOUD_SESSIONTOKEN, } = process.env;
-    if (!options?.ignoreEnvVars && TENCENTCLOUD_SECRETID && TENCENTCLOUD_SECRETKEY) {
+    if (TENCENTCLOUD_SECRETID && TENCENTCLOUD_SECRETKEY) {
         return {
             secretId: TENCENTCLOUD_SECRETID,
             secretKey: TENCENTCLOUD_SECRETKEY,
@@ -13611,13 +13767,30 @@ function resetAuthProgressState() {
 async function peekLoginState(options) {
     const envVarLoginState = normalizeLoginStateFromEnvVars(options);
     if (envVarLoginState) {
+        // API Key 模式：需要先用 API Key 换取临时密钥
+        if ('_type' in envVarLoginState && envVarLoginState._type === 'api_key') {
+            (0, logger_js_1.debug)("peekLoginState: detected CLOUDBASE_API_KEY env var");
+            try {
+                // 优先使用 IDE 注入的工作目录，其次 process.cwd()
+                const projectCwd = process.env.WORKSPACE_FOLDER_PATHS || process.cwd();
+                const credential = await auth.loginByApiKey(envVarLoginState.apiKey, envVarLoginState.envId, { cwd: projectCwd });
+                return credential;
+            }
+            catch (e) {
+                (0, logger_js_1.debug)("peekLoginState: API Key login failed", { error: e instanceof Error ? e.message : String(e) });
+                return null;
+            }
+        }
+        // 腾讯云密钥模式：直接返回
         (0, logger_js_1.debug)("loginByApiSecret");
         return envVarLoginState;
     }
+    // 尝试从 toolbox 本地存储读取（包括项目级 API Key 凭证）
     return auth.getLoginState();
 }
 async function ensureLogin(options) {
     (0, logger_js_1.debug)("TENCENTCLOUD_SECRETID", { hasSecretId: !!process.env.TENCENTCLOUD_SECRETID });
+    (0, logger_js_1.debug)("CLOUDBASE_API_KEY", { hasApiKey: !!process.env.CLOUDBASE_API_KEY });
     const loginState = await peekLoginState({
         ignoreEnvVars: options?.ignoreEnvVars,
     });
@@ -13693,7 +13866,8 @@ async function getLoginState(options) {
     return ensureLogin(options);
 }
 async function logout() {
-    const result = await auth.logout();
+    const cwd = process.env.WORKSPACE_FOLDER_PATHS || process.cwd();
+    const result = await auth.logout({ cwd });
     resetAuthProgressState();
     return result;
 }
@@ -14376,10 +14550,11 @@ function normalizeAgentPayload(params) {
     if (!params) {
         return {};
     }
-    const { name, agentId, runtime, timeout, memorySize, installDependency, ...rest } = params;
+    const { name, description, agentId, runtime, timeout, memorySize, installDependency, zipFile, cosBucketRegion, tempCosObjectName, sessionConfig, ...rest } = params;
     return {
         ...rest,
         ...(normalizeString(name) ? { Name: normalizeString(name) } : {}),
+        ...(normalizeString(description) ? { Description: normalizeString(description) } : {}),
         ...(normalizeString(agentId) ? { AgentId: normalizeString(agentId) } : {}),
         ...(normalizeString(runtime) ? { Runtime: normalizeString(runtime) } : {}),
         ...(normalizeNumber(timeout) !== undefined ? { Timeout: normalizeNumber(timeout) } : {}),
@@ -14389,6 +14564,14 @@ function normalizeAgentPayload(params) {
         ...(normalizeBoolean(installDependency) !== undefined
             ? { InstallDependency: normalizeBoolean(installDependency) }
             : {}),
+        ...(normalizeString(zipFile) ? { ZipFile: normalizeString(zipFile) } : {}),
+        ...(normalizeString(cosBucketRegion)
+            ? { CosBucketRegion: normalizeString(cosBucketRegion) }
+            : {}),
+        ...(normalizeString(tempCosObjectName)
+            ? { TempCosObjectName: normalizeString(tempCosObjectName) }
+            : {}),
+        ...(sessionConfig && typeof sessionConfig === "object" ? { SessionConfig: sessionConfig } : {}),
     };
 }
 function registerAgentTools(server) {
@@ -14463,6 +14646,17 @@ function registerAgentTools(server) {
         inputSchema: {
             action: zod_1.z.enum(MANAGE_AGENT_ACTIONS),
             agentId: zod_1.z.string().optional(),
+            name: zod_1.z.string().optional(),
+            description: zod_1.z.string().optional(),
+            runtime: zod_1.z.string().optional(),
+            timeout: zod_1.z.number().optional(),
+            memorySize: zod_1.z.number().optional(),
+            installDependency: zod_1.z.boolean().optional(),
+            zipFile: zod_1.z.string().optional(),
+            cosBucketRegion: zod_1.z.string().optional(),
+            tempCosObjectName: zod_1.z.string().optional(),
+            sessionConfig: zod_1.z.record(zod_1.z.any()).optional(),
+            cwd: zod_1.z.string().optional(),
             params: zod_1.z.record(zod_1.z.any()).optional(),
         },
         annotations: {
@@ -14472,14 +14666,31 @@ function registerAgentTools(server) {
             openWorldHint: true,
             category: "agents",
         },
-    }, async ({ action, agentId, params, }) => {
+    }, async ({ action, agentId, name, description, runtime, timeout, memorySize, installDependency, zipFile, cosBucketRegion, tempCosObjectName, sessionConfig, cwd, params, }) => {
         try {
             const cloudbase = await getManager();
-            const payload = normalizeAgentPayload(params);
+            const payload = normalizeAgentPayload({
+                name,
+                description,
+                runtime,
+                timeout,
+                memorySize,
+                installDependency,
+                zipFile,
+                cosBucketRegion,
+                tempCosObjectName,
+                sessionConfig,
+                cwd,
+                ...(params ?? {}),
+            });
             if (action === "createAgent") {
+                const normalizedName = normalizeString(payload.Name);
+                if (!normalizedName) {
+                    throw new Error("action=createAgent 时必须提供 name（可通过顶层 name 或 params.name 传入）");
+                }
                 const createPayload = {
                     ...payload,
-                    Name: normalizeString(payload.Name) ?? "",
+                    Name: normalizedName,
                     Runtime: normalizeString(payload.Runtime) ?? "Nodejs20.19",
                 };
                 const result = await cloudbase.agent.createAgent(createPayload);
@@ -14607,6 +14818,8 @@ function shouldRegisterTool(toolName) {
         'manageCloudRun',
         // Download tools - local file downloads
         'manageStorage',
+        // Apps tools - deployApp reads local filePath for code upload
+        'manageApps',
     ];
     const shouldRegister = !cloudIncompatibleTools.includes(toolName);
     if (!shouldRegister) {
@@ -14637,6 +14850,7 @@ const QUERY_ACTIONS = [
     "describeCreateResult",
     "describeTaskStatus",
     "getInstanceInfo",
+    "describeInstance",
 ];
 const MANAGE_ACTIONS = [
     "provisionMySQL",
@@ -14900,7 +15114,9 @@ async function getSqlInstanceInfo({ getManager, cloudBaseOptions, server, }) {
     }
     catch (error) {
         const errorCode = extractErrorCode(error);
-        const isNotFound = errorCode === "FailedOperation.DataSourceNotExist";
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const isNotFound = errorCode === "FailedOperation.DataSourceNotExist"
+            || /envLink not exist|not exist|not found/i.test(errorMessage);
         if (!isNotFound) {
             throw error;
         }
@@ -14910,7 +15126,7 @@ async function getSqlInstanceInfo({ getManager, cloudBaseOptions, server, }) {
             instanceId: "default",
             schema: envId,
             rawStatus: typeof createRawStatus === "string" ? createRawStatus : null,
-            status: createStatus,
+            status: createStatus === "PENDING" || createStatus === "RUNNING" ? createStatus : "NOT_CREATED",
             createResult: createData ?? createResult,
         };
     }
@@ -15457,7 +15673,7 @@ function registerSQLDatabaseTools(server) {
         inputSchema: {
             action: zod_1.z
                 .enum(QUERY_ACTIONS)
-                .describe("runQuery=execute read-only SQL; describeCreateResult=query CreateMySQL result; describeTaskStatus=query MySQL task status; getInstanceInfo=get current SQL instance context"),
+                .describe("runQuery=execute read-only SQL; describeCreateResult=query CreateMySQL result; describeTaskStatus=query MySQL task status; getInstanceInfo=get current SQL instance context; describeInstance=alias of getInstanceInfo"),
             sql: zod_1.z
                 .string()
                 .optional()
@@ -15488,6 +15704,7 @@ function registerSQLDatabaseTools(server) {
             case "describeTaskStatus":
                 return handleDescribeTaskStatus(args, context);
             case "getInstanceInfo":
+            case "describeInstance":
                 return handleGetInstanceInfo(context);
             default:
                 throw new Error(`Unsupported SQL query action: ${args.action}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/cloudbase-mcp",
-  "version": "2.19.5",
+  "version": "2.20.0",
   "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",