generate_heatmap_chart
Create heatmap charts to visualize intensity patterns between two variables using Cartesian coordinates. Input data arrays to generate charts for analysis.
Instructions
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.
Input Schema
TableJSON 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 | Heatmap data array, e.g., [{ gender: 'male', age: '20-30', size: 30 }]. | |
| transpose | No | ||
| xField | Yes | Dimension field. Must exist in the data. | |
| yField | Yes | ||
| sizeField | 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. | |
| xAxisType | No | X-axis type: categorical ('band') or continuous ('linear'). | |
| xAxisOrient | No | X-axis position in the chart. | |
| xAxisTitle | No | X-axis title. | |
| xAxisHasGrid | No | Show vertical grid lines for the X-axis. | |
| xAxisHasLabel | No | Show X-axis labels. | |
| xAxisHasTick | No | Show X-axis ticks. | |
| yAxisType | No | Y-axis type: categorical ('band') or continuous ('linear'). | |
| yAxisOrient | No | Y-axis position in the chart. | |
| yAxisTitle | No | Y-axis title. | |
| yAxisHasGrid | No | Show horizontal grid lines for the Y-axis. | |
| yAxisHasLabel | No | Show Y-axis labels. | |
| yAxisHasTick | No | Show Y-axis ticks. | |
| 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)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`, }); }