create-chart-using-natural-language

Instructions

Implementation Reference

• src/tools/textchart.ts:230-339 (handler)

  The primary handler function for the 'create-chart-using-natural-language' tool. Validates input parameters, constructs the chart configuration from natural language description, fetches the PNG image from QuickChart's text-to-chart API, embeds the base64 image in the response, and optionally saves the image to a file.

  export async function handleTextChartTool(args: any): Promise<any> {
    const description = args.description as string;
    const action = args.action as string;
    
    validateDescription(description);
    validateAction(action);
    validateOutputPath(args.outputPath, action);
    validateDimensions(args.width, args.height);
    validateBackgroundColor(args.backgroundColor);
    validateDataString(args.data1, "Data1");
    validateDataString(args.data2, "Data2");
    validateDataString(args.labels, "Labels");
    validateDataString(args.title, "Title");
  
    const postConfig = buildTextChartConfig(description, {
      width: args.width as number,
      height: args.height as number,
      backgroundColor: args.backgroundColor as string,
      data1: args.data1 as string,
      data2: args.data2 as string,
      labels: args.labels as string,
      title: args.title as string,
    });
    const chartUrl = buildTextChartUrl(description);
  
    const result: any = {
      content: [
        {
          type: "text",
          text: "Below is the chart URL:",
        },
        {
          type: "text",
          text: chartUrl,
        },
      ],
      metadata: {
        chartType: "natural-language",
        generatedAt: new Date().toISOString(),
        chartUrl: chartUrl,
      },
    };
  
    try {
      const pngData = await fetchTextChartContent(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 fetchTextChartContent(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/textchart.ts:11-63 (schema)

  Defines the Tool object with name, description, and detailed inputSchema for parameters including action (get_url/save_file), required description, optional dimensions, data sets, labels, title, and output path.

  export const CREATE_CHART_USING_NATURAL_LANGUAGE_TOOL: Tool = {
    name: "create-chart-using-natural-language",
    description:
      "Create charts from natural language descriptions - 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)",
        },
        description: {
          type: "string",
          description: "Natural language chart description",
        },
        width: {
          type: "integer",
          description: "Chart width in pixels",
        },
        height: {
          type: "integer",
          description: "Chart height in pixels",
        },
        backgroundColor: {
          type: "string",
          description: "Background color",
        },
        data1: {
          type: "string",
          description: "First dataset values (comma-separated)",
        },
        data2: {
          type: "string",
          description: "Second dataset values (comma-separated)",
        },
        labels: {
          type: "string",
          description: "Data labels (comma-separated)",
        },
        title: {
          type: "string",
          description: "Chart title",
        },
      },
      required: ["action", "description"],
    },
  };

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

  Imports the tool definition (schema) and handler function from the implementation file textchart.ts for registration.

    CREATE_CHART_USING_NATURAL_LANGUAGE_TOOL,
    handleTextChartTool,
  } from "./textchart.js";

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

  Registers the tool name to its handler function in the ALL_TOOL_HANDLERS record, which is filtered and used to create the TOOL_HANDLERS export.

  "create-chart-using-natural-language": {
    handler: handleTextChartTool,
    toolName: ToolNames.TEXTCHART,
  },

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

  Adds the tool to the ALL_TOOLS array, which is filtered by enabled tools to create the exported TOOLS array.

  { tool: CREATE_CHART_USING_NATURAL_LANGUAGE_TOOL, name: ToolNames.TEXTCHART },