@tencentcloud/tccc-mcp-server 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tencent Cloud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# @tencentcloud/tccc-mcp-server
+
+**English** | [简体中文](./README_zh.md)
+
+tccc-mcp-server enables AI assistants to quickly integrate with Tencent Cloud Contact Center (TCCC) via MCP (Model Context Protocol).
+
+## Quick start
+
+### 1. Get credentials
+
+| Variable | Required | Description | Where to get it |
+|---|---|---|---|
+| `TENCENTCLOUD_SECRET_ID` | ✅ | Tencent Cloud SecretId (starts with `AKID`) | [CAM - API Key Management](https://console.tencentcloud.com/cam/capi) |
+| `TENCENTCLOUD_SECRET_KEY` | ✅ | Tencent Cloud SecretKey (32-char random string) | Same as above |
+| `TCCC_SDK_APP_ID` | Recommended | Default SdkAppId so you don't pass it on every call | [CCC Console](https://console.tencentcloud.com/ccc) |
+| `TCCC_REGION` | Optional | Explicit region override. If unset, the region is **auto-derived from the SdkAppId of each call**: app IDs in `[20000000, 30000000)` or `[1720000000, 1730000000)` are Singapore-site → `ap-singapore`; all others → `ap-guangzhou` | — |
+
+> ⚠️ **Don't swap the key pair**: `SecretId` starts with `AKID`; `SecretKey` is a 32-character random string. If reversed you'll get `The SecretId is not found`.
+
+### 2. Add to your MCP client
+
+#### WorkBuddy / Cursor / Claude Desktop / Cline (universal format)
+
+```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
+    }
+  }
+}
+```
+
+Config file locations:
+
+| Client | Location |
+|---|---|
+| WorkBuddy | `~/.workbuddy/mcp.json` |
+| Cursor | project `.cursor/mcp.json` or global `~/.cursor/mcp.json` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
+| Cline | MCP panel in VS Code settings |
+
+**Restart your client** after editing — MCP processes are spawned at client startup. The first `npx` run downloads the package (a few seconds); keep `timeout` at 60 s or higher.
+
+#### Offline / air-gapped environments
+
+```bash
+npm install -g @tencentcloud/tccc-mcp-server
+which tccc-mcp-server   # get the absolute path
+```
+
+```json
+{
+  "mcpServers": {
+    "tccc": {
+      "type": "stdio",
+      "command": "/usr/local/bin/tccc-mcp-server",
+      "env": { "...": "..." }
+    }
+  }
+}
+```
+
+### 3. Verify
+
+```bash
+npx -y @tencentcloud/tccc-mcp-server --help
+npx -y @tencentcloud/tccc-mcp-server --version
+```
+
+Then just ask your AI assistant in natural language:
+
+> Which TCCC applications do I have?
+> 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?
+
+## Capability overview (84 APIs)
+
+| Category | Count | Representative tools |
+|---|---|---|
+| Voice AI agents | 13 | `DescribeAIAgentInfoList` `DescribeAIAgentCallList` `DescribeAICallExtractResult` |
+| Agent (staff) management | 11 | `DescribeStaffInfoList` `CreateStaff` `ModifyStaff` `DeleteStaff` `CreateSDKLoginToken` |
+| Number management | 10 | `DescribeNumbers` `CreateOwnNumberApply` `BindNumberCallOutSkillGroup` |
+| Predictive dialing | 10 | `CreatePredictiveDialingCampaign` `DescribePredictiveDialingSessions` |
+| Others | 10 | `DescribeExtension` `DescribeChatMessages` etc. |
+| Call records | 7 | `DescribeTelCdr` `DescribeTelRecordAsr` `DescribeProtectedTelCdr` |
+| Skill groups | 6 | `DescribeSkillGroupInfoList` `BindStaffSkillGroupList` `CreateCCCSkillGroup` |
+| SIP extensions | 6 | `CreateExtension` `ModifyExtension` `DeleteExtension` |
+| Instant-message records | 3 | `DescribeIMCdrList` `DescribeChatMessages` |
+| Auto callout | 3 | `CreateAutoCalloutTask` `DescribeAutoCalloutTasks` |
+| Carrier qualification | 3 | `CreateCompanyApply` `DescribeCarrierPrivilegeNumberApplicants` |
+| 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`.
+
+## ⚠️ 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.
+
+Special notes:
+
+- **`DeleteStaff` has no recycle bin.** Deleted agents can only be recreated; the original staff number is not restored.
+- Bulk-modify APIs usually **overwrite the full configuration** — read the current state first and keep a backup before modifying.
+
+## Security recommendations
+
+1. **Use a CAM sub-account key** restricted to `QcloudCCCReadOnlyAccess` or a minimal custom policy. Never use your root account key.
+2. Keep keys only in your local `env` config; never commit them to version control.
+3. Enable CloudAudit for production operations.
+
+## Troubleshooting
+
+**Q: Tools load fine, but calls fail with `InvalidParameterValue | SdkAppId invalid`**
+
+Run the list tool to see which application IDs actually exist under your key:
+
+```
+describe_cccbuy_info_list
+```
+
+If the target ID is not in the list, your **key belongs to a different Tencent Cloud account** (TCCC apps are not visible across accounts) — switch keys; it's not a typo in the ID.
+
+**Q: `UnknownParameter: SdkAppId not recognized`**
+
+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: 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`).
+
+## Known limitations
+
+- Rate limits: most APIs allow 20 requests/second; `UploadIvrAudio` and `CreateCompanyApply` only 1/second. Throttle bulk operations yourself.
+- File-related APIs like `UploadIvrAudio` take a COS URL, not a file stream — upload the file first.
+- Covers only the `ccc` service of API 3.0 (OpenAPI). TCCC WebSocket / client-SDK signaling is out of scope.
+
+## Development
+
+```bash
+npm install
+npm run generate   # re-parse SDK type definitions into src/tools.json
+npm start          # run locally (stdio)
+```
+
+Tool definitions are generated from `ccc_models.d.ts` (251 structs) and `ccc_client.d.ts` (84 methods) under `node_modules/tencentcloud-sdk-nodejs-ccc/tencentcloud/services/ccc/v20200210/`. Field descriptions come straight from the official JSDoc. After an SDK upgrade, run `npm run generate` to sync.
+
+`prepublishOnly` re-runs `generate` automatically before each publish, so the shipped schema always matches the SDK version.
+
+## License
+
+[MIT](./LICENSE)

