feat(mcp): 🔧 unify MCP configuration format and simplify global installation (#104)

binggg · web-flow · commit f65385d9c1b2 · 2025-07-29T11:31:22.000+08:00
- Unify all MCP configurations to use 'cloudbase' as server name
- Standardize args format to use npm-global-exec@latest
- Remove traditional global installation method
- Update 47 files across docs, config, and MCP package
- Simplify user experience with single recommended approach
diff --git a/README-EN.md b/README-EN.md
@@ -64,9 +64,9 @@ Add the following config to your AI IDE (e.g., Cursor) to enable all CloudBase A
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/README.md b/README.md
@@ -69,9 +69,9 @@
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/config/.codex/config.toml b/config/.codex/config.toml
@@ -3,4 +3,4 @@
 
 [mcp_servers.cloudbase]
 command = "npx"
-args = ["--cache", ".", @cloudbase/cloudbase-mcp@latest"]
+args = ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
diff --git a/config/.comate/mcp.json b/config/.comate/mcp.json
@@ -3,8 +3,7 @@
         "cloudbase": {
             "command": "npx",
             "args": [
-                "--cache",
-                ".",
+                "npm-global-exec@latest",
                 "@cloudbase/cloudbase-mcp@latest"
             ]
         }
diff --git a/config/.cursor/mcp.json b/config/.cursor/mcp.json
@@ -3,8 +3,7 @@
         "cloudbase": {
             "command": "npx",
             "args": [
-                "--cache",
-                ".",
+                "npm-global-exec@latest",
                 "@cloudbase/cloudbase-mcp@latest"
             ]
         }
diff --git a/config/.gemini/settings.json b/config/.gemini/settings.json
@@ -1,10 +1,9 @@
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
       "args": [
-        "--cache",
-        ".",
+        "npm-global-exec@latest",
         "@cloudbase/cloudbase-mcp@latest"
       ]
     }
diff --git a/config/.mcp.json b/config/.mcp.json
@@ -3,8 +3,7 @@
     "cloudbase": {
       "command": "npx",
       "args": [
-        "--cache",
-        ".",
+        "npm-global-exec@latest",
         "@cloudbase/cloudbase-mcp@latest"
       ]
     }
diff --git a/config/.opencode.json b/config/.opencode.json
@@ -1,10 +1,9 @@
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
       "args": [
-        "--cache",
-        ".",
+        "npm-global-exec@latest",
         "@cloudbase/cloudbase-mcp@latest"
       ]
     }
diff --git a/config/.qwen/settings.json b/config/.qwen/settings.json
@@ -1,10 +1,9 @@
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
       "args": [
-        "--cache",
-        ".",
+        "npm-global-exec@latest",
         "@cloudbase/cloudbase-mcp@latest"
       ]
     }
diff --git a/config/.roo/mcp.json b/config/.roo/mcp.json
@@ -3,8 +3,7 @@
         "cloudbase": {
             "command": "npx",
             "args": [
-                "--cache",
-                ".",
+                "npm-global-exec@latest",
                 "@cloudbase/cloudbase-mcp@latest"
             ],
             "disabled": false
diff --git a/config/.vscode/mcp.json b/config/.vscode/mcp.json
@@ -3,8 +3,7 @@
         "cloudbase": {
             "command": "npx",
             "args": [
-                "--cache",
-                ".",
+                "npm-global-exec@latest",
                 "@cloudbase/cloudbase-mcp@latest"
             ]
         }
diff --git a/config/.vscode/settings.json b/config/.vscode/settings.json
@@ -6,8 +6,7 @@
                 "name": "cloudbase",
                 "command": "npx",
                 "args": [
-                    "--cache",
-                    ".",
+                    "npm-global-exec@latest",
                     "@cloudbase/cloudbase-mcp@latest"
                 ]
             }
diff --git a/doc/faq.md b/doc/faq.md
@@ -65,21 +65,16 @@ AI 会自动下载并更新最新的规则配置到你的项目目录。
 
 ### 如何全局安装 CloudBase AI ToolKit？
 
-如果你希望全局安装 CloudBase AI ToolKit 以避免每次使用 npx 下载，可以使用以下方法：
+如果你希望全局安装 CloudBase AI ToolKit 以避免每次使用 npx 下载，推荐使用 `npm-global-exec` 方式，这种方式更稳定且自动处理依赖：
 
