MCP ASCII Charts

Instructions

Implementation Reference

• src/charts/bar-chart.ts:10-23 (handler)

  Main handler function that orchestrates bar chart creation, dispatching to horizontal or vertical renderers based on options.

  export function createBarChart(data: ChartData, options: BarChartOptions = {}): ChartResult {
    const { data: values } = data;
    const { orientation = 'horizontal', showValues = true } = options;
    
    if (values.length === 0) {
      throw new Error('Data array cannot be empty');
    }
  
    if (orientation === 'horizontal') {
      return createHorizontalBarChart(data, showValues);
    } else {
      return createVerticalBarChart(data, showValues);
    }
  }

• src/index.ts:107-149 (schema)

  JSON schema defining the input parameters and validation rules for the create_bar_chart tool.

  inputSchema: {
    type: 'object',
    properties: {
      data: {
        type: 'array',
        items: { type: 'number' },
        description: 'Array of numeric values to plot'
      },
      labels: {
        type: 'array',
        items: { type: 'string' },
        description: 'Optional labels for bars',
        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
      },
      orientation: {
        type: 'string',
        enum: ['horizontal', 'vertical'],
        description: 'Bar orientation (default: horizontal)',
        optional: true
      }
    },
    required: ['data'],
    examples: getToolExamples('create_bar_chart')

• src/index.ts:104-151 (registration)

  Registration of the create_bar_chart tool in the MCP server's tool list response.

  {
    name: 'create_bar_chart',
    description: 'Create horizontal or vertical ASCII bar charts',
    inputSchema: {
      type: 'object',
      properties: {
        data: {
          type: 'array',
          items: { type: 'number' },
          description: 'Array of numeric values to plot'
        },
        labels: {
          type: 'array',
          items: { type: 'string' },
          description: 'Optional labels for bars',
          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
        },
        orientation: {
          type: 'string',
          enum: ['horizontal', 'vertical'],
          description: 'Bar orientation (default: horizontal)',
          optional: true
        }
      },
      required: ['data'],
      examples: getToolExamples('create_bar_chart')
    }
  },

• src/charts/bar-chart.ts:25-94 (helper)

  Helper function implementing the horizontal bar chart rendering logic with labels, scaling, and ASCII art generation.

  function createHorizontalBarChart(data: ChartData, showValues: boolean): ChartResult {
    const { data: values, labels, title, width = 60, height = 15, color = 'white' } = data;
    
    const maxValue = Math.max(...values);
    const minValue = Math.min(...values, 0); // Include 0 for proper scaling
    const valueRange = maxValue - minValue;
    
    // Calculate label width
    const maxLabelLength = labels ? Math.max(...labels.map(l => l.length)) : 0;
    const labelWidth = Math.min(maxLabelLength, 15);
    
    // Calculate bar area
    const barAreaWidth = width - labelWidth - 15; // Reserve space for labels and values
    const barsHeight = Math.min(values.length, height - (title ? 1 : 0));
    
    let result = '';
    
    // Add title
    if (title) {
      result += center(title, width) + '\n';
    }
    
    // Create bars
    for (let i = 0; i < values.length && i < barsHeight; i++) {
      let line = '';
      
      // Add label
      const label = labels && labels[i] ? labels[i].substring(0, labelWidth) : `Item ${i + 1}`;
      line += padRight(label, labelWidth);
      
      // Calculate bar length
      const normalizedValue = valueRange === 0 ? 0.5 : normalize(values[i], minValue, maxValue);
      const barLength = Math.floor(normalizedValue * barAreaWidth);
      
      // Create bar
      const fullBlocks = Math.floor(barLength);
      const remainder = barLength - fullBlocks;
      
      line += ' ';
      line += ASCII_CHARS.fullBlock.repeat(fullBlocks);
      
      // Add partial block if needed
      if (remainder > 0.75) {
        line += ASCII_CHARS.darkShade;
      } else if (remainder > 0.5) {
        line += ASCII_CHARS.mediumShade;
      } else if (remainder > 0.25) {
        line += ASCII_CHARS.lightShade;
      }
      
      // Add value if requested
      if (showValues) {
        const valueStr = ` ${values[i].toFixed(1)}`;
        line += valueStr;
      }
      
      result += line + '\n';
    }
    
    // Apply coloring
    if (color !== 'white') {
      result = colorize(result, color);
    }
    
    return {
      chart: result.trimEnd(),
      title,
      dimensions: { width, height }
    };
  }

• src/utils/examples.ts:25-46 (helper)

  Example input data sets for the create_bar_chart tool, used to populate schema examples.

  create_bar_chart: {
    horizontal: {
      data: [85, 67, 54, 92],
      labels: ["Frontend", "Backend", "DevOps", "QA"],
      title: "Team Performance",
      orientation: "horizontal"
    },
    vertical: {
      data: [12, 19, 15, 25, 22, 18],
      labels: ["Jan", "Feb", "Mar", "Apr", "May", "Jun"],
      title: "Monthly Sales",
      orientation: "vertical",
      color: "cyan"
    },
    comparison: {
      data: [45, 55, 60, 40, 70],
      labels: ["Product A", "Product B", "Product C", "Product D", "Product E"],
      title: "Product Comparison",
      width: 70,
      height: 18
    }
  },