企业官网建设流程全解析

1. 为什么 LLM 直接吐图表配置总是翻车

如果你做过对话式数据分析，大概率遇到过这种场景：用户说“帮我把最近五年销售额画成折线图”，模型很自信地返回一段 JSON，你拿去喂给 ECharts 或者 AntV，结果控制台一片红。要么是chartType写成了type，要么legend.show被写成legend.enabled，再不然就是数据结构对不上，xAxis.data里塞了个对象数组。

我试过最离谱的一次，模型把tooltip的配置项编成了一个根本不存在的tooltip.enabled，前端直接白屏。排查了半天才发现是提示词里塞的图表库文档版本和实际安装的版本不一致。这种问题在 Demo 阶段还能靠人工兜底，一旦上生产，每次图表库升级都意味着要重写一遍提示词，维护成本高得离谱。

核心矛盾在于：LLM 擅长生成自然语言和结构化文本，但它对具体图表库的 API 细节没有稳定记忆。你让它“画个图”，它其实是在概率性地拼凑配置项，拼错了它也不知道。传统方案试图用更长的提示词、更多的 few-shot 示例来约束它，但本质上是在用自然语言的模糊性去对抗 API 的精确性，方向就错了。

GPT-Vis 加 MCP 的思路不一样。MCP 把“生成图表配置”这件事从 LLM 的自由发挥变成了工具调用：模型不再直接输出图表 JSON，而是调用一个标准化的 MCP 工具，由服务端保证返回的配置 100% 符合 GPT-Vis 规范。GPT-Vis 则负责把这份规范配置渲染成可交互的图表。整条链路里，LLM 只负责理解意图和提取数据，配置的合法性由 MCP Server 兜底，渲染的稳定性由 GPT-Vis 保证。

这套方案特别适合三类人：一是做对话式 BI 或报表生成的开发者，用户一句话就要出图；二是做 AI Agent 的团队，需要让 Agent 在分析过程中动态展示可视化结果；三是前端同学想给现有 LLM 应用加图表能力，但不想陷入提示词调优的无底洞。下面我从环境准备开始，一步步把这条链路跑通。

2. TaoToken 统一通道与 MCP Server Chart 前置准备

在动手写代码之前，先把两个前置条件搞定：一个是模型调用的通道，一个是 MCP Server Chart 的本地服务。这两件事看起来独立，实际上后面端到端验证时会串在一起。

先说模型通道。GPT-Vis 加 MCP 的链路里，LLM 需要支持 Function Calling 或 Tool Use，因为 MCP 工具列表要注册给模型。如果你直接用各家厂商的原生 API，每换一个模型就要改一次鉴权和 Base URL，调试阶段来回切换很烦。我的做法是用 TaoToken 统一 Key 和 API 通道，它兼容 OpenAI 的接口格式，Base URL 配成https://taotoken.net/api就行。这样无论后面换 qwen 还是别的支持 tool use 的模型，客户端代码基本不用动。

你需要在 TaoToken 控制台创建一个 API Key，地址是https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console。创建完之后先别关页面，后面配置.env要用。如果你对 Key 的管理和权限划分不熟，可以顺手看一眼接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc，里面把 Base URL、鉴权头、模型 ID 的写法都列清楚了。

再说 MCP Server Chart。它是整个方案里负责“生成合规图表配置”的核心服务。你需要 Node.js 18 以上，我本地用的是 20.11.0。拉代码、装依赖、构建：

git clone https://github.com/antvis/mcp-server-chart.git cd mcp-server-chart pnpm install pnpm build

构建完成后，用 SSE 模式启动服务：

node build/index.js -t sse -p 1122

看到终端输出监听在http://localhost:1122/sse就说明服务起来了。这里有个细节：SSE 模式适合本地开发和调试，如果你要部署到服务器给多人用，记得加鉴权和限流，别裸奔。

接下来准备一个测试用的前端项目。我用 Vite 加 React 搭一个最小环境：

pnpm create vite gpt-vis-demo --template react-ts cd gpt-vis-demo pnpm install pnpm add @antv/gpt-vis @modelcontextprotocol/sdk openai

装完之后，在项目根目录建一个.env文件，把 TaoToken 的配置写进去：

