@cloudbase/cloudbase-mcp 2.25.8 → 2.25.10

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import CloudBase from '@cloudbase/manager-node';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolAnnotations as ToolAnnotations_2 } from '@modelcontextprotocol/sdk/types.js';
 
 export declare const ALL_SUPPORTED_RUNTIMES: ("Nodejs20.19" | "Nodejs18.15" | "Nodejs16.13" | "Nodejs14.18" | "Nodejs12.16" | "Nodejs10.15" | "Nodejs8.9" | "Python3.10" | "Python3.9" | "Python3.7" | "Python3.6" | "Python2.7" | "Php8.0" | "Php7.4" | "Php7.2" | "Java8" | "Java11" | "Golang1")[];
 
@@ -32,6 +35,19 @@ export declare type CloudBaseOptions = CloudBaseConfigBase & {
     requestFn?: CloudApiRequestFn;
 };
 
+/**
+ * registerTool config with CloudBase `annotations.category` retained after
+ * MCP SDK >=1.26 closed ToolAnnotations to strip unknown keys at the type level.
+ */
+export declare type CloudBaseRegisterToolConfig = {
+    title?: string;
+    description?: string;
+    inputSchema?: any;
+    outputSchema?: any;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+};
+
 /**
  * Create a manager with the provided CloudBase options, without using cache
  * @param cloudBaseOptions Provided CloudBase options
@@ -161,7 +177,7 @@ export declare interface ExtendedMcpServer extends McpServer {
     logger?: Logger;
     enabledPlugins?: string[];
     pluginOptions?: PluginOptions;
-    /** 已注册工具的列表，供外部（如微信 IDE）提取并注册到自己的 MCP server */
+    /** Registered tools for external hosts (e.g. WeChat IDE) to re-register. */
     toolDefs: Array<{
         name: string;
         description: string;
@@ -169,6 +185,11 @@ export declare interface ExtendedMcpServer extends McpServer {
         handler: (input: any) => Promise<any>;
     }>;
     setLogger(logger: Logger): void;
+    /**
+     * Same as MCP SDK registerTool, but annotations may include CloudBase `category`.
+     * Handler typing stays intentionally loose to match existing tool call sites.
+     */
+    registerTool(name: string, config: CloudBaseRegisterToolConfig, cb: (...args: any[]) => any): RegisteredTool;
 }
 
 export declare function formatRuntimeList(): string;
