tencent cloud

AI 接入（MCP）
下载PDF
最后更新时间：2025-12-12 17:39:20
AI 接入（MCP）
最后更新时间： 2025-12-12 17:39:20
下载PDF

概览

本文档为开发者提供了清晰、高效的步骤，用于在支持 AI 辅助编程的 IDE（例如 Cursor、Trae、CodeBuddy）中，通过 Model Context Protocol (模型上下文协议) Server 快速集成 TUIKit组件，从而通过 AI 自动生成项目初始化和集成代码。通过配置 MCP Server，AI 可以调用 @tencent-rtc/mcp 提供的工具集，帮您完成以下工作：
帮您自动初始化项目并安装所需依赖。
帮您自动生成 TUIKit 组件的集成代码，让您快速拥有如单聊、群聊、会话列表等核心即时通信功能，无需手动编写大量重复性代码。

步骤1：环境准备

1. 准备开发环境

确保您的本地开发环境中安装了推荐版本的 Node.js 和 npm (Node Package Manager)。
下载与安装：
请访问 Node.js 官方网站 下载并安装适用于您操作系统的版本。
推荐版本：建议使用 Node.js LTS (长期支持) 版本，通常在 18.x 或 20.x 系列。
验证安装：
安装完成后，请打开您电脑上的命令窗口（或叫命令提示符、终端），运行以下命令验证版本：
Windows 系统： 请按下键盘上的 Win 键 + R 键，输入cmd，然后按回车键打开。
Mac 系统： 请按下 Command+ 空格键，输入终端或 Terminal，然后按回车键打开。
node -v
npm -v
如果能正确显示版本号，则环境准备完成。
如果提示没有相关命令或其他错误，请将完整的错误信息截图或文字内容提供给 AI，以便更高效地找到解决方案。

2. 获取 Chat 应用信息

获取您自己的腾讯云即时通信 Chat 应用的凭证信息，参考开通服务创建一个 Chat 应用并获取应用的 SDKAppID 和 secretKey，这将在配置 MCP 时作为环境变量使用。

步骤2：MCP 工具配置

在使用 MCP 工具前，您需要在代码编辑器（例如：Cursor、Trae、CodeBuddy）的配置面板中进行设置。推荐您配置到当前项目的根目录下。
Cursor 配置指引
Trae 配置指引
CodeBuddy 配置指引
1. 下载 Cursor
2. 在项目根目录下创建 .cursor/mcp.json 文件，把 mcpServers 的配置信息更新到 mcp.json 中并进行保存。
{
  "mcpServers": {
    "tencent-rtc": {
      "command": "npx",
      "args": ["-y", "@tencent-rtc/mcp"],
      "env": {
        "SDKAPPID": "YOUR_SDKAPPID",
        "SECRETKEY": "YOUR_SECRET_KEY"
      }
    }
  }
}
注意：请及时保存您修改的配置文件。
Windows 用户： Ctrl + S，Mac 用户： Command+ S 。
3. 当保存文件时，会弹出下图提示，选择 Enable 开启 MCP 工具。

4. 配置完成，在 Cursor 的 Settings - Tools & MCP 选项中检查 MCP 工具是否成功加载 tools。

1. 下载 Trae
2. 单击设置 > MCP > +添加 > 选择 手动添加

3. 单击原始配置（JSON）打开配置文件，把 mcpServers 的配置信息更新到配置文件中并进行保存。
{
  "mcpServers": {
    "tencent-rtc": {
      "command": "npx",
      "args": ["-y", "@tencent-rtc/mcp"],
      "env": {
        "SDKAPPID": "YOUR_SDKAPPID",
        "SECRETKEY": "YOUR_SECRET_KEY"
      }
    }
  }
}
注意：请及时保存您修改的配置文件。
Windows 用户： Ctrl + S，Mac 用户： Command + S 。

4. 选择编辑器默认的 Builder with MCP 或者将 MCP 添加到您自定义的 Builder 中。

1. 下载 CodeBuddy
2. 单击 设置 > 添加 MCP 打开 settings.json 配置 MCP。

3. 把 mcpServers 的配置信息更新到 settings.json文件中并进行保存。
{
  "mcpServers": {
    "tencent-rtc": {
      "command": "npx",
      "args": ["-y", "@tencent-rtc/mcp"],
      "env": {
        "SDKAPPID": "YOUR_SDKAPPID",
        "SECRETKEY": "YOUR_SECRET_KEY"
      }
    }
  }
}
注意：请及时保存您修改的配置文件。
Windows 用户： Ctrl + S，Mac 用户： Command + S 。
4. 检查 MCP 工具是否成功加载 tools。


步骤3：Rules 配置（推荐）

