vchart-mcp-server

Instructions

Implementation Reference

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

  MCP CallToolRequest handler that resolves 'generate_heatmap_chart' to chartType 'heatmap', validates inputs using the tool's schema, invokes 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/heatmap.ts:29-65 (schema)

  Zod schema defining inputs for generate_heatmap_chart: dataTable, xField/yField/sizeField, dimensions, axes configurations, theme, title, background, and colors.

  const schema = z.object({
    output: ChartOutputSchema,
    width: WidthSchema,
    height: HeightSchema,
    dataTable: z
      .array(z.any())
      .describe(
        "Heatmap data array, e.g., [{ gender: 'male', age: '20-30', size: 30 }]."
      )
      .nonempty({ message: "Heatmap data cannot be empty." }),
    transpose: z.boolean().optional(),
  
    xField: XFieldSchema,
    yField: XFieldSchema,
    sizeField: YFieldSchema,
  
    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)

  MCP ListToolsRequest handler dynamically registers all chart tools (including generate_heatmap_chart) by exposing their tool metadata from charts exports.

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

• src/charts/heatmap.ts:67-77 (registration)

  Tool metadata object defining name 'generate_heatmap_chart', description, and inputSchema (converted from Zod), exported as part of 'heatmap' for dynamic registration.

  const tool = {
    name: "generate_heatmap_chart",
    description:
      "Generates a heatmap chart based on a Cartesian coordinate system. It is used to visualize the intensity or density of values at the intersection of two discrete variables, suitable for revealing association patterns and distribution characteristics between variables.",
    inputSchema: convertZodToJsonSchema(schema),
  };
  
  export const heatmap = {
    schema,
    tool,
  };

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

  Core helper function generateChartByType invoked for 'heatmap' chartType: constructs VChart specification from tool inputs, generates chart spec/image/HTML using @visactor/generate-vchart and remote server.

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