generate_treemap_chart

Instructions

Implementation Reference

• src/tools/treemap.ts:28-105 (handler)

  The main tool definition for generate_treemap_chart, including the 'run' async handler function that creates the treemap ECharts option and calls generateChartImage.

  export const generateTreemapChartTool = {
    name: "generate_treemap_chart",
    description:
      "Generate a treemap chart to display hierarchical data and can intuitively show comparisons between items at the same level, such as, show disk space usage with treemap.",
    inputSchema: z.object({
      data: z
        .array(TreeNodeSchema)
        .describe(
          "Data for treemap chart, such as, [{ name: 'Design', value: 70, children: [{ name: 'Tech', value: 20 }] }].",
        )
        .nonempty({ message: "Treemap chart data cannot be empty." }),
      height: HeightSchema,
      theme: ThemeSchema,
      title: TitleSchema,
      width: WidthSchema,
      outputType: OutputTypeSchema,
    }),
    run: async (params: {
      data: Array<TreemapDataType>;
      height: number;
      theme?: "default" | "dark";
      title?: string;
      width: number;
      outputType?: "png" | "svg" | "option";
    }) => {
      const { data, height, theme, title, width, outputType } = params;
  
      const series: Array<SeriesOption> = [
        {
          type: "treemap",
          data: data,
          left: "3%",
          right: "3%",
          bottom: "3%",
          label: {
            show: true,
            formatter: "{b}",
            fontSize: 12,
            color: "#fff",
          },
          emphasis: {
            focus: "descendant",
            itemStyle: {
              borderWidth: 3,
            },
            label: {
              fontSize: 16,
            },
          },
          breadcrumb: {
            show: false,
          },
          roam: false,
          nodeClick: "zoomToNode",
        },
      ];
  
      const echartsOption: EChartsOption = {
        series,
        title: {
          left: "center",
          text: title,
        },
        tooltip: {
          trigger: "item",
        },
      };
  
      return await generateChartImage(
        echartsOption,
        width,
        height,
        theme,
        outputType,
        "generate_treemap_chart",
      );
    },
  };

• src/tools/treemap.ts:32-44 (schema)

  Input schema for the generate_treemap_chart tool using Zod, defining data (array of TreeNodeSchema), height, theme, title, width, and outputType.

  inputSchema: z.object({
    data: z
      .array(TreeNodeSchema)
      .describe(
        "Data for treemap chart, such as, [{ name: 'Design', value: 70, children: [{ name: 'Tech', value: 20 }] }].",
      )
      .nonempty({ message: "Treemap chart data cannot be empty." }),
    height: HeightSchema,
    theme: ThemeSchema,
    title: TitleSchema,
    width: WidthSchema,
    outputType: OutputTypeSchema,
  }),

• src/utils/schema.ts:59-101 (helper)

  createHierarchicalSchema helper function used to build the recursive TreeNodeSchema for hierarchical treemap data (up to depth 5).

  /**
   * Creates a hierarchical schema with explicit nesting to avoid unresolvable $ref.
   * This helper generates nested schemas up to the specified depth to ensure compatibility
   * with strict JSON Schema clients like PydanticAI that don't support relative $ref paths.
   *
   * @param nameDesc - Description for the name field
   * @param valueDesc - Description for the value field
   * @param valueOptional - Whether the value field is optional
   * @param depth - Maximum nesting depth (default: 5)
   * @returns A Zod schema with explicit nesting
   */
  export function createHierarchicalSchema(
    nameDesc: string,
    valueDesc: string,
    valueOptional: boolean,
    depth = 5,
    // biome-ignore lint/suspicious/noExplicitAny: This helper needs to return flexible types for different use cases
  ): any {
    // Build from deepest level up
    let currentLevel = z.object({
      name: z.string().describe(nameDesc),
      value: valueOptional
        ? z.number().optional().describe(valueDesc)
        : z.number().describe(valueDesc),
    });
  
    // Build each level from depth to 1
    for (let i = depth - 1; i >= 1; i--) {
      const childLevel = currentLevel;
      currentLevel = z.object({
        name: z.string().describe(nameDesc),
        value: valueOptional
          ? z.number().optional().describe(valueDesc)
          : z.number().describe(valueDesc),
        children: z
          .array(childLevel)
          .optional()
          .describe("Child nodes for hierarchical structure."),
      }) as typeof currentLevel;
    }
  
    return currentLevel;
  }

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

  Import and registration of generateTreemapChartTool in the tools array (line 31) and re-export (line 53).

  import { generateTreemapChartTool } from "./treemap";
  
  export const tools = [
    generateEChartsTool,
    generateAreaChartTool,
    generateLineChartTool,
    generateBarChartTool,
    generatePieChartTool,
    generateRadarChartTool,
    generateScatterChartTool,
    generateSankeyChartTool,
    generateFunnelChartTool,
    generateGaugeChartTool,
    generateTreemapChartTool,
    generateSunburstChartTool,
    generateHeatmapChartTool,
    generateCandlestickChartTool,
    generateBoxplotChartTool,
    generateGraphChartTool,
    generateParallelChartTool,
    generateTreeChartTool,
  ];
  
  // Re-export individual tools for convenient use in tests and other places
  export {
    generateEChartsTool,
    generateAreaChartTool,
    generateLineChartTool,
    generateBarChartTool,
    generatePieChartTool,
    generateRadarChartTool,
    generateScatterChartTool,
    generateSankeyChartTool,
    generateFunnelChartTool,
    generateGaugeChartTool,
    generateTreemapChartTool,
    generateSunburstChartTool,
    generateHeatmapChartTool,
    generateCandlestickChartTool,
    generateBoxplotChartTool,
    generateGraphChartTool,
    generateParallelChartTool,
    generateTreeChartTool,
  };

