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

TUIKit H5 端界面效果如下图所示:

AI 集成 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 -vnpm -v
如果能正确显示版本号,则环境准备完成。
如果提示
没有相关命令或其他错误, 请将完整的错误信息截图或文字内容提供给 AI,以便更高效地找到解决方案。2. 即时通信 IM 应用信息准备
获取您自己的腾讯云即时通信 IM 应用的凭证信息:
注册账号: 注册一个腾讯云账号。
创建应用: 在腾讯云控制台创建一个 即时通信 IM 应用。
获取密钥: 获取 IM 应用的
SDKAppID 和 secretKey,这将在配置 MCP 时作为环境变量使用。步骤2:MCP 工具配置
在使用 MCP 工具前,您需要在代码编辑器(例如:Cursor、Trae、CodeBuddy、VSCode)的配置面板中进行设置。推荐您配置到当前项目的根目录下。
1. 下载 Cursor
2. 在项目根目录下创建
.cursor/mcp.json 文件,把 mcpServers 的配置信息更新到 mcp.json 中并进行保存。{"mcpServers": {"tencentcloud-sdk-mcp": {"command": "npx","args": ["-y", "@tencentcloud/sdk-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": {"tencentcloud-sdk-mcp": {"command": "npx","args": ["-y", "@tencentcloud/sdk-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": {"tencentcloud-sdk-mcp": {"command": "npx","args": ["-y", "@tencentcloud/sdk-mcp"],"env": {"SDKAPPID": "YOUR_SDKAPPID","SECRETKEY": "YOUR_SECRET_KEY"}}}}
注意:请及时保存您修改的配置文件。
Windows 用户:
Ctrl + S,Mac 用户: Command + S 。4. 检查 MCP 工具是否成功加载 tools。

1. 安装 VS Code CodeBuddy 插件。

2. 插件安装成功后,在侧边栏找到 CODEBUDDY 入口,单击 MCP 市场图标 > 已安装 > 配置 MCP Server。


3. 把
mcpServers 的配置信息更新到配置文件中并进行保存。{"mcpServers": {"tencentcloud-sdk-mcp": {"command": "npx","args": ["-y", "@tencentcloud/sdk-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 (推荐)
4.1 创建和初始化项目
输入提示词, AI 帮您自动创建项目,项目创建成功后 AI 会自动在
App.vue/App.tsx 文件中引入 TUIKit 组件,并以模板代码的方式更新文件。提示词示例:
1. 请使用 TUIKit 组件创建一个 vue3 聊天应用。2. 请使用 TUIKit 组件创建一个 react18 聊天应用。3. 请使用 TUIKit 组件创建一个 UI 类似微信的 vue3 聊天应用。
注意:
如果您已经配置了
SDKAppID 和 secretKey ,在集成过程中会自动帮您生成和填写测试 userID 和 userSig,您可以跳过步骤 4.2 和 4.3 。如果您没有配置
SDKAppID 和 secretKey ,建议您在 MCP 环境变量中进行配置,然后您按照步骤 4.2 和 4.3 获取和填写账号信息。4.2 获取登录账号信息
TUIKit 集成完成后,您需要获取 SDKAppID 登录的账号信息。提示词示例:
请使用 MCP 工具,生成 test001 的 userSig。
4.3 填写登录凭据
AI 输出账号信息后,让 AI 自动将所有登录信息填入代码。
提示词示例:
请将 SDKAppID、userID、userSig 填写到代码中。
场景二:在已有项目中集成 TUIKit
4.1 依赖安装和组件导入
输入提示词, 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,您可以跳过步骤 4.2 和 4.3 。如果您没有配置
SDKAppID 和 secretKey ,建议您在 MCP 环境变量中进行配置,然后您按照步骤 4.2 和 4.3 获取和填写账号信息。4.2 获取登录账号信息
TUIKit 集成完成后,您需要获取 SDKAppID 登录的账号信息。提示词示例:
请使用 MCP 工具,生成 test001 的 userSig。
4.3 填写登录凭据
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 @tencentcloud/sdk-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 集成文档。"}```