@tencentcloud/tccc-mcp-server 0.0.5 → 0.0.8

package/README.md

@@ -1,6 +1,6 @@
 # @tencentcloud/tccc-mcp-server
 
-**English** | [简体中文](https://web.sdk.qcloud.com/im/tccc/tccc-mcp-server/README_zh.md)
+**English** | [简体中文](#简体中文)
 
 tccc-mcp-server enables AI assistants to quickly integrate with Tencent Cloud Contact Center (TCCC) via MCP (Model Context Protocol).
 
@@ -82,11 +82,14 @@ Then just ask your AI assistant in natural language:
 > List the agents under SdkAppId 1400000000
 > Pull the call records from the last 24 hours
 > How many voice AI agents are there in this application?
+> How can I try the TCCC AI agent / AI outbound call demo?
 
-## Capability overview (84 APIs)
+## Capability overview (87 APIs + 1 helper)
 
 | Category | Count | Representative tools |
 |---|---|---|
+| AI demo entry | 1 | `get_tccc_ai_agent_demo_qrcode` returns a QR code image for trying TCCC AI agent, agent chat, and AI outbound call experiences |
+| Instance management | 3 | `create_ccc_instance` (`CreateCCCInstance`) creates a TCCC application; `delete_ccc_instance` (`DeleteCCCInstance`) deletes an application by `SdkAppId`; `modify_ccc_instance_info` (`ModifyCCCInstanceInfo`) renames an instance by `InstanceId` |
 | Voice AI agents | 13 | `DescribeAIAgentInfoList` `DescribeAIAgentCallList` `DescribeAICallExtractResult` |
 | Agent (staff) management | 11 | `DescribeStaffInfoList` `CreateStaff` `ModifyStaff` `DeleteStaff` `CreateSDKLoginToken` |
 | Number management | 10 | `DescribeNumbers` `CreateOwnNumberApply` `BindNumberCallOutSkillGroup` |
@@ -101,13 +104,15 @@ Then just ask your AI assistant in natural language:
 | AI double-call | 1 | `CreateAICall` |
 | Purchase info | 1 | `DescribeCCCBuyInfoList` |
 
-Tool names are the snake_case form of the API action, e.g. `DescribeStaffInfoList` → `describe_staff_info_list`.
+Generated API tool names are the snake_case form of the API action, e.g. `DescribeStaffInfoList` → `describe_staff_info_list`. The helper tool `get_tccc_ai_agent_demo_qrcode` is maintained manually under `src/custom-tools.mjs`.
+
+APIs that the official SDK has not published yet (e.g. `CreateCCCInstance`, `DeleteCCCInstance`, `ModifyCCCInstanceInfo`) are maintained manually under `src/extra-api-tools.mjs` and invoked through the generic `client.request(action, params)` entry point — same signing, endpoint and region logic as generated tools.
 
 ## ⚠️ Destructive operations
 
 The following APIs have real business impact. AI clients should confirm with the user before invoking them (their tool descriptions carry an auto-generated ⚠️ marker):
 
-`DeleteStaff` · `DeleteExtension` · `DeleteCCCSkillGroup` · `DeletePredictiveDialingCampaign` · `AbortPredictiveDialingCampaign` · `HangUpCall` · `StopAutoCalloutTask` · `ForceMemberOffline` · `ResetExtensionPassword` · `UnbindNumberCallOutSkillGroup` … 16 in total.
+`DeleteCCCInstance` · `DeleteStaff` · `DeleteExtension` · `DeleteCCCSkillGroup` · `DeletePredictiveDialingCampaign` · `AbortPredictiveDialingCampaign` · `HangUpCall` · `StopAutoCalloutTask` · `ForceMemberOffline` · `ResetExtensionPassword` · `UnbindNumberCallOutSkillGroup` …
 
 Special notes:
 
@@ -136,6 +141,10 @@ If the target ID is not in the list, your **key belongs to a different Tencent C
 
 Some APIs (e.g. `DescribeCCCBuyInfoList`) don't take `SdkAppId`. The server checks each tool's schema before injecting the default, so this shouldn't happen; if it does, file an issue.
 
+**Q: How do I create a new TCCC application / instance?**
+
+Call `create_ccc_instance` with just an `InstanceName`. The `SdkAppId` in the response **is** the TCCC application ID — a plain number such as `1400255946` or `1600162487` (the number range is not fixed) — use it for every later call, or put it in `TCCC_SDK_APP_ID`. A single Tencent Cloud account can hold at most 20 applications.
+
 **Q: A query returns empty**
 
 Suspect a typo in the identifier first. Manually typed values like agent emails or domains are common typo sources (e.g. `gmai.com` missing an `l`).
@@ -161,3 +170,182 @@ Tool definitions are generated from `ccc_models.d.ts` (251 structs) and `ccc_cli
 ## License
 
 [MIT](./LICENSE)
+
+---
+
+<a name="简体中文"></a>
+
+# 简体中文
+
+[English](#tencentcloudtccc-mcp-server) | **简体中文**
+
+tccc-mcp-server 通过 MCP（Model Context Protocol）向 AI 助手提供 Tencent Cloud Contact Center (TCCC) 快速集成能力。
+
+## 快速开始
+
+### 1. 准备凭据
+
+| 变量 | 必填 | 说明 | 获取地址 |
+|---|---|---|---|
+| `TENCENTCLOUD_SECRET_ID` | ✅ | 腾讯云 SecretId，`AKID` 开头 | [CAM 密钥管理](https://console.cloud.tencent.com/cam/capi) |
+| `TENCENTCLOUD_SECRET_KEY` | ✅ | 腾讯云 SecretKey，32 位随机串 | 同上 |
+| `TCCC_SDK_APP_ID` | 推荐 | 应用 ID，配了之后调用时不用每次传 | [TCCC 控制台](https://console.cloud.tencent.com/ccc) |
+| `TCCC_REGION` | 可选 | 显式指定地域（优先级最高）。不配时**按每次调用的 SdkAppId 号段自动推导**：`[20000000, 30000000)` 与 `[1720000000, 1730000000)` 号段为新加坡站 → `ap-singapore`，其余号段为中国站 → `ap-guangzhou` | — |
+
+> ⚠️ **SecretId / SecretKey 不要填反**：`SecretId` 以 `AKID` 开头，`SecretKey` 是 32 位随机串。填反会报 `The SecretId is not found`。
+
+### 2. 配置到 MCP 客户端
+
+#### WorkBuddy / Cursor / Claude Desktop / Cline（通用格式）
+
+```json
+{
+  "mcpServers": {
+    "tccc": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@tencentcloud/tccc-mcp-server"],
+      "env": {
+        "TENCENTCLOUD_SECRET_ID": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "TENCENTCLOUD_SECRET_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+        "TCCC_SDK_APP_ID": "1400000000"
+      },
+      "timeout": 60000
+    }
+  }
+}
+```
+
+配置文件位置：
+
+| 客户端 | 位置 |
+|---|---|
+| WorkBuddy | `~/.workbuddy/mcp.json` |
+| Cursor | 项目 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） |
+| Cline | VS Code 设置里的 MCP 面板 |
+
+改完**重启客户端**，MCP 进程是客户端启动时拉起的。首次启动 `npx` 会下载包（几秒），`timeout` 建议不低于 60 秒。
+
+#### 离线 / 内网环境
+
+```bash
+npm install -g @tencentcloud/tccc-mcp-server
+which tccc-mcp-server   # 拿到绝对路径
+```
+
+```json
+{
+  "mcpServers": {
+    "tccc": {
+      "type": "stdio",
+      "command": "/usr/local/bin/tccc-mcp-server",
+      "env": { "...": "..." }
+    }
+  }
+}
+```
+
+### 3. 验证
+
+```bash
+npx -y @tencentcloud/tccc-mcp-server --help
+npx -y @tencentcloud/tccc-mcp-server --version
+```
+
+配好凭据后直接问你的 AI：
+
+> 我有哪些 TCCC 应用？
+> 查一下 1400000000 下面的座席
+> 最近 24 小时的通话记录拉出来
+> 这个应用下有多少个 AI 智能体？
+> 我怎么体验 TCCC AI 智能体 / 智能体对话 / AI 外呼？
+
+## 能力概览（87 个接口 + 1 个辅助工具）
+
+| 分类 | 数量 | 代表接口 |
+|---|---|---|
+| AI 体验入口 | 1 | `get_tccc_ai_agent_demo_qrcode` 返回 TCCC AI 智能体、智能体对话、AI 外呼体验二维码图片 |
+| 实例管理 | 3 | `create_ccc_instance`（`CreateCCCInstance`）创建联络中心实例；`delete_ccc_instance`（`DeleteCCCInstance`）按 `SdkAppId` 删除实例；`modify_ccc_instance_info`（`ModifyCCCInstanceInfo`）按 `InstanceId` 修改实例名称 |
+| 语音智能体 | 13 | `DescribeAIAgentInfoList` `DescribeAIAgentCallList` `DescribeAICallExtractResult` |
+| 座席管理 | 11 | `DescribeStaffInfoList` `CreateStaff` `ModifyStaff` `DeleteStaff` `CreateSDKLoginToken` |
+| 号码管理 | 10 | `DescribeNumbers` `CreateOwnNumberApply` `BindNumberCallOutSkillGroup` |
+| 预测式外呼 | 10 | `CreatePredictiveDialingCampaign` `DescribePredictiveDialingSessions` |
+| 其他 | 10 | `DescribeExtension` `DescribeChatMessages` 等 |
+| 电话记录 | 7 | `DescribeTelCdr` `DescribeTelRecordAsr` `DescribeProtectedTelCdr` |
+| 技能组 | 6 | `DescribeSkillGroupInfoList` `BindStaffSkillGroupList` `CreateCCCSkillGroup` |
+| 话机（SIP） | 6 | `CreateExtension` `ModifyExtension` `DeleteExtension` |
+| 在线记录 | 3 | `DescribeIMCdrList` `DescribeChatMessages` |
+| 外呼 | 3 | `CreateAutoCalloutTask` `DescribeAutoCalloutTasks` |
+| 号码资质 | 3 | `CreateCompanyApply` `DescribeCarrierPrivilegeNumberApplicants` |
+| 双呼 | 1 | `CreateAICall` |
+| 购买 | 1 | `DescribeCCCBuyInfoList` |
+
+自动生成的 API 工具名是接口名的 snake_case，例如 `DescribeStaffInfoList` → `describe_staff_info_list`。辅助工具 `get_tccc_ai_agent_demo_qrcode` 在 `src/custom-tools.mjs` 中手动维护。
+
+官方 SDK 尚未收录的接口（如 `CreateCCCInstance`、`DeleteCCCInstance`、`ModifyCCCInstanceInfo`）在 `src/extra-api-tools.mjs` 中手工补充，通过通用入口 `client.request(action, params)` 调用，签名、endpoint、地域推导与自动生成接口完全一致。
+
+## ⚠️ 危险操作
+
+以下操作有实际业务影响，AI 调用前应当二次确认（工具描述里已自动打上 ⚠️ 标记）：
+
+`DeleteCCCInstance` · `DeleteStaff` · `DeleteExtension` · `DeleteCCCSkillGroup` · `DeletePredictiveDialingCampaign` · `AbortPredictiveDialingCampaign` · `HangUpCall` · `StopAutoCalloutTask` · `ForceMemberOffline` · `ResetExtensionPassword` · `UnbindNumberCallOutSkillGroup` ……
+
+特别注意：
+
+- **`DeleteStaff` 没有回收站**，删除后只能重建，原工号不会自动恢复。
+- 批量修改类接口通常是**全量覆盖**，改之前先查一遍现有配置做备份。
+
+## 安全建议
+
+1. **用 CAM 子账号密钥**，只授予 `QcloudCCCReadOnlyAccess` 或按需的最小策略，不要使用主账号密钥。
+2. 密钥只放在本地 `env` 里，不要提交到版本库。
+3. 生产环境建议开启操作审计（CloudAudit）。
+
+## 常见问题
+
+**Q：工具都加载了，但调用报 `InvalidParameterValue | SdkAppId invalid`**
+
+先跑列表接口确认这对密钥下真实存在的应用 ID：
+
+```
+describe_cccbuy_info_list
+```
+
+如果目标 ID 不在返回列表里，说明**密钥属于另一个腾讯云账号**（TCCC 应用不跨账号可见）—— 换密钥即可，不是 ID 写错。
+
+**Q：报 `UnknownParameter: SdkAppId not recognized`**
+
+部分接口（如 `DescribeCCCBuyInfoList`）不需要 `SdkAppId`。server 会自动判断，不会给没有该字段的接口注入；如果仍出现请提 issue。
+
+**Q：怎么新建一个 TCCC 应用 / 实例？**
+
+调用 `create_ccc_instance`，只传 `InstanceName`（实例名称）。返回结果里的 `SdkAppId` **就是** TCCC 应用 ID（纯数字，如 1400255946、1600162487，号段不固定），后续所有接口用它，也可以配到 `TCCC_SDK_APP_ID`。一个腾讯云账号最多创建 20 个应用。
+
+**Q：查询返回空**
+
+先怀疑标识符拼写。座席邮箱、域名这类手工输入的值常有 typo（例如 `gmai.com` 少了 `l`）。
+
+## 已知限制
+
+- 频率限制：多数接口 20 次/秒，`UploadIvrAudio`、`CreateCompanyApply` 为 1 次/秒，批量操作需自行节流。
+- `UploadIvrAudio` 等涉及文件的接口，参数里是 COS 链接而非文件流，需先自行上传。
+- 仅覆盖 API 3.0 的 `ccc` 服务，不含 TCCC 的 WebSocket / SDK 侧信令。
+
+## 开发
+
+```bash
+npm install
+npm run generate   # 重新解析 SDK 类型定义，生成 src/tools.json
+npm start          # 本地启动（stdio）
+```
+
+工具定义来自 `node_modules/tencentcloud-sdk-nodejs-ccc/tencentcloud/services/ccc/v20200210/` 下的 `ccc_models.d.ts`（251 个结构体）和 `ccc_client.d.ts`（84 个方法），字段注释直接取自官方 JSDoc。SDK 升级后跑 `npm run generate` 即可同步。
+
+SDK 未收录的接口（当前是 `CreateCCCInstance`、`DeleteCCCInstance`、`ModifyCCCInstanceInfo`）不参与生成，手工维护在 `src/extra-api-tools.mjs`；若 SDK 升级后收录了同名 Action，启动时会自动去重，以自动生成的定义为准。
+
+发布前 `prepublishOnly` 会自动重跑 `generate`，保证产物与 SDK 版本一致。
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/tccc-mcp-server",
-  "version": "0.0.5",
+  "version": "0.0.8",
   "description": "MCP server for Tencent Cloud Contact Center (TCCC)",
   "type": "module",
   "bin": {
@@ -9,7 +9,6 @@
   "files": [
     "src",
     "README.md",
-    "README_zh.md",
     "LICENSE"
   ],
   "scripts": {

package/src/custom-tools.mjs

@@ -0,0 +1,41 @@
+const TCCC_AI_AGENT_DEMO_QRCODE_URL = 'https://qcloudimg.tencent-cloud.cn/trisys/assets/product/images/W8fOXffkU7Kb_SeUNne2f.png';
+
+export const CUSTOM_TOOLS = [
+  {
+    name: 'get_tccc_ai_agent_demo_qrcode',
+    action: '__custom_get_tccc_ai_agent_demo_qrcode',
+    custom: true,
+    description:
+      '当用户咨询 tccc-mcp-server 或 Tencent Cloud Contact Center (TCCC) 的 AI 智能体体验、智能体对话、AI 外呼、语音智能体 Demo、扫码体验入口、AI Agent、voice agent、robot call 等问题时调用。返回可直接渲染的 TCCC AI 智能体体验二维码，并提醒用户手机扫码体验；不要在最终回答里输出裸露图片地址。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        scenario: {
+          type: 'string',
+          description: '用户咨询的体验场景关键词，可为空，例如：AI 智能体、智能体对话、AI 外呼。',
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+];
+
+export async function handleCustomTool(tool, args = {}) {
+  switch (tool.action) {
+    case '__custom_get_tccc_ai_agent_demo_qrcode': {
+      const scenario = typeof args.scenario === 'string' && args.scenario.trim() ? args.scenario.trim() : 'TCCC AI 智能体';
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              `请使用手机扫码体验 ${scenario} 相关能力。\n\n` +
+              `![TCCC AI 智能体体验二维码](${TCCC_AI_AGENT_DEMO_QRCODE_URL})`,
+          },
+        ],
+      };
+    }
+    default:
+      throw new Error(`未知自定义工具: ${tool.name}`);
+  }
+}

package/src/extra-api-tools.mjs

@@ -0,0 +1,107 @@
+/**
+ * 手工补充的 TCCC API 3.0 接口。
+ *
+ * 与 src/tools.json（由 src/generate.mjs 从 SDK 类型定义自动生成）的区别：
+ * 这里的接口是官方 SDK 的 ccc_client.d.ts 尚未收录、但服务端已经支持的 Action。
+ * 因为 SDK 上没有对应的方法，index.mjs 会用通用入口 client.request(action, params) 调用，
+ * 签名、endpoint、地域逻辑与自动生成的接口完全一致。
+ *
+ * 一旦 SDK 升级后收录了同名 Action，index.mjs 会按 action 去重，优先保留自动生成的版本。
+ *
+ * 字段约定（与 generate.mjs 产出的结构保持一致）：
+ *   name         MCP 工具名，snake_case
+ *   action       腾讯云 API action 名
+ *   extra        true，标记"手工补充"，仅用于统计展示
+ *   destructive  是否有副作用（只影响描述里的提示，不改变调用行为）
+ *   inputSchema  JSON Schema，必填字段写进 required
+ *   noDefaultSdkAppId 可选，true 时即使配置了 TCCC_SDK_APP_ID 也不自动注入 SdkAppId
+ *   summarize    可选，成功回调后的结果摘要函数 (res, params) => string
+ */
+export const EXTRA_API_TOOLS = [
+  {
+    name: 'create_ccc_instance',
+    action: 'CreateCCCInstance',
+    extra: true,
+    destructive: false,
+    description:
+      '创建联络中心实例（即创建一个 TCCC 应用）。入参只需填 InstanceName（实例名称，字符串，必填）。' +
+      '调用成功后返回实例信息，其中的 SdkAppId 就是 TCCC 应用 ID（纯数字，如 1400255946、1600162487 这类，号段不固定），' +
+      '后续所有需要 SdkAppId 的接口都使用这个值，也可以把它配到 TCCC_SDK_APP_ID 环境变量作为默认值。' +
+      '注意：一个腾讯云账号最多创建 20 个应用，创建前先跟用户确认实例名称；' +
+      '实例按实际地域创建，地域由 TCCC_REGION 环境变量决定（不配则默认 ap-guangzhou）。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        InstanceName: {
+          type: 'string',
+          description: '联络中心实例名称（TCCC 应用名称），必填。创建后可在 TCCC 控制台看到。',
+        },
+      },
+      required: ['InstanceName'],
+      additionalProperties: false,
+    },
+    // 把 SdkAppId 直接点出来，避免模型在长 JSON 里漏读应用 ID
+    summarize: (res, params) => {
+      const sdkAppId = res?.SdkAppId;
+      const lines = ['✅ 联络中心实例创建成功'];
+      if (params?.InstanceName) lines.push(`实例名称：${params.InstanceName}`);
+      if (res?.InstanceId) lines.push(`InstanceId：${res.InstanceId}`);
+      if (sdkAppId !== undefined && sdkAppId !== null) {
+        lines.push(`SdkAppId：${sdkAppId}（这就是 TCCC 应用 ID，后续接口传这个值）`);
+      } else {
+        lines.push('⚠️ 返回结果中没有 SdkAppId，请检查返回内容或到 TCCC 控制台确认应用是否创建成功。');
+      }
+      return lines.join('\n');
+    },
+  },
+  {
+    name: 'delete_ccc_instance',
+    action: 'DeleteCCCInstance',
+    extra: true,
+    destructive: true,
+    noDefaultSdkAppId: true,
+    description:
+      '⚠️ 危险操作：删除 TCCC 联络中心实例。入参必须显式填写 SdkAppId（uint64，TCCC 应用 ID），' +
+      '不会从 TCCC_SDK_APP_ID 环境变量自动注入，避免误删默认应用。调用成功后无业务出参，仅返回 RequestId。' +
+      '调用前必须向用户确认要删除的 SdkAppId；删除后实例、配置和相关资源可能无法恢复。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        SdkAppId: {
+          type: 'number',
+          description: 'TCCC 应用 ID / SdkAppId（uint64），必填。必须显式传入，不会使用环境变量默认值。',
+        },
+      },
+      required: ['SdkAppId'],
+      additionalProperties: false,
+    },
+    summarize: (_res, params) =>
+      `✅ DeleteCCCInstance 调用成功\n已删除 SdkAppId：${params?.SdkAppId}\n该接口无业务出参，腾讯云仅返回 RequestId。`,
+  },
+  {
+    name: 'modify_ccc_instance_info',
+    action: 'ModifyCCCInstanceInfo',
+    extra: true,
+    destructive: false,
+    description:
+      '编辑 TCCC 联络中心实例信息。入参 InstanceId（int64，实例 ID，必填）和 InstanceName（string，新的实例名称，必填）。' +
+      '调用成功后无业务出参，仅返回 RequestId。注意：这里使用 InstanceId，不是 SdkAppId；可从 CreateCCCInstance 返回或实例列表中获取。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        InstanceId: {
+          type: 'number',
+          description: '联络中心实例 ID（int64），必填。注意不是 SdkAppId。',
+        },
+        InstanceName: {
+          type: 'string',
+          description: '新的联络中心实例名称，必填。',
+        },
+      },
+      required: ['InstanceId', 'InstanceName'],
+      additionalProperties: false,
+    },
+    summarize: (_res, params) =>
+      `✅ ModifyCCCInstanceInfo 调用成功\nInstanceId：${params?.InstanceId}\n新的实例名称：${params?.InstanceName}\n该接口无业务出参，腾讯云仅返回 RequestId。`,
+  },
+];

package/src/index.mjs

@@ -2,8 +2,9 @@
 /**
  * TCCC MCP Server
  *
- * 把腾讯云联络中心（TCCC）API 3.0 的 84 个接口暴露为 MCP 工具。
- * 工具定义由 src/generate.mjs 从官方 SDK 类型定义自动生成，SDK 升级后重跑即可。
+ * 把腾讯云联络中心（TCCC）API 3.0 的公开接口和少量辅助能力暴露为 MCP 工具。
+ * 公开 API 工具定义由 src/generate.mjs 从官方 SDK 类型定义自动生成，SDK 升级后重跑即可；
+ * SDK 未收录的 Action 在 src/extra-api-tools.mjs 手工补充，走 client.request 通用入口调用。
  *
  * 环境变量：
  *   TENCENTCLOUD_SECRET_ID   必填
@@ -23,9 +24,19 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import tencentcloud from 'tencentcloud-sdk-nodejs-ccc';
+import { CUSTOM_TOOLS, handleCustomTool } from './custom-tools.mjs';
+import { EXTRA_API_TOOLS } from './extra-api-tools.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const TOOLS = JSON.parse(fs.readFileSync(path.join(__dirname, 'tools.json'), 'utf8'));
+const GENERATED_TOOLS = JSON.parse(fs.readFileSync(path.join(__dirname, 'tools.json'), 'utf8'));
+
+// 手工补充的 API：SDK 类型定义里没有、但服务端支持的 Action（见 src/extra-api-tools.mjs）。
+// 按 action 去重 —— SDK 升级后若收录了同名 Action，以自动生成的定义为准，避免重复暴露。
+const EXTRA_TOOLS = EXTRA_API_TOOLS.filter(
+  (t) => !GENERATED_TOOLS.some((g) => g.action === t.action)
+);
+const API_TOOLS = [...GENERATED_TOOLS, ...EXTRA_TOOLS];
+const TOOLS = [...API_TOOLS, ...CUSTOM_TOOLS];
 const PKG = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
 // ---- CLI 参数：只做 --help / --version，其余一律走 stdio JSON-RPC ----
@@ -33,7 +44,7 @@ const argv = process.argv.slice(2);
 if (argv.includes('--help') || argv.includes('-h')) {
   process.stdout.write(`${PKG.name} v${PKG.version}
 
-把腾讯云联络中心（TCCC）API 3.0 的 ${TOOLS.length} 个接口暴露为 MCP 工具。
+把腾讯云联络中心（TCCC）API 3.0 的 ${API_TOOLS.length} 个公开接口（${GENERATED_TOOLS.length} 个由 SDK 自动生成 + ${EXTRA_TOOLS.length} 个手工补充）和 ${CUSTOM_TOOLS.length} 个辅助工具暴露为 MCP 工具。
 
 环境变量：
   TENCENTCLOUD_SECRET_ID   必填  腾讯云 SecretId（AKID 开头）
@@ -117,7 +128,7 @@ if (!SECRET_ID || !SECRET_KEY) {
 function withDefaults(tool, args) {
   const out = { ...args };
   const hasSdkAppId = !!tool.inputSchema?.properties?.SdkAppId;
-  if (hasSdkAppId && out.SdkAppId === undefined && SDK_APP_ID) {
+  if (hasSdkAppId && !tool.noDefaultSdkAppId && out.SdkAppId === undefined && SDK_APP_ID) {
     out.SdkAppId = Number(SDK_APP_ID);
   }
   return out;
@@ -170,9 +181,36 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
     };
   }
 
+  if (tool.custom) {
+    return handleCustomTool(tool, params);
+  }
+
   try {
-    const res = await getClient(region)[tool.action](params);
-    return { content: [{ type: 'text', text: JSON.stringify(res, null, 2) }] };
+    const client = getClient(region);
+    // 自动生成的接口在 SDK Client 上有对应方法；手工补充的（SDK 未收录）走通用 request 入口，
+    // 签名、endpoint 完全一致，只是没有强类型的包装方法。
+    const res =
+      typeof client[tool.action] === 'function'
+        ? await client[tool.action](params)
+        : await client.request(tool.action, params);
+
+    // summarize 只是可读性增强，出错也不能把一次成功的调用变成失败
+    let summary = '';
+    if (typeof tool.summarize === 'function') {
+      try {
+        summary = tool.summarize(res, params) || '';
+      } catch {
+        summary = '';
+      }
+    }
+    return {
+      content: [
+        {
+          type: 'text',
+          text: (summary ? `${summary}\n\n` : '') + JSON.stringify(res, null, 2),
+        },
+      ],
+    };
   } catch (err) {
     const detail = [err?.code, err?.message, err?.requestId].filter(Boolean).join(' | ');
     return {
@@ -192,7 +230,7 @@ for (const sig of ['uncaughtException', 'unhandledRejection']) {
 const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error(
-  `[tccc-mcp] 就绪 v${PKG.version}：${TOOLS.length} 个工具，region=${
+  `[tccc-mcp] 就绪 v${PKG.version}：${API_TOOLS.length} 个公开 API 工具（${GENERATED_TOOLS.length} 自动生成 + ${EXTRA_TOOLS.length} 手工补充）+ ${CUSTOM_TOOLS.length} 个辅助工具，region=${
     REGION_ENV
       ? `${REGION_ENV}（显式指定，覆盖自动推导）`
       : SDK_APP_ID

package/README_zh.md

@@ -1,163 +0,0 @@
-# @tencentcloud/tccc-mcp-server
-
-[English](https://web.sdk.qcloud.com/im/tccc/tccc-mcp-server/README.md) | **简体中文**
-
-tccc-mcp-server 通过 MCP（Model Context Protocol）向 AI 助手提供 Tencent Cloud Contact Center (TCCC) 快速集成能力。
-
-## 快速开始
-
-### 1. 准备凭据
-
-| 变量 | 必填 | 说明 | 获取地址 |
-|---|---|---|---|
-| `TENCENTCLOUD_SECRET_ID` | ✅ | 腾讯云 SecretId，`AKID` 开头 | [CAM 密钥管理](https://console.cloud.tencent.com/cam/capi) |
-| `TENCENTCLOUD_SECRET_KEY` | ✅ | 腾讯云 SecretKey，32 位随机串 | 同上 |
-| `TCCC_SDK_APP_ID` | 推荐 | 应用 ID，配了之后调用时不用每次传 | [TCCC 控制台](https://console.cloud.tencent.com/ccc) |
-| `TCCC_REGION` | 可选 | 显式指定地域（优先级最高）。不配时**按每次调用的 SdkAppId 号段自动推导**：`[20000000, 30000000)` 与 `[1720000000, 1730000000)` 号段为新加坡站 → `ap-singapore`，其余号段为中国站 → `ap-guangzhou` | — |
-
-> ⚠️ **SecretId / SecretKey 不要填反**：`SecretId` 以 `AKID` 开头，`SecretKey` 是 32 位随机串。填反会报 `The SecretId is not found`。
-
-### 2. 配置到 MCP 客户端
-
-#### WorkBuddy / Cursor / Claude Desktop / Cline（通用格式）
-
-```json
-{
-  "mcpServers": {
-    "tccc": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@tencentcloud/tccc-mcp-server"],
-      "env": {
-        "TENCENTCLOUD_SECRET_ID": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-        "TENCENTCLOUD_SECRET_KEY": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
-        "TCCC_SDK_APP_ID": "1400000000"
-      },
-      "timeout": 60000
-    }
-  }
-}
-```
-
-配置文件位置：
-
-| 客户端 | 位置 |
-|---|---|
-| WorkBuddy | `~/.workbuddy/mcp.json` |
-| Cursor | 项目 `.cursor/mcp.json` 或全局 `~/.cursor/mcp.json` |
-| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） |
-| Cline | VS Code 设置里的 MCP 面板 |
-
-改完**重启客户端**，MCP 进程是客户端启动时拉起的。首次启动 `npx` 会下载包（几秒），`timeout` 建议不低于 60 秒。
-
-#### 离线 / 内网环境
-
-```bash
-npm install -g @tencentcloud/tccc-mcp-server
-which tccc-mcp-server   # 拿到绝对路径
-```
-
-```json
-{
-  "mcpServers": {
-    "tccc": {
-      "type": "stdio",
-      "command": "/usr/local/bin/tccc-mcp-server",
-      "env": { "...": "..." }
-    }
-  }
-}
-```
-
-### 3. 验证
-
-```bash
-npx -y @tencentcloud/tccc-mcp-server --help
-npx -y @tencentcloud/tccc-mcp-server --version
-```
-
-配好凭据后直接问你的 AI：
-
-> 我有哪些 TCCC 应用？
-> 查一下 1400000000 下面的座席
-> 最近 24 小时的通话记录拉出来
-> 这个应用下有多少个 AI 智能体？
-
-## 能力概览（84 个接口）
-
-| 分类 | 数量 | 代表接口 |
-|---|---|---|
-| 语音智能体 | 13 | `DescribeAIAgentInfoList` `DescribeAIAgentCallList` `DescribeAICallExtractResult` |
-| 座席管理 | 11 | `DescribeStaffInfoList` `CreateStaff` `ModifyStaff` `DeleteStaff` `CreateSDKLoginToken` |
-| 号码管理 | 10 | `DescribeNumbers` `CreateOwnNumberApply` `BindNumberCallOutSkillGroup` |
-| 预测式外呼 | 10 | `CreatePredictiveDialingCampaign` `DescribePredictiveDialingSessions` |
-| 其他 | 10 | `DescribeExtension` `DescribeChatMessages` 等 |
-| 电话记录 | 7 | `DescribeTelCdr` `DescribeTelRecordAsr` `DescribeProtectedTelCdr` |
-| 技能组 | 6 | `DescribeSkillGroupInfoList` `BindStaffSkillGroupList` `CreateCCCSkillGroup` |
-| 话机（SIP） | 6 | `CreateExtension` `ModifyExtension` `DeleteExtension` |
-| 在线记录 | 3 | `DescribeIMCdrList` `DescribeChatMessages` |
-| 外呼 | 3 | `CreateAutoCalloutTask` `DescribeAutoCalloutTasks` |
-| 号码资质 | 3 | `CreateCompanyApply` `DescribeCarrierPrivilegeNumberApplicants` |
-| 双呼 | 1 | `CreateAICall` |
-| 购买 | 1 | `DescribeCCCBuyInfoList` |
-
-工具名是接口名的 snake_case，例如 `DescribeStaffInfoList` → `describe_staff_info_list`。
-
-## ⚠️ 危险操作
-
-以下操作有实际业务影响，AI 调用前应当二次确认（工具描述里已自动打上 ⚠️ 标记）：
-
-`DeleteStaff` · `DeleteExtension` · `DeleteCCCSkillGroup` · `DeletePredictiveDialingCampaign` · `AbortPredictiveDialingCampaign` · `HangUpCall` · `StopAutoCalloutTask` · `ForceMemberOffline` · `ResetExtensionPassword` · `UnbindNumberCallOutSkillGroup` …… 共 16 个。
-
-特别注意：
-
-- **`DeleteStaff` 没有回收站**，删除后只能重建，原工号不会自动恢复。
-- 批量修改类接口通常是**全量覆盖**，改之前先查一遍现有配置做备份。
-
-## 安全建议
-
-1. **用 CAM 子账号密钥**，只授予 `QcloudCCCReadOnlyAccess` 或按需的最小策略，不要使用主账号密钥。
-2. 密钥只放在本地 `env` 里，不要提交到版本库。
-3. 生产环境建议开启操作审计（CloudAudit）。
-
-## 常见问题
-
-**Q：工具都加载了，但调用报 `InvalidParameterValue | SdkAppId invalid`**
-
-先跑列表接口确认这对密钥下真实存在的应用 ID：
-
-```
-describe_cccbuy_info_list
-```
-
-如果目标 ID 不在返回列表里，说明**密钥属于另一个腾讯云账号**（TCCC 应用不跨账号可见）—— 换密钥即可，不是 ID 写错。
-
-**Q：报 `UnknownParameter: SdkAppId not recognized`**
-
-部分接口（如 `DescribeCCCBuyInfoList`）不需要 `SdkAppId`。server 会自动判断，不会给没有该字段的接口注入；如果仍出现请提 issue。
-
-**Q：查询返回空**
-
-先怀疑标识符拼写。座席邮箱、域名这类手工输入的值常有 typo（例如 `gmai.com` 少了 `l`）。
-
-## 已知限制
-
-- 频率限制：多数接口 20 次/秒，`UploadIvrAudio`、`CreateCompanyApply` 为 1 次/秒，批量操作需自行节流。
-- `UploadIvrAudio` 等涉及文件的接口，参数里是 COS 链接而非文件流，需先自行上传。
-- 仅覆盖 API 3.0 的 `ccc` 服务，不含 TCCC 的 WebSocket / SDK 侧信令。
-
-## 开发
-
-```bash
-npm install
-npm run generate   # 重新解析 SDK 类型定义，生成 src/tools.json
-npm start          # 本地启动（stdio）
-```
-
-工具定义来自 `node_modules/tencentcloud-sdk-nodejs-ccc/tencentcloud/services/ccc/v20200210/` 下的 `ccc_models.d.ts`（251 个结构体）和 `ccc_client.d.ts`（84 个方法），字段注释直接取自官方 JSDoc。SDK 升级后跑 `npm run generate` 即可同步。
-
-发布前 `prepublishOnly` 会自动重跑 `generate`，保证产物与 SDK 版本一致。
-
-## License
-
-[MIT](./LICENSE)