MCP ECharts

Instructions

Implementation Reference

• src/tools/heatmap.ts:44-171 (handler)

  The core handler function 'run' that processes the input data, transforms it into ECharts heatmap format, configures the chart options including visual map, axes, and series, and generates the final chart image using generateChartImage utility.

  run: async (params: {
    axisXTitle?: string;
    axisYTitle?: string;
    data: Array<{ x: string | number; y: string | number; value: number }>;
    height: number;
    theme?: "default" | "dark";
    title?: string;
    width: number;
    outputType?: "png" | "svg" | "option";
  }) => {
    const {
      axisXTitle,
      axisYTitle,
      data,
      height,
      theme,
      title,
      width,
      outputType,
    } = params;
  
    // Extract unique x and y values
    const xValues = Array.from(new Set(data.map((item) => item.x))).sort();
    const yValues = Array.from(new Set(data.map((item) => item.y))).sort();
  
    // Create data map for quick lookup
    const dataMap = new Map();
    for (const item of data) {
      dataMap.set(`${item.x}_${item.y}`, item.value);
    }
  
    // Transform data for ECharts heatmap
    const heatmapData = [];
    for (let i = 0; i < xValues.length; i++) {
      for (let j = 0; j < yValues.length; j++) {
        const value = dataMap.get(`${xValues[i]}_${yValues[j]}`) || 0;
        heatmapData.push([i, j, value]);
      }
    }
  
    // Calculate value range for visual map
    const values = data.map((item) => item.value);
    const minValue = Math.min(...values);
    const maxValue = Math.max(...values);
  
    const series: Array<SeriesOption> = [
      {
        type: "heatmap",
        data: heatmapData,
        label: {
          show: true,
          fontSize: 10,
        },
        emphasis: {
          itemStyle: {
            shadowBlur: 10,
            shadowColor: "rgba(0, 0, 0, 0.5)",
          },
        },
      },
    ];
  
    const echartsOption: EChartsOption = {
      grid: {
        height: "60%",
        top: "15%",
        right: "15%",
        bottom: "10%",
      },
      series,
      title: {
        left: "center",
        text: title,
        top: "3%",
      },
      tooltip: {
        position: "top",
      },
      visualMap: {
        min: minValue,
        max: maxValue,
        calculable: true,
        orient: "horizontal",
        left: "center",
        bottom: "15%",
        inRange: {
          color: [
            "#313695",
            "#4575b4",
            "#74add1",
            "#abd9e9",
            "#e0f3f8",
            "#ffffcc",
            "#fee090",
            "#fdae61",
            "#f46d43",
            "#d73027",
            "#a50026",
          ],
        },
      },
      xAxis: {
        type: "category",
        data: xValues,
        name: axisXTitle,
        splitArea: {
          show: true,
        },
      },
      yAxis: {
        type: "category",
        data: yValues,
        name: axisYTitle,
        splitArea: {
          show: true,
        },
      },
    };
  
    return await generateChartImage(
      echartsOption,
      width,
      height,
      theme,
      outputType,
      "generate_heatmap_chart",
    );
  },

• src/tools/heatmap.ts:29-43 (schema)

  Zod input schema defining parameters like axis titles, data array of {x, y, value}, dimensions, theme, title, and output type for the generate_heatmap_chart tool.

  inputSchema: z.object({
    axisXTitle: AxisXTitleSchema,
    axisYTitle: AxisYTitleSchema,
    data: z
      .array(data)
      .describe(
        "Data for heatmap chart, such as, [{ x: 'Mon', y: '12AM', value: 5 }, { x: 'Tue', y: '1AM', value: 3 }].",
      )
      .nonempty({ message: "Heatmap chart data cannot be empty." }),
    height: HeightSchema,
    theme: ThemeSchema,
    title: TitleSchema,
    width: WidthSchema,
    outputType: OutputTypeSchema,
  }),

• src/tools/index.ts:19-37 (registration)

  Registration of all chart tools including generateHeatmapChartTool in the exported 'tools' array, likely used by the MCP server to register the tool.

  export const tools = [
    generateEChartsTool,
    generateLineChartTool,
    generateBarChartTool,
    generatePieChartTool,
    generateRadarChartTool,
    generateScatterChartTool,
    generateSankeyChartTool,
    generateFunnelChartTool,
    generateGaugeChartTool,
    generateTreemapChartTool,
    generateSunburstChartTool,
    generateHeatmapChartTool,
    generateCandlestickChartTool,
    generateBoxplotChartTool,
    generateGraphChartTool,
    generateParallelChartTool,
    generateTreeChartTool,
  ];

• src/tools/index.ts:52-52 (registration)

  Re-export of generateHeatmapChartTool for convenient use.

  generateHeatmapChartTool,

• src/tools/heatmap.ts:15-24 (schema)

  Zod schema for individual heatmap data points used in the input schema.

  const data = z.object({
    x: z
      .union([z.string(), z.number()])
      .describe("X axis value, such as 'Mon' or 0."),
    y: z
      .union([z.string(), z.number()])
      .describe("Y axis value, such as 'AM' or 0."),
    value: z.number().describe("Heat value at this position, such as 5."),
  });