MCP ASCII Charts

Instructions

Implementation Reference

• src/charts/scatter-plot.ts:10-128 (handler)

  The core handler function that executes the logic for creating ASCII scatter plots from input data, including grid drawing, point plotting, optional trend line, and coloring.
  export function createScatterPlot(data: ChartData, options: ScatterPlotOptions = {}): ChartResult { const { data: values, title, width = 60, height = 15, color = 'white' } = data; const { pointChar = ASCII_CHARS.point, showTrendLine = false } = options; if (values.length === 0) { throw new Error('Data array cannot be empty'); } const chartWidth = width - 10; // Reserve space for y-axis labels const chartHeight = height - 3; // Reserve space for x-axis and title // Create x-values (indices) and y-values (data) const xValues = values.map((_, i) => i); const yValues = values; const minX = Math.min(...xValues); const maxX = Math.max(...xValues); const minY = Math.min(...yValues); const maxY = Math.max(...yValues); // const xRange = maxX - minX || 1; const yRange = maxY - minY || 1; // Create the chart grid const grid = createGrid(width, height); // Draw y-axis labels and grid lines for (let y = 0; y < chartHeight; y++) { const value = maxY - (y / (chartHeight - 1)) * yRange; const label = value.toFixed(1); const labelStr = padLeft(label, 8); // Place y-axis label for (let i = 0; i < Math.min(labelStr.length, 8); i++) { if (8 - i < width) { grid[y][8 - i] = labelStr[i]; } } // Draw y-axis line if (9 < width) { grid[y][9] = y === chartHeight - 1 ? ASCII_CHARS.bottomLeft : y === 0 ? ASCII_CHARS.topLeft : ASCII_CHARS.teeRight; } // Draw horizontal grid lines for (let x = 10; x < width; x++) { if (y === chartHeight - 1) { grid[y][x] = ASCII_CHARS.horizontal; } else if (y % 3 === 0) { grid[y][x] = '·'; // Light grid dots } } } // Draw x-axis labels const labelStep = Math.max(1, Math.floor(xValues.length / 8)); for (let i = 0; i < xValues.length; i += labelStep) { const x = 10 + Math.floor(normalize(xValues[i], minX, maxX) * (chartWidth - 1)); const label = xValues[i].toString(); if (x + label.length <= width && height - 1 >= 0) { for (let j = 0; j < label.length && x + j < width; j++) { grid[height - 1][x + j] = label[j]; } } } // Plot points const plotPoints: { x: number; y: number; originalX: number; originalY: number }[] = []; for (let i = 0; i < values.length; i++) { const normalizedX = normalize(xValues[i], minX, maxX); const normalizedY = normalize(yValues[i], minY, maxY); const plotX = 10 + Math.floor(normalizedX * (chartWidth - 1)); const plotY = Math.floor((1 - normalizedY) * (chartHeight - 1)); const x = clamp(plotX, 10, width - 1); const y = clamp(plotY, 0, chartHeight - 1); plotPoints.push({ x, y, originalX: xValues[i], originalY: yValues[i] }); // Draw the point if (x < width && y < chartHeight) { grid[y][x] = pointChar; } } // Draw trend line if requested if (showTrendLine && values.length > 1) { const trendLine = calculateLinearRegression(plotPoints.map(p => p.originalX), plotPoints.map(p => p.originalY)); drawTrendLine(grid, trendLine, minX, maxX, minY, maxY, chartWidth, chartHeight); } // Convert grid to string and apply coloring let chart = gridToString(grid); if (color !== 'white') { chart = colorize(chart, color); } // Add title if provided if (title) { const titleLine = center(title, width); chart = titleLine + '\n' + chart; } return { chart, title, dimensions: { width, height } }; }
• src/index.ts:152-193 (registration)

  Tool registration in the MCP server's listTools handler, defining name, description, and input schema for create_scatter_plot.
  { name: 'create_scatter_plot', description: 'Generate ASCII scatter plots for correlation analysis', inputSchema: { type: 'object', properties: { data: { type: 'array', items: { type: 'number' }, description: 'Array of y-values (x-values will be indices)' }, labels: { type: 'array', items: { type: 'string' }, description: 'Optional point labels', optional: true }, title: { type: 'string', description: 'Optional chart title', optional: true }, width: { type: 'number', description: 'Chart width (10-200, default: 60)', optional: true }, height: { type: 'number', description: 'Chart height (5-50, default: 15)', optional: true }, color: { type: 'string', description: 'ANSI color name', optional: true } }, required: ['data'], examples: getToolExamples('create_scatter_plot') } },
• src/index.ts:155-191 (schema)

  Input schema definition for the create_scatter_plot tool, outlining required data array and optional parameters like title, dimensions, and color.
  inputSchema: { type: 'object', properties: { data: { type: 'array', items: { type: 'number' }, description: 'Array of y-values (x-values will be indices)' }, labels: { type: 'array', items: { type: 'string' }, description: 'Optional point labels', optional: true }, title: { type: 'string', description: 'Optional chart title', optional: true }, width: { type: 'number', description: 'Chart width (10-200, default: 60)', optional: true }, height: { type: 'number', description: 'Chart height (5-50, default: 15)', optional: true }, color: { type: 'string', description: 'ANSI color name', optional: true } }, required: ['data'], examples: getToolExamples('create_scatter_plot')
• src/index.ts:358-364 (registration)

  Dispatch logic in the generateChart function that routes calls to the createScatterPlot handler.
  case 'create_scatter_plot': { progress.nextStep('Generating scatter plot'); result = await withRequestTracking( () => Promise.resolve(createScatterPlot(chartData)), 'create_scatter_plot' )(); break;
• src/utils/examples.ts:48-66 (helper)

  Example data sets and parameters for testing the create_scatter_plot tool.
  create_scatter_plot: { correlation: { data: [1, 2, 3, 5, 8, 13, 21, 34], title: "Growth Pattern Analysis", width: 50, height: 12 }, distribution: { data: [12, 15, 18, 22, 19, 25, 30, 28, 35, 40], title: "Data Distribution", color: "magenta" }, trend: { data: [100, 110, 105, 115, 120, 125, 130, 128, 135], title: "Trend Analysis", width: 60, height: 15 } },