vchart-mcp-server

Instructions

Implementation Reference

• src/server.ts:43-125 (handler)

  The MCP CallToolRequest handler that executes the tool. It maps the tool name to the chart type ('range_column'), validates inputs using the tool's schema, calls generateChartByType, and returns the chart output (spec, image URL, or HTML).

  server.setRequestHandler(CallToolRequestSchema, async request => {
    const toolName = request.params.name;
    const chartType = Object.keys(Charts).find(
      key => (Charts as any)[key].tool.name === toolName
    );
  
    if (!chartType) {
      throw new McpError(
        ErrorCode.MethodNotFound,
        `Unknown tool: ${request.params.name}.`
      );
    }
  
    try {
      // Validate input using Zod before generating chart
      const args = request.params.arguments || {};
  
      // Select the appropriate schema based on the chart type
      const schema = Charts[chartType as keyof typeof Charts].schema;
  
      if (schema) {
        const result = schema.safeParse(args);
        if (!result.success) {
          throw new McpError(
            ErrorCode.InvalidParams,
            `Invalid parameters: ${result.error.message}`
          );
        }
      }
  
      const res = await generateChartByType(chartType, args);
  
      if (res && (res as any).spec) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify((res as any).spec, null, 2),
            },
          ],
        };
      }
  
      if (res && (res as any).image) {
        return {
          content: [
            {
              type: 'text',
              text: (res as any).image,
            },
          ],
        };
      }
  
      if (res && (res as any).html) {
        return {
          content: [
            {
              type: 'text',
              text: (res as any).html,
            },
          ],
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: 'Failed to generate chart',
          },
        ],
      };
    } catch (error: any) {
      if (error instanceof McpError) {
        throw error;
      }
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to generate chart: ${error?.message || 'Unknown error.'}`
      );
    }
  });

• src/charts/range_column.ts:30-66 (schema)

  Input schema (Zod) specific to range column chart, requiring dataTable and two yFields (e.g., min/max).

  const schema = z.object({
    output: ChartOutputSchema,
    width: WidthSchema,
    height: HeightSchema,
  
    dataTable: z
      .array(z.any())
      .describe(
        "Data for the range column chart, e.g., [{ category: 'Category 01', min: 10, max: 50 }]."
      )
      .nonempty({ message: "Range column chart data must not be empty." }),
  
    xField: XFieldSchema,
    yField: z.array(YFieldSchema).length(2),
    colorField: ColorFieldSchema,
  
    chartTheme: ThemeSchema,
    title: TitleTextSchema,
    subTitle: TitleSubTextSchema,
    titleOrient: TitleOrientSchema,
    xAxisType: XAxisTypeSchema,
    xAxisOrient: XAxisOrientSchema,
    xAxisTitle: XAxisTitleSchema,
    xAxisHasGrid: XAxisHasGridSchema,
    xAxisHasLabel: XAxisHasLabelSchema,
    xAxisHasTick: XAxisHasTickSchema,
  
    yAxisType: YAxisTypeSchema,
    yAxisOrient: YAxisOrientSchema,
    yAxisTitle: YAxisTitleSchema,
    yAxisHasGrid: YAxisHasGridSchema,
    yAxisHasLabel: YAxisHasLabelSchema,
    yAxisHasTick: YAxisHasTickSchema,
  
    background: BackgroundSchema,
    colors: ColorsSchema,
  });

• src/server.ts:34-38 (registration)

  Registers all chart tools (including generate_range_column_chart) for the MCP listTools request.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: Object.values(Charts).map(chart => (chart as any).tool),
    };
  });

• src/charts/range_column.ts:68-73 (registration)

  Tool metadata definition with name, description, and schema conversion for MCP registration.

  const tool = {
    name: "generate_range_column_chart",
    description:
      "Generate a range column chart to display the value range (such as minimum and maximum) for each category, suitable for comparing the range distribution across different categories.",
    inputSchema: convertZodToJsonSchema(schema),
  };

• src/utils/generateChart.ts:42-202 (helper)

  Helper function that generates the chart spec for type 'range_column' using @visactor/generate-vchart and renders the output based on 'output' field.

  export async function generateChartByType(chartType: string, options: any) {
    const {
      title,
      subTitle,
      titleOrient,
      xAxisType,
      xAxisOrient,
      xAxisTitle,
      xAxisHasGrid,
      xAxisHasLabel,
      xAxisHasTick,
  
      yAxisType,
      yAxisOrient,
      yAxisTitle,
      yAxisHasGrid,
      yAxisHasLabel,
      yAxisHasTick,
  
      leftYAxisTitle,
      leftYAxisHasGrid,
      leftYAxisHasLabel,
      leftYAxisHasTick,
  
      rightYAxisTitle,
      rightYAxisHasGrid,
      rightYAxisHasLabel,
      rightYAxisHasTick,
  
      angleAxisTitle,
      angleAxisHasGrid,
      angleAxisHasLabel,
      angleAxisHasTick,
      angleAxisType,
  
      radiusAxisHasGrid,
      radiusAxisHasLabel,
      radiusAxisHasTick,
      radiusAxisType,
      radiusAxisTitle,
  
      output,
      width,
      height,
      ...res
    } = options;
  
    const opts = { ...res };
    const titleObj = filterValidAttributes({
      text: title,
      subText: subTitle,
      orient: titleOrient,
    });
    const xAxisObj = filterValidAttributes({
      type: xAxisType,
      orient: xAxisOrient,
      title: xAxisTitle,
      hasGrid: xAxisHasGrid,
      hasLabel: xAxisHasLabel,
      hasTick: xAxisHasTick,
    });
    const yAxisObj = filterValidAttributes({
      type: yAxisType,
      orient: yAxisOrient,
      title: yAxisTitle,
      hasGrid: yAxisHasGrid,
      hasLabel: yAxisHasLabel,
      hasTick: yAxisHasTick,
    });
    const leftYAxisObj = filterValidAttributes({
      title: leftYAxisTitle,
      hasGrid: leftYAxisHasGrid,
      hasLabel: leftYAxisHasLabel,
      hasTick: leftYAxisHasTick,
    });
    const rightYAxisObj = filterValidAttributes({
      title: rightYAxisTitle,
      hasGrid: rightYAxisHasGrid,
      hasLabel: rightYAxisHasLabel,
      hasTick: rightYAxisHasTick,
    });
    const angleAxisObj = filterValidAttributes({
      title: angleAxisTitle,
      hasGrid: angleAxisHasGrid,
      hasLabel: angleAxisHasLabel,
      hasTick: angleAxisHasTick,
      type: angleAxisType,
    });
    const radiusAxisObj = filterValidAttributes({
      hasGrid: radiusAxisHasGrid,
      hasLabel: radiusAxisHasLabel,
      hasTick: radiusAxisHasTick,
      type: radiusAxisType,
      title: radiusAxisTitle,
    });
  
    const cell: Record<string, string> = {};
  
    [
      "xField",
      "yField",
      "colorField",
      "categoryField",
      "valueField",
      "wordField",
      "sizeField",
      "timeField",
      "sourceField",
      "targetField",
      "setsField",
      "radiusField",
    ].forEach((fieldName) => {
      if (isValid(options[fieldName])) {
        cell[fieldName.replace("Field", "")] = options[fieldName];
        delete opts[fieldName];
      }
    });
  
    opts.cell = cell;
  
    if (!isEmpty(titleObj)) {
      opts.title = titleObj;
    }
  
    const axes = [
      xAxisObj,
      yAxisObj,
      leftYAxisObj,
      rightYAxisObj,
      angleAxisObj,
      radiusAxisObj,
    ];
  
    if (axes.some((axis) => !isEmpty(axis))) {
      opts.axes = axes.filter((axis) => !isEmpty(axis));
    }
  
    const { spec } = generateChart(options.chartType ?? chartType, opts);
  
    if (!spec) {
      return null;
    }
  
    if (output === "spec") {
      if (isValid(width)) {
        spec.width = width;
      }
      if (isValid(height)) {
        spec.height = height;
      }
  
      return {
        spec: spec,
      };
    }
  
    return gentrateChartImageOrHtml(output, spec, {
      width: `${width ?? 500}px`,
      height: `${height ?? 500}px`,
    });
  }