做一个图表MCP Server，分分钟的事儿？

为什么叒要造轮子？

最近在开发一个智能体，核心能力之一是数据可视化。用户需要直观的图表来理解数据，而不仅仅是数字。

• 需求： 智能体需要根据用户输入或分析结果，动态生成图表。
• 矛盾点： 调研了现有的几个流行的图表类MCP Server，发现它们几乎都只支持生成静态图片（如PNG, SVG）。静态图缺乏交互性（悬停提示、缩放、图例切换等），用户体验受限，无法满足更深入的数据探索需求。
• 最初的思路： 既然ECharts功能强大、交互性好，社区成熟，那自己封装一个ECharts，生成HTML文件，让智能体调用这个工具提供可交互图表，应该是个可行的方案。当时觉得，这应该是个“分分钟”就能完成的小工具。

实践过程：从“自由”到“稳定”的五次迭代

现实很快证明，这个“分分钟”的项目需要持续优化。以下是经历的五个主要版本及其中的挑战：

版本一：追求最大自由度 - chartOptions 参数（看起来参数极简但是功能强大）

• 设计： 工具核心参数 chartOptions (JSON字符串)，智能体需生成完整的ECharts配置项JSON，工具将其嵌入HTML模板返回。
• 优点：
  • 灵活性极高： 理论上支持ECharts所有图表类型和配置。
• 挑战：
  • JSON参数过长： 复杂图表配置JSON可达数千甚至上万字符。例如，一个稍显复杂的双Y轴图表配置如下：

    {
      "title": {
        "text": "示例图表"
      },
      "tooltip": {
        "trigger": "axis"
      },
      "legend": {
        "data": ["蒸发量", "降水量"]
      },
      "xAxis": {
        "type": "category",
        "data": ["一月", "二月", "三月", "四月", "五月", "六月", "七月"]
      },
      "yAxis": [
        {
          "type": "value",
          "name": "蒸发量",
          "axisLabel": {
            "formatter": "{value} ml"
          }
        },
        {
          "type": "value",
          "name": "降水量",
          "axisLabel": {
            "formatter": "{value} °C"
          }
        }
      ],
      "series": [
        {
          "name": "蒸发量",
          "type": "bar",
          "data": [2.0, 4.9, 7.0, 23.2, 25.6, 76.7, 135.6]
        },
        {
          "name": "降水量",
          "type": "line",
          "yAxisIndex": 1,
          "data": [2.0, 2.2, 3.3, 4.5, 6.3, 10.2, 20.3]
        }
      ]
    }
    

    这个JSON字符串长度已接近1000字符，更复杂的图表会轻松突破数千甚至上万字符。
  • 生成速度慢： 大模型生成超长JSON时流式输出速度明显下降。
  • 上下文压力： 超长JSON极易消耗模型上下文窗口，影响后续任务。
  • JSON格式错误频发： 这是最关键的问题。 大模型生成JSON时极易犯低级错误（缺失括号、逗号、引号不匹配等），导致工具内部参数校验失败，调用中断。智能体难以定位错误，修复困难。
• 结论： 过度的自由牺牲了稳定性，此方案在复杂场景下不可行。

版本二：内置图表样式，聚焦数据参数

• 设计： 在工具内部预定义常用图表样式和布局。 工具仅接收核心数据参数：chartType (图表类型)、title (标题)、xAxisData (X轴数据)、yAxisData (Y轴数据)、seriesData (系列数据)等。 这样一来，生成同样的双Y轴图表，调用参数可以简化为：

{
  "templateId": "line-chart-tech-blue",
  "data": {
    "categories": ["一月", "二月", "三月", "四月", "五月", "六月", "七月"],
    "series": [
      {
        "name": "蒸发量",
        "data": [2.0, 4.9, 7.0, 23.2, 25.6, 76.7, 135.6]
      },
      {
        "name": "降水量",
        "data": [2.0, 2.2, 3.3, 4.5, 6.3, 10.2, 20.3]
      }
    ]
  }
}

参数字符数减少了80%以上，核心信息（数据）被清晰分离出来。

• 优点：
  • 参数大幅简化： 参数量级显著降低（几十到几百字符）。
  • 生成速度提升： 大模型只需生成少量关键数据。
  • 上下文压力减小： 参数长度可控。