AI 助手的精准性和技术约束的执行依赖于规则配置，这是确保 AI 能够正确理解您的 TUIKit 需求并生成符合规范代码的强制性前置步骤。推荐您在代码编辑器中配置 MCP 工具时，同时配置 Rules 内容。
注意：
您可以配置为项目级别的规则，只在当前项目中生效。
部分编辑器需要选择规则触发的方式，Cursor 请选择 Apply Intelligently, CodeBuddy 请选择智能体请求。
Rules 内容获取： 完整的规则内容请直接参考本文档末尾的 附录：Rules 内容。

步骤4：集成 TUIKit

配置完成后，您即可通过 AI 提示词与 AI 进行对话，快速集成 TUIKit 组件。

场景一：新建项目并集成 TUIKit（推荐）

创建和初始化项目

输入提示词，AI 帮您自动创建项目，项目创建成功后 AI 会自动在 App.vue/App.tsx 文件中引入 TUIKit 组件，并以模板代码的方式更新文件。
提示词示例：
  1. 请使用 TUIKit 组件创建一个 vue3 聊天应用。
  2. 请使用 TUIKit 组件创建一个 react18 聊天应用。
  3. 请使用 TUIKit 组件创建一个 UI 类似微信的 vue3 聊天应用。
注意：
如果您已经配置了 SDKAppID 和 secretKey ，在集成过程中会自动帮您生成和填写测试 userID 和 userSig，您可以跳过下面的步骤。
如果您没有配置 SDKAppID 和 secretKey ，建议您在 MCP 环境变量中进行配置，然后您按照下面的步骤获取和填写账号信息。

获取登录账号信息

TUIKit 集成完成后，您需要获取 SDKAppID 登录的账号信息。
提示词示例：
请使用 MCP 工具，生成 test001 的 userSig。

填写登录凭据

AI 输出账号信息后，让 AI 自动将所有登录信息填入代码。
提示词示例：
请将 SDKAppID、userID、userSig 填写到代码中。

场景二：在已有项目中集成 TUIKit

依赖安装和组件导入

输入提示词，AI 帮您在已有项目中集成 TUIKit 组件，您可以选择集成完整的 TUIKit 组件或者只集成 Chat 聊天窗口组件。提示词中请务必指定目标文件路径，以提高 AI 操作的准确性（例如：请在 src/views/chat.vue 中集成 TUIKit）。
提示词示例：
  1. 请在 xxx 中集成 vue3 Chat TUIKit 组件。// 集成完整的 Chat TUIKit 组件
  2. 请在 xxx 中集成 vue3 Chat 聊天窗口组件。// 集成 Chat 聊天窗口组件
注意：
如果您已经配置了 SDKAppID 和 secretKey ，在集成过程中会自动帮您生成和填写测试 userID 和 userSig，您可以跳过下面的步骤。
如果您没有配置 SDKAppID 和 secretKey ，建议您在 MCP 环境变量中进行配置，然后您按照下面的步骤获取和填写账号信息。

获取登录账号信息

TUIKit 集成完成后，您需要获取 SDKAppID 登录的账号信息。
提示词示例：
请使用 MCP 工具，生成 test001 的 userSig。

填写登录凭据

AI 输出签名后，让 AI 自动将所有登录信息填入代码。
提示词示例：
请将 SDKAppID、userID、userSig 填写到代码中。

步骤5：运行项目

AI 会尝试使用项目中配置的启动命令（例如运行 npm run dev、pnpm run dev 命令）启动项目。
如果项目没有自动启动，您可以手动输入启动指令，AI 会自动执行。

常见问题

如何保证 AI 能够准确匹配到 MCP 工具？

结构化提示词： 对于复杂的设计需求（例如客服场景），建议使用结构化提示词，帮助 AI 更准确地还原您的设计稿。
包含关键词： 在提示词中包含例如 TUIKit、Chat、Vue3 或 React 等关键词，可以提高 AI 对您需求的理解。

如何手动安装 MCP Server ?

如果您需要手动安装 MCP Server, 请在终端执行以下命令：
npx -y @tencent-rtc/mcp

AI 创建项目过程中，如果遇到文件夹访问权限问题，怎么解决?

如果遇到本地目录访问权限问题，建议使用 sudo 权限给目录赋予写权限。


如果 AI 创建 React 项目默认使用 React 19，导致 React TUIKit 集成报错，如何解决 ?

引导 AI 把 React 版本降到 react@18，并重新安装依赖。

MCP 工具生成的 userSig 登录失败，怎么办 ?

MCP 工具生成的 userSig 登录失败，可能是因为在某些特定 IDE 下自动写入时字符被修改了，您可以让 AI 重新生成或者手动复制 userSig 到代码中。

附录：Rules 内容

# ChatKit_Web_FeatureRouter 规则文档：Web Chat UIKit 全能路由

## 目的描述 (Description)

