vchart-mcp-server

Instructions

Implementation Reference

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

  MCP call_tool request handler that implements execution for all chart tools by mapping the tool name to the corresponding chart module ("wordcloud_venn" for generate_wordcloud_venn), validating inputs with the schema, and calling generateChartByType.

  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/wordcloud.ts:16-47 (schema)

  Zod input schema definition for the generate_wordcloud_venn tool, including parameters for data, fields, dimensions, styling, and chart type (wordcloud or venn).

  const schema = z.object({
    output: ChartOutputSchema, // Output format/schema for the chart
    width: WidthSchema, // Chart width
    height: HeightSchema, // Chart height
    chartType: z.enum(["wordcloud", "venn"]),
  
    dataTable: z
      .array(z.any())
      .describe("Data for the chart, e.g., [{ word: 'TEST', value: 10 }].")
      .nonempty({ message: "data cannot be empty." }), // Data array must not be empty
  
    colorField: z
      .string()
      .nonempty({ message: "The field for words or sets cannot be empty." })
      .describe(
        "Specifies the field in the dataset that represents each word (for word clouds) or the set (for Venn diagrams). For Venn diagrams, use a comma-separated string to describe the set. This field must exist in the dataset."
      ),
  
    valueField: z
      .string()
      .describe(
        "Specifies the field representing the metric value. Required for Venn diagrams."
      ),
  
    chartTheme: ThemeSchema, // Chart theme
    title: TitleTextSchema, // Chart title
    subTitle: TitleSubTextSchema, // Chart subtitle
    titleOrient: TitleOrientSchema, // Title orientation
  
    background: BackgroundSchema, // Chart background
    colors: ColorsSchema, // Chart colors
  });

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

  MCP list_tools request handler that registers all chart tools, including generate_wordcloud_venn, by returning their tool definitions from the Charts modules.

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

• src/charts/wordcloud.ts:49-59 (registration)

  Tool metadata definition (name, description, inputSchema) and export as wordcloud_venn module for use in Charts namespace.

  const tool = {
    name: "generate_wordcloud_venn",
    description:
      "Generate a word cloud to visualize word frequency or importance, or a Venn diagram to show relationships such as intersections and unions between sets.",
    inputSchema: convertZodToJsonSchema(schema),
  };
  
  export const wordcloud_venn = {
    schema,
    tool,
  };

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

  Core chart generation utility function called by the handler, processes input options into VChart spec using generateChart from @visactor/generate-vchart library, renders to image/html/spec based on chartType (wordcloud_venn here) and handles axis, title, data field mapping.

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