@tencentcloud/sdk-mcp 1.7.5 → 1.7.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## Version 1.7.7 @2026.09.11
+
+### 变更
+- 优化 MCP 连接稳定性与可观测性，提升异常定位与运行诊断效率。
+
+## Version 1.7.6 @2026.09.09
+
+### 变更
+- 清理知识库中引流入口信息，减少知识库检索噪声。
+- 重构工具定义：统一工具的调用边界、触发语义和模板结构。
+- 调整全局 Workflow 语义为“咨询流专用”，降低工具路由歧义。
+
+### 修复
+- 修复部分集成工具定义中的边界冲突与参数文案不一致问题（如 `get_native_callkit_core_integration`），提升调用稳定性。
+
 ## Version 1.7.5 @2026.09.04
 
 ### 变更

package/README.md

@@ -1,27 +1,25 @@
-## 腾讯云 SDK MCP Server 使用说明
+## 腾讯云 SDK MCP Server
 
-本仓库提供一个基于 CLI 的 Model Context Protocol（MCP）Server，向 LLM 工具暴露腾讯云 SDK 文档与 API 资料，帮助 AI Agent 更准确地理解并集成腾讯云实时音视频能力。
+腾讯云 SDK MCP Server 通过 MCP（Model Context Protocol）向 AI 助手提供官方文档检索与集成能力，帮助你更快完成腾讯云实时音视频相关开发（Chat/Call/Live/Room/RTCEngine/TIMPush）。
 
+## 功能概览
 
-## 功能特性
-
-- **高效检索**：支持腾讯云实时音视频文档检索，快速定位官方资料与实践说明。
-- **覆盖全面**：支持 Chat（IM）、Call、Live、Room、RTCEngine（TRTC SDK）、TIMPush 等产品域。
-- **智能路由**：支持产品/平台语义识别与消歧，在必要时引导补齐平台与框架信息。
-- **集成友好**：除文档问答外，提供 Web / Android / iOS / Flutter 等含 UI 集成入口。
-- **官方可信**：基于官方资料，提升答案可靠性与可落地性。
-- **广泛兼容**：通过 STDIN/STDOUT 的 JSON-RPC 提供 MCP 能力，可接入 Cursor / Codex / Claude / CodeBuddy 等 MCP 客户端。
-- **开箱即用**：`npx` 即可运行，低接入门槛。
+- **官方资料检索**：快速定位产品文档、集成指引与最佳实践。
+- **智能分流**：按产品、平台、框架进行语义路由，降低检索噪声。
+- **代码集成能力**：支持 Web / Android / iOS / Flutter 等主流端侧集成入口。
+- **MCP 兼容**：可接入 Cursor、CodeBuddy、Codex、Claude 等 MCP 客户端。
 
 ## 环境要求
-- Node.js（>= 18）与 npm
-- 支持 MCP 的 IDE
 
+- Node.js >= 18
+- npm
+- 任一支持 MCP 的 IDE / AI 客户端
+
+## 30 秒快速开始（免控制台创建应用试用）
 
-## 使用方式
-### 标准接入流程
+### 1) 配置 MCP Server（试用模式）
 
-- Step1：在你的 Cursor 项目中，创建或编辑 `.cursor/mcp.json` 或 `~/.cursor/mcp.json`，添加如下配置。
+以 Cursor 为例，在项目 `.cursor/mcp.json`（或 `~/.cursor/mcp.json`）中添加：
 
 ```json
 {
@@ -30,67 +28,77 @@
       "command": "npx",
       "args": ["-y", "@tencentcloud/sdk-mcp@latest"],
       "env": {
-        "SDKAPPID": "YOUR_SDKAPPID",
-        "SECRETKEY": "YOUR_SECRET_KEY"
+        "SDKAPPID": "",
+        "SECRETKEY": ""
       }
     }
   }
 }
 ```
-保存后会弹出提示，在提示中点击 **Enable**。
 