• 挑战：
  • JSON格式错误依然存在： 参数简化后，大模型生成时仍会偶尔出现JSON格式错误（如数组元素间缺逗号、字符串未加引号），导致工具调用失败。 例如，LLM可能生成如下的JSON：

    {
      "templateId": "line-chart-tech-blue",
      "data": {
        "categories": ["一月", "二月", "三月"],
        "series": [
          {
            "name": "蒸发量",
            "data": [2.0, 4.9, 7.0]
          },
          {
            "name": "降水量",
            "data": [2.0, 2.2, 3.3] // <--- 此处可能多一个逗号
          }, // <--- 或此处多一个逗号
        ]
      }
    }
    

    这种细微错误在复杂场景下仍会触发工具校验失败。
  • 外部修复的局限性： 曾考虑在Workflow中外挂JSON校验/修复模型，但这增加了系统复杂度和延迟，且核心问题未在工具内部解决。修复模型本身也可能引入偏差。
• 结论： 简化参数有效缓解了主要矛盾，但JSON格式错误问题仍需在工具内部解决。

版本三：尝试JSON自动修复的教训

• 设计： 在工具内部实现基于规则的JSON自动修复逻辑，尝试修复常见格式错误（补全括号、逗号等）。
• 优点：
  • 尝试内部解决稳定性问题。
• 挑战：
  • 修复效果有限： 只能处理预定义的、模式明确的简单错误。对于复杂或意外错误（嵌套混乱、键名错误），修复逻辑无能为力或可能引入更严重问题。
  • “偏差放大器”风险： 这是最深刻的教训。原始数据 -> 智能体理解 -> 生成参数，这个过程已有信息损失和潜在偏差。若调用参数再经不可靠的自动修复，可能进一步扭曲原始意图，导致最终图表与用户需求不符。修复带来的“稳定”可能是虚假的，代价是准确性。例如，LLM因上下文截断生成：

    {
      "templateId": "line-chart-tech-blue",
      "data": {
        "categories": ["一月", "二月", "三月"],
        "series": [
          {
            "name": "蒸发量",
            "data": [2.0, 4.9, 7.0]
          },
          {
            "name": "降水量",
            "data": [2.0, 2.2 // <--- 数据点被截断
          }
        ]
      }
    }
    

    修复器可能补全 }使JSON合法，但丢失的3.3 数据点永远无法恢复，导致图表展示错误信息。
• 结论： 基于简单规则的自动修复风险大于收益，被放弃。

版本四：扁平化参数结构 - 稳定性的突破

• 设计： 彻底简化参数结构，避免嵌套JSON，全部采用扁平化数组：
  • titles: string[] (标题数组)
  • xAxisLabels: string[] (X轴标签数组)
  • seriesNames: string[] (系列名称数组)
  • seriesData: number[][] (核心数据二维数组)
  • chartTypes: string[] (系列类型数组)

实际调用参数示例（类似函数调用风格）:

# 伪代码表示实际工具调用参数结构
tool_call(
  chart_type='bar_line_chart',  # 指定组合图表类型
  title='蒸发量与降水量',       # 单一标题
  categories=['一月', '二月', '三月', '四月', '五月', '六月', '七月'],
  series_names=['蒸发量', '降水量'],
  series_types=['bar', 'line'],  # 指定每个系列的类型
  series_data=[[2.0, 4.9, 7.0, 23.2, 25.6, 76.7, 135.6],[2.0, 2.2, 3.3, 4.5, 6.3, 10.2, 20.3]] # 系列数据
  y_axis_names=['蒸发量 (ml)', '降水量 (°C)'] # Y轴名称
)

这种结构将嵌套关系转化为命名约定（如series_data_0对应series_names[0]），极大降低了LLM生成复杂符号的负担。

• 优点：
  • 结构极度简单： 参数由多个独立的扁平数组组成，无复杂嵌套。
  • 符号数量锐减： 数组结构相比嵌套JSON，所需 {}, :, "key" 等符号显著减少，大模型生成错误概率大幅降低。
  • 表现稳定： 实践证明，扁平化数组是大模型最擅长、最稳定生成的参数格式。工具调用成功率接近100%。
  • 校验简单可靠： 工具内部只需检查数组存在性、长度匹配性、数据类型基本正确性。
• 缺点：
  • 灵活性受限： 无法支持ECharts所有高级配置，样式和交互细节需在工具内部固化或通过有限参数控制。这是为稳定性付出的必要代价。
• 结论： 这是关键转折点。 通过牺牲部分灵活性换取极高稳定性，找到了大模型与工具交互的“最佳实践”。扁平化数组参数设计是我在这个场景中当前阶段的最优解。

版本五：交付升级 - 生成可访问链接

• 设计： 工具生成HTML后，自动上传至对象存储服务（如COS/OSS），并返回公开可访问的HTTP下载链接。工具返回结果示例：

"https://your-cos-bucket.com/charts/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8.html"

• 优点：
  • 交付简洁： 智能体只需返回链接，用户点击即可在浏览器中打开完整可交互图表。
  • 跨平台兼容： 任何支持浏览器的设备均可访问。
  • 持久化与分享： 图表以文件形式存储，可保留和分享。
  • 减轻智能体负担： 智能体无需处理HTML渲染或存储逻辑。
