vchart-mcp-server

Instructions

Implementation Reference

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

  The central MCP CallToolRequestHandler that handles execution for all chart tools, including 'generate_sankey_chart'. It maps tool name to chartType ('sankey'), validates input with the specific Zod schema, calls generateChartByType('sankey', args), 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/utils/generateChart.ts:42-202 (helper)

  Core helper function generateChartByType that implements the chart generation logic for all types including Sankey. Processes input options (sourceField -> cell.source, etc.), generates VChart spec using @visactor/generate-vchart, and renders to image/HTML/spec via a 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`,
    });
  }

• src/charts/sankey.ts:16-48 (schema)

  Zod schema defining the input parameters and validation for the generate_sankey_chart tool.

  const schema = z.object({
    output: ChartOutputSchema,
    width: WidthSchema,
    height: HeightSchema,
    dataTable: z
      .array(z.any())
      .describe(
        "Data for the Sankey diagram, e.g., [{ category: 'category 01', value: 10 }]."
      )
      .nonempty({ message: "Sankey diagram data cannot be empty." }),
  
    sourceField: z
      .string()
      .nonempty({ message: "Source field cannot be empty." })
      .describe(
        "The source field in the Sankey diagram; must exist in the data."
      ),
    targetField: z
      .string()
      .nonempty({ message: "Target field cannot be empty." })
      .describe(
        "The target field in the Sankey diagram; must exist in the data."
      ),
    valueField: YFieldSchema,
  
    chartTheme: ThemeSchema,
    title: TitleTextSchema,
    subTitle: TitleSubTextSchema,
    titleOrient: TitleOrientSchema,
  
    background: BackgroundSchema,
    colors: ColorsSchema,
  });

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

  MCP ListToolsRequestHandler that registers and lists all chart tools, including generate_sankey_chart, by exporting tool metadata from Charts module.

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

• src/charts/sankey.ts:50-60 (registration)

  Tool metadata definition and export for dynamic registration in the MCP server.

  const tool = {
    name: "generate_sankey_chart",
    description:
      "Generate a Sankey diagram to visualize the flow relationships between nodes in complex networks, suitable for displaying the distribution and flow paths of source and target data.",
    inputSchema: convertZodToJsonSchema(schema),
  };
  
  export const sankey = {
    schema,
    tool,
  };