@tencentcloud/tccc-mcp-server 0.0.10 → 0.0.14

package/README.md

@@ -84,7 +84,7 @@ Then just ask your AI assistant in natural language:
 > How many voice AI agents are there in this application?
 > How can I try the TCCC AI agent / AI outbound call demo?
 
-## Capability overview (87 APIs + 1 helper)
+## Capability overview (87 APIs + 2 helpers)
 
 | Category | Count | Representative tools |
 |---|---|---|
@@ -261,7 +261,7 @@ npx -y @tencentcloud/tccc-mcp-server --version
 > 这个应用下有多少个 AI 智能体？
 > 我怎么体验 TCCC AI 智能体 / 智能体对话 / AI 外呼？
 
-## 能力概览（87 个接口 + 1 个辅助工具）
+## 能力概览（87 个接口 + 2 个辅助工具）
 
 | 分类 | 数量 | 代表接口 |
 |---|---|---|

package/package.json

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

package/src/analytics.mjs

@@ -0,0 +1,266 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const OTLP_DOMAIN = 'otlp.tccc.qcloud.com';
+export const OTLP_INTL_DOMAIN = 'otlp.connect.tencentcloud.com';
+export const OTLP_ID = 'tccc';
+export const OTLP_INTL_ID = 'tcccsg';
+// 预留美国站 ID 覆盖位；当前公开代码里没有稳定的美国站号段，默认复用国际站 ID。
+export const OTLP_US_ID = process.env.TCCC_MCP_OTLP_US_ID || OTLP_INTL_ID;
+
+const SERVER_NAME = 'tccc-mcp-server';
+const DEFAULT_SDK_APP_ID = process.env.TCCC_SDK_APP_ID || '';
+const REPORT_DISABLED = /^(1|true|yes|off)$/i.test(process.env.TCCC_MCP_OTLP_DISABLED || '');
+const REPORT_TIMEOUT_MS = Number(process.env.TCCC_MCP_OTLP_TIMEOUT_MS || 1500);
+const INCLUDE_RAW_QUESTION = /^(1|true|yes)$/i.test(process.env.TCCC_MCP_ANALYTICS_INCLUDE_RAW_QUESTION || '');
+const SESSION_ID = randomUUID();
+const loggerMap = new Map();
+
+// ULID: 26 位 Crockford Base32（10 位毫秒时间戳 + 16 位随机），可排序、对 URL 安全。
+const ULID_ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ';
+const ULID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+
+function ulid() {
+  let time = Date.now();
+  let timePart = '';
+  for (let i = 0; i < 10; i++) {
+    timePart = ULID_ENCODING[time % 32] + timePart;
+    time = Math.floor(time / 32);
+  }
+  // 256 % 32 === 0，取模无偏
+  const randomPart = Array.from(randomBytes(16), (b) => ULID_ENCODING[b % 32]).join('');
+  return timePart + randomPart;
+}
+
+const USER_ID_FILE = process.env.TCCC_MCP_USER_ID_FILE || join(homedir(), '.tccc-mcp-server', 'user-id');
+
+function getOrCreateUserId() {
+  try {
+    if (existsSync(USER_ID_FILE)) {
+      const cached = readFileSync(USER_ID_FILE, 'utf8').trim();
+      if (ULID_PATTERN.test(cached)) return cached;
+    }
+    mkdirSync(dirname(USER_ID_FILE), { recursive: true });
+    const id = ulid();
+    writeFileSync(USER_ID_FILE, id, 'utf8');
+    return id;
+  } catch {
+    // 缓存不可读写（如只读文件系统）时降级为本次进程内的临时 ID
+    return ulid();
+  }
+}
+
+const USER_ID = process.env.TCCC_MCP_USER_ID || getOrCreateUserId();
+
+const SINGAPORE_RANGES = [
+  [20000000, 30000000],
+  [1720000000, 1730000000],
+];
+
+const USA_RANGES = [];
+
+export function isSingaporeSite(sdkAppId) {
+  const n = Number(sdkAppId);
+  return Number.isFinite(n) && SINGAPORE_RANGES.some(([lo, hi]) => n >= lo && n < hi);
+}
+
+export function isUSASite(sdkAppId) {
+  const n = Number(sdkAppId);
+  return Number.isFinite(n) && USA_RANGES.some(([lo, hi]) => n >= lo && n < hi);
+}
+
+export function isIntlSite(sdkAppId) {
+  return isSingaporeSite(sdkAppId) || isUSASite(sdkAppId);
+}
+
+export function GET_OTLP_DOMAIN_BY_SDKAPPID(sdkAppId) {
+  if (isIntlSite(sdkAppId)) {
+    return OTLP_INTL_DOMAIN;
+  }
+  return OTLP_DOMAIN;
+}
+
+export function GET_OTLP_ID_BY_SDKAPPID(sdkAppId) {
+  if (isUSASite(sdkAppId)) {
+    return OTLP_US_ID;
+  }
+  if (isSingaporeSite(sdkAppId)) {
+    return OTLP_INTL_ID;
+  }
+  return OTLP_ID;
+}
+
+function getOtlpEndpoint(sdkAppId) {
+  if (process.env.TCCC_MCP_OTLP_ENDPOINT) return process.env.TCCC_MCP_OTLP_ENDPOINT;
+  const otlpDomain = GET_OTLP_DOMAIN_BY_SDKAPPID(sdkAppId);
+  return `https://${otlpDomain}/v1/logs`;
+}
+
+function toAnyValue(value) {
+  if (value === undefined || value === null) return { stringValue: '' };
+  if (typeof value === 'boolean') return { boolValue: value };
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) return { intValue: String(value) };
+    return { doubleValue: value };
+  }
+  if (typeof value === 'bigint') return { intValue: value.toString() };
+  if (Array.isArray(value)) {
+    return { arrayValue: { values: value.map(toAnyValue) } };
+  }
+  if (typeof value === 'object') {
+    return {
+      kvlistValue: {
+        values: Object.entries(value).map(([key, item]) => ({ key, value: toAnyValue(item) })),
+      },
+    };
+  }
+  return { stringValue: String(value) };
+}
+
+function toAttributes(attrs = {}) {
+  return Object.entries(attrs)
+    .filter(([, value]) => value !== undefined)
+    .map(([key, value]) => ({ key, value: toAnyValue(value) }));
+}
+
+function nowUnixNano() {
+  return (BigInt(Date.now()) * 1000000n).toString();
+}
+
+const SEVERITY = {
+  debug: { severityNumber: 5, severityText: 'debug' },
+  info: { severityNumber: 9, severityText: 'info' },
+  warn: { severityNumber: 13, severityText: 'warn' },
+  error: { severityNumber: 17, severityText: 'error' },
+};
+
+class Logger {
+  constructor({ logLevel = 0, url, id, name, attributes = {} }) {
+    this.logLevel = logLevel;
+    this.url = url;
+    this.id = id;
+    this.name = name;
+    this.attributes = attributes;
+  }
+
+  emit({ level = 'info', msg, attributes = {} }) {
+    if (REPORT_DISABLED) return;
+    const severity = SEVERITY[level] || SEVERITY.info;
+    const payload = {
+      resourceLogs: [
+        {
+          resource: {
+            attributes: toAttributes({
+              'service.name': this.name,
+              'tps.tenant.id': this.id,
+              ...this.attributes,
+            }),
+          },
+          scopeLogs: [
+            {
+              scope: { name: this.name },
+              logRecords: [
+                {
+                  timeUnixNano: nowUnixNano(),
+                  observedTimeUnixNano: nowUnixNano(),
+                  ...severity,
+                  body: { stringValue: msg || '' },
+                  attributes: toAttributes({
+                    ...attributes,
+                    sessionId: SESSION_ID,
+                    userId: USER_ID,
+                  }),
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REPORT_TIMEOUT_MS);
+    if (typeof timer.unref === 'function') timer.unref();
+
+    fetch(this.url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Tps-TenantID': this.id,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    })
+      .catch((err) => {
+        if (process.env.TCCC_DEBUG_ANALYTICS) {
+          console.error('[tccc-mcp] analytics report failed:', err?.message || err);
+        }
+      })
+      .finally(() => clearTimeout(timer));
+  }
+}
+
+export function getLogger(sdkAppId, pkgVersion) {
+  const normalizedSdkAppId = String(sdkAppId || DEFAULT_SDK_APP_ID || 'unknown');
+  let logger = loggerMap.get(normalizedSdkAppId);
+  if (!logger) {
+    logger = new Logger({
+      logLevel: 0,
+      url: getOtlpEndpoint(normalizedSdkAppId),
+      id: GET_OTLP_ID_BY_SDKAPPID(normalizedSdkAppId),
+      name: SERVER_NAME,
+      attributes: {
+        pkgVersion,
+        sdkAppId: normalizedSdkAppId,
+      },
+    });
+    loggerMap.set(normalizedSdkAppId, logger);
+  }
+  return logger;
+}
+
+export function inferSdkAppId(params = {}) {
+  for (const key of ['SdkAppId', 'sdkAppId']) {
+    const v = params[key];
+    if (v !== undefined && v !== null && v !== '') return String(v);
+  }
+  if (Array.isArray(params.SdkAppIds) && params.SdkAppIds.length > 0) return String(params.SdkAppIds[0]);
+  if (DEFAULT_SDK_APP_ID) return String(DEFAULT_SDK_APP_ID);
+  return 'unknown';
+}
+
+export function recordToolCall({ tool, params, pkgVersion, region, requestId, errorCode, errorMessage }) {
+  const sdkAppId = inferSdkAppId(params);
+  const logger = getLogger(sdkAppId, pkgVersion);
+  logger.emit({
+    level: errorCode ? 'warn' : 'info',
+    msg: `[mcp.tool_call] ${tool?.name || 'unknown'} ${errorCode ? 'failure' : 'success'}`,
+    attributes: {
+      eventName: 'mcp.tool_call',
+      toolName: tool?.name,
+      requestId,
+      errorCode,
+      errorMessage: errorMessage ? String(errorMessage).slice(0, 300) : undefined,
+      sdkAppId,
+      region,
+    },
+  });
+}
+
+export function recordUserIntent({ intent, confidence, rawQuestion, sdkAppId, pkgVersion }) {
+  const normalizedSdkAppId = String(sdkAppId || DEFAULT_SDK_APP_ID || 'unknown');
+  const logger = getLogger(normalizedSdkAppId, pkgVersion);
+  logger.emit({
+    level: 'info',
+    msg: `[mcp.user_intent] ${intent || 'unknown'}`,
+    attributes: {
+      eventName: 'mcp.user_intent',
+      intent: intent || 'unknown',
+      confidence: typeof confidence === 'number' ? confidence : undefined,
+      sdkAppId: normalizedSdkAppId,
+      rawQuestion: INCLUDE_RAW_QUESTION && rawQuestion ? String(rawQuestion).slice(0, 500) : undefined,
+    },
+  });
+}

package/src/custom-tools.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { recordUserIntent } from './analytics.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const TCCC_AI_AGENT_DEMO_QRCODE_PATH = path.join(__dirname, 'assets', 'tccc-ai-agent-demo-qrcode.png');
@@ -31,12 +32,49 @@ export const CUSTOM_TOOLS = [
       additionalProperties: false,
     },
   },
+  {
+    name: 'record_tccc_user_intent',
+    action: '__custom_record_tccc_user_intent',
+    custom: true,
+    analyticsOnly: true,
+    description:
+      '当用户咨询 tccc-mcp-server 或 TCCC 相关问题、但不一定需要立即调用具体业务 API 时，可调用本工具记录用户咨询意图分类，用于产品使用统计。不要记录 SecretId、SecretKey、Token、手机号、邮箱等敏感信息；rawQuestion 默认不上报原文，除非显式设置 TCCC_MCP_ANALYTICS_INCLUDE_RAW_QUESTION=1。',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        intent: {
+          type: 'string',
+          description: '意图分类，例如 ai_demo、human_ai_collaboration、service_efficiency、instance_management、staff_management、record_query、troubleshooting、product_consulting。',
+        },
+        confidence: {
+          type: 'number',
+          description: '分类置信度，0 到 1，可选。',
+        },
+        sdkAppId: {
+          type: 'string',
+          description: '如果上下文里已有 SdkAppId，可填写；否则留空。',
+        },
+        rawQuestion: {
+          type: 'string',
+          description: '可选原始问题。默认只上报长度，不上报原文；不要包含密钥、手机号、邮箱等敏感信息。',
+        },
+      },
+      required: ['intent'],
+      additionalProperties: false,
+    },
+  },
 ];
 
-export async function handleCustomTool(tool, args = {}) {
+export async function handleCustomTool(tool, args = {}, context = {}) {
   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 智能体';
+      recordUserIntent({
+        intent: 'ai_demo',
+        confidence: 1,
+        sdkAppId: args.sdkAppId,
+        pkgVersion: context.pkgVersion,
+      });
       return {
         content: [
           {
@@ -53,6 +91,23 @@ export async function handleCustomTool(tool, args = {}) {
         ],
       };
     }
+    case '__custom_record_tccc_user_intent': {
+      recordUserIntent({
+        intent: args.intent,
+        confidence: args.confidence,
+        rawQuestion: args.rawQuestion,
+        sdkAppId: args.sdkAppId,
+        pkgVersion: context.pkgVersion,
+      });
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `已记录 TCCC 咨询意图：${args.intent}${args.topic ? `（${args.topic}）` : ''}`,
+          },
+        ],
+      };
+    }
     default:
       throw new Error(`未知自定义工具: ${tool.name}`);
   }

package/src/index.mjs

@@ -24,6 +24,7 @@ import {
   ListToolsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
 import tencentcloud from 'tencentcloud-sdk-nodejs-ccc';
+import { recordToolCall } from './analytics.mjs';
 import { CUSTOM_TOOLS, handleCustomTool } from './custom-tools.mjs';
 import { EXTRA_API_TOOLS } from './extra-api-tools.mjs';
 
@@ -152,12 +153,24 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const tool = TOOLS.find((t) => t.name === name);
   if (!tool) throw new Error(`未知工具: ${name}`);
 
+  let region = DEFAULT_REGION;
+  const finish = (result, meta = {}) => {
+    recordToolCall({
+      tool,
+      params,
+      pkgVersion: PKG.version,
+      region,
+      ...meta,
+    });
+    return result;
+  };
+
   const params = withDefaults(tool, args);
 
   // 地域决策：显式 TCCC_REGION 环境变量 > 按本次调用生效的 SdkAppId 推导 > 启动默认值。
   // 这样同一会话里混合调用中国站/新加坡站应用时，各自走对的地域。
   const effectiveAppId = tool.inputSchema?.properties?.SdkAppId ? params.SdkAppId : undefined;
-  const region =
+  region =
     REGION_ENV ||
     (effectiveAppId !== undefined ? regionFromSdkAppId(effectiveAppId) : null) ||
     DEFAULT_REGION;
@@ -168,21 +181,35 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   // 必填参数本地校验，避免白跑一次网络请求
   const missing = (tool.inputSchema.required || []).filter((k) => params[k] === undefined);
   if (missing.length) {
-    return {
-      isError: true,
-      content: [
-        {
-          type: 'text',
-          text: `缺少必填参数: ${missing.join(', ')}\n接口: ${tool.action}（${
-            tool.inputSchema.properties[missing[0]]?.description || ''
-          }）`,
-        },
-      ],
-    };
+    return finish(
+      {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: `缺少必填参数: ${missing.join(', ')}\n接口: ${tool.action}（${
+              tool.inputSchema.properties[missing[0]]?.description || ''
+            }）`,
+          },
+        ],
+      },
+      { errorCode: 'MissingParameter', errorMessage: `缺少必填参数: ${missing.join(', ')}` }
+    );
   }
 
   if (tool.custom) {
-    return handleCustomTool(tool, params);
+    try {
+      const res = await handleCustomTool(tool, params, { pkgVersion: PKG.version, region });
+      return finish(res);
+    } catch (err) {
+      return finish(
+        {
+          isError: true,
+          content: [{ type: 'text', text: `调用 ${tool.action} 失败: ${err?.message || err}` }],
+        },
+        { errorCode: err?.code || 'CustomToolError', errorMessage: err?.message || String(err) }
+      );
+    }
   }
 
   try {
@@ -203,20 +230,26 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         summary = '';
       }
     }
-    return {
-      content: [
-        {
-          type: 'text',
-          text: (summary ? `${summary}\n\n` : '') + JSON.stringify(res, null, 2),
-        },
-      ],
-    };
+    return finish(
+      {
+        content: [
+          {
+            type: 'text',
+            text: (summary ? `${summary}\n\n` : '') + JSON.stringify(res, null, 2),
+          },
+        ],
+      },
+      { requestId: res?.RequestId }
+    );
   } catch (err) {
     const detail = [err?.code, err?.message, err?.requestId].filter(Boolean).join(' | ');
-    return {
-      isError: true,
-      content: [{ type: 'text', text: `调用 ${tool.action} 失败: ${detail || err}` }],
-    };
+    return finish(
+      {
+        isError: true,
+        content: [{ type: 'text', text: `调用 ${tool.action} 失败: ${detail || err}` }],
+      },
+      { requestId: err?.requestId, errorCode: err?.code, errorMessage: err?.message || String(err) }
+    );
   }
 });