• src/utils/imageHandler.ts:39-170 (helper)

  generateChartImage helper function that renders the ECharts option and returns the image (Base64, MinIO URL, SVG, or option JSON) based on configuration.

  export async function generateChartImage(
    echartsOption: EChartsOption,
    width = 800,
    height = 600,
    theme: "default" | "dark" = "default",
    outputType: ImageOutputFormat = "png",
    toolName = "unknown",
  ): Promise<ImageHandlerResult> {
    // Debug logging
    if (process.env.DEBUG_MCP_ECHARTS) {
      console.error(`[DEBUG] ${toolName} generating chart:`, {
        width,
        height,
        theme,
        outputType,
        optionKeys: Object.keys(echartsOption),
      });
    }
  
    try {
      // Render chart
      const result = await renderECharts(
        echartsOption,
        width,
        height,
        theme,
        outputType,
      );
  
      // Determine output type
      const isImage = outputType !== "svg" && outputType !== "option";
  
      if (!isImage) {
        // SVG or configuration options, return text directly
        const response = {
          content: [
            {
              type: "text" as const,
              text: result as string,
            },
          ],
        };
  
        if (process.env.DEBUG_MCP_ECHARTS) {
          console.error(`[DEBUG] ${toolName} chart generated successfully:`, {
            contentType: "text",
            textLength: (result as string).length,
          });
        }
  
        return response;
      }
  
      // PNG image type
      const buffer = result as Buffer;
  
      if (isMinIOConfigured()) {
        try {
          // Use MinIO storage, return URL
          const url = await storeBufferToMinIO(buffer, "png", "image/png");
  
          const response = {
            content: [
              {
                type: "text" as const,
                text: url,
              },
            ],
          };
  
          if (process.env.DEBUG_MCP_ECHARTS) {
            console.error(`[DEBUG] ${toolName} chart generated successfully:`, {
              contentType: "text",
              url: url,
            });
          }
  
          return response;
        } catch (minioError) {
          // MinIO failed, log warning and fallback to Base64
          if (process.env.DEBUG_MCP_ECHARTS) {
            console.error(
              `[DEBUG] ${toolName} MinIO storage failed, falling back to Base64:`,
              {
                error:
                  minioError instanceof Error
                    ? minioError.message
                    : String(minioError),
              },
            );
          }
          // Continue to Base64 fallback below
        }
      }
  
      // Fallback to Base64
      const base64Data = buffer.toString("base64");
  
      const response = {
        content: [
          {
            type: "image" as const,
            data: base64Data,
            mimeType: "image/png",
          },
        ],
      };
  
      if (process.env.DEBUG_MCP_ECHARTS) {
        console.error(`[DEBUG] ${toolName} chart generated successfully:`, {
          contentType: "image",
          dataLength: base64Data.length,
        });
      }
  
      return response;
    } catch (error) {
      // Error logging
      if (process.env.DEBUG_MCP_ECHARTS) {
        console.error(`[DEBUG] ${toolName} chart generation failed:`, {
          error: error instanceof Error ? error.message : String(error),
          stack: error instanceof Error ? error.stack : undefined,
        });
      }
  
      throw new Error(
        `Chart rendering failed: ${
          error instanceof Error ? error.message : String(error)
        }`,
      );
    }
  }