• 缺点：
  • 运行环境的参差： MCP Server的部署环境会影响HTML文件的上传成败，比如上传COS需要区分内网外网，比如要区分开发环境和IDC。
• 实现要点：
  • 工具需集成对象存储SDK。
  • 需配置存储桶权限（公开读取或预签名URL）。
  • 需考虑文件命名策略和清理策略（可选）。
• 结论： 完成了从“生成内容”到“交付服务”的闭环，提供了生产级用户体验。

过程中的几点认知更新

这个“分分钟”项目，最终演变为对“如何设计大模型友好工具”的深度探索。以下几点认知，我认为比代码实现本身更具普适价值：

1. 工具规划：精简胜于冗余，职责必须分明

   • 避免“工具泛滥”： 工具过多会导致智能体选择困难或误选，影响效果。并非越多越好。
   • 坚持单一职责： 每个工具应只做一件事，并做好它。例如，“生成柱状图”、“生成折线图”、“上传文件”应作为独立工具。这使智能体决策更清晰，工具实现和测试更简单。我们最终按主要图表类型拆分了工具。

2. 参数设计：极简是王道，ID是理想态

   • 追求极致简洁： 大模型对复杂参数结构的理解和生成能力有限。参数设计应尽可能简单。
   • 最佳实践：一个ID搞定： 最理想的状态是工具仅需一个标识符（ID）（如 dataId, templateId）。所有复杂数据或配置通过此ID在系统其他地方（数据库、缓存、配置文件）预先定义或准备好。工具仅执行与ID关联的确定性操作。这彻底消除了参数层面的噪声和错误风险。 虽然当前版本未完全实现，但这是未来优化方向（如让智能体先生成数据配置ID，再调用图表工具）。

3. 参数描述：清晰、简短、示例、扁平化

   • 描述需精准明确： 每个参数的描述必须简短、清晰、无歧义。
   • 示例至关重要： 务必为每个参数提供清晰的示例值！ 示例是引导大模型正确生成参数的最有效方式。示例应覆盖典型场景和边界情况。例如，对 series_data 参数的描述： "series_data": { "type": "array", "items": {"type": "number"}, "description": "第一个数据系列的数据点数组，数值类型。例如: [10, 20, 30]" }
   • 坚决避免嵌套JSON： 除非绝对必要且能确保稳定性（如版本一被证明不可行），单一参数绝不应使用嵌套JSON对象。优先使用基本类型（string, number, boolean）和扁平数组（string[], number[]）。嵌套结构是大模型生成错误的“高发区”。

4. 错误处理：明确原因，给出建议，指引路径

   • 错误信息是关键： 工具调用失败时，返回给智能体的错误信息（message）至关重要。它直接影响智能体（尤其是基于ReAct等框架的智能体）能否理解问题并尝试修复。
   • “原因+建议”是标准： 错误信息必须清晰说明失败的具体原因，并给出明确的、可操作的修改建议。例如，当 series_data_0 包含非数字时的错误响应：

{
  "error": "Parameter 'series_data_0' contains non-numeric value 'N/A' at index 3.",
  "suggestion": "Please ensure all values in 'series_data' arrays are valid numbers. You may need to clean the source data or set a default value like 0 for missing data points."
}

• 为智能体提供路径： 良好的错误信息相当于为智能体的“思考-行动”循环（ReAct）提供了明确的下一步行动指引，帮助其从错误中恢复，而非陷入死循环或放弃。这极大提升了系统的鲁棒性和用户体验。

这是一个生成的图表的示例：

总结：从“分分钟”到“分阶段”的工程实践

回到标题：“做一个图表MCP Server，分分钟的事儿？” 答案显然是否定的。它绝非一个“分分钟”就能完美交付的简单任务。它是一个需要经历需求分析、技术选型、原型验证、问题暴露、迭代优化、认知升级的完整工程过程。

然而，这个过程的价值远超预期。我们不仅最终交付了一个稳定、可用、用户体验良好的可交互图表MCP Server，更重要的是，我们深刻理解了如何设计“大模型友好”的工具。那些关于工具规划、参数设计、描述规范、错误处理的认知更新，是可以在未来所有大模型应用开发中复用的宝贵经验。

所以，下次听到“分分钟搞定”的说法时，不妨理性看待。因为真正的价值，往往就藏在那些看似“分分钟”背后，需要“分阶段”去克服的挑战和沉淀的工程智慧之中。

模型，平台，工具都在迅速进化，我遇到的问题可能很快就会（或许已经）“不成问题”。

希望我的这些实践经验和思考，能为大家在构建更强大的AI应用时提供一些参考。