MCP ASCII Charts

Instructions

Implementation Reference

• src/charts/histogram.ts:17-147 (handler)

  Main handler function executing the core logic for generating ASCII histogram charts from numeric data, including bin calculation, ASCII grid rendering with bars, axes, labels, and summary statistics.
  export function createHistogram(data: ChartData, options: HistogramOptions = {}): ChartResult { const { data: values, title, width = 60, height = 15, color = 'white' } = data; const { bins = 10, showFrequency = true } = options; if (values.length === 0) { throw new Error('Data array cannot be empty'); } // Calculate histogram bins const histogramBins = calculateHistogramBins(values, bins); const maxCount = Math.max(...histogramBins.map(bin => bin.count)); const chartWidth = width - 12; // Reserve space for y-axis labels const chartHeight = height - 3; // Reserve space for x-axis and title // Create the chart grid const grid = createGrid(width, height); // Draw y-axis labels (counts or frequencies) for (let y = 0; y < chartHeight; y++) { const value = maxCount - (y / (chartHeight - 1)) * maxCount; const label = showFrequency ? ((value / values.length) * 100).toFixed(1) + '%' : Math.round(value).toString(); const labelStr = padLeft(label, 10); // Place y-axis label for (let i = 0; i < Math.min(labelStr.length, 10); i++) { if (10 - i < width) { grid[y][10 - i] = labelStr[i]; } } // Draw y-axis line if (11 < width) { grid[y][11] = y === chartHeight - 1 ? ASCII_CHARS.bottomLeft : y === 0 ? ASCII_CHARS.topLeft : ASCII_CHARS.teeRight; } // Draw horizontal grid lines for (let x = 12; x < width; x++) { if (y === chartHeight - 1) { grid[y][x] = ASCII_CHARS.horizontal; } else if (y % 2 === 0) { grid[y][x] = '·'; // Light grid dots } } } // Draw histogram bars const barWidth = Math.max(1, Math.floor(chartWidth / histogramBins.length)); for (let i = 0; i < histogramBins.length; i++) { const bin = histogramBins[i]; const barStartX = 12 + Math.floor(i * chartWidth / histogramBins.length); const normalizedCount = maxCount === 0 ? 0 : normalize(bin.count, 0, maxCount); const barHeight = Math.floor(normalizedCount * chartHeight); // Draw bar from bottom up for (let y = 0; y < barHeight; y++) { const gridY = chartHeight - 1 - y; if (gridY >= 0 && gridY < chartHeight) { for (let x = 0; x < barWidth && barStartX + x < width; x++) { grid[gridY][barStartX + x] = ASCII_CHARS.fullBlock; } } } // Add count/frequency on top of bar if space allows if (barHeight < chartHeight - 1) { const valueStr = showFrequency ? ((bin.count / values.length) * 100).toFixed(0) : bin.count.toString(); const valueY = chartHeight - barHeight - 1; if (valueY >= 0 && valueY < chartHeight) { for (let j = 0; j < valueStr.length && barStartX + j < width; j++) { grid[valueY][barStartX + j] = valueStr[j]; } } } } // Draw x-axis labels (bin ranges) for (let i = 0; i < Math.min(histogramBins.length, 6); i++) { // Limit labels to avoid crowding const bin = histogramBins[i]; const barStartX = 12 + Math.floor(i * chartWidth / histogramBins.length); const labelY = height - 1; // Create range label const rangeLabel = `${bin.min.toFixed(1)}-${bin.max.toFixed(1)}`; const label = rangeLabel.substring(0, Math.min(rangeLabel.length, barWidth + 2)); if (labelY >= 0) { for (let j = 0; j < label.length && barStartX + j < width; j++) { grid[labelY][barStartX + j] = label[j]; } } } // Convert grid to string and apply coloring let chart = gridToString(grid); if (color !== 'white') { chart = colorize(chart, color); } // Add title and statistics let result = ''; if (title) { result += center(title, width) + '\n'; } result += chart; // Add summary statistics const mean = values.reduce((a, b) => a + b, 0) / values.length; const sortedValues = [...values].sort((a, b) => a - b); const median = sortedValues.length % 2 === 0 ? (sortedValues[sortedValues.length / 2 - 1] + sortedValues[sortedValues.length / 2]) / 2 : sortedValues[Math.floor(sortedValues.length / 2)]; const statsLine = `n=${values.length}, μ=${mean.toFixed(2)}, median=${median.toFixed(2)}`; result += '\n' + center(statsLine, width); return { chart: result, title, dimensions: { width, height: height + 1 } // Account for stats line }; }
• src/index.ts:195-235 (schema)

  MCP tool schema definition including input validation schema with properties for data, title, dimensions, color, and bins; registered in ListTools response.
  name: 'create_histogram', description: 'Create ASCII histograms for frequency distribution', inputSchema: { type: 'object', properties: { data: { type: 'array', items: { type: 'number' }, description: 'Array of numeric values for distribution' }, 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 }, bins: { type: 'number', description: 'Number of histogram bins (default: 10)', minimum: 3, maximum: 50, optional: true } }, required: ['data'], examples: getToolExamples('create_histogram') }
• src/index.ts:367-375 (registration)

  Tool registration in the generateChart switch statement, dispatching calls to the createHistogram handler with parsed parameters.
  case 'create_histogram': { progress.nextStep('Generating histogram'); const bins = params.bins || 10; result = await withRequestTracking( () => Promise.resolve(createHistogram(chartData, { bins })), 'create_histogram' )(); break; }
• src/charts/histogram.ts:149-187 (helper)

  Helper function to compute histogram bins from input data values, used by the main handler.
  function calculateHistogramBins(values: number[], numBins: number): HistogramBin[] { const minValue = Math.min(...values); const maxValue = Math.max(...values); const range = maxValue - minValue; const binWidth = range / numBins; const bins: HistogramBin[] = []; // Create bins for (let i = 0; i < numBins; i++) { const min = minValue + i * binWidth; const max = i === numBins - 1 ? maxValue : minValue + (i + 1) * binWidth; bins.push({ min, max, count: 0, frequency: 0 }); } // Count values in each bin for (const value of values) { for (let i = 0; i < bins.length; i++) { const bin = bins[i]; if (value >= bin.min && (value <= bin.max || (i === bins.length - 1 && value === bin.max))) { bin.count++; break; } } } // Calculate frequencies for (const bin of bins) { bin.frequency = bin.count / values.length; } return bins; }
• src/utils/examples.ts:68-87 (helper)

  Example inputs for the create_histogram tool, used in tool registration for documentation.
  create_histogram: { distribution: { data: [1, 2, 2, 3, 3, 3, 4, 4, 5, 6, 6, 7, 8, 9], title: "Value Distribution", bins: 5 }, performance: { data: [85, 87, 90, 92, 88, 91, 89, 93, 86, 94, 88, 90, 92], title: "Performance Scores", bins: 8, color: "yellow" }, large_dataset: { data: Array.from({length: 100}, () => Math.random() * 100), title: "Random Data Distribution", bins: 12, width: 70, height: 20 } },