create-chart-using-apexcharts

Instructions

Implementation Reference

• src/tools/apexcharts.ts:193-294 (handler)

  The main handler function that executes the core logic: validates inputs, builds ApexCharts config, fetches image from QuickChart API, generates base64 image and URL, handles file saving.

  export async function handleApexChartsTool(args: any): Promise<any> {
    const config = args.config as any;
    const action = args.action as string;
    
    validateConfig(config);
    validateAction(action);
    validateOutputPath(args.outputPath, action);
    validateDimensions(args.width, args.height);
    validateApexChartsVersion(args.apexChartsVersion);
  
    const postConfig = buildApexChartsConfig(config, {
      width: args.width as number,
      height: args.height as number,
      apexChartsVersion: args.apexChartsVersion as string,
    });
    const chartUrl = buildApexChartsUrl(config);
  
    const result: any = {
      content: [
        {
          type: "text",
          text: "Below is the chart URL:",
        },
        {
          type: "text",
          text: chartUrl,
        },
      ],
      metadata: {
        chartType: config?.chart?.type || "unknown",
        generatedAt: new Date().toISOString(),
        chartUrl: chartUrl,
      },
    };
  
    try {
      const pngData = await fetchApexChartsContent(postConfig, "png");
      const pngBase64 = Buffer.from(pngData).toString("base64");
  
      result.content.push(
        {
          type: "text",
          text: "Below is the PNG image:",
        },
        {
          type: "image",
          data: pngBase64,
          mimeType: "image/png",
        }
      );
      result.metadata.pngBase64 = pngBase64;
    } catch (error) {
      result.content.unshift({
        type: "text",
        text: "⚠️ Failed to fetch chart image",
      });
      result.content.push({
        type: "text",
        text: `Error: ${error instanceof Error ? error.message : String(error)}`,
      });
      result.metadata.error =
        error instanceof Error ? error.message : String(error);
    }
  
    if (action === "get_url") {
      return result;
    }
  
    const format = "png";
    const outputPath = getDownloadPath(
      args.outputPath as string | undefined,
      format
    );
  
    try {
      const dir = path.dirname(outputPath);
      if (!fs.existsSync(dir)) {
        fs.mkdirSync(dir, { recursive: true });
      }
  
      const data = await fetchApexChartsContent(postConfig, format);
      fs.writeFileSync(outputPath, data);
  
      result.metadata.savedPath = outputPath;
      result.content.push({
        type: "text",
        text: "Below is the saved file path:",
      });
      result.content.push({
        type: "text",
        text: outputPath,
      });
      return result;
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to save chart: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

• src/tools/apexcharts.ts:11-47 (schema)

  The Tool object definition containing the inputSchema for parameter validation, description, and name.

  export const CREATE_CHART_USING_APEXCHARTS_TOOL: Tool = {
    name: "create-chart-using-apexcharts",
    description:
      "Create charts using Apex Charts - get chart image URL or save chart image to file",
    inputSchema: {
      type: "object",
      properties: {
        action: {
          type: "string",
          enum: ["get_url", "save_file"],
          description: "Whether to get chart URL or save as file",
        },
        outputPath: {
          type: "string",
          description:
            "Path where to save the file (only used with action=save_file)",
        },
        config: {
          type: "object",
          description: "Apex Charts JSON configuration",
        },
        width: {
          type: "integer",
          description: "Image width in pixels",
        },
        height: {
          type: "integer",
          description: "Image height in pixels",
        },
        apexChartsVersion: {
          type: "string",
          description: "Apex Charts version to use",
        },
      },
      required: ["action", "config"],
    },
  };

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

  Maps the tool name to its handler function in the central TOOL_HANDLERS registry.

  "create-chart-using-apexcharts": {
    handler: handleApexChartsTool,
    toolName: ToolNames.APEXCHARTS,
  },

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

  Includes the tool in the ALL_TOOLS array for conditional enabling and export.

  { tool: CREATE_CHART_USING_APEXCHARTS_TOOL, name: ToolNames.APEXCHARTS },

• src/tools/help.ts:52-104 (helper)

  Documentation metadata including description, supported chart types, examples, and links used in the help tool.

  "create-chart-using-apexcharts": {
    name: "create-chart-using-apexcharts",
    description:
      "Create charts using ApexCharts library - get chart image URL or save chart image to file",
    documentation:
      "https://quickchart.io/documentation/apex-charts-image-rendering/",
    additionalResources: {
      apexchartsDocumentation: "https://apexcharts.com/docs/",
      apexchartsDemos: "https://apexcharts.com/javascript-chart-demos/",
      quickChartGallery: "https://quickchart.io/gallery/",
    },
    supportedChartTypes: [
      "line - Line charts for depicting trends and behaviors over time",
      "area - Area charts for showing cumulative data trends",
      "bar - Bar charts for categorical data comparison",
      "column - Column charts for vertical data comparison",
      "pie - Pie charts for proportion visualization",
      "donut - Donut charts for enhanced proportion display",
      "scatter - Scatter plots for correlation analysis",
      "bubble - Bubble charts for multi-dimensional data",
      "candlestick - Candlestick charts for financial data",
      "boxplot - Box plots for statistical data distribution",
      "heatmap - Heat maps for matrix data visualization",
      "treemap - Tree maps for hierarchical data",
      "radar - Radar charts for multi-variable comparison",
      "radialbar - Radial bar charts and circular gauges",
      "rangearea - Range area charts for data ranges",
      "rangebar - Range bar charts for time periods",
      "funnel - Funnel charts for process visualization",
    ],
    promptExamples: [
      'Financial Dashboards: "Create a candlestick chart for stock prices"',
      'Interactive Reports: "Generate a multi-series area chart with zoom functionality"',
      'Time Series Analysis: "Show real-time data with datetime axis charts"',
    ],
    usageExample: {
      action: "save_file",
      config: {
        series: [
          {
            name: "Sales",
            data: [30, 40, 45, 50, 49, 60, 70, 91],
          },
        ],
        chart: {
          type: "line",
        },
        xaxis: {
          categories: ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug"],
        },
      },
    },
  },