Alpha ESS MCP Server

Instructions

Set battery discharge configuration for a specific Alpha ESS system.
If no serial provided, auto-selects if only one system exists.

Args:
    enabled: True to enable battery discharge, False to disable
    dp1_start: Start time for discharge period 1 (HH:MM format, minutes must be :00, :15, :30, :45)
    dp1_end: End time for discharge period 1 (HH:MM format, minutes must be :00, :15, :30, :45)
    dp2_start: Start time for discharge period 2 (HH:MM format, minutes must be :00, :15, :30, :45)
    dp2_end: End time for discharge period 2 (HH:MM format, minutes must be :00, :15, :30, :45)
    discharge_cutoff_soc: Percentage to stop discharging battery at (0-100)
    serial: The serial number of the Alpha ESS system (optional)
    
Returns:
    dict: Result of discharge configuration update with success status

Implementation Reference

• main.py:878-954 (handler)

  The core handler function for the 'set_battery_discharge' tool. It is decorated with @mcp.tool(), which registers it as an MCP tool. The function handles serial auto-discovery, authenticates with the Alpha ESS API, and calls updateDisChargeConfigInfo to set the discharge parameters.

  @mcp.tool()
  async def set_battery_discharge(
          enabled: bool,
          dp1_start: str,
          dp1_end: str,
          dp2_start: str,
          dp2_end: str,
          discharge_cutoff_soc: float,
          serial: Optional[str] = None
  ) -> dict[str, Any]:
      """
      Set battery discharge configuration for a specific Alpha ESS system.
      If no serial provided, auto-selects if only one system exists.
      
      Args:
          enabled: True to enable battery discharge, False to disable
          dp1_start: Start time for discharge period 1 (HH:MM format, minutes must be :00, :15, :30, :45)
          dp1_end: End time for discharge period 1 (HH:MM format, minutes must be :00, :15, :30, :45)
          dp2_start: Start time for discharge period 2 (HH:MM format, minutes must be :00, :15, :30, :45)
          dp2_end: End time for discharge period 2 (HH:MM format, minutes must be :00, :15, :30, :45)
          discharge_cutoff_soc: Percentage to stop discharging battery at (0-100)
          serial: The serial number of the Alpha ESS system (optional)
          
      Returns:
          dict: Result of discharge configuration update with success status
      """
      client = None
      try:
          # Auto-discover serial if not provided
          if not serial:
              serial_info = await get_default_serial()
              if not serial_info['success'] or not serial_info['serial']:
                  return {
                      "success": False,
                      "message": f"Serial auto-discovery failed: {serial_info['message']}",
                      "data": None,
                      "available_systems": serial_info.get('systems', [])
                  }
              serial = serial_info['serial']
  
          app_id, app_secret = get_alpha_credentials()
          client = alphaess(app_id, app_secret)
  
          # Update the discharge configuration using the proper method signature
          result = await client.updateDisChargeConfigInfo(
              serial,
              discharge_cutoff_soc,  # batUseCap
              1 if enabled else 0,  # ctrDis
              dp1_end,
              dp2_end,
              dp1_start,
              dp2_start
          )
  
          return {
              "success": True,
              "message": f"Successfully updated discharge config for {serial}",
              "data": result,
              "serial_used": serial
          }
  
      except ValueError as e:
          return {
              "success": False,
              "message": f"Configuration or parameter error: {str(e)}",
              "data": None
          }
      except Exception as e:
          return {
              "success": False,
              "message": f"Error setting battery discharge config: {str(e)}",
              "data": None
          }
      finally:
          if client:
              await client.close()