-**1. 全局安装**
-```bash
-npm i @cloudbase/cloudbase-mcp@latest -g
-```
-
-**2. 更新 MCP 配置**
-安装完成后，将 MCP 配置中的 `command` 从 `npx` 改为直接使用命令：
+**推荐配置方式：**
 
 ```json
 {
   "mcpServers": {
     "cloudbase": {
-      "command": "cloudbase-mcp"
+      "command": "npx",
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
@@ -89,10 +84,9 @@ npm i @cloudbase/cloudbase-mcp@latest -g
 - 启动速度更快，无需每次下载
 - 避免网络问题导致的启动失败
 - 减少 npx 缓存相关问题
-
-**注意事项：**
-- 需要手动更新：`npm update @cloudbase/cloudbase-mcp -g`
-- 确保全局安装的版本是最新的
+- 自动安装和管理依赖
+- 避免全局安装可能遇到的权限和环境问题
+- 自动获取最新版本
 
 ---
 
@@ -103,18 +97,10 @@ npm i @cloudbase/cloudbase-mcp@latest -g
 **1. 检查环境配置**
 - 确保 Node.js 版本为 v18.15.0 及以上
 - macOS 用户且使用 nvm 管理 Node.js 的，请务必设置默认 Node 版本为 v18.15.0 及以上，避免不同终端版本不一致导致的问题。
-  设置默认版本命令示例：
-  ```bash
-  nvm alias default 18.15.0
-  ```
 - 检查网络连接，建议设置 npm 源为腾讯镜像源：
   ```bash
   npm config set registry https://mirrors.cloud.tencent.com/npm/
   ```
-- 输入如下命令测试，若无异常报错则为正常启动服务
-  ```bash
-  npx @cloudbase/cloudbase-mcp@latest
-  ```
 
 **2. 清理缓存**
 - 清理 npx 缓存（npx 存在缓存 bug 可能导致安装问题）：
@@ -131,8 +117,8 @@ npm i @cloudbase/cloudbase-mcp@latest -g
 - 如果上述方法无效，可以删除 MCP 配置后重新添加
 - 确保使用最新的配置格式
 
-**5. 尝试全局安装**
-- 如果 npx 方式持续有问题，可以尝试[全局安装方式](#如何全局安装-cloudbase-ai-toolkit)
+**5. 尝试 npm-global-exec 方式**
+- 如果 npx 方式持续有问题，推荐使用 npm-global-exec 方式，这种方式更稳定且自动处理依赖
 
 **6. 使用 inspector 工具验证 MCP 连接**
 - 如果上述方法都无效，可以通过 inspector 工具进一步排查 MCP 是否正常：
@@ -156,6 +142,62 @@ npm i @cloudbase/cloudbase-mcp@latest -g
 
 ---
 
+### MCP 配置后提示 MCP error -32001: Request timed out
+
+如果在配置 MCP 时遇到 `MCP error -32001: Request timed out` 错误，可以按以下步骤解决：
+
+**1. 检查环境配置**
+- 确保 Node.js 版本为 v18.15.0 及以上
+- macOS 用户且使用 nvm 管理 Node.js 的，请务必设置默认 Node 版本为 v18.15.0 及以上，避免不同终端版本不一致导致的问题。
+  设置默认版本命令示例：
+  ```bash
+  nvm alias default 18.15.0
+  ```
+- 检查网络连接，建议设置 npm 源为腾讯镜像源：
+  ```bash
+  npm config set registry https://mirrors.cloud.tencent.com/npm/
+  ```
+
+**2. 使用 npm-global-exec 工具安装 @cloudbase/cloudbase-mcp 到本地**
+
+2.1 在终端中执行如下命令
+```bash
+npx -y npm-global-exec@latest @cloudbase/cloudbase-mcp@latest
+```
+
+2.2 执行完成后，确认终端命令执行结果如下图，表示已安装成功 @cloudbase/cloudbase-mcp 且测试启动server 正常（确认后这里可以 ctrl+c 关掉）
+![](https://qcloudimg.tencent-cloud.cn/raw/223c92ffcb54fad9210ec6d77a61dcea.png)
+
+> 可以在用户 home 主目录下找到 cloudbase-mcp 文件夹，确认里面是否正确安装了 @cloudbase/cloudbase-mcp
+
+**3. 重新配置 MCP**
+
+3.1 重启 IDE
+
+3.2 删除原有的 CloudBase MCP Server 配置，并使用新的 MCP Server 配置如下
+
+```json
+{
+  "mcpServers": {
+	  "cloudbase": {
+		  "command": "npx",
+		  "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
+		}
+	}
+}
+```
+
+3.3 等待约10-20s，可以看到 CloudBase MCP 正常
+
+- CodeBuddy中正常配置效果
+![](https://qcloudimg.tencent-cloud.cn/raw/3ad6cefbfee790ad3b42eea0cdb752cb.png)
+
+- Visual Studio Code 中 CodeBuddy 插件配置 CloudBase MCP 正常效果
+![](https://qcloudimg.tencent-cloud.cn/raw/b6e70f722768d4a844280102378358fe.png)
+
+- Cursor 中正常配置效果
+![](https://qcloudimg.tencent-cloud.cn/raw/344fe2c5a96a3e19c6cafc2bcbe73f96.png)
+
 ### MCP 配置不生效怎么办？
 
 1. 检查配置格式是否正确
@@ -183,7 +225,7 @@ Safari 浏览器在某些情况下可能存在兼容性问题，影响授权流
   "mcpServers": {
     "cloudbase-mcp": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"],
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"],
       "env": {
         "TENCENTCLOUD_SECRETID": "腾讯云 SecretId",
         "TENCENTCLOUD_SECRETKEY": "腾讯云 SecretKey",
diff --git a/doc/getting-started.md b/doc/getting-started.md
@@ -50,7 +50,7 @@
   "mcpServers": {
     "cloudbase": {
       "command": "npx",
-      "args": ["--cache", ".", "@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/cline.md b/doc/ide-setup/cline.md
@@ -66,8 +66,7 @@
       "timeout": 60,
       "command": "npx",
       "args": [
-        "--cache",
-        ".",
+        "npm-global-exec@latest",
         "@cloudbase/cloudbase-mcp@latest"
       ],
       "transportType": "stdio",
diff --git a/doc/ide-setup/codebuddy.md b/doc/ide-setup/codebuddy.md
@@ -72,7 +72,7 @@
   "mcpServers": {
     "cloudbase": {
       "command": "npx",
-      "args": ["--cache", ".","@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/cursor.md b/doc/ide-setup/cursor.md
@@ -66,9 +66,9 @@
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["--cache",".", "@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/gemini-cli.md b/doc/ide-setup/gemini-cli.md
@@ -72,9 +72,9 @@ npx @google/gemini-cli
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["--cache", ".", "@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/opencode.md b/doc/ide-setup/opencode.md
@@ -68,9 +68,9 @@ yarn global add opencode
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/qwen-code.md b/doc/ide-setup/qwen-code.md
@@ -61,9 +61,9 @@ npx @qwen-code/qwen-code
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/tongyi-lingma.md b/doc/ide-setup/tongyi-lingma.md
@@ -59,9 +59,9 @@
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/trae.md b/doc/ide-setup/trae.md
@@ -59,9 +59,9 @@
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["--cache", ".", "@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/ide-setup/windsurf.md b/doc/ide-setup/windsurf.md
@@ -59,9 +59,9 @@
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/index.md b/doc/index.md
@@ -53,9 +53,9 @@
 ```json
 {
   "mcpServers": {
-    "cloudbase-mcp": {
+    "cloudbase": {
       "command": "npx",
-      "args": ["--cache", ".", "@cloudbase/cloudbase-mcp@latest"]
+      "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]
     }
   }
 }
diff --git a/doc/mcp-listing-materials-zh.md b/doc/mcp-listing-materials-zh.md
diff --git a/doc/mcp-listing-materials.md b/doc/mcp-listing-materials.md
diff --git a/doc/mcp-tools.md b/doc/mcp-tools.md
diff --git a/doc/plugins.md b/doc/plugins.md
diff --git a/doc/plugins/miniprogram.md b/doc/plugins/miniprogram.md
diff --git a/mcp/DOC.md b/mcp/DOC.md
diff --git a/mcp/Intro.md b/mcp/Intro.md
diff --git a/mcp/README.md b/mcp/README.md
diff --git a/mcp/package-lock.json b/mcp/package-lock.json

Original file line number	Diff line number	Diff line change
`@@ -64,9 +64,9 @@ Add the following config to your AI IDE (e.g., Cursor) to enable all CloudBase A`
`64`	`64`	```json
`65`	`65`	`{`
`66`	`66`	`"mcpServers": {`
`67`		`- "cloudbase-mcp": {`
	`67`	`+ "cloudbase": {`
`68`	`68`	`"command": "npx",`
`69`		`- "args": ["@cloudbase/cloudbase-mcp@latest"]`
	`69`	`+ "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]`
`70`	`70`	`}`
`71`	`71`	`}`
`72`	`72`	`}`
Original file line number	Diff line number	Diff line change
`@@ -69,9 +69,9 @@`
`69`	`69`	```json
`70`	`70`	`{`
`71`	`71`	`"mcpServers": {`
`72`		`- "cloudbase-mcp": {`
	`72`	`+ "cloudbase": {`
`73`	`73`	`"command": "npx",`
`74`		`- "args": ["@cloudbase/cloudbase-mcp@latest"]`
	`74`	`+ "args": ["npm-global-exec@latest", "@cloudbase/cloudbase-mcp@latest"]`
`75`	`75`	`}`
`76`	`76`	`}`
`77`	`77`	`}`
Original file line number	Diff line number	Diff line change
`@@ -3,8 +3,7 @@`
`3`	`3`	`"cloudbase": {`
`4`	`4`	`"command": "npx",`
`5`	`5`	`"args": [`
`6`		`- "--cache",`
`7`		`- ".",`
	`6`	`+ "npm-global-exec@latest",`
`8`	`7`	`"@cloudbase/cloudbase-mcp@latest"`
`9`	`8`	`]`
`10`	`9`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,10 +1,9 @@`
`1`	`1`	`{`
`2`	`2`	`"mcpServers": {`
`3`		`- "cloudbase-mcp": {`
	`3`	`+ "cloudbase": {`
`4`	`4`	`"command": "npx",`
`5`	`5`	`"args": [`
`6`		`- "--cache",`
`7`		`- ".",`
	`6`	`+ "npm-global-exec@latest",`
`8`	`7`	`"@cloudbase/cloudbase-mcp@latest"`
`9`	`8`	`]`
`10`	`9`	`}`