create_scatter_plot

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
    }
  },