VITE_OPENAI_API_KEY=sk-你的TaoToken密钥 VITE_OPENAI_BASE_URL=https://taotoken.net/api VITE_OPENAI_MODEL=qwen-plus

注意VITE_OPENAI_BASE_URL后面不要加/v1，OpenAI SDK 会自己拼路径。模型 ID 选一个支持 tool use 的，qwen-plus 实测可以。如果你用的是别的模型，把VITE_OPENAI_MODEL换掉就行，Base URL 和 Key 不用动，这就是统一通道的好处。

到这里，模型通道和 MCP 服务都就绪了。下一步是把 MCP 工具注册给模型，并让前端能渲染 GPT-Vis 的 Markdown 语法。

3. 可复制配置：MCP 工具注册与 GPT-Vis 组件接入

这一节是整篇文章的核心，我会把 MCP 客户端连接、工具列表获取、模型调用、GPT-Vis 渲染这四段代码完整写出来，你可以直接复制到项目里跑。

先看 MCP 客户端的连接。在src下新建mcpClient.ts：

import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js"; const MCP_SERVER_URL = "http://localhost:1122/sse"; export async function createMcpClient() { const transport = new SSEClientTransport(new URL(MCP_SERVER_URL)); const client = new Client( { name: "gpt-vis-demo", version: "1.0.0" }, { capabilities: {} } ); await client.connect(transport); return client; } export async function listMcpTools(client: Client) { const res = await client.listTools(); return res.tools.map((tool) => ({ type: "function" as const, function: { name: tool.name, description: tool.description, parameters: tool.inputSchema, }, })); }

这段代码做了两件事：建立 SSE 连接，把 MCP Server 暴露的工具转换成 OpenAI Function Calling 需要的格式。tool.inputSchema是 MCP 协议自带的 JSON Schema，直接塞给模型就行，不用手写参数定义。

然后是模型调用。新建src/chat.ts：