此规则集是 Web 平台 ChatKit 的**核心功能路由器**。它封装了对 **Web ChatKit** 产品线的所有用户意图识别逻辑，旨在将用户查询（从组件集成到通用工具）**直接、精准**地路由到对应的 MCP 工具 ID，提高 MCP 文档的命中率。

---

## 强制性技术约束 (MANDATORY CONSTRAINTS)

以下是集成 Web ChatKit 时必须遵守的技术约束。智能体在回答相关问题时必须严格遵循这些限制。

### AI 解析提示:

* **通用限制：**
    * 获取 UserSig 时，需提示用户输入 userID 用于获取 userSig 来登录。
* **Vue 集成限制：**
    * 集成 Vue UIKit 时，只允许使用 `@tencentcloud/chat-uikit-vue3`。
* **React 集成限制 (版本与流程)：**
    * **强制版本：** 必须使用 **React 18.2.0** 和 **react-dom 18.2.0**。绝对禁止使用 React 19.x 或任何非 18.2.0 版本。
    * **创建流程：** 严禁直接使用 `create-react-app`。推荐使用 Vite (`npx create-vite@latest project-name --template react-ts`)。
    * **强制降级与验证：** 项目创建后，必须立即通过 `npm install react@18.2.0 react-dom@18.2.0` 强制降级到指定版本，并检查 `package.json` 确认版本正确。
* **音视频集成限制：**
    * **强制接口：** 在已集成 Chat 的项目中添加音视频通话功能时，必须使用 **calls 接口**，**call/groupCall 接口** 已废弃。

---

## 规则映射表 (Tool Mappings)

```json
{
  "ruleId": "ChatKit_Web_FeatureRouter",
  "ruleName": "ChatKit_Web_FeatureRouter",
  "description": "处理 Web 平台 ChatKit 的所有请求。此文件包含产品特有功能和通用工具映射。",
  "priority": "HIGH",
  "strategy": "INTENT_TOOL_MAPPING",
  "mappings": [
    {
      "intentKeywords": ["完整聊天功能", "全部组件", "聊天列表", "会话列表", "集成全套", "整个UI", "全套功能", "基础功能"],
      "matchedToolId": "get_web_chat_uikit_integration",
      "toolDescriptionHint": "获取包含 ConversationList、Chat、 ContactList、ChatSetting 的完整 TUIKit 集成文档。"
    },
    {
      "intentKeywords": ["聊天窗口", "对话框", "聊天界面", "发送消息", "输入框", "MessageList"],
      "matchedToolId": "get_web_chat_window_integration",
      "toolDescriptionHint": "获取仅包含 Chat、MessageList、MessageInput 等核心聊天窗口组件的集成文档。"
    },
    {
      "intentKeywords": ["组件详情","ConversationList 属性", "Chat 组件说明","ChatHeader 属性", "MessageList 属性", "MessageInput 属性", "ChatSetting 属性", "ContactList 详细", "参数说明", "修改","自定义","样式"],
      "matchedToolId": "get_web_chat_uikit_component_detail",
      "toolDescriptionHint": "获取 TUIKit 单个组件（例如 ConversationList、ChatHeader、MessageList、MessageInput）的详细使用文档和属性说明。"
    },
    {
      "intentKeywords": ["初始化", "登录 API", "会话激活", "初始化登录", "鉴权", "用户登录"],
      "matchedToolId": "get_web_chat_uikit_init",
      "toolDescriptionHint": "获取 TUIKit 组件初始化和登录相关的 API 和示例代码。"
    },
    {
      "intentKeywords": ["获取 UserSig", "用户签名", "UserSig 生成", "用户凭据", "登录凭证"],
      "matchedToolId": "get_usersig",
      "toolDescriptionHint": "获取登录 IM 应用所需的用户凭据。"
    },
    {
      "intentKeywords": ["语音通话", "通话", "视频通话", "语音呼叫", "Web Call", "集成通话", "CallKit"],
      "matchedToolId": "get_web_call_uikit_integration",
      "toolDescriptionHint": "获取在现有 Chat 集成中添加音视频通话（CallKit）功能所需的文档和集成步骤。"
    },
    {
      "intentKeywords": ["用什么框架", "React 怎么用", "Vue 集成", "哪个平台", "技术选型", "集成方式", "聊天集成"],
      "matchedToolId": "present_framework_choice",
      "toolDescriptionHint": "用户未指定技术栈或平台，建议使用此工具呈现框架或平台选择界面，以缩小文档范围。"
    }
  ],
  "defaultToolId": "get_web_chat_uikit_integration",
  "defaultAction": "当用户意图匹配度低于阈值或无法明确识别时，默认优先提供完整的 TUIKit 集成文档。"
}
```

本页内容是否解决了您的问题？
您也可以 联系销售 或 提交工单 以寻求帮助。
是
否

文档反馈