Excel MCP Server

Instructions

Implementation Reference

• src/excel_mcp/server.py:123-139 (handler)

  The primary handler and registration for the 'validate_formula_syntax' MCP tool. It processes inputs, resolves file paths, calls the validation helper, and returns results or errors.

  @mcp.tool()
  def validate_formula_syntax(
      filepath: str,
      sheet_name: str,
      cell: str,
      formula: str,
  ) -> str:
      """Validate Excel formula syntax without applying it."""
      try:
          full_path = get_excel_path(filepath)
          result = validate_formula_impl(full_path, sheet_name, cell, formula)
          return result["message"]
      except (ValidationError, CalculationError) as e:
          return f"Error: {str(e)}"
      except Exception as e:
          logger.error(f"Error validating formula: {e}")
          raise

• src/excel_mcp/validation.py:14-95 (helper)

  Core helper function (validate_formula_in_cell_operation, imported as validate_formula_impl) that performs detailed formula syntax validation, cell reference checks, workbook loading, and comparison with existing cell content.

  def validate_formula_in_cell_operation(
      filepath: str,
      sheet_name: str,
      cell: str,
      formula: str
  ) -> dict[str, Any]:
      """Validate Excel formula before writing"""
      try:
          wb = load_workbook(filepath)
          if sheet_name not in wb.sheetnames:
              raise ValidationError(f"Sheet '{sheet_name}' not found")
  
          if not validate_cell_reference(cell):
              raise ValidationError(f"Invalid cell reference: {cell}")
  
          # First validate the provided formula's syntax
          is_valid, message = validate_formula(formula)
          if not is_valid:
              raise ValidationError(f"Invalid formula syntax: {message}")
  
          # Additional validation for cell references in formula
          cell_refs = re.findall(r'[A-Z]+[0-9]+(?::[A-Z]+[0-9]+)?', formula)
          for ref in cell_refs:
              if ':' in ref:  # Range reference
                  start, end = ref.split(':')
                  if not (validate_cell_reference(start) and validate_cell_reference(end)):
                      raise ValidationError(f"Invalid cell range reference in formula: {ref}")
              else:  # Single cell reference
                  if not validate_cell_reference(ref):
                      raise ValidationError(f"Invalid cell reference in formula: {ref}")
  
          # Now check if there's a formula in the cell and compare
          sheet = wb[sheet_name]
          cell_obj = sheet[cell]
          current_formula = cell_obj.value
  
          # If cell has a formula (starts with =)
          if isinstance(current_formula, str) and current_formula.startswith('='):
              if formula.startswith('='):
                  if current_formula != formula:
                      return {
                          "message": "Formula is valid but doesn't match cell content",
                          "valid": True,
                          "matches": False,
                          "cell": cell,
                          "provided_formula": formula,
                          "current_formula": current_formula
                      }
              else:
                  if current_formula != f"={formula}":
                      return {
                          "message": "Formula is valid but doesn't match cell content",
                          "valid": True,
                          "matches": False,
                          "cell": cell,
                          "provided_formula": formula,
                          "current_formula": current_formula
                      }
                  else:
                      return {
                          "message": "Formula is valid and matches cell content",
                          "valid": True,
                          "matches": True,
                          "cell": cell,
                          "formula": formula
                      }
          else:
              return {
                  "message": "Formula is valid but cell contains no formula",
                  "valid": True,
                  "matches": False,
                  "cell": cell,
                  "provided_formula": formula,
                  "current_content": str(current_formula) if current_formula else ""
              }
  
      except ValidationError as e:
          logger.error(str(e))
          raise
      except Exception as e:
          logger.error(f"Failed to validate formula: {e}")
          raise ValidationError(str(e))

• src/excel_mcp/validation.py:165-195 (helper)

  Supporting helper function for basic formula syntax validation, including parenthesis balancing and unsafe function detection.

  def validate_formula(formula: str) -> tuple[bool, str]:
      """Validate Excel formula syntax and safety"""
      if not formula.startswith("="):
          return False, "Formula must start with '='"
  
      # Remove the '=' prefix for validation
      formula = formula[1:]
  
      # Check for balanced parentheses
      parens = 0
      for c in formula:
          if c == "(":
              parens += 1
          elif c == ")":
              parens -= 1
          if parens < 0:
              return False, "Unmatched closing parenthesis"
  
      if parens > 0:
          return False, "Unclosed parenthesis"
  
      # Basic function name validation
      func_pattern = r"([A-Z]+)\("
      funcs = re.findall(func_pattern, formula)
      unsafe_funcs = {"INDIRECT", "HYPERLINK", "WEBSERVICE", "DGET", "RTD"}
  
      for func in funcs:
          if func in unsafe_funcs:
              return False, f"Unsafe function: {func}"
  
      return True, "Formula is valid"