@tencent-rtc/mcp 1.7.5 → 1.7.7

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # CHANGELOG
 
+## Version 1.7.7 @2026.09.11
+
+### Changed
+- Optimized MCP connection stability and observability, improving exception troubleshooting and runtime diagnostics.
+
+## Version 1.7.6 @2026.09.09
+
+### Changed
+- Cleaned traffic-entry content in the knowledge base to reduce retrieval noise.
+- Refactored tool definitions: unified invocation boundaries, trigger semantics, and template structures across tools.
+- Adjusted global Workflow semantics to be consultation-flow-only, reducing tool-routing ambiguity.
+
+### Fixed
+- Fixed boundary conflicts and inconsistent parameter wording in some integration tool definitions (for example, `get_native_callkit_core_integration`), improving invocation stability.
+
 ## Version 1.7.5 @2026.09.04
 
 ### Changed

package/README.md

@@ -1,25 +1,25 @@
-## Tencent RTC SDK MCP Server Guide
+## Tencent RTC SDK MCP Server
 
-This repository provides a CLI-based Model Context Protocol (MCP) Server that exposes Tencent RTC SDK documentation and API resources to LLM tools, helping AI agents deliver more accurate implementation guidance and integration support.
+Tencent RTC SDK MCP Server exposes official Tencent Cloud RTC knowledge and integration capabilities to AI assistants through MCP (Model Context Protocol), helping teams deliver Chat/Call/Live/Room/RTCEngine/TIMPush implementations faster.
 
-## Features
+## Highlights
 
-- **Efficient retrieval**: Supports Tencent RTC documentation retrieval for fast access to official references and best practices.
-- **Broad coverage**: Covers Chat (IM), Call, Live, Room, RTCEngine (TRTC SDK), and TIMPush domains.
-- **Intelligent routing**: Supports product/platform intent disambiguation and prompts for missing platform/framework information when needed.
-- **Integration-friendly**: In addition to documentation Q&A, provides integration entry points for Web / Android / iOS / Flutter, including UI-based integration directions.
-- **Reliable source**: Grounded in official Tencent Cloud materials to improve answer reliability and implementation readiness.
-- **Wide compatibility**: Exposes MCP capabilities over STDIN/STDOUT JSON-RPC, compatible with MCP clients such as Cursor / Codex / Claude / CodeBuddy.
-- **Quick start**: Run with `npx` and get started with minimal setup.
+- **Official knowledge retrieval**: Quickly locate product docs, integration guides, and best practices.
+- **Intent-aware routing**: Routes by product, platform, and framework to reduce retrieval noise.
+- **Integration generation support**: Supports Web / Android / iOS / Flutter integration entry points.
+- **MCP compatible**: Works with Cursor, CodeBuddy, Codex, Claude, and other MCP clients.
 
 ## Requirements
-- Node.js (>= 18) and npm
-- An MCP-capable IDE
 
-## Usage
-### Standard setup flow
+- Node.js >= 18
+- npm
+- Any MCP-capable IDE / AI client
 
-- Step1: In your Cursor project, create or edit `.cursor/mcp.json` or `~/.cursor/mcp.json` and add the following configuration.
+## 30-Second Quick Start (No console app creation required)
+
+### 1) Configure MCP Server (Trial mode)
+
+Using Cursor as an example, add this to your project `.cursor/mcp.json` (or `~/.cursor/mcp.json`):
 
 ```json
 {
@@ -28,67 +28,75 @@ This repository provides a CLI-based Model Context Protocol (MCP) Server that ex
       "command": "npx",
       "args": ["-y", "@tencent-rtc/mcp@latest"],
       "env": {
-        "SDKAPPID": "YOUR_SDKAPPID",
-        "SECRETKEY": "YOUR_SECRET_KEY"
+        "SDKAPPID": "",
+        "SECRETKEY": ""
       }
     }
   }
 }
 ```
-After saving, a prompt appears. Click **Enable** in the prompt.
 
