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}"