MCP Server Chart

Instructions

Implementation Reference

• src/utils/callTool.ts:44-111 (handler)

  Generic handler function for all chart generation tools, including 'generate_column_chart'. Maps the tool name to the chart type 'column' via CHART_TYPE_MAP, validates input arguments using the specific schema from Charts.column.schema, generates the chart URL by calling generateChartUrl, and returns the MCP-formatted response with the URL and spec.

  export async function callTool(tool: string, args: object = {}) {
    logger.info(`Calling tool: ${tool}`);
    const chartType = CHART_TYPE_MAP[tool as keyof typeof CHART_TYPE_MAP];
  
    if (!chartType) {
      logger.error(`Unknown tool: ${tool}`);
      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${tool}.`);
    }
  
    try {
      // Validate input using Zod before sending to API.
      // Select the appropriate schema based on the chart type.
      const schema = Charts[chartType].schema;
  
      if (schema) {
        // Use safeParse instead of parse and try-catch.
        const result = z.object(schema).safeParse(args);
        if (!result.success) {
          logger.error(`Invalid parameters: ${result.error.message}`);
          throw new McpError(
            ErrorCode.InvalidParams,
            `Invalid parameters: ${result.error.message}`,
          );
        }
      }
  
      const isMapChartTool = [
        "generate_district_map",
        "generate_path_map",
        "generate_pin_map",
      ].includes(tool);
  
      if (isMapChartTool) {
        // For map charts, we use the generateMap function, and return the mcp result.
        const { metadata, ...result } = await generateMap(tool, args);
        return result;
      }
  
      const url = await generateChartUrl(chartType, args);
      logger.info(`Generated chart URL: ${url}`);
  
      return {
        content: [
          {
            type: "text",
            text: url,
          },
        ],
        _meta: {
          description:
            "This is the chart's spec and configuration, which can be renderred to corresponding chart by AntV GPT-Vis chart components.",
          spec: { type: chartType, ...args },
        },
      };
      // biome-ignore lint/suspicious/noExplicitAny: <explanation>
    } catch (error: any) {
      logger.error(
        `Failed to generate chart: ${error.message || "Unknown error"}.`,
      );
      if (error instanceof McpError) throw error;
      if (error instanceof ValidateError)
        throw new McpError(ErrorCode.InvalidParams, error.message);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to generate chart: ${error?.message || "Unknown error."}`,
      );
    }
  }

• src/charts/column.ts:23-60 (schema)

  Zod-based input schema definition for the generate_column_chart tool, specifying data structure, grouping/stacking options, styling, theme, dimensions, and axis titles.

  const schema = {
    data: z
      .array(data)
      .describe(
        "Data for column chart, such as, [{ category: 'Category A', value: 10 }, { category: 'Category B', value: 20 }], when grouping or stacking is needed for column, the data should contain a 'group' field, such as, [{ category: 'Beijing', value: 825, group: 'Gas Car' }, { category: 'Beijing', value: 1000, group: 'Electric Car' }].",
      )
      .nonempty({ message: "Column chart data cannot be empty." }),
    group: z
      .boolean()
      .optional()
      .default(true)
      .describe(
        "Whether grouping is enabled. When enabled, column charts require a 'group' field in the data. When `group` is true, `stack` should be false.",
      ),
    stack: z
      .boolean()
      .optional()
      .default(false)
      .describe(
        "Whether stacking is enabled. When enabled, column charts require a 'group' field in the data. When `stack` is true, `group` should be false.",
      ),
    style: z
      .object({
        backgroundColor: BackgroundColorSchema,
        palette: PaletteSchema,
        texture: TextureSchema,
      })
      .optional()
      .describe(
        "Style configuration for the chart with a JSON object, optional.",
      ),
    theme: ThemeSchema,
    width: WidthSchema,
    height: HeightSchema,
    title: TitleSchema,
    axisXTitle: AxisXTitleSchema,
    axisYTitle: AxisYTitleSchema,
  };

• src/charts/column.ts:63-72 (registration)

  Tool descriptor registration for 'generate_column_chart', including name, description, input schema (JSON-converted from Zod), and annotations. Exported as part of the 'column' module for inclusion in Charts.

  const tool = {
    name: "generate_column_chart",
    description:
      "Generate a column chart, which are best for comparing categorical data, such as, when values are close, column charts are preferable because our eyes are better at judging height than other visual elements like area or angles.",
    inputSchema: zodToJsonSchema(schema),
    annotations: {
      title: "Generate Column Chart",
      readOnlyHint: true,
    },
  };

• src/server.ts:64-77 (registration)

  Registers the MCP tool handlers on the server: listTools returns all enabled chart tools (including generate_column_chart via dynamic Charts lookup), and callTool delegates execution to utils/callTool for the named tool.

  function setupToolHandlers(server: Server): void {
    logger.info("setting up tool handlers...");
    server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: getEnabledTools().map((chart) => chart.tool),
    }));
  
    // biome-ignore lint/suspicious/noExplicitAny: <explanation>
    server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
      logger.info("calling tool", request.params.name, request.params.arguments);
  
      return await callTool(request.params.name, request.params.arguments);
    });
    logger.info("tool handlers set up");
  }

• src/utils/callTool.ts:9-36 (helper)

  Mapping from tool names to internal chart types; 'generate_column_chart' maps to 'column' for schema lookup and chart generation.

  const CHART_TYPE_MAP = {
    generate_area_chart: "area",
    generate_bar_chart: "bar",
    generate_boxplot_chart: "boxplot",
    generate_column_chart: "column",
    generate_district_map: "district-map",
    generate_dual_axes_chart: "dual-axes",
    generate_fishbone_diagram: "fishbone-diagram",
    generate_flow_diagram: "flow-diagram",
    generate_funnel_chart: "funnel",
    generate_histogram_chart: "histogram",
    generate_line_chart: "line",
    generate_liquid_chart: "liquid",
    generate_mind_map: "mind-map",
    generate_network_graph: "network-graph",
    generate_organization_chart: "organization-chart",
    generate_path_map: "path-map",
    generate_pie_chart: "pie",
    generate_pin_map: "pin-map",
    generate_radar_chart: "radar",
    generate_sankey_chart: "sankey",
    generate_scatter_chart: "scatter",
    generate_treemap_chart: "treemap",
    generate_venn_chart: "venn",
    generate_violin_chart: "violin",
    generate_waterfall_chart: "waterfall",
    generate_word_cloud_chart: "word-cloud",
  } as const;