-![mcp-server-prompt](https://web.sdk.qcloud.com/im/assets/images/mcp-server-prompt.png)
+### 2) 确认服务已连接
 
-- Step2：进入 **Cursor Settings**（右上角齿轮）-> **MCP**，确认 `tencentcloud-sdk-mcp` 已启用。
+在 MCP 面板确认 `tencentcloud-sdk-mcp` 状态为 **Connected**。
 
-![cursor-setting](https://web.sdk.qcloud.com/im/assets/images/cursor-setting.png)
+### 3) 用前缀显式激活工具
 
-- Step3：在 IDE 中直接描述你的需求，让 AI 基于腾讯云 SDK 文档完成实现或答疑。
+建议在问题前加 `@tencentcloud-sdk-mcp`，提升工具命中率与回答稳定性。
 
-### 可选：全局安装
+示例：
 
-如需在本地全局快速调用，可先执行：
+```text
+@tencentcloud-sdk-mcp H5 集成 Web IM SDK 怎么发送语音消息？
+```
+
+## 完整配置（需要在控制台创建应用）
 
-```bash
-npx -y @tencentcloud/sdk-mcp
+```json
+{
+  "mcpServers": {
+    "tencentcloud-sdk-mcp": {
+      "command": "npx",
+      "args": ["-y", "@tencentcloud/sdk-mcp@latest"],
+      "env": {
+        "SDKAPPID": "YOUR_SDKAPPID",
+        "SECRETKEY": "YOUR_SECRET_KEY"
+      }
+    }
+  }
+}
 ```
 
-## 更新记录
+控制台入口：
+- 即时通信 IM 控制台：`https://console.cloud.tencent.com/im`
+- 音视频 TRTC 控制台：`https://console.cloud.tencent.com/trtc`
 
-> 仅展示最近更新，完整历史请查看 `CHANGELOG.md`。
+## 接入准备说明
 
-## Version 1.7.5 @2026.09.04
+- **无账号/未创建应用也可先试用**：可先体验文档检索与知识咨询能力。
+- `SDKAPPID`：你的 IM/TRTC 应用 ID（控制台获取）。
+- `SECRETKEY`：用于测试生成 `userSig`。
+- **生产环境要求**：`userSig` 必须由服务端签发，不建议长期使用本地测试签发方式。
 
-### 变更
-- 重构 `preflight-route` 决策模型为 **agent-first 最小纠偏**：以 agent 传入的 `product/frameworks` 为主，prompt 仅用于高置信纠错与收窄，避免无证扩张。
-- 优化框架轴冲突处理：新增/强化 `react-native`、`miniprogram` 强锁策略，并在强锁场景下区分 host-env（`android/ios`）与真实 framework，减少误收窄。
-- 优化 native TRTC 纠偏：当 prompt 命中 native TRTC 类/方法且无 WebRTC 硬信号时，将 `rtcengine` 收窄为 `native_trtc_sdk`，降低 web/native 串场景风险。
+## 常见问题
 
-### 修复
-- 修复强框架词以“被动提及”出现时对 agent 结果过度覆盖的问题，降低文档枚举词触发误纠偏的概率。
+- **连接失败/工具未激活**：检查 MCP 配置是否生效，确认服务状态为 Connected。
+- **`npx` 异常**：可清理 `npx` 缓存后重试：`rm -rf ~/.npm/_npx && npm cache verify`。
+- **`userSig` 无效**：重新调用 `get_usersig` 生成。
+
+## 更新记录
 
-## Version 1.7.4 @2026.08.31
+> 仅展示最近更新，完整历史请查看 `CHANGELOG.md`。
 
-### 新增
-- 新增 CallKit Flutter 最佳实践文档 4 篇：Android 后台通话保活、iOS 后台音频保活、iOS 启动崩溃排查、后台来电无通知排查。
-- 新增 CallKit Android 视频交友场景（VideoChat Demo）最佳实践文档，覆盖 Demo 跑通与组件快速集成。
-- 新增 CallKit HarmonyOS 平台支持：含 UI 集成指南与 API 参考文档。
-- 新增 CallKit 小程序 & uni-app 集成文档：含 UI 集成指南、API 参考、uni-app 打包指南。
-- 新增 CallKit uni-app（Android/iOS）独立集成文档与 API 参考。
-- 新增 Chat Vue3/React H5 移动端集成文档。
+## Version 1.7.7 @2026.09.11
 
 ### 变更
-- 优化 Chat 含 UI 检索标签：vue/react 的 framework 从单标签改为双标签（`['vue','web']` / `['react','web']`），使 `frameworks=['web']` 也能命中 Chat Web 端文档。
-
-## Version 1.7.3 @2026.08.17
+- 优化 MCP 连接稳定性与可观测性，提升异常定位与运行诊断效率。
 
-### 新增
-- 新增 RoomKit 多端集成、录制、白板、网络代理、AI 降噪与字幕翻译等知识库资源，扩充 Room 产品域知识覆盖。
-- 新增错误码、日志级别、屏幕分享自动停止及微信小程序报错排查等最佳实践文档。
-- 新增通用加性 rerank 模块，实现锚点选择与短语提取，并集成到搜索重排逻辑，提升召回排序准确率。
+## Version 1.7.6 @2026.09.09
 
 ### 变更
-- 优化 BM25 索引为无原型对象，提升索引结构的隔离性与稳定性。
+- 清理知识库中引流入口信息，减少知识库检索噪声。
+- 重构工具定义：统一工具的调用边界、触发语义和模板结构。
+- 调整全局 Workflow 语义为“咨询流专用”，降低工具路由歧义。
 
 ### 修复
-- 修复 BM25 打分受原型键污染导致的异常，增加原型键守卫，避免打分污染与 NaN 问题。
+- 修复部分集成工具定义中的边界冲突与参数文案不一致问题（如 `get_native_callkit_core_integration`），提升调用稳定性。

package/index.js

@@ -2,15 +2,37 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { createServer } from './server.js';
 import { ServerConfig } from './server-config.js';
+import { normalizeError } from './utils/normalize-error.js';
+import { reportCLSClient } from './utils/report-cls-client.js';
 // 启动服务器
+let startTime = 0;
 async function main() {
+    startTime = Date.now();
     ServerConfig.getInstance();
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error('RTC Official MCP Server running on stdio');
 }
-main().catch((error) => {
+main().then(() => {
+    reportCLSClient({
+        method: 'mcp_connect_success',
+        from: 'stdio',
+        info: JSON.stringify({
+            status: 'success',
+            latency_ms: Date.now() - startTime,
+        }),
+    });
+}).catch((error) => {
+    reportCLSClient({
+        method: 'mcp_connect_fail',
+        from: 'stdio',
+        info: JSON.stringify({
+            status: 'fail',
+            latency_ms: Date.now() - startTime,
+            ...normalizeError(error),
+        }),
+    });
     console.error('Server error:', error);
     process.exit(1);
 });

package/knowledge/chunker.js

@@ -125,6 +125,7 @@ function buildChunk(meta, source, title, body, id, char_start, char_end, extra)
         types: meta.types,
         scenario: meta.scenario,
         variant: meta.variant,
+        platform: meta.platform,
         scope: meta.scope,
         doc_kind: meta.doc_kind,
         capability_status: meta.capability_status,

package/knowledge/path-meta.js

@@ -65,6 +65,7 @@ export function inferPathMeta(relativeSource) {
     let types = corpus === 'integration' ? ['integration'] : [];
     let scenario = null;
     let variant;
+    let platform;
     let doc_kind;
     let capability_status;
     let retrievable_scope;
@@ -78,10 +79,19 @@ export function inferPathMeta(relativeSource) {
     else if (normalized.startsWith('knowledge/chat/') || normalized.startsWith('integration/chat/')) {
         product = 'chat';
         if (parts.includes('preset') && parts.length >= 4) {
-            const fw = normalizeFrameworkDir(parts[parts.indexOf('preset') + 1]);
+            const presetIdx = parts.indexOf('preset');
+            const fw = normalizeFrameworkDir(parts[presetIdx + 1]);
+            const platformSegment = String(parts[presetIdx + 2] ?? '').toLowerCase();
             // vue/react 运行在 Web/H5 端，追加 web 标签，使 frameworks=['web'] 也能命中
             framework = (fw === 'vue' || fw === 'react') ? [fw, 'web'] : [fw];
             variant = 'preset';
+            // 仅在显式 h5/mobile 路径时标记为移动网页；默认按 desktop 处理，避免误伤 native 路由
+            if (platformSegment === 'h5' || platformSegment === 'mobile') {
+                platform = 'mobile';
+            }
+            else {
+                platform = 'desktop';
+            }
             // preset 下的 integration.md 显式标记 integration type
             if (fileName.toLowerCase() === 'integration.md') {
                 types.push('integration');
@@ -371,6 +381,7 @@ export function inferPathMeta(relativeSource) {
         scenario,
         corpus,
         variant,
+        platform,
         scope,
         doc_kind,
         capability_status,

package/knowledge/search/search-core.js

@@ -151,16 +151,24 @@ export function sourceTitle(source) {
     const base = source.split('/').pop()?.replace(/\.md$/i, '') ?? source;
     return base || source;
 }
-export function pickNarrativeSource(_exactHits, ranked, poolWithContent) {
+function detectH5Intent(prompt) {
+    return /(\bh5\b|移动端网页|手机网页|mobile\s*web|web\s*mobile)/i.test(prompt);
+}
+function hasNativeIntent(prompt) {
+    return /(android|ios|flutter|react\s*native|react-native|uni-?app|harmonyos|鸿蒙|原生|小程序|miniprogram)/i.test(prompt);
+}
+export function pickNarrativeSource(prompt, ranked, poolWithContent) {
     const bySource = new Map();
     const chunksById = new Map(poolWithContent.map((chunk) => [chunk.id, chunk]));
-    const upsertSource = (source, score, weight) => {
+    const h5BoostEnabled = detectH5Intent(prompt) && !hasNativeIntent(prompt);
+    const upsertSource = (source, score, weight, platform) => {
         const prev = bySource.get(source);
         if (!prev) {
             bySource.set(source, {
                 hitCount: 1,
                 bestScore: score,
                 weightedScore: score * weight,
+                platform,
             });
             return;
         }
@@ -168,6 +176,7 @@ export function pickNarrativeSource(_exactHits, ranked, poolWithContent) {
             hitCount: prev.hitCount + 1,
             bestScore: Math.max(prev.bestScore, score),
             weightedScore: prev.weightedScore + score * weight,
+            platform: prev.platform ?? platform,
         });
     };
     const topScore = ranked[0]?.score ?? 0;
@@ -178,12 +187,21 @@ export function pickNarrativeSource(_exactHits, ranked, poolWithContent) {
             continue;
         if (topScore > 0 && idx > 120 && item.score < topScore * 0.03)
             break;
-        const weight = idx < 20 ? 1 : idx < 80 ? 0.7 : 0.5;
-        upsertSource(chunk.source, item.score, weight);
+        let weight = idx < 20 ? 1 : idx < 80 ? 0.7 : 0.5;
+        if (h5BoostEnabled && chunk.platform === 'mobile') {
+            weight *= 1.3;
+        }
+        upsertSource(chunk.source, item.score, weight, chunk.platform);
     }
     const candidates = [...bySource.entries()].sort((a, b) => {
         if (b[1].weightedScore !== a[1].weightedScore)
             return b[1].weightedScore - a[1].weightedScore;
+        if (h5BoostEnabled && a[1].platform !== b[1].platform) {
+            if (a[1].platform === 'mobile')
+                return 1;
+            if (b[1].platform === 'mobile')
+                return -1;
+        }
         if (b[1].hitCount !== a[1].hitCount)
             return b[1].hitCount - a[1].hitCount;
         return b[1].bestScore - a[1].bestScore;

package/knowledge/search/search-knowledge.js

@@ -340,7 +340,7 @@ export function searchKnowledge(params) {
     }
     const resolveNarrativeState = (passSnapshot) => {
         const source = retrievalMode === 'narrative'
-            ? pickNarrativeSource(passSnapshot.exactHits, passSnapshot.rankedWithMultipliers, passSnapshot.poolWithContent)
+            ? pickNarrativeSource(norm.prompt, passSnapshot.rankedWithMultipliers, passSnapshot.poolWithContent)
             : null;
         const document = source ? buildNarrativeDocument(source, allChunks) : null;
         const quality = assessNarrativeCompleteness(document, norm.prompt);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencentcloud/sdk-mcp",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",