fix: MCP 工具能力映射不清导致 CLI 任务无法正确迁移

config/.claude/skills/cloudbase-cli/SKILL.md

@@ -57,6 +57,61 @@ Use when the user wants to manage CloudBase resources via command line:
 - Console UI operations
 - CloudBase Agent SDK development → use `cloudbase-agent-ts`
 
+## CLI → MCP Tool Mapping (when CLI is disabled)
+
+When the runtime environment disables CLI (e.g., MCP-only mode), use these MCP tool equivalents instead of `tcb` commands:
+
+### Permission & Role Management
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb role list` | `queryPermissions(action="listRoles")` |
+| `tcb role get --id <roleId>` | `queryPermissions(action="getRole", roleId="<roleId>")` |
+| `tcb role get --identity <identity>` | `queryPermissions(action="getRole", roleIdentity="<identity>")` |
+| `tcb role get --name <name>` | `queryPermissions(action="getRole", roleName="<name>")` |
+| `tcb role create --name <n> --identity <i>` | `managePermissions(action="createRole", roleName="<n>", roleIdentity="<i>", policies=[...], memberUids=[...])` |
+| `tcb role update --id <id> --add-users` | `managePermissions(action="updateRole", roleId="<id>", memberUids=[...])` or `managePermissions(action="addRoleMembers", ...)` |
+| `tcb role update --id <id> --add-policies` | `managePermissions(action="addRolePolicies", roleId="<id>", policies=[...])` |
+| `tcb role delete <ids...>` | `managePermissions(action="deleteRoles", roleIds=[...])` |
+| `tcb permission get table:users` | `queryPermissions(action="getResourcePermission", resourceType="sqlDatabase", resourceId="users")` |
+| `tcb permission get collection:posts` | `queryPermissions(action="getResourcePermission", resourceType="noSqlDatabase", resourceId="posts")` |
+| `tcb permission set table:users --level readonly` | `managePermissions(action="updateResourcePermission", resourceType="sqlDatabase", resourceId="users", permission="READONLY")` |
+
+### User Management
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb user list` | `queryPermissions(action="listUsers")` |
+| `tcb user list --name <name>` | `queryPermissions(action="listUsers", username="<name>")` |
+| `tcb user update <uid> --status BLOCKED` | `managePermissions(action="updateUser", uid="<uid>", userStatus="BLOCKED")` |
+
+### Function Management
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb fn list` | `queryFunctions(action="listFunctions")` |
+| `tcb fn detail <name>` | `queryFunctions(action="getFunction", functionName="<name>")` |
+| `tcb fn logs <name>` | `queryFunctions(action="getFunctionLogs", functionName="<name>")` |
+| `tcb fn deploy` | `manageFunctions(action="updateFunctionCode", functionRootPath="...", functionName="...")` |
+| `tcb fn create` | `manageFunctions(action="createFunction", ...)` |
+
+### Database Operations
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb db list` | `readNoSqlDatabaseStructure(action="listCollections")` |
+| `tcb db query <collection>` | `readNoSqlDatabaseContent(collection="<collection>", ...)` |
+| `tcb mysql query "SELECT..."` | `querySqlDatabase(action="executeReadSQL", statement="SELECT...")` |
+
+### Storage & Hosting
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb hosting deploy ./dist` | `uploadFiles(localPath="./dist", cloudPath="/")` |
+| `tcb storage upload ./file.txt /path` | `manageStorage(action="uploadFile", localPath="./file.txt", cloudPath="/path")` |
+
+> ⚠️ **Important**: When CLI is disabled, do NOT attempt to run `tcb` commands via shell. Use the MCP tool equivalents listed above. Check the runtime capability notice at the start of the conversation to determine which capabilities are enabled.
+
 ## How to use this skill (for a coding agent)
 
 1. **Always load `references/core.md` first** — it covers authentication,

config/.claude/skills/cloudbase-cli/references/permission.md

@@ -10,6 +10,27 @@ CloudBase access control has **three independent layers** — know which one to
 
 > ⚠️ Role policies and resource permissions are **two parallel systems with NO automatic sync**. Changing a role policy does NOT affect `permission get` results, and vice versa. Audit both separately.
 
+## MCP Tool Equivalents (when CLI is disabled)
+
+If the runtime environment shows CLI is disabled, use these MCP tools instead:
+
+| CLI Command | MCP Tool Call |
+|-------------|---------------|
+| `tcb role list` | `queryPermissions(action="listRoles")` |
+| `tcb role get --id <id>` | `queryPermissions(action="getRole", roleId="<id>")` |
+| `tcb role get --identity <i>` | `queryPermissions(action="getRole", roleIdentity="<i>")` |
+| `tcb role get --name <n>` | `queryPermissions(action="getRole", roleName="<n>")` |
+| `tcb role create` | `managePermissions(action="createRole", roleName, roleIdentity, policies, memberUids)` |
+| `tcb role update --add-users` | `managePermissions(action="addRoleMembers", roleId, memberUids)` |
+| `tcb role update --add-policies` | `managePermissions(action="addRolePolicies", roleId, policies)` |
+| `tcb role delete` | `managePermissions(action="deleteRoles", roleIds)` |
+| `tcb permission get table:users` | `queryPermissions(action="getResourcePermission", resourceType="sqlDatabase", resourceId="users")` |
+| `tcb permission set table:users --level readonly` | `managePermissions(action="updateResourcePermission", resourceType="sqlDatabase", resourceId="users", permission="READONLY")` |
+| `tcb user list` | `queryPermissions(action="listUsers")` |
+| `tcb user update <uid> --status BLOCKED` | `managePermissions(action="updateUser", uid="<uid>", userStatus="BLOCKED")` |
+
+> ⚠️ Do NOT attempt `tcb` commands when CLI is disabled. Check the runtime capability notice to determine available interfaces.
+
 ---
 
 ## When to Use

config/source/skills/cloudbase-cli/SKILL.md

@@ -57,6 +57,61 @@ Use when the user wants to manage CloudBase resources via command line:
 - Console UI operations
 - CloudBase Agent SDK development → use `cloudbase-agent-ts`
 
+## CLI → MCP Tool Mapping (when CLI is disabled)
+
+When the runtime environment disables CLI (e.g., MCP-only mode), use these MCP tool equivalents instead of `tcb` commands:
+
+### Permission & Role Management
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb role list` | `queryPermissions(action="listRoles")` |
+| `tcb role get --id <roleId>` | `queryPermissions(action="getRole", roleId="<roleId>")` |
+| `tcb role get --identity <identity>` | `queryPermissions(action="getRole", roleIdentity="<identity>")` |
+| `tcb role get --name <name>` | `queryPermissions(action="getRole", roleName="<name>")` |
+| `tcb role create --name <n> --identity <i>` | `managePermissions(action="createRole", roleName="<n>", roleIdentity="<i>", policies=[...], memberUids=[...])` |
+| `tcb role update --id <id> --add-users` | `managePermissions(action="updateRole", roleId="<id>", memberUids=[...])` or `managePermissions(action="addRoleMembers", ...)` |
+| `tcb role update --id <id> --add-policies` | `managePermissions(action="addRolePolicies", roleId="<id>", policies=[...])` |
+| `tcb role delete <ids...>` | `managePermissions(action="deleteRoles", roleIds=[...])` |
+| `tcb permission get table:users` | `queryPermissions(action="getResourcePermission", resourceType="sqlDatabase", resourceId="users")` |
+| `tcb permission get collection:posts` | `queryPermissions(action="getResourcePermission", resourceType="noSqlDatabase", resourceId="posts")` |
+| `tcb permission set table:users --level readonly` | `managePermissions(action="updateResourcePermission", resourceType="sqlDatabase", resourceId="users", permission="READONLY")` |
+
+### User Management
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb user list` | `queryPermissions(action="listUsers")` |
+| `tcb user list --name <name>` | `queryPermissions(action="listUsers", username="<name>")` |
+| `tcb user update <uid> --status BLOCKED` | `managePermissions(action="updateUser", uid="<uid>", userStatus="BLOCKED")` |
+
+### Function Management
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb fn list` | `queryFunctions(action="listFunctions")` |
+| `tcb fn detail <name>` | `queryFunctions(action="getFunction", functionName="<name>")` |
+| `tcb fn logs <name>` | `queryFunctions(action="getFunctionLogs", functionName="<name>")` |
+| `tcb fn deploy` | `manageFunctions(action="updateFunctionCode", functionRootPath="...", functionName="...")` |
+| `tcb fn create` | `manageFunctions(action="createFunction", ...)` |
+
+### Database Operations
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb db list` | `readNoSqlDatabaseStructure(action="listCollections")` |
+| `tcb db query <collection>` | `readNoSqlDatabaseContent(collection="<collection>", ...)` |
+| `tcb mysql query "SELECT..."` | `querySqlDatabase(action="executeReadSQL", statement="SELECT...")` |
+
+### Storage & Hosting
+
+| CLI Command | MCP Tool Equivalent |
+|-------------|---------------------|
+| `tcb hosting deploy ./dist` | `uploadFiles(localPath="./dist", cloudPath="/")` |
+| `tcb storage upload ./file.txt /path` | `manageStorage(action="uploadFile", localPath="./file.txt", cloudPath="/path")` |
+
+> ⚠️ **Important**: When CLI is disabled, do NOT attempt to run `tcb` commands via shell. Use the MCP tool equivalents listed above. Check the runtime capability notice at the start of the conversation to determine which capabilities are enabled.
+
 ## How to use this skill (for a coding agent)
 
 1. **Always load `references/core.md` first** — it covers authentication,

config/source/skills/cloudbase-cli/references/permission.md

@@ -10,6 +10,27 @@ CloudBase access control has **three independent layers** — know which one to
 
 > ⚠️ Role policies and resource permissions are **two parallel systems with NO automatic sync**. Changing a role policy does NOT affect `permission get` results, and vice versa. Audit both separately.
 
+## MCP Tool Equivalents (when CLI is disabled)
+
+If the runtime environment shows CLI is disabled, use these MCP tools instead:
+
+| CLI Command | MCP Tool Call |
+|-------------|---------------|
+| `tcb role list` | `queryPermissions(action="listRoles")` |
+| `tcb role get --id <id>` | `queryPermissions(action="getRole", roleId="<id>")` |
+| `tcb role get --identity <i>` | `queryPermissions(action="getRole", roleIdentity="<i>")` |
+| `tcb role get --name <n>` | `queryPermissions(action="getRole", roleName="<n>")` |
+| `tcb role create` | `managePermissions(action="createRole", roleName, roleIdentity, policies, memberUids)` |
+| `tcb role update --add-users` | `managePermissions(action="addRoleMembers", roleId, memberUids)` |
+| `tcb role update --add-policies` | `managePermissions(action="addRolePolicies", roleId, policies)` |
+| `tcb role delete` | `managePermissions(action="deleteRoles", roleIds)` |
+| `tcb permission get table:users` | `queryPermissions(action="getResourcePermission", resourceType="sqlDatabase", resourceId="users")` |
+| `tcb permission set table:users --level readonly` | `managePermissions(action="updateResourcePermission", resourceType="sqlDatabase", resourceId="users", permission="READONLY")` |
+| `tcb user list` | `queryPermissions(action="listUsers")` |
+| `tcb user update <uid> --status BLOCKED` | `managePermissions(action="updateUser", uid="<uid>", userStatus="BLOCKED")` |
+
+> ⚠️ Do NOT attempt `tcb` commands when CLI is disabled. Check the runtime capability notice to determine available interfaces.
+
 ---
 
 ## When to Use

mcp/src/tools/permissions.test.ts

@@ -127,6 +127,19 @@ describe("permission tools", () => {
     ({ tools } = createMockServer());
   });
 
+  it("queryPermissions metadata should explain CLI role mapping", () => {
+    const meta = tools.queryPermissions.meta;
+
+    expect(meta.description).toContain("tcb role list");
+    expect(meta.description).toContain("tcb role get --id|--identity|--name");
+    expect(meta.description).toContain("成员列表");
+    expect(meta.inputSchema.action.description).toContain("listRoles");
+    expect(meta.inputSchema.action.description).toContain("tcb role get --id|--identity|--name");
+    expect(meta.inputSchema.roleId.description).toContain("tcb role get --id <roleId>");
+    expect(meta.inputSchema.roleIdentity.description).toContain("tcb role get --identity <roleIdentity>");
+    expect(meta.inputSchema.roleName.description).toContain("tcb role get --name <roleName>");
+  });
+
   it("queryPermissions(action=listUsers) should use user service", async () => {
     const result = await tools.queryPermissions.handler({ action: "listUsers" });
     const payload = JSON.parse(result.content[0].text);

mcp/src/tools/permissions.ts

@@ -342,17 +342,30 @@ export function registerPermissionTools(server: ExtendedMcpServer) {
     {
       title: "查询权限与用户配置",
       description:
-        "权限域统一只读入口。支持查询资源权限、角色列表/详情、应用用户列表/详情。",
+        '权限域统一只读入口。支持查询资源权限、角色列表/详情、应用用户列表/详情。角色查询等价于 CLI `tcb role list` / `tcb role get --id|--identity|--name [--detail]`：`listRoles` 用于列出角色，`getRole` 用于按角色 ID、标识或名称读取单个角色，并返回成员列表与策略列表等详情。',
       inputSchema: {
-        action: z.enum(QUERY_PERMISSION_ACTIONS),
+        action: z
+          .enum(QUERY_PERMISSION_ACTIONS)
+          .describe(
+            '可填写的值: `getResourcePermission`, `listResourcePermissions`, `listRoles`, `getRole`, `listUsers`, `getUser`。角色查询时：`listRoles` 等价于 `tcb role list`，`getRole` 等价于 `tcb role get --id|--identity|--name [--detail]`。',
+          ),
         resourceType: z
           .enum(["noSqlDatabase", "sqlDatabase", "function", "storage"])
           .optional(),
         resourceId: z.string().optional(),
         resourceIds: z.array(z.string()).optional(),
-        roleId: z.string().optional(),
-        roleIdentity: z.string().optional(),
-        roleName: z.string().optional(),
+        roleId: z
+          .string()
+          .optional()
+          .describe('action=`getRole` 时按角色 ID 查询，等价于 `tcb role get --id <roleId>`。与 `roleIdentity` / `roleName` 三选一。'),
+        roleIdentity: z
+          .string()
+          .optional()
+          .describe('action=`getRole` 时按角色标识查询，等价于 `tcb role get --identity <roleIdentity>`。与 `roleId` / `roleName` 三选一。'),
+        roleName: z
+          .string()
+          .optional()
+          .describe('action=`getRole` 时按角色名称查询，等价于 `tcb role get --name <roleName>`。与 `roleId` / `roleIdentity` 三选一。'),
         uid: z.string().optional(),
         username: z.string().optional(),
         pageNo: z.number().optional(),
@@ -563,9 +576,13 @@ export function registerPermissionTools(server: ExtendedMcpServer) {
     {
       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 模板。",
+        '权限域统一写入口。支持修改资源权限、角色管理、成员与策略增删、应用用户 CRUD。角色写操作等价于 CLI `tcb role create` / `tcb role update` / `tcb role delete` 以及成员、策略增删。`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 模板。',
       inputSchema: {
-        action: z.enum(MANAGE_PERMISSION_ACTIONS),
+        action: z
+          .enum(MANAGE_PERMISSION_ACTIONS)
+          .describe(
+            '可填写的值: `updateResourcePermission`, `createRole`, `updateRole`, `deleteRoles`, `addRoleMembers`, `removeRoleMembers`, `addRolePolicies`, `removeRolePolicies`, `createUser`, `updateUser`, `deleteUsers`。角色写操作可对应 CLI `tcb role create/update/delete`。',
+          ),
         resourceType: z
           .enum(["noSqlDatabase", "sqlDatabase", "function", "storage"])
           .optional()