@cloudbase/cloudbase-mcp 2.20.2 → 2.21.0

package/dist/index.js

@@ -1703,7 +1703,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.20.2" || 0}
+- MCP 版本：${process.env.npm_package_version || "2.21.0" || 0}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -1784,7 +1784,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.20.2" : 0;
+            const mcpVersion =  true ? "2.21.0" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -7349,7 +7349,7 @@ function registerStorageTools(server) {
     // Tool 1: queryStorage - 查询存储信息（只读操作）
     server.registerTool("queryStorage", {
         title: "查询 CloudBase 存储信息",
-        description: "查询 CloudBase 云存储信息，支持列出目录文件、获取文件信息、获取临时下载链接等只读操作。返回的文件信息包括文件名、大小、修改时间、下载链接等。注意：action=url 返回的 temporaryUrl 是临时签名链接，有效期由 maxAge 参数决定（默认1小时），不要当作永久公网地址使用。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导出 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。",
+        description: "查询 CloudBase 云存储信息，支持列出目录文件、获取文件信息、获取临时下载链接等只读操作。返回的文件信息包括文件名、大小、修改时间、下载链接等。注意：action=url 返回的 temporaryUrl 是临时签名链接，有效期由 maxAge 参数决定（默认1小时），不要当作永久公网地址使用。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导出 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。\n\n💡 存储桶 ACL 权限管理请使用 permissions 工具：queryPermissions(action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\") 查询，managePermissions(action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"READONLY\") 设置。",
         inputSchema: queryStorageInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -7478,7 +7478,7 @@ function registerStorageTools(server) {
     // Tool 2: manageStorage - 管理存储文件（写操作）
     server.registerTool("manageStorage", {
         title: "管理 CloudBase 存储文件",
-        description: "管理 CloudBase 云存储文件，仅用于 COS/Storage 对象，不用于静态网站托管。支持上传文件/目录、下载文件/目录、删除文件/目录等操作。删除操作需要设置force=true进行确认，防止误删除重要文件。注意：上传后返回的 temporaryUrl 是临时签名链接，1小时后过期，不要当作永久公网地址写入配置或持久化存储。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。",
+        description: "管理 CloudBase 云存储文件，仅用于 COS/Storage 对象，不用于静态网站托管。支持上传文件/目录、下载文件/目录、删除文件/目录等操作。删除操作需要设置force=true进行确认，防止误删除重要文件。注意：上传后返回的 temporaryUrl 是临时签名链接，1小时后过期，不要当作永久公网地址写入配置或持久化存储。工具还会基于 DescribeEnvs 返回的 Storages[0].CdnDomain 推导 publicUrl，⚠️ 警告：publicUrl 仅在存储桶 ACL 为公有读（所有用户可读）时才能被匿名访问；默认私有读写存储桶返回的 publicUrl 会 403，此时请继续使用 temporaryUrl 或先通过控制台/SDK 将目标路径设置为公有读。\n\n💡 存储桶 ACL 权限管理请使用 permissions 工具：queryPermissions(action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\") 查询，managePermissions(action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"READONLY\") 设置。",
         inputSchema: manageStorageInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -9275,7 +9275,7 @@ class TelemetryReporter {
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
         // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.20.2" || 0;
+        const mcpVersion = process.env.npm_package_version || "2.21.0" || 0;
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -10993,8 +10993,8 @@ function registerPermissionTools(server) {
         }
     };
     server.registerTool?.("queryPermissions", {
-        title: "查询权限与用户配置",
-        description: "权限域统一只读入口。支持查询资源权限、角色列表/详情、应用用户列表/详情。",
+        title: "查询 CloudBase 权限与用户配置",
+        description: "查询 CloudBase 权限与用户配置，支持查询资源权限（数据库/云函数/存储桶等）、角色列表/详情、应用用户列表/详情。\n\n示例：\n- 查询存储桶权限：`action=\"getResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\"`",
         inputSchema: {
             action: zod_1.z.enum(QUERY_PERMISSION_ACTIONS),
             resourceType: zod_1.z
@@ -11154,8 +11154,8 @@ function registerPermissionTools(server) {
         }
     }));
     server.registerTool?.("managePermissions", {
-        title: "管理权限与用户配置",
-        description: "权限域统一写入口。支持修改资源权限、角色管理、成员与策略增删、应用用户 CRUD。`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单；前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。注意：`securityRule` 的详细语义取决于 `resourceType`；`doc._openid`、`auth.openid`、查询条件子集校验，以及 `create` / `update` / `delete` JSON 模板仅适用于 `resourceType=\"noSqlDatabase\"` 的文档数据库安全规则。配置 `function` 或 `storage` 时，请参考各自官方安全规则文档，而不是复用 NoSQL 模板。",
+        title: "管理 CloudBase 权限与用户配置",
+        description: "管理 CloudBase 权限与用户配置，支持修改资源权限（数据库/云函数/存储桶等）、角色管理、成员与策略增删、应用用户 CRUD。\n\n示例：\n- 设置存储桶为私有：`action=\"updateResourcePermission\", resourceType=\"storage\", resourceId=\"bucket-name\", permission=\"PRIVATE\"`\n- 创建角色：`action=\"createRole\", roleName=\"admin\", roleIdentity=\"admin\"`\n\n注意：`createUser` / `updateUser` 是环境侧应用用户管理能力，适合测试账号、管理员或预置用户，不应替代浏览器里的 Web SDK 注册表单。前端用户名密码注册应使用 `auth.signUp({ username, password })`，登录应使用 `auth.signInWithPassword({ username, password })`。`securityRule` 的详细语义取决于 `resourceType`，请参考对应官方文档。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_PERMISSION_ACTIONS),
             resourceType: zod_1.z
@@ -11649,14 +11649,28 @@ async function downloadFile(url, filePath, redirectCount = 0) {
             .on("error", reject);
     });
 }
-// 解压ZIP文件
+// 解压ZIP文件（含 zip slip 防护）
 async function extractZip(zipPath, extractPath) {
     try {
         // 创建解压目录
         await fsPromises.mkdir(extractPath, { recursive: true });
-        // 使用 adm-zip 库进行解压
+        // 使用 adm-zip 库逐条目解压，防止 zip slip 路径穿越
         const zip = new adm_zip_1.default(zipPath);
-        zip.extractAllTo(extractPath, true);
+        const entries = zip.getEntries();
+        const resolvedExtractPath = path.resolve(extractPath);
+        for (const entry of entries) {
+            // 跳过目录条目，后面由 mkdir 自动创建
+            if (entry.isDirectory)
+                continue;
+            const entryPath = path.resolve(resolvedExtractPath, entry.entryName);
+            if (!entryPath.startsWith(resolvedExtractPath + path.sep)) {
+                throw new Error(`解压失败: ZIP 文件中包含非法的路径 "${entry.entryName}"，已安全拦截`);
+            }
+            // 确保目标目录存在
+            await fsPromises.mkdir(path.dirname(entryPath), { recursive: true });
+            // 写入文件
+            await fsPromises.writeFile(entryPath, entry.getData());
+        }
     }
     catch (error) {
         throw new Error(`解压失败: ${error instanceof Error ? error.message : "未知错误"}`);
@@ -11831,7 +11845,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.20.2" : 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.21.0" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])
@@ -12026,8 +12040,9 @@ exports.registerAppTools = registerAppTools;
 const zod_1 = __webpack_require__(2971);
 const cloudbase_manager_js_1 = __webpack_require__(3431);
 const json_content_js_1 = __webpack_require__(4365);
-const QUERY_APP_ACTIONS = ["listApps", "getApp", "listAppVersions", "getAppVersion"];
-const MANAGE_APP_ACTIONS = ["deployApp", "deleteApp", "deleteAppVersion"];
+const cloud_mode_js_1 = __webpack_require__(9684);
+const QUERY_APP_ACTIONS = ["listApps", "getApp", "listAppVersions", "getAppVersion", "getBuildLog"];
+const MANAGE_APP_ACTIONS = ["deployApp", "getUploadUrl", "deleteApp", "deleteAppVersion"];
 const APP_FRAMEWORKS = ["vue", "react", "next", "nuxt", "vite", "angular", "static"];
 function buildEnvelope(data, message) {
     return {
@@ -12046,18 +12061,37 @@ function buildErrorEnvelope(error) {
 function getCloudAppService(cloudbase) {
     return cloudbase.cloudAppService ?? cloudbase.getCloudAppService?.();
 }
+function normalizeAccessUrlFromDomain(domain) {
+    if (typeof domain !== "string" || !domain.trim())
+        return {};
+    const trimmed = domain.trim();
+    const withProtocol = /^https?:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+    try {
+        const url = new URL(withProtocol);
+        url.hash = "";
+        url.search = "";
+        url.pathname = url.pathname === "/" ? "" : url.pathname.replace(/\/+$/, "");
+        return {
+            domain: url.host,
+            accessUrl: url.toString().replace(/\/$/, ""),
+        };
+    }
+    catch {
+        return {};
+    }
+}
 function registerAppTools(server) {
     const cloudBaseOptions = server.cloudBaseOptions;
     const getManager = () => (0, cloudbase_manager_js_1.getCloudBaseManager)({ cloudBaseOptions });
     server.registerTool?.("queryApps", {
-        title: "查询 CloudApp",
-        description: "CloudApp 域统一只读入口。可先查应用/版本，再在重新部署后用 listAppVersions 或 getAppVersion 按 serviceName 验证是否生成了新版本与最新构建状态。",
+        title: "查询 CloudBase 应用部署状态",
+        description: "查询 CloudBase 应用部署的应用和版本。可查应用列表/详情、版本列表/详情；部署后用 getAppVersion 按 buildId 轮询构建状态；getBuildLog 可查询构建日志用于诊断失败原因。",
         inputSchema: {
             action: zod_1.z.enum(QUERY_APP_ACTIONS),
             serviceName: zod_1.z
                 .string()
                 .optional()
-                .describe("CloudApp 服务名。getApp / listAppVersions / getAppVersion 时必填；重新部署后复用同一个 serviceName 查询版本历史。"),
+                .describe("CloudBase 应用服务名。getApp / listAppVersions / getAppVersion / getBuildLog 时必填；重新部署后复用同一个 serviceName 查询版本历史。"),
             searchKey: zod_1.z.string().optional().describe("按应用服务名模糊搜索关键词，仅 action=listApps 时使用。"),
             pageNo: zod_1.z.number().optional().describe("分页页码，从 1 开始。"),
             pageSize: zod_1.z.number().optional().describe("分页大小。"),
@@ -12068,14 +12102,18 @@ function registerAppTools(server) {
             buildId: zod_1.z
                 .string()
                 .optional()
-                .describe("构建 ID。getAppVersion 时可与 versionName 二选一；部署返回 BuildId 后可直接用它轮询状态。"),
+                .describe("构建 ID。getAppVersion 时可与 versionName 二选一；部署返回 BuildId 后可直接用它轮询状态。getBuildLog 时必填。"),
+            start: zod_1.z
+                .number()
+                .optional()
+                .describe("构建日志偏移量，用于分页拉取后续日志。仅 action=getBuildLog 时使用，不传时从开头返回。"),
         },
         annotations: {
             readOnlyHint: true,
             openWorldHint: true,
             category: "apps",
         },
-    }, async ({ action, serviceName, searchKey, pageNo, pageSize, versionName, buildId, }) => {
+    }, async ({ action, serviceName, searchKey, pageNo, pageSize, versionName, buildId, start, }) => {
         try {
             const cloudbase = await getManager();
             const appService = getCloudAppService(cloudbase);
@@ -12095,7 +12133,7 @@ function registerAppTools(server) {
                     apps: result.ServiceList ?? [],
                     total: result.Total ?? 0,
                     raw: result,
-                }, "CloudApp 列表查询成功"));
+                }, "CloudBase 应用列表查询成功"));
             }
             if (!serviceName) {
                 throw new Error(`action=${action} 时必须提供 serviceName`);
@@ -12110,7 +12148,7 @@ function registerAppTools(server) {
                     action,
                     serviceName,
                     app: result,
-                }, "CloudApp 详情查询成功"));
+                }, "CloudBase 应用详情查询成功"));
             }
             if (action === "listAppVersions") {
                 const result = await appService.describeAppVersionList({
@@ -12126,7 +12164,34 @@ function registerAppTools(server) {
                     versions: result.VersionList ?? [],
                     total: result.Total ?? 0,
                     raw: result,
-                }, "CloudApp 版本列表查询成功"));
+                }, "CloudBase 应用版本列表查询成功"));
+            }
+            if (action === "getBuildLog") {
+                if (!buildId) {
+                    throw new Error("action=getBuildLog 时必须提供 buildId");
+                }
+                const result = await cloudbase.commonService("tcb", "2018-06-08").call({
+                    Action: "DescribeCloudBaseRunBuildLog",
+                    Param: {
+                        EnvId: cloudBaseOptions?.envId || process.env.CLOUDBASE_ENV_ID,
+                        ServiceName: serviceName,
+                        BuildId: buildId,
+                        Start: start ?? 0,
+                    },
+                });
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const logs = result.Response?.LogList || [];
+                return (0, json_content_js_1.jsonContent)(buildEnvelope({
+                    action,
+                    serviceName,
+                    buildId,
+                    logs,
+                    total: result.Response?.Total || logs.length,
+                    nextStart: result.Response?.NextStart,
+                    raw: result,
+                }, logs.length > 0
+                    ? `查询到 ${logs.length} 条构建日志`
+                    : "暂无构建日志"));
             }
             const result = await appService.describeAppVersion({
                 deployType: "static-hosting",
@@ -12135,56 +12200,105 @@ function registerAppTools(server) {
                 buildId,
             });
             (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
-            return (0, json_content_js_1.jsonContent)(buildEnvelope({
+            const isFailed = result.Status === "FAILED";
+            const payload = {
                 action,
                 serviceName,
+                status: result.Status,
+                buildId: result.BuildId,
+                failReason: result.FailReason,
+                buildDuration: result.BuildDuration,
                 version: result,
-            }, "CloudApp 版本详情查询成功"));
+            };
+            if (isFailed) {
+                payload.nextStep = {
+                    action: "查询构建日志",
+                    tool: "queryApps",
+                    args: {
+                        action: "getBuildLog",
+                        serviceName,
+                        buildId: result.BuildId,
+                    },
+                    hint: `构建失败。调用 queryApps(action="getBuildLog", serviceName="${serviceName}", buildId="${result.BuildId}") 查看构建日志，诊断失败原因。`,
+                };
+            }
+            return (0, json_content_js_1.jsonContent)(buildEnvelope(payload, `CloudBase 应用版本详情查询成功（状态: ${result.Status}${result.FailReason ? `, 失败原因: ${result.FailReason}` : ""}${isFailed ? "，可查询构建日志" : ""}）`));
         }
         catch (error) {
             return (0, json_content_js_1.jsonContent)(buildErrorEnvelope(error));
         }
     });
     server.registerTool?.("manageApps", {
-        title: "管理 CloudApp",
-        description: "CloudApp 域统一写入口。action=deployApp 会先 uploadCode 再 createApp；首次调用创建应用，后续复用同一个 serviceName 会直接触发重新部署并生成新版本，无需先删除旧应用。",
+        title: "部署应用到 CloudBase（独立子域名）",
+        description: "部署 Web 应用到 CloudBase（构建前后端，部署到独立子域名）。\n" +
+            "action=getUploadUrl 获取预签名上传 URL（cloud mode 下使用），返回上传地址和 cosTimestamp。\n" +
+            "action=deployApp 上传源码 ZIP 并触发远端构建部署管道：\n" +
+            "  1. 远端 npm install（可通过 installCmd=\"\" 跳过）\n" +
+            "  2. 远端 npm run build（可通过 buildCmd=\"\" 跳过）\n" +
+            "  3. 远端 tcb hosting deploy\n" +
+            "\n" +
+            "域名格式：`<serviceName>-<envId>.webapps.tcloudbase.com`（每个 serviceName 一个独立子域名）\n" +
+            "\n" +
+            "✅ 推荐用法（新项目／需要独立域名的 Web 应用，首选此工具）：\n" +
+            "  新建项目首次部署时，传 framework=static, installCmd=\"\", buildCmd=\"\" 跳过远端构建，\n" +
+            "  只执行 tcb hosting deploy。部署后获得独立子域名，支持版本管理。\n" +
+            "\n" +
+            "⚠️ 兼容性说明：\n" +
+            "- 已有项目若之前用 manageHosting 部署过（域名格式：`<envId>-<appId>.tcloudbaseapp.com`），\n" +
+            "  切换到 manageApps 会产生全新的 URL，老链接失效。请保持原部署方式不变。\n" +
+            "- 如需判断：调用 queryHosting 检查是否已有托管文件。\n" +
+            "\n" +
+            "与 manageHosting 对比：\n" +
+            "- manageApps（本工具，新项目首选）：域名 `<serviceName>-<envId>.webapps.tcloudbase.com`，独立子域名，支持版本管理\n" +
+            "- manageHosting（已有项目或 fallback）：域名 `<envId>-<appId>.tcloudbaseapp.com/<path>`，共享环境域名\n" +
+            "两者均可绑定自定义域名。\n" +
+            "\n" +
+            "⚠️ 如果 manageApps 构建失败，先用 queryApps(action=\"getBuildLog\") 查日志；仍不行再 fallback 到 manageHosting。",
         inputSchema: {
             action: zod_1.z.enum(MANAGE_APP_ACTIONS),
             serviceName: zod_1.z
                 .string()
-                .describe("CloudApp 服务名。deployApp 时复用现有 serviceName 会新增一个部署版本并触发重新部署，而不是删除重建。"),
+                .describe("CloudBase 应用服务名，会体现在域名中：`<serviceName>-<envId>.webapps.tcloudbase.com`。deployApp 时复用现有 serviceName 会新增一个部署版本并触发重新部署，而不是删除重建。首次部署请用新名称。"),
             filePath: zod_1.z
                 .string()
                 .optional()
-                .describe("要上传并部署的本地项目根目录或 zip 文件绝对路径。deployApp 时必填；通常传源码所在目录而不是 build 产物目录，构建产物目录请用 buildPath 指定。"),
+                .describe("要上传并部署的本地项目根目录绝对路径。本地模式下 deployApp 时必填；通常传源码所在目录（含 package.json 和源码），不是 dist 目录。构建产物目录请用 buildPath 指定。cloud mode 下无需传此参数，改用 cosTimestamp。"),
+            cosTimestamp: zod_1.z
+                .string()
+                .optional()
+                .describe("可选 COS 时间戳。传入此值则直接使用已上传的代码创建应用，跳过本地文件上传。需先调用 getUploadUrl 获取预签名 URL，上传 ZIP 包后再传此时间戳。cloud mode 下为必填；本地模式也可传此值代替 filePath。两个路径二选一：filePath（本地打包上传）或 cosTimestamp（预签名 URL 上传）。"),
             appPath: zod_1.z
                 .string()
                 .optional()
-                .describe("应用线上访问路径（hosting mount path），例如 /my-web-app。不是本地目录路径；省略时默认为 /serviceName。"),
+                .describe("应用线上访问路径（hosting mount path），例如 /my-web-app。不是本地目录路径；CloudApp 已有独立子域名，省略时默认为 /（根路径）。"),
             buildPath: zod_1.z
                 .string()
                 .optional()
-                .describe("构建产物目录，相对于 filePath，例如 dist 或 build。纯静态 HTML 如果入口文件直接在项目根目录，可省略。"),
+                .describe("构建产物目录，相对于 filePath，例如 dist 或 build。\n" +
+                "⚠️ 传此值后远端构建系统会 cd 到此目录再执行 tcb hosting deploy，因此 deployCmd 会自动使用 .（当前目录）而非目录名，避免路径重复（如 dist/dist 错误）。\n" +
+                "纯静态 HTML 如果在项目根目录可省略，但注意 deployCmd 默认用 dist。"),
             framework: zod_1.z
                 .enum(APP_FRAMEWORKS)
                 .optional()
-                .describe("前端框架类型。可选值：vue、react、next、nuxt、vite、angular、static；纯 HTML/静态站点请传 static。"),
+                .describe("前端框架类型。可选值：vue、react、next、nuxt、vite、angular、static。\n" +
+                "即使传 static，仍会经过远端构建管道。如果本地已构建好，建议改用 manageHosting 直接上传，可完全跳过远端构建。"),
             nodeJsVersion: zod_1.z
                 .string()
                 .optional()
-                .describe("构建时使用的 Node.js 版本；不传时由 CloudApp 使用默认值。"),
+                .describe("构建时使用的 Node.js 版本；不传时由 CloudBase 使用默认值。"),
             installCmd: zod_1.z
                 .string()
                 .optional()
-                .describe("依赖安装命令，例如 npm install；静态资源无需安装依赖时可省略。"),
+                .describe("依赖安装命令，例如 npm install。不传时默认 npm install。本地已安装或无需安装可传空字符串 '' 跳过，但远端仍会执行 tcb hosting deploy。"),
             buildCmd: zod_1.z
                 .string()
                 .optional()
-                .describe("构建命令，例如 npm run build；纯静态 HTML 无构建步骤时可省略。"),
+                .describe("构建命令，例如 npm run build。不传时默认 npm run build。本地已构建好可传空字符串 '' 跳过构建步骤。若希望完全跳过远端管道，请改用 manageHosting。"),
             deployCmd: zod_1.z
                 .string()
                 .optional()
-                .describe("自定义部署命令。通常无需填写，只有在默认部署步骤不满足要求时才传。"),
+                .describe("自定义部署命令。通常无需填写，默认自动生成 tcb hosting deploy 命令。" +
+                "有 buildPath 时远端已 cd 到该目录，默认用 . 作为源码路径；无 buildPath 时默认用 dist。"),
             ignore: zod_1.z.array(zod_1.z.string()).optional().describe("上传时忽略的文件/目录 glob 模式，例如 **/node_modules/**。"),
             versionName: zod_1.z
                 .string()
@@ -12198,48 +12312,155 @@ function registerAppTools(server) {
             openWorldHint: true,
             category: "apps",
         },
-    }, async ({ action, serviceName, filePath, appPath, buildPath, framework, nodeJsVersion, installCmd, buildCmd, deployCmd, ignore, versionName, }) => {
+    }, async ({ action, serviceName, filePath, cosTimestamp, appPath, buildPath, framework, nodeJsVersion, installCmd, buildCmd, deployCmd, ignore, versionName, }) => {
         try {
             const cloudbase = await getManager();
             const appService = getCloudAppService(cloudbase);
             if (!appService) {
                 throw new Error("当前 manager 未提供 cloudAppService");
             }
-            if (action === "deployApp") {
-                if (!filePath) {
-                    throw new Error("action=deployApp 时必须提供 filePath");
+            // getUploadUrl — 获取预签名上传 URL（cloud mode 专用）
+            if (action === "getUploadUrl") {
+                if (!serviceName) {
+                    throw new Error("action=getUploadUrl 时必须提供 serviceName");
                 }
-                const uploadResult = await appService.uploadCode({
+                const cosInfoResult = await appService.describeCosInfo({
                     deployType: "static-hosting",
                     serviceName,
-                    localPath: filePath,
-                    ignore,
                 });
-                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, uploadResult);
+                (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, cosInfoResult);
+                const defaultIgnore = ["node_modules/**", ".git/**", ".DS_Store", "**/.DS_Store"];
+                // eslint-disable-next-line max-len
+                const zipCmd = "zip -r upload.zip . -x 'node_modules/**' -x '.git/**' -x '.DS_Store' -x '**/.DS_Store'";
+                const followupArgs = {
+                    action: "deployApp",
+                    serviceName,
+                    cosTimestamp: cosInfoResult.UnixTimestamp,
+                };
+                return (0, json_content_js_1.jsonContent)(buildEnvelope({
+                    action,
+                    serviceName,
+                    uploadUrl: cosInfoResult.UploadUrl,
+                    uploadHeaders: cosInfoResult.UploadHeaders,
+                    cosTimestamp: cosInfoResult.UnixTimestamp,
+                    method: "PUT",
+                    ignore: defaultIgnore,
+                    zipCommand: zipCmd,
+                    nextAction: {
+                        action: "上传代码到预签名 URL",
+                        hint: "请先在本地打包项目代码（排除 node_modules/.git），再将其上传到预签名 URL，然后调用 deployApp 触发构建",
+                        details: [
+                            `1. 打包: ${zipCmd}`,
+                            `2. 上传: curl -X PUT -T upload.zip '${cosInfoResult.UploadUrl}'`,
+                            `3. 触发构建: manageApps(action="deployApp", serviceName="${serviceName}", cosTimestamp="${cosInfoResult.UnixTimestamp}")`,
+                        ],
+                        followup: {
+                            tool: "manageApps",
+                            args: followupArgs,
+                        },
+                    },
+                }, "预签名上传 URL 获取成功。请上传代码后调用 deployApp 触发构建。"));
+            }
+            if (action === "deployApp") {
+                // cloud mode 下必须有 cosTimestamp；本地模式必须有 filePath
+                if ((0, cloud_mode_js_1.isCloudMode)()) {
+                    if (!cosTimestamp) {
+                        throw new Error("cloud mode 下 deployApp 需要 cosTimestamp 参数。请先调用 getUploadUrl 获取预签名上传 URL。" +
+                            "上传代码后再用 cosTimestamp 调用 deployApp。");
+                    }
+                }
+                else if (!filePath && !cosTimestamp) {
+                    throw new Error("action=deployApp 时必须提供 filePath（本地模式）或 cosTimestamp（cloud mode）。");
+                }
+                // 上传代码到 COS（仅本地模式需要，cloud mode 用 cosTimestamp 跳过）
+                let cosTs = cosTimestamp;
+                if (filePath && !cosTs) {
+                    const uploadResult = await appService.uploadCode({
+                        deployType: "static-hosting",
+                        serviceName,
+                        localPath: filePath,
+                        ignore,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, uploadResult);
+                    cosTs = uploadResult.cosTimestamp;
+                }
+                // 构建命令智能默认值
+                const resolvedInstallCmd = installCmd ?? "npm install";
+                const resolvedBuildCmd = buildCmd ?? "npm run build";
+                const resolvedDeployPath = appPath || "/";
+                const resolvedBuildPath = buildPath || "";
+                // ⚠️ 远端构建系统在有 buildPath 时 cd 到此目录再执行 tcb hosting deploy
+                // 部署命令用 "." 避免 dist/dist 重复。framework=static 无构建步骤，用根目录
+                const resolvedDeployCmd = deployCmd || (resolvedBuildPath || framework === "static"
+                    ? `tcb hosting deploy . ${resolvedDeployPath}`
+                    : `tcb hosting deploy dist ${resolvedDeployPath}`);
+                // 触发远端构建
                 const result = await appService.createApp({
                     deployType: "static-hosting",
                     serviceName,
                     buildType: "ZIP",
                     staticConfig: {
-                        appPath,
-                        buildPath,
+                        appPath: resolvedDeployPath,
+                        buildPath: resolvedBuildPath,
                         framework,
                         nodeJsVersion,
-                        cosTimestamp: uploadResult.cosTimestamp,
+                        cosTimestamp: cosTs,
                         staticCmd: {
-                            installCmd,
-                            buildCmd,
-                            deployCmd,
+                            installCmd: resolvedInstallCmd,
+                            buildCmd: resolvedBuildCmd,
+                            deployCmd: resolvedDeployCmd,
                         },
                     },
                 });
                 (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, result);
+                const { BuildId, VersionName } = result;
+                let appInfo;
+                let domain;
+                let accessUrl;
+                let accessUrlLookupWarning;
+                try {
+                    appInfo = await appService.describeAppInfo({
+                        deployType: "static-hosting",
+                        serviceName,
+                    });
+                    (0, cloudbase_manager_js_1.logCloudBaseResult)(server.logger, appInfo);
+                    ({ domain, accessUrl } = normalizeAccessUrlFromDomain(appInfo?.Domain));
+                }
+                catch (error) {
+                    accessUrlLookupWarning = error instanceof Error ? error.message : String(error);
+                }
                 return (0, json_content_js_1.jsonContent)(buildEnvelope({
                     action,
                     serviceName,
-                    upload: uploadResult,
+                    versionName: VersionName,
+                    buildId: BuildId,
+                    domain,
+                    accessUrl,
+                    accessUrlSource: accessUrl ? "describeAppInfo.Domain" : undefined,
+                    accessUrlLookupWarning,
+                    app: appInfo,
+                    upload: { cosTimestamp: cosTs },
                     deployment: result,
-                }, "CloudApp 部署成功"));
+                    buildConfig: {
+                        installCmd: resolvedInstallCmd,
+                        buildCmd: resolvedBuildCmd,
+                        deployCmd: resolvedDeployCmd,
+                    },
+                    nextStep: {
+                        action: "轮询构建状态",
+                        tool: "queryApps",
+                        args: {
+                            action: "getAppVersion",
+                            serviceName,
+                            buildId: BuildId,
+                        },
+                        hint: accessUrl
+                            ? `调用 queryApps(action="getAppVersion", serviceName="${serviceName}", buildId="${BuildId}") 轮询构建状态，直到 status 变为 SUCCESS 或 FAILED。构建成功后，后续记录部署时必须使用本结果的 accessUrl=${accessUrl}，不要自行拼接域名。若状态为 FAILED，可继续调用 queryApps(action="getBuildLog", serviceName="${serviceName}", buildId="${BuildId}") 查看构建日志诊断失败原因。`
+                            : `调用 queryApps(action="getAppVersion", serviceName="${serviceName}", buildId="${BuildId}") 轮询构建状态，直到 status 变为 SUCCESS 或 FAILED；再调用 queryApps(action="getApp", serviceName="${serviceName}") 读取 app.Domain 作为 accessUrl，不能自行拼接域名。若状态为 FAILED，可继续调用 queryApps(action="getBuildLog", serviceName="${serviceName}", buildId="${BuildId}") 查看构建日志诊断失败原因。`,
+                    },
+                }, accessUrl
+                    ? "CloudBase 应用构建已触发，已返回真实 accessUrl；请通过 queryApps 轮询构建状态。"
+                    : "CloudBase 应用构建已触发，请通过 queryApps 轮询构建状态，并用 getApp 读取真实域名。"));
             }
             if (action === "deleteApp") {
                 const result = await appService.deleteApp({
@@ -12251,7 +12472,7 @@ function registerAppTools(server) {
                     action,
                     serviceName,
                     raw: result,
-                }, "CloudApp 删除成功"));
+                }, "CloudBase 应用删除成功"));
             }
             if (!versionName) {
                 throw new Error("action=deleteAppVersion 时必须提供 versionName");
@@ -12267,7 +12488,7 @@ function registerAppTools(server) {
                 serviceName,
                 versionName,
                 raw: result,
-            }, "CloudApp 版本删除成功"));
+            }, "CloudBase 应用版本删除成功"));
         }
         catch (error) {
             return (0, json_content_js_1.jsonContent)(buildErrorEnvelope(error));
@@ -13071,6 +13292,16 @@ async function resolveHostingStaticDomain(cloudbase, logger) {
         return undefined;
     }
 }