package/README_zh.md

@@ -0,0 +1,163 @@
+# @tencentcloud/tccc-mcp-server
+
+[English](./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)

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@tencentcloud/tccc-mcp-server",
+  "version": "0.0.1",
+  "description": "MCP server for Tencent Cloud Contact Center (TCCC)",
+  "type": "module",
+  "bin": {
+    "tccc-mcp-server": "./src/index.mjs"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "README_zh.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "generate": "node src/generate.mjs",
+    "start": "node src/index.mjs",
+    "prepublishOnly": "npm run generate"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "tencentcloud-sdk-nodejs-ccc": "^4.1.310"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "modelcontextprotocol",
+    "tccc",
+    "tencentcloud",
+    "tencent",
+    "call-center",
+    "contact-center",
+    "voice-agent",
+    "llm",
+    "ai",
+    "agent",
+    "腾讯云",
+    "云联络中心",
+    "呼叫中心"
+  ],
+  "author": "qiaoyang",
+  "license": "MIT",
+  "homepage": "https://github.com/tencentcloud/tccc-mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tencentcloud/tccc-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tencentcloud/tccc-mcp-server/issues"
+  }
+}

package/src/generate.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * 从腾讯云官方 SDK 的 TypeScript 类型定义自动生成 MCP 工具定义。
+ *
+ * 数据源：node_modules/tencentcloud-sdk-nodejs-ccc/tencentcloud/services/ccc/v20200210/
+ *   - ccc_models.d.ts ：251 个结构体，每个字段带 JSDoc 中文说明 + 是否可选
+ *   - ccc_client.d.ts ：84 个接口方法，带 JSDoc 中文说明
+ *
+ * 输出：src/tools.json（MCP tools/list 用的定义清单）
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const SDK_DIR = path.resolve(
+  __dirname,
+  '../node_modules/tencentcloud-sdk-nodejs-ccc/tencentcloud/services/ccc/v20200210'
+);
+const OUT = path.join(__dirname, 'tools.json');
+
+if (!fs.existsSync(SDK_DIR)) {
+  console.error('找不到 CCC SDK 类型定义，请先执行 npm install：', SDK_DIR);
+  process.exit(1);
+}
+
+const modelsSrc = fs.readFileSync(path.join(SDK_DIR, 'ccc_models.d.ts'), 'utf8');
+const clientSrc = fs.readFileSync(path.join(SDK_DIR, 'ccc_client.d.ts'), 'utf8');
+
+/** 把 JSDoc 里的 HTML 与星号清理成一行纯文本描述 */
+function cleanDoc(raw) {
+  return raw
+    .replace(/^\s*\*\s?/gm, '')
+    .replace(/<br\s*\/?>/gi, ' ')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+// ---------- 1. 解析所有 interface ----------
+const models = new Map();
+const ifaceRe = /export interface (\w+) \{([\n\r][\s\S]*?)\n\}/g;
+let m;
+while ((m = ifaceRe.exec(modelsSrc))) {
+  const fields = [];
+  const fieldRe = /\/\*\*([\s\S]*?)\*\/\s*\n\s*(\w+)(\??):\s*([^;]+);/g;
+  let f;
+  while ((f = fieldRe.exec(m[2]))) {
+    fields.push({ name: f[2], optional: f[3] === '?', tsType: f[4].trim(), doc: cleanDoc(f[1]) });
+  }
+  models.set(m[1], fields);
+}
+
+// ---------- 2. TS 类型 -> JSON Schema（递归展开嵌套结构体） ----------
+function tsToSchema(tsType, depth = 0, seen = new Set()) {
+  const t = tsType.trim();
+  const arr = /^Array<(.*)>$/.exec(t);
+  if (arr) return { type: 'array', items: tsToSchema(arr[1], depth, seen) };
+  // 联合类型：腾讯云 SDK 里常见 `number | bigint`（int64 字段）。
+  // 逐个分支解析，取第一个能识别的具体类型；全都不认识才退化成 object。
+  if (t.includes('|')) {
+    for (const branch of t.split('|').map((s) => s.trim())) {
+      if (!branch) continue;
+      const s = tsToSchema(branch, depth, seen);
+      if (s.type !== 'object' || s.properties) return s;
+    }
+    return { type: 'object', additionalProperties: true };
+  }
+  if (t === 'string') return { type: 'string' };
+  if (t === 'number') return { type: 'number' };
+  if (t === 'boolean') return { type: 'boolean' };
+  if (models.has(t) && depth < 6 && !seen.has(t)) {
+    return structToSchema(models.get(t), depth + 1, new Set([...seen, t]));
+  }
+  return { type: 'object', additionalProperties: true }; // 兜底，避免丢字段
+}
+
+function structToSchema(fields, depth = 0, seen = new Set()) {
+  const schema = { type: 'object', properties: {}, required: [], additionalProperties: false };
+  for (const f of fields) {
+    const s = tsToSchema(f.tsType, depth, seen);
+    if (f.doc) s.description = f.doc;
+    schema.properties[f.name] = s;
+    if (!f.optional) schema.required.push(f.name);
+  }
+  if (!schema.required.length) delete schema.required;
+  return schema;
+}
+
+// ---------- 3. 解析 client 方法 ----------
+/** 具有副作用/破坏性的接口，执行前必须向用户二次确认 */
+const DESTRUCTIVE = /^(Delete|Abort|Stop|HangUp|Reset|Disable|Force|Unbind|TransferToManual|PlaySoundCall|ControlAIConversation)/;
+
+const tools = [];
+const methodRe =
+  /\/\*\*([\s\S]*?)\*\/\s*\n\s*(\w+)\(req: (\w+Request), cb\?: \(error: string, rep: (\w+Response)\) => void\): Promise<\w+Response>;/g;
+
+while ((m = methodRe.exec(clientSrc))) {
+  const [, docRaw, action, reqName] = m;
+  const fields = models.get(reqName);
+  if (!fields) {
+    console.warn(`  ! 跳过 ${action}：找不到 ${reqName}`);
+    continue;
+  }
+  const inputSchema = structToSchema(fields);
+  const desc = cleanDoc(docRaw) || action;
+  const dangerous = DESTRUCTIVE.test(action);
+
+  tools.push({
+    // MCP 工具名用 snake_case，便于模型调用
+    name: action.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase(),
+    action,
+    destructive: dangerous,
+    description: (dangerous ? '⚠️ 危险/有副作用操作，执行前必须先向用户确认。' : '') + desc.slice(0, 400),
+    inputSchema,
+  });
+}
+
+tools.sort((a, b) => a.name.localeCompare(b.name));
+fs.writeFileSync(OUT, JSON.stringify(tools, null, 2));
+
+const totalFields = tools.reduce((a, t) => a + Object.keys(t.inputSchema.properties || {}).length, 0);
+console.log(`✓ 已生成 ${tools.length} 个 MCP 工具 -> ${OUT}`);
+console.log(`  结构体 ${models.size} 个，参数字段 ${totalFields} 个，平均 ${(totalFields / tools.length).toFixed(1)} 个/接口`);
+console.log(`  危险操作标记：${tools.filter((t) => t.destructive).length} 个`);