vchart-mcp-server

Instructions

Implementation Reference

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

  Generic MCP CallTool handler that dispatches to generateChartByType based on tool name matching 'generate_scatter_chart' to chartType 'scatter'. Validates input with scatter schema and returns image/html/spec.

  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/scatter.ts:29-63 (schema)

  Zod schema defining the input parameters and validation for the generate_scatter_chart tool, including dataTable, xField, yField, etc.

  const schema = z.object({
    output: ChartOutputSchema,
    width: WidthSchema,
    height: HeightSchema,
    dataTable: z
      .array(z.any())
      .describe("Scatter chart data, e.g., [{ x: 34, y: 10, category: 'A' }].")
      .nonempty({ message: 'Scatter chart data cannot be empty.' }),
  
    xField: YFieldSchema,
    yField: YFieldSchema,
    sizeField: z.string().optional().describe('Numeric field for bubble size.'),
    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 the generate_scatter_chart tool by including it in the list of tools returned for ListToolsRequest, sourced from Charts.scatter.tool.

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

• src/charts/scatter.ts:65-75 (registration)

  Defines the tool metadata (name, description, schema) exported as scatter.tool, which is imported and listed in the MCP server.

  const tool = {
    name: 'generate_scatter_chart',
    description:
      'Generate a scatter chart to visually display the distribution, clustering trends, and correlations of data points in two-dimensional or multi-dimensional space. Suitable for analyzing relationships between variables, outlier detection, and similar scenarios.',
    inputSchema: convertZodToJsonSchema(schema),
  };
  
  export const scatter = {
    schema,
    tool,
  };

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

  Helper function that implements the chart generation logic for 'scatter' type: normalizes options, extracts fields (xField, yField, sizeField, colorField), generates VChart spec, and produces image/html/spec output.

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