Excel MCP Server

Instructions

Implementation Reference

• src/handlers/data-operations.ts:5-98 (handler)

  The primary handler implementation for the 'read_file' MCP tool. Handles file reading, chunking with offset/limit, metadata generation, warnings, and large file suggestions.

  async readFile(args: ToolArgs): Promise<ToolResponse> {
    try {
      if (!args.filePath) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                success: false,
                error: 'Missing required parameter: filePath',
              }, null, 2),
            },
          ],
        };
      }
  
      const { filePath, sheet, offset, limit } = args;
      const result = await readFileContentWithWarnings(filePath, sheet);
  
      // Store original data info for metadata
      const totalRows = result.data.length;
      const totalColumns = result.data[0]?.length || 0;
      const headers = totalRows > 0 ? result.data[0] : [];
  
      // Apply chunking if offset or limit are specified
      let chunkedData = result.data;
      let chunkMetadata = null;
  
      if (offset !== undefined || limit !== undefined) {
        const requestedOffset = offset || 0;
        const requestedLimit = limit || (totalRows - requestedOffset);
  
        // Validate chunk boundaries
        const { validOffset, validLimit } = validateChunkBoundaries(result.data, requestedOffset, requestedLimit);
  
        const endRow = validOffset + validLimit;
        chunkedData = result.data.slice(validOffset, endRow);
  
        chunkMetadata = {
          offset: validOffset,
          limit: validLimit,
          totalRows,
          returnedRows: chunkedData.length,
          hasMore: endRow < totalRows,
          nextOffset: endRow < totalRows ? endRow : null,
          note: validOffset > 0 && totalRows > 0 ? "This chunk doesn't include headers. Consider including row 0 for headers." : undefined,
        };
      }
  
      const response: any = {
        success: true,
        data: chunkedData,
        rowCount: chunkedData.length,
        columnCount: totalColumns,
        headers: headers,
      };
  
      // Add chunk metadata if chunking was used
      if (chunkMetadata) {
        response.chunkInfo = chunkMetadata;
      }
  
      // Include warnings if they exist
      if (result.warnings) {
        response.warnings = result.warnings;
      }
  
      // Add suggestion for large files
      if (!chunkMetadata && totalRows > 10000) {
        response.suggestion = `Large file detected (${totalRows} rows). Consider using offset/limit parameters for chunked reading to avoid token limits.`;
      }
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(response, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: false,
              error: error instanceof Error ? error.message : 'Unknown error occurred',
            }, null, 2),
          },
        ],
      };
    }
  }

• src/index.ts:1199-1200 (registration)

  MCP server registration mapping the tool name 'read_file' to the DataOperationsHandler.readFile method in the CallToolRequestSchema handler.

  case 'read_file':
    return await this.dataOpsHandler.readFile(toolArgs);

• src/index.ts:72-96 (schema)

  Tool schema definition including name, description, and input schema validation for the 'read_file' tool, provided in ListToolsRequestSchema response.

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

• src/utils/file-utils.ts:32-112 (helper)

  Core helper function that performs the actual file reading for CSV and Excel files, generates warnings for data quality issues, and returns parsed data. Called by the read_file handler.

  export async function readFileContentWithWarnings(filePath: string, sheet?: string): Promise<FileReadResult> {
    const ext = path.extname(filePath).toLowerCase();
    const absolutePath = path.resolve(filePath);
    const warnings: string[] = [];
  
    try {
      await fs.access(absolutePath);
    } catch {
      throw new Error(`File not found: ${filePath}`);
    }
  
    if (ext === '.csv') {
      const content = await fs.readFile(absolutePath, 'utf-8');
  
      // Check for binary content that might cause issues
      if (content.includes('\u0000') || content.includes('\uFFFD')) {
        throw new Error('File appears to contain binary data and cannot be read as CSV');
      }
  
      try {
        const parsed = csv.parse(content, {
          skip_empty_lines: true,
          relax_quotes: true,
          relax_column_count: true,
        });
  
        // Additional validation - ensure we have some valid data
        if (parsed.length === 0) {
          throw new Error('empty file: No valid CSV data found in file');
        }
  
        // Check for malformed CSV issues and add warnings
        if (parsed.length > 1) {
          const expectedColumns = parsed[0].length;
          let inconsistentRows = 0;
  
          for (let i = 1; i < parsed.length; i++) {
            if (parsed[i].length !== expectedColumns) {
              inconsistentRows++;
            }
          }
  
          if (inconsistentRows > 0) {
            warnings.push(`CSV file has ${inconsistentRows} rows with inconsistent column count`);
          }
        }
  
        // Check for potential data quality issues
        const emptyRows = parsed.filter((row: any[]) => row.every((cell: any) => cell === '')).length;
        if (emptyRows > 0) {
          warnings.push(`Found ${emptyRows} completely empty rows`);
        }
  
        return { data: parsed, warnings: warnings.length > 0 ? warnings : undefined };
      } catch (parseError) {
        throw new Error(`Failed to parse CSV file: ${parseError instanceof Error ? parseError.message : 'Unknown parsing error'}`);
      }
    } else if (ext === '.xlsx' || ext === '.xls') {
      const workbook = new ExcelJS.Workbook();
      await workbook.xlsx.readFile(absolutePath);
      const sheetName = sheet || workbook.worksheets[0]?.name;
      const worksheet = workbook.getWorksheet(sheetName);
  
      if (!worksheet) {
        throw new Error(`Sheet "${sheetName}" not found in workbook`);
      }
  
      const data: any[][] = [];
      worksheet.eachRow((row, rowNumber) => {
        const rowData: any[] = [];
        row.eachCell((cell, colNumber) => {
          rowData[colNumber - 1] = cell.value || '';
        });
        data.push(rowData);
      });
  
      return { data, warnings: warnings.length > 0 ? warnings : undefined };
    } else {
      throw new Error('Unsupported file format. Please use .csv, .xlsx, or .xls files.');
    }
  }