@tencentcloud/tccc-mcp-server 0.0.1

package/src/index.mjs

@@ -0,0 +1,202 @@
+#!/usr/bin/env node
+/**
+ * TCCC MCP Server
+ *
+ * 把腾讯云联络中心（TCCC）API 3.0 的 84 个接口暴露为 MCP 工具。
+ * 工具定义由 src/generate.mjs 从官方 SDK 类型定义自动生成，SDK 升级后重跑即可。
+ *
+ * 环境变量：
+ *   TENCENTCLOUD_SECRET_ID   必填
+ *   TENCENTCLOUD_SECRET_KEY  必填
+ *   TCCC_SDK_APP_ID          可选，缺省的 SdkAppId（多数接口必填，配了就不用每次传）
+ *   TCCC_REGION              可选，显式指定则始终使用；否则按 SdkAppId 号段自动推导：
+ *                             [20000000, 30000000) 与 [1720000000, 1730000000) 为新加坡站
+ *                             → ap-singapore，其余为中国站 → ap-guangzhou
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import tencentcloud from 'tencentcloud-sdk-nodejs-ccc';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TOOLS = JSON.parse(fs.readFileSync(path.join(__dirname, 'tools.json'), 'utf8'));
+const PKG = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+
+// ---- CLI 参数：只做 --help / --version，其余一律走 stdio JSON-RPC ----
+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 工具。
+
+环境变量：
+  TENCENTCLOUD_SECRET_ID   必填  腾讯云 SecretId（AKID 开头）
+  TENCENTCLOUD_SECRET_KEY  必填  腾讯云 SecretKey
+  TCCC_SDK_APP_ID          选填  缺省 SdkAppId，配了就不用每次调用都传
+  TCCC_REGION              选填  显式指定则始终使用；未指定时按 SdkAppId 号段
+                                 自动推导（新加坡站号段 → ap-singapore，
+                                 其余 → ap-guangzhou）
+
+用法：
+  npx -y ${PKG.name}
+
+获取密钥：https://console.cloud.tencent.com/cam/capi
+获取 SdkAppId：https://console.cloud.tencent.com/ccc
+`);
+  process.exit(0);
+}
+if (argv.includes('--version') || argv.includes('-v')) {
+  process.stdout.write(`${PKG.version}\n`);
+  process.exit(0);
+}
+
+const SECRET_ID = process.env.TENCENTCLOUD_SECRET_ID;
+const SECRET_KEY = process.env.TENCENTCLOUD_SECRET_KEY;
+const SDK_APP_ID = process.env.TCCC_SDK_APP_ID;
+const REGION_ENV = process.env.TCCC_REGION;
+
+// 按 SdkAppId 号段推导地域：[20000000, 30000000) 与 [1720000000, 1730000000)
+// 是新加坡站 → ap-singapore；其余号段是中国站 → ap-guangzhou。
+const SINGAPORE_RANGES = [
+  [20000000, 30000000],
+  [1720000000, 1730000000],
+];
+function regionFromSdkAppId(id) {
+  if (id === null || id === undefined || id === '') return null;
+  const n = Number(id);
+  // Number(null)/Number('')/Number(false) 均为 0，必须排除，否则会误判为中国站
+  if (!Number.isFinite(n) || n <= 0) return null;
+  if (SINGAPORE_RANGES.some(([lo, hi]) => n >= lo && n < hi)) return 'ap-singapore';
+  return 'ap-guangzhou';
+}
+
+const DEFAULT_REGION = REGION_ENV || (SDK_APP_ID ? regionFromSdkAppId(SDK_APP_ID) : null) || 'ap-guangzhou';
+
+// 客户端按 region 缓存：SdkAppId 是每次调用可变的参数，
+// 不同应用的站区不同，必须按本次调用实际生效的 SdkAppId 动态选 region。
+const CccClient = tencentcloud.ccc.v20200210.Client;
+const clientCache = new Map();
+function getClient(region) {
+  if (!clientCache.has(region)) {
+    clientCache.set(region, new CccClient({
+      credential: { secretId: SECRET_ID, secretKey: SECRET_KEY },
+      region,
+      profile: { httpProfile: { endpoint: 'ccc.tencentcloudapi.com', reqTimeout: 30 } },
+    }));
+  }
+  return clientCache.get(region);
+}
+
+if (!SECRET_ID || !SECRET_KEY) {
+  const miss = [!SECRET_ID && 'TENCENTCLOUD_SECRET_ID', !SECRET_KEY && 'TENCENTCLOUD_SECRET_KEY'].filter(Boolean);
+  console.error(
+    `[tccc-mcp] 启动失败：缺少环境变量 ${miss.join(' / ')}\n` +
+      `\n` +
+      `请在 MCP 配置的 env 里补上，例如：\n` +
+      `  "env": {\n` +
+      `    "TENCENTCLOUD_SECRET_ID": "AKID...",\n` +
+      `    "TENCENTCLOUD_SECRET_KEY": "...",\n` +
+      `    "TCCC_SDK_APP_ID": "1400000000"\n` +
+      `  }\n` +
+      `\n` +
+      `密钥获取：https://console.cloud.tencent.com/cam/capi\n` +
+      `注意：SecretId 以 AKID 开头，SecretKey 是 32 位随机串，两者不要填反。`
+  );
+  process.exit(1);
+}
+
+// SdkAppId 未显式传入时，用环境变量兜底，省得每个调用都问一遍。
+// 必须校验该接口的 schema 里真的有 SdkAppId 字段——像 DescribeCCCBuyInfoList 这种
+// 只有 SdkAppIds（复数）的接口，注入 SdkAppId 会被服务端拒绝（UnknownParameter）。
+function withDefaults(tool, args) {
+  const out = { ...args };
+  const hasSdkAppId = !!tool.inputSchema?.properties?.SdkAppId;
+  if (hasSdkAppId && out.SdkAppId === undefined && SDK_APP_ID) {
+    out.SdkAppId = Number(SDK_APP_ID);
+  }
+  return out;
+}
+
+const server = new Server(
+  { name: PKG.name, version: PKG.version },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  const tool = TOOLS.find((t) => t.name === name);
+  if (!tool) throw new Error(`未知工具: ${name}`);
+
+  const params = withDefaults(tool, args);
+
+  // 地域决策：显式 TCCC_REGION 环境变量 > 按本次调用生效的 SdkAppId 推导 > 启动默认值。
+  // 这样同一会话里混合调用中国站/新加坡站应用时，各自走对的地域。
+  const effectiveAppId = tool.inputSchema?.properties?.SdkAppId ? params.SdkAppId : undefined;
+  const region =
+    REGION_ENV ||
+    (effectiveAppId !== undefined ? regionFromSdkAppId(effectiveAppId) : null) ||
+    DEFAULT_REGION;
+  if (process.env.TCCC_DEBUG) {
+    console.error(`[tccc-mcp] ${tool.action} region=${region} SdkAppId=${effectiveAppId ?? '(无)'}`);
+  }
+
+  // 必填参数本地校验，避免白跑一次网络请求
+  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 || ''
+          }）`,
+        },
+      ],
+    };
+  }
+
+  try {
+    const res = await getClient(region)[tool.action](params);
+    return { content: [{ type: 'text', text: JSON.stringify(res, null, 2) }] };
+  } catch (err) {
+    const detail = [err?.code, err?.message, err?.requestId].filter(Boolean).join(' | ');
+    return {
+      isError: true,
+      content: [{ type: 'text', text: `调用 ${tool.action} 失败: ${detail || err}` }],
+    };
+  }
+});
+
+// 兜住所有未处理异常：stdio 下进程一崩，客户端只会看到"连接已关闭"，无从排查。
+for (const sig of ['uncaughtException', 'unhandledRejection']) {
+  process.on(sig, (err) => {
+    console.error(`[tccc-mcp] ${sig}:`, err?.stack || err);
+  });
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(
+  `[tccc-mcp] 就绪 v${PKG.version}：${TOOLS.length} 个工具，region=${
+    REGION_ENV
+      ? `${REGION_ENV}（显式指定，覆盖自动推导）`
+      : SDK_APP_ID
+        ? `${DEFAULT_REGION}（按 TCCC_SDK_APP_ID=${SDK_APP_ID} 推导，调用时若传入其他号段的 SdkAppId 会自动切换）`
+        : `${DEFAULT_REGION}（未配置 TCCC_SDK_APP_ID 时的默认值，调用时按实际 SdkAppId 推导）`
+  }${SDK_APP_ID ? '' : '（未配置 TCCC_SDK_APP_ID，调用时需显式传 SdkAppId）'}`
+);