generate_sankey_chart
Visualize flow relationships between nodes in complex networks to display distribution and flow paths of source and target data using Sankey diagrams.
Instructions
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.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"dataTable": "<dataTable>",
"sourceField": "<sourceField>",
"targetField": "<targetField>",
"valueField": "<valueField>"
},
"name": "generate_sankey_chart"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| output | No | Chart output type. Defaults to 'image'. | image |
| width | No | Chart width. Optional, defaults to 500. | |
| height | No | Chart height. Optional, defaults to 500. | |
| dataTable | Yes | Data for the Sankey diagram, e.g., [{ category: 'category 01', value: 10 }]. | |
| sourceField | Yes | The source field in the Sankey diagram; must exist in the data. | |
| targetField | Yes | The target field in the Sankey diagram; must exist in the data. | |
| valueField | Yes | Measure field. Must be numeric and exist in the data. | |
| chartTheme | No | Chart theme. Optional, defaults to 'light'. | |
| title | No | Chart title text. | |
| subTitle | No | Chart subtitle text. | |
| titleOrient | No | Title position in the chart. | |
| background | No | Chart background color (hex). Optional, defaults to white. | |
| colors | No | Color palette for chart elements. |
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, };