Merge pull request #505 from TencentCloudBase/feature/update-skills-and-configs

feat(tooling): ✨ expand manager-node 5.1 auth and workflow support

Author: binggg

config/source/skills/auth-tool/SKILL.md

@@ -375,7 +375,25 @@ Prefer MCP: `queryAppAuth(action="getStaticDomain")` — use `cdnDomain` / `stat
 }
 ```
 
-### 8. Client Configuration Boundary
+### 8. Provider Lifecycle Boundary
+
+Use provider lifecycle APIs when the identity source itself needs to be created, updated, or removed.
+
+Preferred MCP tool path:
+
+- `queryAppAuth(action="listProviders")`
+- `queryAppAuth(action="getProvider")`
+- `manageAppAuth(action="addProvider")`
+- `manageAppAuth(action="updateProvider")`
+- `manageAppAuth(action="deleteProvider")`
+
+Guidance:
+
+- Use `addProvider` when the provider record does not exist yet and you need to create it with `providerType`, optional `providerId`, `displayName`, and `config`.
+- Use `updateProvider` when the provider already exists and only its configuration or enablement state needs to change.
+- Use `deleteProvider` when the provider must be removed entirely instead of only disabling it.
+
+### 9. Client Configuration Boundary
 
 Use client APIs for client metadata and token/session settings. Do not use them as a replacement for login strategy or provider management.
 
