generate_funnel_chart

Instructions

Implementation Reference

• src/tools/funnel.ts:37-118 (handler)

  The `run` function that executes the funnel chart generation logic. Transforms input data into ECharts funnel series options and calls `generateChartImage` to render the chart.

    run: async (params: {
      data: Array<{ category: string; value: number }>;
      height: number;
      theme?: "default" | "dark";
      title?: string;
      width: number;
      outputType?: "png" | "svg" | "option";
    }) => {
      const { data, height, theme, title, width, outputType } = params;
  
      // Transform data for ECharts funnel chart
      const funnelData = data.map((item) => ({
        name: item.category,
        value: item.value,
      }));
  
      const series: Array<SeriesOption> = [
        {
          type: "funnel",
          data: funnelData,
          left: "10%",
          top: 60,
          width: "80%",
          height: "80%",
          min: 0,
          max: Math.max(...data.map((item) => item.value)),
          minSize: "0%",
          maxSize: "100%",
          sort: "descending",
          gap: 2,
          label: {
            show: true,
            position: "inside",
            fontSize: 12,
            color: "#fff",
          },
          labelLine: {
            length: 10,
            lineStyle: {
              width: 1,
              type: "solid",
            },
          },
          itemStyle: {
            borderColor: "#fff",
            borderWidth: 1,
          },
          emphasis: {
            label: {
              fontSize: 16,
            },
          },
        },
      ];
  
      const echartsOption: EChartsOption = {
        series,
        title: {
          left: "center",
          text: title,
        },
        tooltip: {
          trigger: "item",
        },
        legend: {
          left: "center",
          orient: "horizontal",
          bottom: 10,
          data: funnelData.map((item) => item.name),
        },
      };
  
      return await generateChartImage(
        echartsOption,
        width,
        height,
        theme,
        outputType,
        "generate_funnel_chart",
      );
    },
  };

• src/tools/funnel.ts:12-36 (schema)

  Input schema definition for the funnel chart tool. Defines the 'data' array (with category/value objects), height, theme, title, width, and outputType fields using Zod schemas.

  // Funnel chart data schema
  const data = z.object({
    category: z
      .string()
      .describe("Stage category name, such as 'Browse Website'."),
    value: z.number().describe("Value at this stage, such as 50000."),
  });
  
  export const generateFunnelChartTool = {
    name: "generate_funnel_chart",
    description:
      "Generate a funnel chart to visualize the progressive reduction of data as it passes through stages, such as, the conversion rates of users from visiting a website to completing a purchase.",
    inputSchema: z.object({
      data: z
        .array(data)
        .describe(
          "Data for funnel chart, such as, [{ category: 'Browse Website', value: 50000 }, { category: 'Add to Cart', value: 35000 }, { category: 'Generate Order', value: 25000 }].",
        )
        .nonempty({ message: "Funnel chart data cannot be empty." }),
      height: HeightSchema,
      theme: ThemeSchema,
      title: TitleSchema,
      width: WidthSchema,
      outputType: OutputTypeSchema,
    }),

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

  Registration of `generateFunnelChartTool` in the tools array at line 29, making it available to the MCP server.

  export const tools = [
    generateEChartsTool,
    generateAreaChartTool,
    generateLineChartTool,
    generateBarChartTool,
    generatePieChartTool,
    generateRadarChartTool,
    generateScatterChartTool,
    generateSankeyChartTool,
    generateFunnelChartTool,

• src/index.ts:28-31 (registration)

  The MCP server registration loop that iterates over all tools (including generate_funnel_chart) and registers them with the MCP SDK via `server.tool()`.

  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);

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

  The `generateChartImage` helper function called by the funnel chart handler. Renders the ECharts option and returns the result as Base64 image, SVG text, or MinIO URL.

  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)
        }`,
      );
    }
  }