generate_sunburst_chart

Instructions

Implementation Reference

• src/tools/sunburst.ts:28-131 (handler)

  The main tool definition for generate_sunburst_chart, containing both the schema (inputSchema) and the handler (run function). The run function constructs the ECharts sunburst series configuration and calls generateChartImage to produce the output.

  export const generateSunburstChartTool = {
    name: "generate_sunburst_chart",
    description:
      "Generate a sunburst chart to display multi-level hierarchical data, such as, organizational structure, file system hierarchy, or category breakdown.",
    inputSchema: z.object({
      data: z
        .array(SunburstNodeSchema)
        .describe(
          "Data for sunburst chart, such as, [{ name: 'Technology', value: 100, children: [{ name: 'Frontend', value: 60, children: [{ name: 'React', value: 30 }] }] }].",
        )
        .nonempty({ message: "Sunburst chart data cannot be empty." }),
      height: HeightSchema,
      theme: ThemeSchema,
      title: TitleSchema,
      width: WidthSchema,
      outputType: OutputTypeSchema,
    }),
    run: async (params: {
      data: Array<SunburstDataType>;
      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: "sunburst",
          data: data,
          radius: [0, "90%"],
          center: ["50%", "50%"],
          sort: undefined,
          emphasis: {
            focus: "ancestor",
          },
          label: {
            show: true,
            fontSize: 12,
            color: "#000",
            minAngle: 10,
          },
          itemStyle: {
            borderRadius: 7,
            borderWidth: 2,
            borderColor: "#fff",
          },
          levels: [
            {},
            {
              r0: "15%",
              r: "35%",
              itemStyle: {
                borderWidth: 2,
              },
              label: {
                rotate: "tangential",
              },
            },
            {
              r0: "35%",
              r: "70%",
              label: {
                align: "right",
              },
            },
            {
              r0: "70%",
              r: "72%",
              label: {
                position: "outside",
                padding: 3,
                silent: false,
              },
              itemStyle: {
                borderWidth: 3,
              },
            },
          ],
        },
      ];
  
      const echartsOption: EChartsOption = {
        series,
        title: {
          left: "center",
          text: title,
        },
        tooltip: {
          trigger: "item",
        },
      };
  
      return await generateChartImage(
        echartsOption,
        width,
        height,
        theme,
        outputType,
        "generate_sunburst_chart",
      );
    },
  };

• src/tools/sunburst.ts:21-26 (schema)

  The SunburstNodeSchema is created via createHierarchicalSchema, defining the recursive structure with name, value, and optional children fields for hierarchical data.

  const SunburstNodeSchema = createHierarchicalSchema(
    "Node name, such as 'Technology'.",
    "Node value, such as 100.",
    false, // value is required for sunburst
    // biome-ignore lint/suspicious/noExplicitAny: Zod type inference requires any for recursive type compatibility
  ) satisfies z.ZodType<SunburstDataType, any, any>;

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

  The reusable createHierarchicalSchema helper function that builds nested Zod schemas up to a configurable depth (default 5) to avoid unresolvable $ref in JSON Schema.

  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:16-39 (registration)

  Import and registration of generateSunburstChartTool in the tools array, which is then iterated over in src/index.ts to register with the MCP server.

  import { generateSunburstChartTool } from "./sunburst";
  import { generateTreeChartTool } from "./tree";
  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,
  ];

• src/index.ts:22-35 (registration)

  The MCP server creation function that iterates over all tools and registers each with server.tool(name, description, inputSchema, run).

  function createEChartsServer(): McpServer {
    const server = new McpServer({
      name: "mcp-echarts",
      version: "0.1.0",
    });
  
    for (const tool of tools) {
      const { name, description, inputSchema, run } = tool;
      // biome-ignore lint/suspicious/noExplicitAny: <explanation>
      server.tool(name, description, inputSchema.shape as any, run as any);
    }
  
    return server;
  }