@@ -410,14 +428,20 @@ Both tools should default to the current selected environment's default client.
 }
 ```
 
-### 9. Get Publishable Key
+### 10. Publishable Key and API Key Boundary
 
 Preferred MCP tool path:
 
 - `queryAppAuth(action="getPublishableKey")`
 - `manageAppAuth(action="ensurePublishableKey")`
+- `queryAppAuth(action="listApiKeys")`
+- `manageAppAuth(action="createApiKey")`
+- `manageAppAuth(action="deleteApiKey")`
+
+Use the shortcut pair `getPublishableKey` / `ensurePublishableKey` for the most common frontend-readiness flow.
+Use the generic API key lifecycle actions when you need inventory, pagination, non-publishable keys, or explicit deletion.
 
-**Query existing key**:
+**Query existing publishable key**:
 ```js
 {
     "params": { "EnvId": `env`, "KeyType": "publish_key", "PageNumber": 1, "PageSize": 10 },
@@ -427,7 +451,18 @@ Preferred MCP tool path:
 ```
 `queryAppAuth(action="getPublishableKey")` should always force `KeyType="publish_key"` and return a short payload with `publishableKey`, `keyId`, `keyName`, `expireAt`, and `createdAt`.
 
-**Ensure key exists**:
+**List API keys**:
+```json
+{
+  "action": "listApiKeys",
+  "keyType": "api_key",
+  "pageNumber": 1,
+  "pageSize": 20
+}
+```
+Use `listApiKeys` for a general key inventory view. It supports optional `keyType`, `pageNumber`, and `pageSize`.
+
+**Ensure publishable key exists**:
 ```js
 {
     "params": { "EnvId": `env`, "KeyType": "publish_key" },
@@ -437,9 +472,29 @@ Preferred MCP tool path:
 ```
 `manageAppAuth(action="ensurePublishableKey")` should first query the existing `publish_key`; if one already exists, return it directly; otherwise create it and return the new key. This keeps the MCP interface short and avoids requiring the model to reason about `KeyType` or whether a key already exists.
 
+**Create a generic API key**:
+```json
+{
+  "action": "createApiKey",
+  "keyType": "api_key",
+  "keyName": "server-prod",
+  "expireIn": 86400
+}
+```
+`createApiKey` defaults to `publish_key` when `keyType` is omitted, but it can also create `api_key` for generic service-side access.
+
+**Delete an API key**:
+```json
+{
+  "action": "deleteApiKey",
+  "keyId": "api-key-id"
+}
+```
+Use `deleteApiKey` only when you intentionally want to revoke that key token.
+
 If creation fails, direct user to: "https://tcb.cloud.tencent.com/dev?envId=`env`#/env/apikey"
 
-### 10. Custom Login Keys
+### 11. Custom Login Keys
 
 Preferred MCP tool path: `manageAppAuth(action="createCustomLoginKeys")`
 

doc/mcp-tools.md

@@ -793,18 +793,24 @@ API名：storage API介绍：Storage API - 云存储 HTTP API
 ---
 
 ### `manageAppAuth`
-应用侧认证配置写入口。用于修改登录方式、provider、client 配置，确保 publishable key 和创建自定义登录密钥。
+应用侧认证配置写入口。用于修改登录方式、provider、client 配置，以及创建或删除 API key、自定义登录密钥。
 
 #### 参数
 
 <table>
 <thead><tr><th>参数名</th><th>类型</th><th>必填</th><th>说明</th></tr></thead>
 <tbody>
-<tr><td><code>action</code></td><td>string</td><td>是</td><td>可填写的值: "patchLoginStrategy", "updateProvider", "updateClientConfig", "ensurePublishableKey", "createCustomLoginKeys"</td></tr>
+<tr><td><code>action</code></td><td>string</td><td>是</td><td>可填写的值: "patchLoginStrategy", "addProvider", "updateProvider", "deleteProvider", "updateClientConfig", "ensurePublishableKey", "createApiKey", "deleteApiKey", "createCustomLoginKeys"</td></tr>
 <tr><td><code>patch</code></td><td>object</td><td></td><td>patchLoginStrategy 使用的简化登录策略 patch，如 &#123; usernamePassword: true &#125;</td></tr>
-<tr><td><code>providerId</code></td><td>string</td><td></td><td>provider 标识，如 email、google</td></tr>
+<tr><td><code>providerId</code></td><td>string</td><td></td><td>provider 标识，如 email、google；addProvider 时也可作为自定义 provider Id</td></tr>
+<tr><td><code>providerType</code></td><td>string</td><td></td><td>addProvider 时的 provider 协议类型，如 OAUTH、OIDC、EMAIL</td></tr>
+<tr><td><code>displayName</code></td><td>string or object</td><td></td><td>addProvider 时的展示名称，可传字符串或多语言对象</td></tr>
 <tr><td><code>clientId</code></td><td>string</td><td></td><td>updateClientConfig 时的客户端 Id；省略时默认使用当前环境 ID</td></tr>
 <tr><td><code>config</code></td><td>object</td><td></td><td>provider / client 的配置对象</td></tr>
+<tr><td><code>keyType</code></td><td>string</td><td></td><td>createApiKey 时的 API key 类型，默认 "publish_key"</td></tr>
+<tr><td><code>keyName</code></td><td>string</td><td></td><td>createApiKey 时的 API key 名称</td></tr>
+<tr><td><code>expireIn</code></td><td>number</td><td></td><td>createApiKey 时的有效期，单位秒；0 表示不过期</td></tr>
+<tr><td><code>keyId</code></td><td>string</td><td></td><td>deleteApiKey 时的 API key 唯一标识</td></tr>
 </tbody>
 </table>
 

mcp/package-lock.json

@@ -65,7 +65,7 @@
   "dependencies": {
     "@cloudbase/cals": "^1.2.23",
     "@cloudbase/functions-framework": "^1.14.0",
-    "@cloudbase/manager-node": "5.0.0",
+    "@cloudbase/manager-node": "^5.1.0",
     "@cloudbase/mcp": "^1.0.0-beta.25",
     "@cloudbase/toolbox": "^0.7.19",
     "@modelcontextprotocol/sdk": "1.13.1",

mcp/package.json

@@ -121,6 +121,121 @@ describe("cloudbase manager auth gate", () => {
     await expect(getEnvId()).resolves.toBe("env-1");
   });
 
+  it("should resolve actual env region when envId is provided without region", async () => {
+    process.env.TCB_REGION = "ap-shanghai";
+    mockPeekLoginState.mockResolvedValue({
+      secretId: "sid",
+      secretKey: "skey",
+      token: "token",
+    });
+    mockCommonServiceCall.mockResolvedValue({
+      EnvList: [
+        {
+          EnvId: "env-explicit",
+          Alias: "prod",
+          Region: "ap-guangzhou",
+        },
+      ],
+    });
+
+    const { getCloudBaseManager } = await import("./cloudbase-manager.js");
+
+    await expect(
+      getCloudBaseManager({
+        cloudBaseOptions: {
+          envId: "env-explicit",
+        },
+      }),
+    ).resolves.toMatchObject({
+      commonService: expect.any(Function),
+      env: expect.any(Object),
+    });
+
+    expect(mockCloudBaseCtor).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        secretId: "sid",
+        secretKey: "skey",
+        token: "token",
+        envId: "env-explicit",
+        region: "ap-guangzhou",
+      }),
+    );
+    expect(mockCommonServiceCall).toHaveBeenCalledWith(
+      expect.objectContaining({
+        Action: "DescribeEnvs",
+      }),
+    );
+  });
+
+  it("should honor explicit region without resolving env candidates", async () => {
+    mockPeekLoginState.mockResolvedValue({
+      secretId: "sid",
+      secretKey: "skey",
+      token: "token",
+    });
+
+    const { getCloudBaseManager } = await import("./cloudbase-manager.js");
+
+    await expect(
+      getCloudBaseManager({
+        cloudBaseOptions: {
+          envId: "env-explicit",
+          region: "ap-guangzhou",
+        },
+      }),
+    ).resolves.toMatchObject({
+      commonService: expect.any(Function),
+      env: expect.any(Object),
+    });
+
+    expect(mockCloudBaseCtor).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        secretId: "sid",
+        secretKey: "skey",
+        token: "token",
+        envId: "env-explicit",
+        region: "ap-guangzhou",
+      }),
+    );
+    expect(mockCommonServiceCall).not.toHaveBeenCalled();
+  });
+
+  it("should prefer actual env region over fallback region when login envId is already known", async () => {
+    process.env.TCB_REGION = "ap-shanghai";
+    mockPeekLoginState.mockResolvedValue({
+      secretId: "sid",
+      secretKey: "skey",
+      token: "token",
+      envId: "env-guangzhou",
+    });
+    mockCommonServiceCall.mockResolvedValue({
+      EnvList: [
+        {
+          EnvId: "env-guangzhou",
+          Alias: "prod",
+          Region: "ap-guangzhou",
+        },
+      ],
+    });
+
+    const { getCloudBaseManager } = await import("./cloudbase-manager.js");
+
+    await expect(getCloudBaseManager()).resolves.toMatchObject({
+      commonService: expect.any(Function),
+      env: expect.any(Object),
+    });
+
+    expect(mockCloudBaseCtor).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        secretId: "sid",
+        secretKey: "skey",
+        token: "token",
+        envId: "env-guangzhou",
+        region: "ap-guangzhou",
+      }),
+    );
+  });
+
   it("should fail fast with ENV_REQUIRED when login exists but multiple envs", async () => {
     mockPeekLoginState.mockResolvedValue({
       secretId: "sid",