Skip to main content
Glama
ishayoyo

Excel MCP Server

by ishayoyo

get_headers

Extract column headers from Excel or CSV files to understand data structure and prepare for analysis.

Instructions

Get the column headers (first row) of a file

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
filePathYesPath to the CSV or Excel file
sheetNoSheet name for Excel files (optional)

Implementation Reference

  • Implementation of the getHeaders handler function that reads the first row (headers) from a CSV/Excel file and returns it as JSON.
    async getHeaders(args: ToolArgs): Promise<ToolResponse> {
      try {
        const { filePath, sheet } = args;
        const data = await readFileContent(filePath, sheet);
    
        if (data.length === 0) {
          return {
            content: [
              {
                type: 'text',
                text: JSON.stringify({
                  success: false,
                  error: 'File is empty',
                }, null, 2),
              },
            ],
          };
        }
    
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: true,
                headers: data[0],
              }, null, 2),
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                error: error instanceof Error ? error.message : 'Unknown error occurred',
              }, null, 2),
            },
          ],
        };
      }
    }
  • JSON schema definition for the 'get_headers' tool, including input parameters filePath (required) and sheet (optional).
      name: 'get_headers',
      description: 'Get the column headers (first row) of a file',
      inputSchema: {
        type: 'object',
        properties: {
          filePath: {
            type: 'string',
            description: 'Path to the CSV or Excel file',
          },
          sheet: {
            type: 'string',
            description: 'Sheet name for Excel files (optional)',
          },
        },
        required: ['filePath'],
      },
    },
  • src/index.ts:1205-1206 (registration)
    Dispatch registration in the CallToolRequestSchema handler that maps the 'get_headers' tool name to the dataOpsHandler.getHeaders method.
    case 'get_headers':
      return await this.dataOpsHandler.getHeaders(toolArgs);
  • src/index.ts:68-1190 (registration)
    Overall tool list registration via setRequestHandler(ListToolsRequestSchema) that includes the get_headers tool schema.
    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools: [
        // Basic Data Tools
        {
          name: 'read_file',
          description: 'Read an entire CSV or Excel file with optional chunking for large files',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional, defaults to first sheet)',
              },
              offset: {
                type: 'number',
                description: 'Starting row index for chunked reading (0-based, optional)',
              },
              limit: {
                type: 'number',
                description: 'Maximum number of rows to return (optional, enables chunking)',
              },
            },
            required: ['filePath'],
          },
        },
        {
          name: 'get_cell',
          description: 'Get the value of a specific cell using A1 notation',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              cell: {
                type: 'string',
                description: 'Cell address in A1 notation (e.g., "A1", "B5")',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'cell'],
          },
        },
        {
          name: 'get_range',
          description: 'Get values from a range of cells',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              startCell: {
                type: 'string',
                description: 'Start cell in A1 notation (e.g., "A1")',
              },
              endCell: {
                type: 'string',
                description: 'End cell in A1 notation (e.g., "D10")',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'startCell', 'endCell'],
          },
        },
        {
          name: 'get_headers',
          description: 'Get the column headers (first row) of a file',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath'],
          },
        },
        {
          name: 'search',
          description: 'Search for cells containing a specific value',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              searchValue: {
                type: 'string',
                description: 'Value to search for',
              },
              exact: {
                type: 'boolean',
                description: 'Whether to match exactly or contains (default: false)',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'searchValue'],
          },
        },
        {
          name: 'filter_rows',
          description: 'Filter rows based on column values',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              column: {
                type: 'string',
                description: 'Column name or index (0-based)',
              },
              condition: {
                type: 'string',
                description: 'Condition: equals, contains, greater_than, less_than',
                enum: ['equals', 'contains', 'greater_than', 'less_than'],
              },
              value: {
                type: 'string',
                description: 'Value to compare against',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'column', 'condition', 'value'],
          },
        },
        {
          name: 'aggregate',
          description: 'Perform aggregation operations on a column',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              column: {
                type: 'string',
                description: 'Column name or index (0-based)',
              },
              operation: {
                type: 'string',
                description: 'Aggregation operation',
                enum: ['sum', 'average', 'count', 'min', 'max'],
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'column', 'operation'],
          },
        },
    
        // Chunked Reading Tools
        {
          name: 'read_file_chunked',
          description: 'Read large files in manageable chunks to avoid token limits',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
              chunkIndex: {
                type: 'number',
                description: 'Chunk index to read (0-based, defaults to 0)',
                default: 0,
              },
              chunkSize: {
                type: 'number',
                description: 'Number of rows per chunk (optional, auto-calculated if not provided)',
              },
            },
            required: ['filePath'],
          },
        },
        {
          name: 'get_file_info',
          description: 'Analyze file size and get chunking recommendations',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath'],
          },
        },
    
        // Analytics Tools
        {
          name: 'statistical_analysis',
          description: 'Perform comprehensive statistical analysis on a column',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              column: {
                type: 'string',
                description: 'Column name or index (0-based)',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'column'],
          },
        },
        {
          name: 'correlation_analysis',
          description: 'Calculate correlation between two numeric columns',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              column1: {
                type: 'string',
                description: 'First column name or index (0-based)',
              },
              column2: {
                type: 'string',
                description: 'Second column name or index (0-based)',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'column1', 'column2'],
          },
        },
        {
          name: 'data_profile',
          description: 'Generate comprehensive data profiling report for all columns',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath'],
          },
        },
        {
          name: 'pivot_table',
          description: 'Create pivot table with grouping and aggregation',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file',
              },
              groupBy: {
                type: 'string',
                description: 'Column to group by',
              },
              aggregateColumn: {
                type: 'string',
                description: 'Column to aggregate',
              },
              operation: {
                type: 'string',
                description: 'Aggregation operation',
                enum: ['sum', 'average', 'count', 'min', 'max'],
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
            },
            required: ['filePath', 'groupBy', 'aggregateColumn', 'operation'],
          },
        },
    
        // Financial Analysis Tools (CFO-Level)
        {
          name: 'dcf_analysis',
          description: 'Perform Discounted Cash Flow (DCF) valuation analysis for investment evaluation',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file with cash flow data'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              },
              assumptions: {
                type: 'object',
                description: 'DCF assumptions (optional)',
                properties: {
                  initialInvestment: { type: 'number', description: 'Initial investment amount (negative)' },
                  growthRate: { type: 'number', description: 'Annual growth rate (0.15 = 15%)' },
                  discountRate: { type: 'number', description: 'Discount rate/WACC (0.12 = 12%)' },
                  terminalMultiple: { type: 'number', description: 'Terminal value multiple (8x)' },
                  projectionYears: { type: 'number', description: 'Number of projection years' }
                }
              }
            },
            required: ['filePath']
          }
        },
        {
          name: 'budget_variance_analysis',
          description: 'Analyze budget vs actual performance with variance calculations',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file with budget and actual data'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              },
              actualColumn: {
                type: 'string',
                description: 'Column name or index containing actual values'
              },
              budgetColumn: {
                type: 'string',
                description: 'Column name or index containing budget values'
              }
            },
            required: ['filePath', 'actualColumn', 'budgetColumn']
          }
        },
        {
          name: 'ratio_analysis',
          description: 'Perform comprehensive financial ratio analysis with industry benchmarks',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file with financial statement data'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              }
            },
            required: ['filePath']
          }
        },
        {
          name: 'scenario_modeling',
          description: 'Perform what-if scenario analysis with multiple assumptions',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file with base data'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              },
              scenarios: {
                type: 'array',
                description: 'Array of scenario definitions',
                items: {
                  type: 'object',
                  properties: {
                    name: { type: 'string', description: 'Scenario name' },
                    assumptions: {
                      type: 'object',
                      description: 'Key-value pairs of assumption changes',
                      additionalProperties: { type: 'number' }
                    }
                  },
                  required: ['name', 'assumptions']
                }
              }
            },
            required: ['filePath', 'scenarios']
          }
        },
        {
          name: 'trend_analysis',
          description: 'Analyze time series trends, growth rates, seasonality, and forecasting for sales and performance data',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file with time series data'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              },
              dateColumn: {
                type: 'string',
                description: 'Column name or index containing date/time values'
              },
              valueColumn: {
                type: 'string',
                description: 'Column name or index containing numeric values to analyze'
              },
              periods: {
                type: 'number',
                description: 'Number of future periods to forecast (default: 12)',
                default: 12
              }
            },
            required: ['filePath', 'dateColumn', 'valueColumn']
          }
        },
    
        // File Operations Tools
        {
          name: 'write_file',
          description: 'Write data to a new CSV or Excel file (supports multiple sheets for Excel)',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path for the new file (must end with .csv, .xlsx, or .xls)',
              },
              data: {
                type: 'array',
                description: 'Array of arrays representing rows of data (single sheet mode)',
                items: {
                  type: 'array',
                },
              },
              headers: {
                type: 'array',
                description: 'Optional headers for the first row (single sheet mode)',
                items: {
                  type: 'string',
                },
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (single sheet mode, defaults to "Sheet1")',
              },
              sheets: {
                type: 'array',
                description: 'Array of sheet objects for multi-sheet Excel files',
                items: {
                  type: 'object',
                  properties: {
                    name: {
                      type: 'string',
                      description: 'Sheet name',
                    },
                    data: {
                      type: 'array',
                      description: 'Array of arrays representing rows of data',
                      items: {
                        type: 'array',
                      },
                    },
                    headers: {
                      type: 'array',
                      description: 'Optional headers for the first row',
                      items: {
                        type: 'string',
                      },
                    },
                  },
                  required: ['name', 'data'],
                },
              },
            },
            required: ['filePath'],
          },
        },
        {
          name: 'add_sheet',
          description: 'Add a new sheet to an existing Excel file',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the existing Excel file (.xlsx or .xls)',
              },
              sheetName: {
                type: 'string',
                description: 'Name for the new sheet',
              },
              data: {
                type: 'array',
                description: 'Array of arrays representing rows of data',
                items: {
                  type: 'array',
                },
              },
              headers: {
                type: 'array',
                description: 'Optional headers for the first row',
                items: {
                  type: 'string',
                },
              },
              position: {
                type: 'number',
                description: 'Position to insert the sheet (0-based index, optional)',
              },
            },
            required: ['filePath', 'sheetName', 'data'],
          },
        },
        {
          name: 'write_multi_sheet',
          description: 'Create a complex Excel file with multiple sheets, formulas, and inter-sheet references',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path for the new Excel file (must end with .xlsx or .xls)',
              },
              sheets: {
                type: 'array',
                description: 'Array of sheet definitions',
                items: {
                  type: 'object',
                  properties: {
                    name: {
                      type: 'string',
                      description: 'Sheet name',
                    },
                    data: {
                      type: 'array',
                      description: 'Array of arrays representing rows of data',
                      items: {
                        type: 'array',
                      },
                    },
                    headers: {
                      type: 'array',
                      description: 'Optional headers for the first row',
                      items: {
                        type: 'string',
                      },
                    },
                    formulas: {
                      type: 'array',
                      description: 'Array of formula definitions',
                      items: {
                        type: 'object',
                        properties: {
                          cell: {
                            type: 'string',
                            description: 'Cell address in A1 notation (e.g., "A1", "B5")',
                          },
                          formula: {
                            type: 'string',
                            description: 'Excel formula (e.g., "=SUM(A1:A10)", "=Sheet1!A1+Sheet2!B2")',
                          },
                        },
                        required: ['cell', 'formula'],
                      },
                    },
                  },
                  required: ['name', 'data'],
                },
              },
              sheetReferences: {
                type: 'boolean',
                description: 'Enable inter-sheet formula references (default: true)',
              },
            },
            required: ['filePath', 'sheets'],
          },
        },
        {
          name: 'export_analysis',
          description: 'Export analysis results (pivot tables, statistics, etc.) to a new file',
          inputSchema: {
            type: 'object',
            properties: {
              analysisType: {
                type: 'string',
                description: 'Type of analysis to export',
                enum: ['pivot_table', 'statistical_analysis', 'correlation', 'data_profile'],
              },
              sourceFile: {
                type: 'string',
                description: 'Path to the source data file',
              },
              outputFile: {
                type: 'string',
                description: 'Path for the output file',
              },
              analysisParams: {
                type: 'object',
                description: 'Parameters for the analysis (depends on analysisType)',
              },
            },
            required: ['analysisType', 'sourceFile', 'outputFile', 'analysisParams'],
          },
        },
        {
          name: 'format_cells',
          description: 'Apply formatting to Excel cells (fonts, colors, borders, alignment)',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the Excel file (.xlsx or .xls)',
              },
              range: {
                type: 'string',
                description: 'Cell range in A1 notation (e.g., "A1", "A1:C5", "B2:D10")',
              },
              styling: {
                type: 'object',
                description: 'Formatting options to apply',
                properties: {
                  font: {
                    type: 'object',
                    description: 'Font styling options',
                    properties: {
                      bold: { type: 'boolean', description: 'Make text bold' },
                      italic: { type: 'boolean', description: 'Make text italic' },
                      underline: { type: 'boolean', description: 'Underline text' },
                      size: { type: 'number', description: 'Font size (e.g., 12, 14, 16)' },
                      color: { type: 'string', description: 'Font color in ARGB format (e.g., "FFFF0000" for red)' },
                      name: { type: 'string', description: 'Font name (e.g., "Arial", "Times New Roman")' }
                    }
                  },
                  fill: {
                    type: 'object',
                    description: 'Background fill options',
                    properties: {
                      color: { type: 'string', description: 'Background color in ARGB format (e.g., "FFFFFF00" for yellow)' },
                      pattern: { type: 'string', description: 'Fill pattern (default: "solid")' }
                    }
                  },
                  border: {
                    type: 'object',
                    description: 'Border styling options',
                    properties: {
                      style: { type: 'string', description: 'Border style: thin, medium, thick, dotted, dashed' },
                      color: { type: 'string', description: 'Border color in ARGB format (e.g., "FF000000" for black)' },
                      top: { type: 'boolean', description: 'Apply border to top (default: true)' },
                      bottom: { type: 'boolean', description: 'Apply border to bottom (default: true)' },
                      left: { type: 'boolean', description: 'Apply border to left (default: true)' },
                      right: { type: 'boolean', description: 'Apply border to right (default: true)' }
                    }
                  },
                  alignment: {
                    type: 'object',
                    description: 'Text alignment options',
                    properties: {
                      horizontal: { type: 'string', description: 'Horizontal alignment: left, center, right, justify' },
                      vertical: { type: 'string', description: 'Vertical alignment: top, middle, bottom' },
                      wrapText: { type: 'boolean', description: 'Wrap text within cell' },
                      textRotation: { type: 'number', description: 'Text rotation angle in degrees' }
                    }
                  },
                  numberFormat: {
                    type: 'string',
                    description: 'Number format (e.g., "$#,##0.00", "0.00%", "mm/dd/yyyy")'
                  }
                }
              },
              sheet: {
                type: 'string',
                description: 'Sheet name (optional, defaults to first sheet)',
              },
            },
            required: ['filePath', 'range', 'styling'],
          },
        },
        {
          name: 'auto_fit_columns',
          description: 'Automatically adjust column widths to fit content in Excel files',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the Excel file (.xlsx or .xls)',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name (optional, defaults to all sheets)',
              },
              columns: {
                type: 'array',
                description: 'Specific columns to auto-fit (optional, defaults to all columns). Can be column letters (e.g., ["A", "B"]) or numbers (e.g., [1, 2])',
                items: {
                  oneOf: [
                    { type: 'string', description: 'Column letter (e.g., "A", "B", "C")' },
                    { type: 'number', description: 'Column number (1-based, e.g., 1, 2, 3)' }
                  ]
                }
              },
              minWidth: {
                type: 'number',
                description: 'Minimum column width (default: 10)',
                default: 10
              },
              maxWidth: {
                type: 'number',
                description: 'Maximum column width (default: 60)',
                default: 60
              },
              padding: {
                type: 'number',
                description: 'Extra padding to add to calculated width (default: 2)',
                default: 2
              }
            },
            required: ['filePath'],
          },
        },
    
        // AI-Powered Tools
        {
          name: 'evaluate_formula',
          description: 'Evaluate an Excel formula with given context',
          inputSchema: {
            type: 'object',
            properties: {
              formula: {
                type: 'string',
                description: 'Excel formula to evaluate (e.g., "=SUM(A1:A10)", "=VLOOKUP(B2,C:D,2,FALSE)")',
              },
              context: {
                type: 'object',
                description: 'Cell values and ranges for formula evaluation (optional)',
                additionalProperties: true,
              },
            },
            required: ['formula'],
          },
        },
        {
          name: 'parse_natural_language',
          description: 'Convert natural language to Excel formula or command',
          inputSchema: {
            type: 'object',
            properties: {
              query: {
                type: 'string',
                description: 'Natural language query (e.g., "sum all sales", "find duplicates", "average by category")',
              },
              filePath: {
                type: 'string',
                description: 'Path to file for context (optional)',
              },
              provider: {
                type: 'string',
                description: 'Preferred AI provider: anthropic, openai, deepseek, gemini, or local (optional)',
                enum: ['anthropic', 'openai', 'deepseek', 'gemini', 'local'],
              },
            },
            required: ['query'],
          },
        },
        {
          name: 'explain_formula',
          description: 'Explain what an Excel formula does in plain English',
          inputSchema: {
            type: 'object',
            properties: {
              formula: {
                type: 'string',
                description: 'Excel formula to explain (e.g., "=VLOOKUP(A2,B:C,2,FALSE)")',
              },
              provider: {
                type: 'string',
                description: 'Preferred AI provider: anthropic, openai, deepseek, gemini, or local (optional)',
                enum: ['anthropic', 'openai', 'deepseek', 'gemini', 'local'],
              },
            },
            required: ['formula'],
          },
        },
        {
          name: 'ai_provider_status',
          description: 'Check status of available AI providers',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
        {
          name: 'smart_data_analysis',
          description: 'AI-powered analysis suggestions for your data',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file to analyze',
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)',
              },
              provider: {
                type: 'string',
                description: 'Preferred AI provider: anthropic, openai, deepseek, gemini, or local (optional)',
                enum: ['anthropic', 'openai', 'deepseek', 'gemini', 'local'],
              },
            },
            required: ['filePath'],
          },
        },
    
        // Validation Tools (legacy - to be refactored)
        {
          name: 'validate_data_consistency',
          description: 'Cross-validate data integrity across related files',
          inputSchema: {
            type: 'object',
            properties: {
              primaryFile: {
                type: 'string',
                description: 'Path to the primary data file to validate'
              },
              referenceFiles: {
                type: 'array',
                items: { type: 'string' },
                description: 'Array of reference file paths for validation'
              },
              validationRules: {
                type: 'array',
                items: {
                  type: 'string',
                  enum: ['referential_integrity', 'data_completeness', 'value_ranges']
                },
                description: 'Specific validation rules to apply (optional, defaults to all)'
              },
              keyColumns: {
                type: 'array',
                items: { type: 'string' },
                description: 'Specific columns to validate for referential integrity (optional)'
              },
              autoDetectRelationships: {
                type: 'boolean',
                description: 'Automatically detect column relationships (default: true)'
              },
              tolerance: {
                type: 'number',
                description: 'Tolerance for numeric validations (default: 0.01)'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              },
              reportFormat: {
                type: 'string',
                enum: ['summary', 'detailed'],
                description: 'Format of validation report (default: detailed)'
              }
            },
            required: ['primaryFile', 'referenceFiles']
          }
        },
    
        // Bulk Operations Tools (legacy - to be refactored)
        {
          name: 'bulk_aggregate_multi_files',
          description: 'Aggregate same column across multiple files in parallel',
          inputSchema: {
            type: 'object',
            properties: {
              filePaths: {
                type: 'array',
                items: { type: 'string' },
                description: 'Array of file paths to process'
              },
              column: {
                type: 'string',
                description: 'Column name or index (0-based) to aggregate'
              },
              operation: {
                type: 'string',
                enum: ['sum', 'average', 'count', 'min', 'max'],
                description: 'Aggregation operation'
              },
              consolidate: {
                type: 'boolean',
                description: 'Whether to return consolidated result or per-file breakdown (default: true)'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              },
              filters: {
                type: 'array',
                description: 'Optional filters to apply before aggregation',
                items: {
                  type: 'object',
                  properties: {
                    column: { type: 'string' },
                    condition: {
                      type: 'string',
                      enum: ['equals', 'contains', 'greater_than', 'less_than', 'not_equals']
                    },
                    value: { type: ['string', 'number'] }
                  },
                  required: ['column', 'condition', 'value']
                }
              }
            },
            required: ['filePaths', 'column', 'operation']
          }
        },
        {
          name: 'bulk_filter_multi_files',
          description: 'Filter data across multiple files with optional export',
          inputSchema: {
            type: 'object',
            properties: {
              filePaths: {
                type: 'array',
                items: { type: 'string' },
                description: 'Array of file paths to process'
              },
              filters: {
                type: 'array',
                description: 'Filters to apply to the data',
                items: {
                  type: 'object',
                  properties: {
                    column: { type: 'string' },
                    condition: {
                      type: 'string',
                      enum: ['equals', 'contains', 'greater_than', 'less_than', 'not_equals']
                    },
                    value: { type: ['string', 'number'] }
                  },
                  required: ['column', 'condition', 'value']
                }
              },
              outputMode: {
                type: 'string',
                enum: ['count', 'export', 'summary'],
                description: 'How to return results: count only, export to file, or summary with counts'
              },
              outputPath: {
                type: 'string',
                description: 'Output file path (required when outputMode is "export")'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              }
            },
            required: ['filePaths', 'filters', 'outputMode']
          }
        },
    
        // Excel Workflow Tools
        {
          name: 'find_duplicates',
          description: 'Find and manage duplicate rows in Excel/CSV files with multiple strategies',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file'
              },
              columns: {
                type: 'array',
                items: { type: 'string' },
                description: 'Columns to check for duplicates (empty = all columns)'
              },
              action: {
                type: 'string',
                enum: ['highlight', 'remove', 'export_duplicates', 'report_only'],
                description: 'What to do with duplicates (default: report_only)'
              },
              keepFirst: {
                type: 'boolean',
                description: 'Keep first occurrence when removing (default: true)'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              }
            },
            required: ['filePath']
          }
        },
        {
          name: 'data_cleaner',
          description: 'Batch data cleaning operations with intelligent detection of common data quality issues',
          inputSchema: {
            type: 'object',
            properties: {
              filePath: {
                type: 'string',
                description: 'Path to the CSV or Excel file'
              },
              operations: {
                type: 'array',
                items: {
                  type: 'string',
                  enum: [
                    'trim_whitespace', 'fix_dates', 'standardize_numbers',
                    'remove_empty_rows', 'standardize_phone_formats', 'standardize_names',
                    'remove_special_chars', 'fix_currency'
                  ]
                },
                description: 'Array of cleaning operations to apply'
              },
              preview: {
                type: 'boolean',
                description: 'Show preview before applying changes (default: false)'
              },
              sheet: {
                type: 'string',
                description: 'Sheet name for Excel files (optional)'
              }
            },
            required: ['filePath']
          }
        },
        {
          name: 'vlookup_helper',
          description: 'Intelligent VLOOKUP setup and execution with error handling and fuzzy matching',
          inputSchema: {
            type: 'object',
            properties: {
              sourceFile: {
                type: 'string',
                description: 'File with data that needs lookup values'
              },
              lookupFile: {
                type: 'string',
                description: 'File to lookup values from'
              },
              lookupColumn: {
                type: 'string',
                description: 'Column name or index to match on'
              },
              returnColumns: {
                type: 'array',
                items: { type: 'string' },
                description: 'Columns to return from lookup table (empty = all except lookup column)'
              },
              fuzzyMatch: {
                type: 'boolean',
                description: 'Enable fuzzy string matching for lookups (default: false)'
              },
              handleErrors: {
                type: 'boolean',
                description: 'Auto-handle #N/A errors with fallbacks (default: true)'
              },
              sourceSheet: {
                type: 'string',
                description: 'Sheet name for source Excel file (optional)'
              },
              lookupSheet: {
                type: 'string',
                description: 'Sheet name for lookup Excel file (optional)'
              }
            },
            required: ['sourceFile', 'lookupFile', 'lookupColumn']
          }
        },
      ],
    }));
  • src/index.ts:13-13 (registration)
    Import of DataOperationsHandler class used for get_headers handler.
    import { DataOperationsHandler } from './handlers/data-operations';
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but omits critical details such as error handling (e.g., for invalid file paths or unsupported formats), performance considerations (e.g., for large files), or output format. This is a significant gap for a tool with potential file I/O operations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It avoids redundancy and wastes no space, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (file I/O with potential format variations) and lack of annotations or output schema, the description is incomplete. It fails to address behavioral aspects like error cases, output structure, or limitations, leaving gaps that could hinder effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with clear parameter documentation in the input schema. The description adds no additional meaning beyond implying the tool works with CSV or Excel files (hinted by 'sheet' parameter), but this is already covered in the schema. Baseline 3 is appropriate as the schema adequately defines parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Get') and resource ('column headers (first row) of a file'), distinguishing it from siblings like 'get_cell' or 'get_range' by focusing on header extraction rather than cell values or data ranges. It precisely defines the tool's function without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'read_file' or 'get_file_info', which might also provide header information. It lacks context on prerequisites (e.g., file format compatibility) or exclusions, leaving usage decisions to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ishayoyo/excel-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server