import OpenAI from "openai"; import type { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { listMcpTools } from "./mcpClient"; const openai = new OpenAI({ apiKey: import.meta.env.VITE_OPENAI_API_KEY, baseURL: import.meta.env.VITE_OPENAI_BASE_URL, dangerouslyAllowBrowser: true, }); export async function chatWithChart( client: Client, userMessage: string ): Promise<string> { const tools = await listMcpTools(client); const completion = await openai.chat.completions.create({ model: import.meta.env.VITE_OPENAI_MODEL, messages: [ { role: "system", content: "你是数据分析助手。当用户需要图表时，调用可用的图表工具生成配置，不要自己编造图表 JSON。", }, { role: "user", content: userMessage }, ], tools, tool_choice: "auto", }); const choice = completion.choices[0]; const toolCall = choice.message.tool_calls?.[0]; if (!toolCall) { return choice.message.content ?? ""; } const args = JSON.parse(toolCall.function.arguments); const result = await client.callTool({ name: toolCall.function.name, arguments: args, }); const meta = (result as any)._meta; if (!meta?.spec) { throw new Error("MCP 返回结果缺少 _meta.spec 字段"); } const specJson = JSON.stringify(meta.spec, null, 2); return "```vis-chart\n" + specJson + "\n```"; }

这里有几个关键点。第一，tool_choice设为auto，让模型自己判断要不要调工具。第二，拿到tool_calls后解析参数，再通过client.callTool真正执行 MCP 工具。第三，从返回结果的_meta.spec里提取图表配置，包装成 GPT-Vis 能识别的vis-chart代码块。这个_meta.spec就是 MCP Server Chart 保证合规的配置，前端不需要再做任何字段映射。

最后是前端渲染。修改src/App.tsx：

import { useState } from "react"; import { GPTVis } from "@antv/gpt-vis"; import { createMcpClient } from "./mcpClient"; import { chatWithChart } from "./chat"; function App() { const [input, setInput] = useState(""); const [markdown, setMarkdown] = useState(""); const [loading, setLoading] = useState(false); const handleSend = async () => { setLoading(true); try { const client = await createMcpClient(); const result = await chatWithChart(client, input); setMarkdown(result); } catch (err) { setMarkdown("出错：" + (err as Error).message); } finally { setLoading(false); } }; return ( <div style={{ padding: 24 }}> <input value={input} onChange={(e) => setInput(e.target.value)} placeholder="试试：帮我画一个 2019-2023 年销售额折线图" style={{ width: 400, marginRight: 8 }} /> <button onClick={handleSend} disabled={loading}> {loading ? "生成中..." : "生成图表"} </button> <div style={{ marginTop: 24 }}> <GPTVis>{markdown}</GPTVis> </div> </div> ); } export default App;

GPTVis组件接收 Markdown 字符串，遇到vis-chart代码块会自动解析并渲染成 AntV 图表。你不需要手动解析 JSON，也不需要判断图表类型，GPT-Vis 内部会根据spec.type分发到对应的渲染器。

如果你用的是 Cline 或 Claude Code 这类支持 MCP 的编码工具，配置方式略有不同。以 Cline 的 MCP 配置为例，在cline_mcp_settings.json里加：

{ "mcpServers": { "chart": { "url": "http://localhost:1122/sse", "type": "sse" } } }

这样 Cline 就能直接调用图表工具。注意这里同样需要保证 Base URL、Key、Model ID 三件套在模型侧配置正确，否则工具调用的请求发不出去。

4. 端到端验证：从用户输入到图表渲染的完整请求

配置写完之后，跑一遍完整流程，确认每个环节都通。启动 MCP Server：

cd mcp-server-chart node build/index.js -t sse -p 1122

再启动前端：

cd gpt-vis-demo pnpm dev

浏览器打开http://localhost:5173，在输入框里输入“帮我画一个 2019 到 2023 年销售额折线图，数据分别是 100、150、200、180、220”。点生成图表。

正常情况下，你会看到浏览器先发起一次模型请求，模型返回一个tool_calls，里面调用的是generate_line_chart之类的工具名。然后前端拿这个工具名和参数去调 MCP Server，MCP Server 返回_meta.spec，前端把它包装成vis-chart代码块，最后 GPTVis 渲染出一条折线图。

如果你想在终端里单独验证 MCP Server 是否正常，可以用 curl 模拟一次工具调用。先拿到工具列表：

curl -N http://localhost:1122/sse

SSE 是长连接，curl 会一直挂着，你可以在另一个终端里用 Node 脚本调callTool。更简单的方式是直接在前端加一行console.log(meta.spec)，看控制台输出的配置结构。一个正常的spec大概长这样：

{ "type": "line", "data": [ { "time": "2019", "value": 100 }, { "time": "2020", "value": 150 }, { "time": "2021", "value": 200 }, { "time": "2022", "value": 180 }, { "time": "2023", "value": 220 } ], "encode": { "x": "time", "y": "value" } }

注意type字段是line，不是chartType；encode里用x和y做字段映射，而不是xAxis.data。这就是 MCP Server 帮你规范化之后的结果，模型不需要知道这些细节，它只负责把数据填进工具参数里。

验证成功之后，你可以试着换几种图表类型。比如输入“用柱状图展示各部门人数”，模型会调用柱状图工具，返回的spec.type变成column或bar，GPT-Vis 会自动切换渲染器。再试试“画一个桑基图展示用户流转”，MCP Server Chart 支持桑基图，返回的配置里会有source和target字段。整个过程你不需要改任何前端代码，这就是标准化协议加专业渲染引擎的价值。

如果你在验证时发现图表没出来，先看浏览器控制台有没有报错，再看 Network 面板里模型请求和 MCP 请求的返回。大部分问题出在工具调用参数解析或者_meta.spec提取上，下一节我把常见报错列出来。

5. 常见报错排查：401、local proxy failed 与 choices 解析失败

这一节按真实报错来，你遇到哪个就对照哪个。

401 Unauthorized。这个最常见，通常是 TaoToken 的 Key 没配对，或者.env文件没被 Vite 加载。先确认VITE_OPENAI_API_KEY的值是完整的sk-开头字符串，没有多余空格。然后检查VITE_OPENAI_BASE_URL是不是https://taotoken.net/api，注意不要写成https://taotoken.net/api/v1，OpenAI SDK 会自己拼/v1/chat/completions，你多写一层就变成/api/v1/v1/...，直接 404 或 401。改完.env记得重启pnpm dev，Vite 不会热更新环境变量。

local proxy failed。这个报错一般出现在 MCP 客户端连接阶段，说明 SSE 连接没建立起来。先确认 MCP Server 是不是真的在1122端口监听，用lsof -i :1122或netstat -ano | findstr 1122查一下。如果端口被占用，换一个端口，同时把mcpClient.ts里的MCP_SERVER_URL和 Cline 配置里的 URL 一起改掉。还有一种情况是 MCP Server 启动时用了 stdio 模式而不是 SSE 模式，-t sse参数别漏了。

reading 'choices' 报错。这个通常发生在completion.choices[0]这一行，说明模型返回体里没有choices字段。原因可能是 Base URL 配错导致请求打到了非 OpenAI 兼容的接口，或者模型 ID 写错了。先打印完整的completion对象看结构，确认返回的是标准 OpenAI 格式。如果用的是 TaoToken 通道，检查VITE_OPENAI_MODEL是不是一个支持 tool use 的模型，有些模型不支持 Function Calling，返回体里就不会有tool_calls。

OAuth 相关报错。如果你在 Claude Code 或某些 IDE 插件里配置 MCP 时看到 OAuth 错误，通常是因为 MCP Server 配置里带了不必要的鉴权字段。本地 SSE 模式的 MCP Server 不需要 OAuth，把配置里的auth或headers相关字段删掉，只保留url和type就行。如果你用的是 Codex 的auth.json，确认里面的base_url和api_key与 TaoToken 控制台一致，不要混用其他平台的凭证。

图表渲染空白但无报错。检查_meta.spec是否被正确提取。在chatWithChart里加一行console.log(JSON.stringify(meta.spec))，看输出是不是合法的图表配置。如果spec是 undefined，说明 MCP 工具返回结构和你预期的不一样，打印完整的result对象看_meta在哪一层。另外确认GPTVis组件接收的 Markdown 里代码块语言标识是vis-chart，写成json或chart都不会触发渲染。

工具调用参数解析失败。模型返回的tool_calls[0].function.arguments是一个 JSON 字符串，直接JSON.parse可能因为模型多输出了换行或转义字符而失败。加一层 try-catch，失败时打印原始字符串，必要时用正则提取花括号之间的内容再解析。实测下来，qwen-plus 在工具调用参数上的稳定性不错，但如果你换了一个较小的模型，参数格式可能会飘。

6. 把这条链路用起来：从 Demo 到生产的三点经验

跑通 Demo 只是第一步，真正要用在对话式数据分析或报表生成场景里，还有几件事值得提前想清楚。

第一，MCP Server 的部署位置。本地开发用 SSE 没问题，但生产环境建议把 MCP Server 部署成独立服务，前面加一层网关做鉴权和限流。因为图表生成涉及数据，如果 MCP Server 直接暴露在公网，任何人都能调你的工具。你可以把 MCP Server 和模型调用都收在服务端，前端只负责渲染 GPT-Vis，这样 Key 和工具列表都不会泄露到浏览器。

第二，模型的选择和降级策略。不是所有模型都稳定支持 tool use，有些模型在工具调用时会漏参数或者编造工具名。我的做法是在服务端维护一个模型白名单，只允许支持 Function Calling 的模型走 MCP 链路。如果模型不支持，降级到纯文本回复，不要让用户看到报错。TaoToken 的好处是切换模型只改一个 Model ID，Base URL 和 Key 不动，方便你做 A/B 测试。

第三，GPT-Vis 的流式渲染。GPT-Vis 支持流式输出时逐步渲染，但 MCP 工具调用是阻塞的，你得等工具返回完整spec才能渲染。如果你要做打字机效果，可以把模型回复和图表渲染分开：模型先输出一段文字说明，工具调用完成后单独渲染图表。这样用户感知上不会觉得卡顿。

这套方案我已经在几个内部报表工具里用了一段时间，最明显的感受是前端不再需要写一堆容错逻辑去猜模型返回的字段。MCP Server 把配置规范这件事收口了，GPT-Vis 把渲染这件事标准化了，开发者只需要关注业务数据和交互。如果你也在做 LLM 可视化，建议从这条链路开始试，比纯提示词工程省心得多。