Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:536-554 (handler)

  The MCP tool handler for 'validate_excel_range'. This function is decorated with @mcp.tool() for registration and executes the validation logic by delegating to the validate_range_impl helper.
  @mcp.tool() def validate_excel_range( filepath: str, sheet_name: str, start_cell: str, end_cell: Optional[str] = None ) -> str: """Validate if a range exists and is properly formatted.""" try: full_path = get_excel_path(filepath) range_str = start_cell if not end_cell else f"{start_cell}:{end_cell}" result = validate_range_impl(full_path, sheet_name, range_str) return result["message"] except ValidationError as e: return f"Error: {str(e)}" except Exception as e: logger.error(f"Error validating range: {e}") raise
• src/excel_mcp/validation.py:97-163 (helper)

  Core helper function implementing the range validation logic. Checks sheet existence, parses range, validates bounds against worksheet dimensions, and returns detailed validation info. This is called by the handler as validate_range_impl.
  def validate_range_in_sheet_operation( filepath: str, sheet_name: str, start_cell: str, end_cell: str | None = None, ) -> dict[str, Any]: """Validate if a range exists in a worksheet and return data range info.""" try: wb = load_workbook(filepath) if sheet_name not in wb.sheetnames: raise ValidationError(f"Sheet '{sheet_name}' not found") worksheet = wb[sheet_name] # Get actual data dimensions data_max_row = worksheet.max_row data_max_col = worksheet.max_column # Validate range try: start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell) except ValueError as e: raise ValidationError(f"Invalid range: {str(e)}") # If end not specified, use start if end_row is None: end_row = start_row if end_col is None: end_col = start_col # Validate bounds against maximum possible Excel limits is_valid, message = validate_range_bounds( worksheet, start_row, start_col, end_row, end_col ) if not is_valid: raise ValidationError(message) range_str = f"{start_cell}" if end_cell is None else f"{start_cell}:{end_cell}" data_range_str = f"A1:{get_column_letter(data_max_col)}{data_max_row}" # Check if range is within data or extends beyond extends_beyond_data = ( end_row > data_max_row or end_col > data_max_col ) return { "message": ( f"Range '{range_str}' is valid. " f"Sheet contains data in range '{data_range_str}'" ), "valid": True, "range": range_str, "data_range": data_range_str, "extends_beyond_data": extends_beyond_data, "data_dimensions": { "max_row": data_max_row, "max_col": data_max_col, "max_col_letter": get_column_letter(data_max_col) } } except ValidationError as e: logger.error(str(e)) raise except Exception as e: logger.error(f"Failed to validate range: {e}") raise ValidationError(str(e))
• src/excel_mcp/validation.py:198-235 (helper)

  Supporting helper function used by the main validation logic to check if the specified range bounds are within the worksheet's max_row and max_column.
  def validate_range_bounds( worksheet: Worksheet, start_row: int, start_col: int, end_row: int | None = None, end_col: int | None = None, ) -> tuple[bool, str]: """Validate that cell range is within worksheet bounds""" max_row = worksheet.max_row max_col = worksheet.max_column try: # Check start cell bounds if start_row < 1 or start_row > max_row: return False, f"Start row {start_row} out of bounds (1-{max_row})" if start_col < 1 or start_col > max_col: return False, ( f"Start column {get_column_letter(start_col)} " f"out of bounds (A-{get_column_letter(max_col)})" ) # If end cell specified, check its bounds if end_row is not None and end_col is not None: if end_row < start_row: return False, "End row cannot be before start row" if end_col < start_col: return False, "End column cannot be before start column" if end_row > max_row: return False, f"End row {end_row} out of bounds (1-{max_row})" if end_col > max_col: return False, ( f"End column {get_column_letter(end_col)} " f"out of bounds (A-{get_column_letter(max_col)})" ) return True, "Range is valid" except Exception as e: return False, f"Invalid range: {e!s}"