@@ -528,6 +549,18 @@ declare class TelemetryReporter {
 
 export declare const telemetryReporter: TelemetryReporter;
 
+export { Tool }
+
+/**
+ * CloudBase extends MCP ToolAnnotations with a stable `category` hint used by
+ * IDE UIs for grouping. SDK >=1.26 types annotations as a closed/strip object,
+ * so we keep category via an intersection while still passing it through at
+ * runtime (listTools returns registered annotations without schema stripping).
+ */
+export declare type ToolAnnotations = ToolAnnotations_2 & {
+    category?: string;
+};
+
 export declare interface ToolResponse {
     success: boolean;
     [key: string]: any;

package/dist/index.js

@@ -33,6 +33,7 @@ Object.defineProperty(exports, "__esModule", ({ value: true }));
 exports.DEFAULT_CREATE_ENV_RESOURCES = exports.CREATE_ENV_RESOURCE_VALUES = void 0;
 exports.resolveCreateEnvResources = resolveCreateEnvResources;
 exports.simplifyEnvList = simplifyEnvList;
+exports.isUsableNoSqlDatabaseEntry = isUsableNoSqlDatabaseEntry;
 exports.registerEnvTools = registerEnvTools;
 const toolbox_1 = __webpack_require__(2090);
 const zod_1 = __webpack_require__(2971);
@@ -597,19 +598,21 @@ async function enrichEnvInfoWithBilling(params) {
  * CloudBase environment can have any combination of:
  * - PostgreSQL (CloudBase PG / pgstore): signaled by `EnvInfo.PostgreSQL[]`
  *   non-empty and/or `EnvInfo.Meta` containing `postgresql=enable`.
- * - NoSQL document database + the matching legacy COS-style bucket:
- *   signaled by `EnvInfo.Databases[]` (with InstanceId / RUNNING) and the
- *   bucket exposed in `EnvInfo.Storages[]`.
+ * - NoSQL document database (flexdb): signaled ONLY by a usable entry in
+ *   `EnvInfo.Databases[]`. The usable signal is a non-empty `InstanceId`
+ *   (FlexDB Tag, typically `tnt-...` — same value `getDatabaseInstanceId`
+ *   / ListTables `Tag` consume) with `Status` missing or `RUNNING`.
+ *   Cloud storage (`EnvInfo.Storages[]` / CreateEnv `storage`) is unrelated
+ *   and must never flip `RuntimeBackends.nosql`.
  * - MySQL: signaled by a non-empty `EnvInfo.MysqlInstances[]` (or similar
  *   field, name varies). In a pure PG environment this is absent.
  *
- * In particular: a CloudBase PG environment commonly STILL has the NoSQL
- * Database + Storage running in parallel. NoSQL is therefore "co-present"
- * — its collection APIs, NoSQL `securityRule`s, and the legacy
- * `app.uploadFile()` upload flow remain valid for collections / files
- * that already live there. The thing that is NOT a substitute for the new
- * PG surface is using NoSQL collections to model a brand-new business
- * table that the task explicitly puts in PG.
+ * In particular: a CloudBase PG environment commonly STILL has flexdb
+ * provisioned in parallel (`Databases[].InstanceId = tnt-...`). NoSQL is
+ * therefore "co-present" — its collection APIs and NoSQL `securityRule`s
+ * remain valid for collections that already live there. The thing that is
+ * NOT a substitute for the new PG surface is using NoSQL collections to
+ * model a brand-new business table that the task explicitly puts in PG.
  *
  * What this enrichment does:
  * - Adds `EnvInfo.RuntimeMode = "postgresql" | "nosql"` based on whether
@@ -617,11 +620,29 @@ async function enrichEnvInfoWithBilling(params) {
  *   business data when set to "postgresql".
  * - Adds `EnvInfo.RuntimeBackends`, a structured snapshot of which
  *   backends are actually available (postgresql / nosql / mysql), so the
- *   agent does not have to re-read `Databases`/`Storages`/`PostgreSQL`.
+ *   agent does not have to re-read `Databases`/`PostgreSQL`.
  * - Adds `EnvInfo.RuntimeModeHints` summarizing which API/tool to prefer
  *   for new code, including an explicit `MysqlNotAvailable` line when
  *   MySQL is absent — that one IS a hard "do not use" signal.
  */
+/** Exported for unit tests / live-fixture checks against FlexDB InstanceId. */
+function isUsableNoSqlDatabaseEntry(db) {
+    if (!db || typeof db !== "object") {
+        return false;
+    }
+    const entry = db;
+    const instanceId = typeof entry.InstanceId === "string" ? entry.InstanceId.trim() : "";
+    // Empty InstanceId means no flexdb tenant — same failure mode as
+    // getDatabaseInstanceId() throwing "无法获取数据库实例ID".
+    if (!instanceId) {
+        return false;
+    }
+    // Some API versions omit Status; when present, only RUNNING counts as usable.
+    if (entry.Status != null && String(entry.Status).toUpperCase() !== "RUNNING") {
+        return false;
+    }
+    return true;
+}
 async function enrichEnvInfoWithRuntimeMode(result, manager) {
     const envInfo = result?.EnvInfo;
     if (!envInfo || typeof envInfo !== "object") {
@@ -634,14 +655,12 @@ async function enrichEnvInfoWithRuntimeMode(result, manager) {
         /^postgre[_]?sql$/i.test(item.Key) &&
         String(item.Value).toLowerCase() === "enable");
     const hasPostgresql = pgList.length > 0 || metaPostgresEnabled;
-    // NoSQL document DB shows up under Databases[]; the matching legacy bucket
-    // shows up under Storages[]. Treat NoSQL as available when either side is
-    // non-empty (an old env may keep one without the other).
+    // NoSQL = flexdb tenant id on Databases[].InstanceId (typically tnt-...).
+    // Aligns with getDatabaseInstanceId() / ListTables Tag. Storage is unrelated.
     const databasesList = Array.isArray(envInfo.Databases)
         ? envInfo.Databases
         : [];
-    const storagesList = Array.isArray(envInfo.Storages) ? envInfo.Storages : [];
-    const hasNoSql = databasesList.length > 0 || storagesList.length > 0;
+    const hasNoSql = databasesList.some(isUsableNoSqlDatabaseEntry);
     // MySQL field name has been seen as MysqlInstances / MySQLInstances /
     // MySQL across API versions; check any of them.
     const mysqlList = (() => {
@@ -688,8 +707,8 @@ async function enrichEnvInfoWithRuntimeMode(result, manager) {
             Permissions: "PG table permissions use Row-Level Security. Run `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` and `CREATE POLICY` via `managePgDatabase(action=\"execute\", confirm=true)`. `managePermissions(resourceType=\"noSqlDatabase\", securityRule=...)` only governs NoSQL collection rules and has NO effect on PG tables — keep using it for the NoSQL collections that already exist here.",
             Storage: "PG-mode browser uploads should use `app.storage.from().upload(<bucket>/<key>, file)` against an explicitly-created `pgstore` bucket (same model as Supabase Storage; the v3 SDK does not auto-create one). `EnvInfo.Storages[]` here is the legacy NoSQL bucket — it is still usable for the legacy `app.uploadFile()` flow but is NOT a valid pgstore target.",
             CoexistingNoSQL: hasNoSql
-                ? "This env also has the legacy NoSQL Database + Storage running. Existing collections, existing `app.uploadFile()` calls, existing `managePermissions(resourceType=\"noSqlDatabase\")` rules all remain valid for legacy data."
-                : "No legacy NoSQL Database/Storage observed in this env.",
+                ? "This env also has a usable NoSQL (flexdb) InstanceId in EnvInfo.Databases[] (FlexDB Tag, typically tnt-...). Existing collections and `managePermissions(resourceType=\"noSqlDatabase\")` rules remain valid for that data."
+                : "No usable NoSQL (flexdb) InstanceId in EnvInfo.Databases[] — do not assume app.database() / NoSQL MCP tools work. Cloud storage does not imply flexdb.",
             MysqlNotAvailable: hasMysql
                 ? "MySQL instance(s) detected — see EnvInfo.MysqlInstances."
                 : "No MySQL instance is provisioned for this env. Do NOT use `manageMysqlDatabase` / `queryMysqlDatabase` (those are MySQL-specific) and do NOT read the `relational-database-mcp-cloudbase` skill — that family targets MySQL, not CloudBase PG.",
@@ -2718,6 +2737,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", ({ value: true }));
+exports.applyCategoryAnnotationMeta = applyCategoryAnnotationMeta;
 exports.wrapServerWithTelemetry = wrapServerWithTelemetry;
 const os_1 = __importDefault(__webpack_require__(8116));
 const cloudbase_manager_js_1 = __webpack_require__(3431);
@@ -2725,6 +2745,30 @@ const cloud_mode_js_1 = __webpack_require__(9684);
 const logger_js_1 = __webpack_require__(3039);
 const telemetry_js_1 = __webpack_require__(5880);
 const tool_result_js_1 = __webpack_require__(9835);
+/**
+ * Mirror annotations.category into _meta.category.
+ *
+ * MCP SDK Client >=1.26 parses tools/list with a stripping ToolAnnotationsSchema,
+ * which drops unknown annotation keys. `_meta` remains available to clients, while
+ * the server wire payload still includes annotations.category for non-SDK hosts.
+ */
+function applyCategoryAnnotationMeta(config) {
+    const category = config?.annotations?.category;
+    if (typeof category !== "string" || category.length === 0) {
+        return config;
+    }
+    const existingMeta = config._meta && typeof config._meta === "object" ? config._meta : undefined;
+    if (existingMeta && existingMeta.category === category) {
+        return config;
+    }
+    return {
+        ...config,
+        _meta: {
+            ...existingMeta,
+            category,
+        },
+    };
+}
 /**
  * 生成 GitHub Issue 创建链接
  * @param toolName 工具名称
@@ -2772,7 +2816,7 @@ ${envIdSection}
 ## 环境信息
 - 操作系统: ${os_1.default.type()} ${os_1.default.release()}
 - Node.js版本: ${process.version}
-- MCP 版本：${process.env.npm_package_version || "2.25.8" || 0}
+- MCP 版本：${process.env.npm_package_version || ( true ? "2.25.10" : 0)}
 - 系统架构: ${os_1.default.arch()}
 - 时间: ${new Date().toISOString()}
 - 请求ID: ${requestId}
@@ -2853,7 +2897,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.25.8" : 0;
+            const mcpVersion =  true ? "2.25.10" : 0;
             const requestIdSuffix = requestId ? `\n🆔 RequestId: ${requestId}` : '';
             const enhancedErrorMessage = `${errorMessage}${requestIdSuffix}\n\n📦 CloudBase MCP v${mcpVersion}\n🔗 遇到问题？请复制以下链接到浏览器打开\n即可自动携带错误详情快速创建 GitHub Issue：\n${issueLink}`;
             // 创建新的错误对象，保持原有的错误类型但更新消息
@@ -2950,7 +2994,7 @@ function wrapServerWithTelemetry(server) {
         // Use the wrapped handler, passing the server instance
         const wrappedHandler = createWrappedHandler(toolName, handler, server);
         // Call the original registerTool method
-        return originalRegisterTool(toolName, toolConfig, wrappedHandler);
+        return originalRegisterTool(toolName, applyCategoryAnnotationMeta(toolConfig ?? {}), wrappedHandler);
     };
 }
 /**
@@ -3189,14 +3233,15 @@ async function createCloudBaseMcpServer(options) {
     server.toolDefs = [];
     const originalRegisterTool = server.registerTool.bind(server);
     server.registerTool = ((name, meta, handler) => {
+        const toolMeta = (0, tool_wrapper_js_1.applyCategoryAnnotationMeta)(meta ?? {});
         // 同步记录到 toolDefs
         server.toolDefs.push({
             name,
-            description: meta?.description ?? meta?.title ?? '',
-            inputSchema: meta?.inputSchema ?? {},
+            description: toolMeta?.description ?? toolMeta?.title ?? '',
+            inputSchema: toolMeta?.inputSchema ?? {},
             handler,
         });
-        return originalRegisterTool(name, meta, async (args) => {
+        return originalRegisterTool(name, toolMeta, async (args) => {
             try {
                 return await handler(args);
             }
@@ -7576,6 +7621,7 @@ async function registerRagTools(server) {
       强烈推荐始终优先使用固定技能文档 (skill)、OpenAPI 文档 (openapi) 或 CloudBase 官方文档 (docs) 模式进行检索，仅当固定文档无法覆盖你的问题时，再使用向量查询 (vector) 模式。
 
       ⚠️ 重要：当 CloudBase skills 处于禁用状态或当前 IDE 不支持 skill 文件读取时，必须使用 searchKnowledgeBase(mode=skill, skillName=...) 来获取 CloudBase 技能文档内容，而不是尝试直接读取 skill 文件。直接读取可能返回 400 错误。示例：
+      - 需要最小 Web+数据库 Demo 路径时：searchKnowledgeBase(mode=skill, skillName=minimal-web-baas-demo)
       - 需要 auth-tool 指南时：searchKnowledgeBase(mode=skill, skillName=auth-tool)
       - 需要 auth-web 指南时：searchKnowledgeBase(mode=skill, skillName=auth-web)
       - 需要 cloudbase-agent 指南时：searchKnowledgeBase(mode=skill, skillName=cloudbase-agent)
@@ -11207,8 +11253,9 @@ class TelemetryReporter {
         const osRelease = os_1.default.release(); // 操作系统版本
         const nodeVersion = process.version; // Node.js版本
         const arch = os_1.default.arch(); // 系统架构
-        // 从构建时注入的版本号获取MCP版本信息
-        const mcpVersion = process.env.npm_package_version || "2.25.8" || 0;
+        // Build-time injected version; guard for vitest / non-webpack runtimes.
+        const mcpVersion = process.env.npm_package_version ||
+            ( true ? "2.25.10" : 0);
         return {
             userAgent: `${osType} ${osRelease} ${arch} ${nodeVersion} CloudBase-MCP/${mcpVersion}`,
             deviceId: this.deviceId,
@@ -16743,7 +16790,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.25.8" : 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.25.10" : 0}），便于后续维护和版本追踪\n- 下载 rules 模板时，如果项目中已存在 README.md 文件，系统会自动保护该文件不被覆盖（除非设置 overwrite=true）`,
         inputSchema: {
             template: zod_1.z
                 .enum(["react", "vue", "miniprogram", "uniapp", "rules"])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudbase/cloudbase-mcp",
-  "version": "2.25.8",
+  "version": "2.25.10",
   "packageManager": "pnpm@10.8.0",
   "description": "CloudBase MCP Server — operate Tencent CloudBase (database, auth, functions, storage, hosting) from AI coding tools via the Model Context Protocol. Part of CloudBase AI Toolkit.",
   "main": "./dist/index.cjs",
@@ -69,7 +69,6 @@
   "dependencies": {},
   "devDependencies": {
     "@microsoft/api-extractor": "^7.57.6",
-    "@modelcontextprotocol/sdk": "^1.13.3",
     "@rollup/plugin-commonjs": "^28.0.1",
     "@rollup/plugin-inject": "^5.0.5",
     "@rollup/plugin-json": "^6.1.0",