@tencentcloud/tccc-mcp-server 0.0.6 → 0.0.8

package/README.md

@@ -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`).
@@ -250,11 +259,14 @@ npx -y @tencentcloud/tccc-mcp-server --version
 > 查一下 1400000000 下面的座席
 > 最近 24 小时的通话记录拉出来
 > 这个应用下有多少个 AI 智能体？
+> 我怎么体验 TCCC AI 智能体 / 智能体对话 / AI 外呼？
 
-## 能力概览（84 个接口）
+## 能力概览（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` |
@@ -269,13 +281,15 @@ npx -y @tencentcloud/tccc-mcp-server --version
 | 双呼 | 1 | `CreateAICall` |
 | 购买 | 1 | `DescribeCCCBuyInfoList` |
 
-工具名是接口名的 snake_case，例如 `DescribeStaffInfoList` → `describe_staff_info_list`。
+自动生成的 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 调用前应当二次确认（工具描述里已自动打上 ⚠️ 标记）：
 
-`DeleteStaff` · `DeleteExtension` · `DeleteCCCSkillGroup` · `DeletePredictiveDialingCampaign` · `AbortPredictiveDialingCampaign` · `HangUpCall` · `StopAutoCalloutTask` · `ForceMemberOffline` · `ResetExtensionPassword` · `UnbindNumberCallOutSkillGroup` …… 共 16 个。
+`DeleteCCCInstance` · `DeleteStaff` · `DeleteExtension` · `DeleteCCCSkillGroup` · `DeletePredictiveDialingCampaign` · `AbortPredictiveDialingCampaign` · `HangUpCall` · `StopAutoCalloutTask` · `ForceMemberOffline` · `ResetExtensionPassword` · `UnbindNumberCallOutSkillGroup` ……
 
 特别注意：
 
@@ -304,6 +318,10 @@ describe_cccbuy_info_list
 
 部分接口（如 `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`）。
@@ -324,6 +342,8 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/tccc-mcp-server",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "MCP server for Tencent Cloud Contact Center (TCCC)",
   "type": "module",
   "bin": {

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