-![mcp-server-prompt](https://web.sdk.qcloud.com/im/assets/images/mcp-server-prompt-en.png)
+### 2) Confirm server is connected
 
-- Step2: Go to **Cursor Settings** (top-right gear icon) -> **MCP**, and make sure `tencent-rtc` is enabled.
+In your MCP panel, ensure `tencent-rtc` shows **Connected**.
 
-![cursor-setting](https://web.sdk.qcloud.com/im/assets/images/cursor-setting-en.png)
+### 3) Explicitly trigger tools
 
-- Step3: Describe your requirements directly in the IDE, and let the AI complete implementation or troubleshooting based on Tencent Cloud SDK documentation.
+For higher tool activation rate and more stable results, prefix your prompt with `@tencent-rtc`.
 
-### Optional: global install
+Example:
 
-If you want quick global invocation locally, run:
+```text
+@tencent-rtc How do I send an audio message when integrating the Web IM SDK in H5?
+```
+
+## Full Configuration (Requires creating an app in console)
 
-```bash
-npx -y @tencent-rtc/mcp
+```json
+{
+  "mcpServers": {
+    "tencent-rtc": {
+      "command": "npx",
+      "args": ["-y", "@tencent-rtc/mcp@latest"],
+      "env": {
+        "SDKAPPID": "YOUR_SDKAPPID",
+        "SECRETKEY": "YOUR_SECRET_KEY"
+      }
+    }
+  }
+}
 ```
 
-## Changelog
+Console entries: `https://console.trtc.io`
 
-> Only recent updates are listed here. For full history, see `CHANGELOG.md`.
+## Prerequisites
 
-## Version 1.7.5 @2026.09.04
+- **No account / no app yet? You can still try first**: Start with document retrieval and knowledge Q&A in trial mode.
+- `SDKAPPID`: Your IM/TRTC application ID from Tencent Cloud console.
+- `SECRETKEY`: Used for local/test `userSig` generation.
+- **Production requirement**: `userSig` must be generated by your server-side service.
 
-### Changed
-- Refactored the `preflight-route` decision model to an **agent-first, minimal-correction** strategy: prioritize agent-provided `product/frameworks`, and use prompt signals only for high-confidence corrections and narrowing to avoid unsupported expansion.
-- Optimized framework-axis conflict handling: added/enhanced strong-lock strategies for `react-native` and `miniprogram`, and in strong-lock scenarios, separated host environment (`android/ios`) from the actual framework to reduce over-narrowing.
-- Optimized native TRTC correction: when the prompt matches native TRTC classes/methods and no WebRTC hard signal is present, narrow `rtcengine` to `native_trtc_sdk` to reduce web/native cross-routing risk.
+## Common Issues
 
-### Fixed
-- Fixed over-overriding of agent results when strong framework terms are only passively mentioned, reducing false corrections triggered by doc-enumeration terms.
+- **Connection failed / tool not activated**: Verify MCP config and Connected status.
+- **`npx` failures**: Retry after cache cleanup: `rm -rf ~/.npm/_npx && npm cache verify`.
+- **Invalid `userSig`**: Regenerate via `get_usersig`.
 
-## Version 1.7.4 @2026.08.31
+## Changelog
 
-### Added
-- Added 4 CallKit Flutter best-practice docs: Android background call keep-alive, iOS background audio keep-alive, iOS startup crash troubleshooting, background incoming call notification troubleshooting.
-- Added CallKit Android video chat dating scenario (VideoChat Demo) best-practice doc, covering Demo setup and component quick integration.
-- Added CallKit HarmonyOS platform support: UIKit integration guide and API reference.
-- Added CallKit Mini Program & uni-app docs: UIKit integration guide, API reference, uni-app packaging guide.
-- Added CallKit uni-app (Android/iOS) standalone integration docs and API reference.
-- Added Chat Vue3/React H5 mobile integration docs.
+> Only the latest release is shown here. See `CHANGELOG.md` for full history.
 
-### Changed
-- Optimized Chat UIKit search tags: vue/react framework changed from single tag to dual tags (`['vue','web']` / `['react','web']`), allowing `frameworks=['web']` to match Chat Web docs.
+## Version 1.7.7 @2026.09.11
 
-## Version 1.7.3 @2026.08.17
+### Changed
+- Optimized MCP connection stability and observability, improving exception troubleshooting and runtime diagnostics.
 
-### Added
-- Added knowledge base resources for RoomKit multi-platform integration, recording, whiteboard, network proxy, AI noise reduction, and subtitle translation, expanding coverage of the Room product domain.
-- Added best-practice docs covering error codes, log levels, automatic screen-share stop, and WeChat Mini Program error troubleshooting.
-- Added a generic additive rerank module with anchor selection and phrase extraction, integrated into the search reranking logic to improve recall ranking accuracy.
+## Version 1.7.6 @2026.09.09
 
 ### Changed
-- Optimized the BM25 index to use prototype-less objects, improving the isolation and stability of the index structure.
+- Cleaned traffic-entry content in the knowledge base to reduce retrieval noise.
+- Refactored tool definitions: unified invocation boundaries, trigger semantics, and template structures across tools.
+- Adjusted global Workflow semantics to be consultation-flow-only, reducing tool-routing ambiguity.
 
 ### Fixed
-- Fixed BM25 scoring anomalies caused by prototype-key pollution by adding prototype-key guards, preventing score pollution and NaN issues.
+- Fixed boundary conflicts and inconsistent parameter wording in some integration tool definitions (for example, `get_native_callkit_core_integration`), improving invocation stability.

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": "@tencent-rtc/mcp",
-  "version": "1.7.5",
+  "version": "1.7.7",
   "description": "Tencent Cloud MCP Server for SDK",
   "type": "module",
   "main": "index.js",