企业官网建设流程全解析

1. 为什么要在 TDesign Chatbot 里接 MCP

TDesign 是腾讯开源的企业级设计体系，覆盖 Vue 2/Vue 3/React/小程序/Flutter/UniApp 多技术栈，还自带 Starter Kit 脚手架和 Chatbot 智能对话组件。它比较特别的一点是提供了 tdesign-mcp 这个本地 MCP 服务器，AI 编程工具接上之后能直接查组件 API、示例代码、图标和变更记录，写页面时不用来回翻文档。

但实际联调时，很多人卡在同一个地方：Chatbot 组件本身能跑，MCP 通道却连不上，或者连上了但 AI 工具读不到组件信息。原因通常是配置文件骨架没搭对——MCP 服务端、TaoToken 统一 Key、Chatbot 前端三者的配置散在不同文件里，缺一个字段就静默失败。

这篇就聚焦这个场景：面向前端开发者本地联调，交付可复制的config.toml和settings.json骨架，标出 TaoToken 统一 Key 该填在哪，最后给出启动后验证 MCP 通道连通的具体动作和预期输出。适合已经在用 TDesign Starter、想给 Chatbot 接上 MCP 能力的前端同学。

2. TaoToken 前置准备：统一 Key 与接入地址

TaoToken 在这里的角色是统一模型接入层。TDesign Chatbot 要调对话模型，tdesign-mcp 要调工具模型，如果每个服务各配一套 Key，本地联调时改一处漏一处。用 TaoToken 的统一 Key，两个地方填同一个值就行。

你需要先拿到 Key。登录 TaoToken 控制台，在 API Keys 页面创建一个新 Key，复制出来备用。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API Keys 页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

接入地址统一用 https://taotoken.net/api ，注意这个地址不带 UTM 参数，直接写进配置即可。模型对话相关的能力走 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 可以查看可用模型列表。

注意：Key 只存在本地配置文件里，不要提交到 Git。建议在项目根目录加.gitignore排除config.toml和settings.json，或者用环境变量注入。

如果你后续要做长期编码或 Agent 类任务，可以了解 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

3. 可复制配置：config.toml 与 settings.json 骨架

这一节是核心。TDesign Starter 初始化后，项目里通常没有 MCP 相关配置，需要手动补两个文件。下面给的是最小可用骨架，字段含义逐条说明。

3.1 config.toml：MCP 服务端与模型接入

在项目根目录新建config.toml。这个文件负责声明 MCP 服务器怎么启动、模型走哪个网关。

# config.toml - TDesign Chatbot + MCP 本地联调配置 [mcp] # MCP 服务端启动方式，tdesign-mcp 通过 npx 拉起 server_command = "npx" server_args = ["-y", "tdesign-mcp-server@latest"] # 本地 MCP 通道监听端口，默认 3100，冲突可改 port = 3100 # 启动超时，毫秒 startup_timeout = 15000 [model] # TaoToken 统一接入地址，不带 UTM base_url = "https://taotoken.net/api" # 统一 Key，从控制台复制后填这里 api_key = "sk-你的TaoTokenKey" # Chatbot 对话使用的模型 chat_model = "gpt-4o-mini" # MCP 工具调用使用的模型 tool_model = "gpt-4o-mini" # 请求超时，秒 timeout = 60 [chatbot] # Chatbot 组件挂载路径 mount_path = "/chat" # 是否开启流式输出 stream = true # 会话历史保留条数 history_limit = 20

几个容易填错的点：server_args里的-y不能省，否则 npx 会交互式询问导致启动卡住；port如果被占用，MCP 通道会起不来但前端不一定报错，后面排障会讲怎么查；api_key填的是 TaoToken 的 Key，不是模型厂商的 Key。

3.2 settings.json：AI 编程工具侧的 MCP 注册

如果你用的是支持 MCP 的 AI 编程工具（比如 Qoder、Claude Code 等），需要在工具的 settings 里注册 tdesign-mcp。以通用格式为例，在项目根目录建.mcp/settings.json：