+async function assertHostingUploadEnvironmentReady(cloudbase, cloudBaseOptions, logger) {
+    const envId = await (0, cloudbase_manager_js_1.getEnvId)(cloudBaseOptions);
+    const envInfo = await cloudbase.env.getEnvInfo();
+    (0, cloudbase_manager_js_1.logCloudBaseResult)(logger, envInfo);
+    const staticStorage = envInfo.EnvInfo?.StaticStorages?.[0];
+    if (staticStorage?.Bucket) {
+        return;
+    }
+    throw new Error(`当前环境 ${envId} 未发现静态托管资源配置，无法上传文件。请先确认 MCP 已绑定到已开通静态托管的 CloudBase 环境；如需切换环境，请调用 auth(action="set_env", envId="目标环境ID") 后重试。`);
+}
 function buildFailureResult(action, error) {
     return (0, tool_result_js_1.buildJsonToolResult)({
         success: false,
@@ -13255,7 +13486,7 @@ function registerHostingTools(server) {
     });
     server.registerTool('manageHosting', {
         title: '管理 CloudBase 静态托管',
-        description: '管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。若任务只是查看配置、文件或域名状态，请改用 queryHosting。',
+        description: '管理 CloudBase 静态托管的变更操作。action=upload 上传本地构建产物到共享域名（域名格式：<envId>-<appId>.tcloudbaseapp.com/<cloudPath>）；action=delete 删除托管文件或目录（必须 confirm=true）；action=setWebsiteDocument 设置首页/错误页/路由规则；action=enableService 开通静态托管；action=bindDomain / unbindDomain / updateDomain 管理自定义域名；action=downloadFile / downloadDirectory 下载托管内容到本地。⚠️ 新项目部署优先使用 manageApps（部署到独立子域名），本工具适合已有老项目继续使用或作为 manageApps 的 fallback。manageApps 与 manageHosting 域名不同，切换会导致老链接失效。若任务只是查看配置、文件或域名状态，请改用 queryHosting。',
         inputSchema: manageHostingInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -13276,6 +13507,7 @@ function registerHostingTools(server) {
                     }
                     let result;
                     try {
+                        await assertHostingUploadEnvironmentReady(cloudbase, cloudBaseOptions, server.logger);
                         result = await cloudbase.hosting.uploadFiles({
                             localPath: input.localPath,
                             cloudPath: input.cloudPath,
@@ -14841,8 +15073,6 @@ 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) {

package/package.json

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