diff --git a/config/.claude/skills/cloudbase-cli/SKILL.md b/config/.claude/skills/cloudbase-cli/SKILL.md index 41f20af2..03ce4dea 100644 --- a/config/.claude/skills/cloudbase-cli/SKILL.md +++ b/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 ` | `queryPermissions(action="getRole", roleId="")` | +| `tcb role get --identity ` | `queryPermissions(action="getRole", roleIdentity="")` | +| `tcb role get --name ` | `queryPermissions(action="getRole", roleName="")` | +| `tcb role create --name --identity ` | `managePermissions(action="createRole", roleName="", roleIdentity="", policies=[...], memberUids=[...])` | +| `tcb role update --id --add-users` | `managePermissions(action="updateRole", roleId="", memberUids=[...])` or `managePermissions(action="addRoleMembers", ...)` | +| `tcb role update --id --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 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 ` | `queryPermissions(action="listUsers", username="")` | +| `tcb user update --status BLOCKED` | `managePermissions(action="updateUser", uid="", userStatus="BLOCKED")` | + +### Function Management + +| CLI Command | MCP Tool Equivalent | +|-------------|---------------------| +| `tcb fn list` | `queryFunctions(action="listFunctions")` | +| `tcb fn detail ` | `queryFunctions(action="getFunction", functionName="")` | +| `tcb fn logs ` | `queryFunctions(action="getFunctionLogs", functionName="")` | +| `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 ` | `readNoSqlDatabaseContent(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, diff --git a/config/.claude/skills/cloudbase-cli/references/permission.md b/config/.claude/skills/cloudbase-cli/references/permission.md index 065fd14a..6226c103 100644 --- a/config/.claude/skills/cloudbase-cli/references/permission.md +++ b/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 ` | `queryPermissions(action="getRole", roleId="")` | +| `tcb role get --identity ` | `queryPermissions(action="getRole", roleIdentity="")` | +| `tcb role get --name ` | `queryPermissions(action="getRole", roleName="")` | +| `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 --status BLOCKED` | `managePermissions(action="updateUser", uid="", userStatus="BLOCKED")` | + +> ⚠️ Do NOT attempt `tcb` commands when CLI is disabled. Check the runtime capability notice to determine available interfaces. + --- ## When to Use diff --git a/config/source/skills/cloudbase-cli/SKILL.md b/config/source/skills/cloudbase-cli/SKILL.md index 41f20af2..03ce4dea 100644 --- a/config/source/skills/cloudbase-cli/SKILL.md +++ b/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 ` | `queryPermissions(action="getRole", roleId="")` | +| `tcb role get --identity ` | `queryPermissions(action="getRole", roleIdentity="")` | +| `tcb role get --name ` | `queryPermissions(action="getRole", roleName="")` | +| `tcb role create --name --identity ` | `managePermissions(action="createRole", roleName="", roleIdentity="", policies=[...], memberUids=[...])` | +| `tcb role update --id --add-users` | `managePermissions(action="updateRole", roleId="", memberUids=[...])` or `managePermissions(action="addRoleMembers", ...)` | +| `tcb role update --id --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 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 ` | `queryPermissions(action="listUsers", username="")` | +| `tcb user update --status BLOCKED` | `managePermissions(action="updateUser", uid="", userStatus="BLOCKED")` | + +### Function Management + +| CLI Command | MCP Tool Equivalent | +|-------------|---------------------| +| `tcb fn list` | `queryFunctions(action="listFunctions")` | +| `tcb fn detail ` | `queryFunctions(action="getFunction", functionName="")` | +| `tcb fn logs ` | `queryFunctions(action="getFunctionLogs", functionName="")` | +| `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 ` | `readNoSqlDatabaseContent(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, diff --git a/config/source/skills/cloudbase-cli/references/permission.md b/config/source/skills/cloudbase-cli/references/permission.md index 065fd14a..6226c103 100644 --- a/config/source/skills/cloudbase-cli/references/permission.md +++ b/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 ` | `queryPermissions(action="getRole", roleId="")` | +| `tcb role get --identity ` | `queryPermissions(action="getRole", roleIdentity="")` | +| `tcb role get --name ` | `queryPermissions(action="getRole", roleName="")` | +| `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 --status BLOCKED` | `managePermissions(action="updateUser", uid="", userStatus="BLOCKED")` | + +> ⚠️ Do NOT attempt `tcb` commands when CLI is disabled. Check the runtime capability notice to determine available interfaces. + --- ## When to Use diff --git a/mcp/src/tools/permissions.test.ts b/mcp/src/tools/permissions.test.ts index 6b34fdc4..2d0de810 100644 --- a/mcp/src/tools/permissions.test.ts +++ b/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 "); + expect(meta.inputSchema.roleIdentity.description).toContain("tcb role get --identity "); + expect(meta.inputSchema.roleName.description).toContain("tcb role get --name "); + }); + 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); diff --git a/mcp/src/tools/permissions.ts b/mcp/src/tools/permissions.ts index 350bc3f3..5b736946 100644 --- a/mcp/src/tools/permissions.ts +++ b/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 `。与 `roleIdentity` / `roleName` 三选一。'), + roleIdentity: z + .string() + .optional() + .describe('action=`getRole` 时按角色标识查询，等价于 `tcb role get --identity `。与 `roleId` / `roleName` 三选一。'), + roleName: z + .string() + .optional() + .describe('action=`getRole` 时按角色名称查询，等价于 `tcb role get --name `。与 `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()