{ "mcpServers": { "tdesign-mcp-server": { "command": "npx", "args": ["-y", "tdesign-mcp-server@latest"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的TaoTokenKey" } } } }

这里env里的两个变量是给 MCP 服务端读的，让它调模型时走 TaoToken 网关。command和args必须和config.toml里的server_command/server_args保持一致，否则会出现「前端以为连上了、工具侧其实没起来」的假连通。

3.3 两个文件的字段对照

对照表的意思是：凡是两边都有的字段，值必须一致。端口只在 config.toml 里配，settings.json 不需要。

4. 启动与验证：确认 MCP 通道真的通了

配置写完，启动顺序有讲究。先起 MCP 服务端，再起前端 dev server，最后在 Chatbot 里发一条消息验证。

4.1 启动 MCP 服务端

在项目根目录执行：

npx -y tdesign-mcp-server@latest --port 3100

预期输出类似：

tdesign-mcp-server started listening on http://127.0.0.1:3100 tools registered: 5

看到tools registered: 5说明 tdesign-mcp 的 5 个工具（查组件、看文档、找图标、查变更记录、查 DOM 结构）都注册好了。如果只显示 0 或报错，先别急着起前端。

4.2 启动 TDesign Starter 前端

另开一个终端：

npm install npm run dev

访问 http://localhost:3002 ，进入 Chatbot 页面（路径取决于你mount_path的配置，默认/chat）。

4.3 验证 MCP 通道连通

在 Chatbot 输入框里发一条能触发工具调用的消息，比如：

帮我查一下 TDesign 的 Button 组件有哪些 props

预期行为：Chatbot 先显示「正在调用工具」，然后返回 Button 组件的 props 列表。如果返回的是模型自己编的内容而不是真实文档，说明 MCP 通道没通，模型在裸答。

更直接的验证方式是看 MCP 服务端终端的日志。通道连通时，每发一条触发工具的消息，终端会打印类似：

[tool] tdesign_get_component_doc called [tool] args: {"component": "Button"} [tool] response: 200, 1.2kb

看到[tool]开头的日志，就说明 Chatbot → MCP → TaoToken → 模型这条链路是通的。没有日志就是没通，进下一节排障。

5. 本篇常见错排查

5.1 MCP 服务端起不来，端口被占用

报错长这样：

Error: listen EADDRINUSE: address already in use 127.0.0.1:3100

先查谁占了端口：

lsof -i :3100

拿到 PID 后 kill 掉，或者把config.toml里的mcp.port改成 3101，同时启动命令的--port也要改，两边保持一致。

5.2 Chatbot 能回消息，但从不调工具

现象是模型正常聊天，但问组件文档时它自己编。原因通常是settings.json里的env没配，MCP 服务端拿不到 TaoToken 的地址和 Key，工具注册失败但进程还活着。

排查动作：看 MCP 服务端启动日志里tools registered是不是 5。如果是 0，检查env.TAOTOKEN_BASE_URL和env.TAOTOKEN_API_KEY是否填了、Key 是否复制完整（别漏了sk-前缀）。

5.3 报 401 或鉴权失败

Error: 401 Unauthorized

两种可能：Key 填错，或者base_url带了多余路径。TaoToken 的接入地址就是https://taotoken.net/api，不要在后面加/v1之类的后缀。Key 重新从控制台复制一次，注意前后不要有空格。

5.4 npx 拉包超时

npm ERR! network timeout

tdesign-mcp-server 首次拉取需要联网。如果本地 npm 源慢，可以临时切到国内镜像：

npm config set registry https://registry.npmmirror.com

拉成功后再切回来。这个和 MCP 配置无关，纯粹是包下载问题。

5.5 改了配置不生效

MCP 服务端和前端都要重启。只重启前端，MCP 服务端还是旧配置；只重启 MCP，前端缓存的连接信息没更新。改完config.toml或settings.json，两个终端都 Ctrl+C 再重新起。

6. 接下来怎么走

配置骨架跑通之后，你可以把config.toml里的chat_model换成更强的模型试试工具调用效果，模型列表在 https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 看。如果要做更复杂的 Agent 流程，比如让 Chatbot 连续调多个 MCP 工具，Coding Plan 里有对应的额度方案：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

联调时我习惯把 MCP 服务端日志单独开一个终端窗口盯着，[tool]日志一出来就知道链路通了，比在前端猜快得多。Key 的管理建议用环境变量注入，别硬编码在文件里，团队协作时少很多麻烦。