Alpha ESS MCP Server

Instructions

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

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

Implementation Reference

• main.py:805-876 (handler)

  The handler function for the 'set_battery_charge' tool. Decorated with @mcp.tool() for automatic registration in FastMCP. Handles input parameters, auto-selects serial number if not provided, authenticates with Alpha ESS API, and calls updateChargeConfigInfo to set the battery charge configuration.

  @mcp.tool()
  async def set_battery_charge(
          enabled: bool,
          dp1_start: str,
          dp1_end: str,
          dp2_start: str,
          dp2_end: str,
          charge_cutoff_soc: float,
          serial: Optional[str] = None
  ) -> dict[str, Any]:
      """
      Set battery charging configuration for a specific Alpha ESS system.
      If no serial provided, auto-selects if only one system exists.
      
      Args:
          enabled: True to enable charging from grid, False to disable
          dp1_start: Start time for charging period 1 (HH:MM format, minutes must be :00, :15, :30, :45)
          dp1_end: End time for charging period 1 (HH:MM format, minutes must be :00, :15, :30, :45)
          dp2_start: Start time for charging period 2 (HH:MM format, minutes must be :00, :15, :30, :45)
          dp2_end: End time for charging period 2 (HH:MM format, minutes must be :00, :15, :30, :45)
          charge_cutoff_soc: Percentage to stop charging from grid at (0-100)
          serial: The serial number of the Alpha ESS system (optional)
          
      Returns:
          dict: Result of charge 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)
  
          # Set battery charge configuration
          result = await client.updateChargeConfigInfo(
              serial, enabled, dp1_start, dp1_end,
              dp2_start, dp2_end, charge_cutoff_soc
          )
  
          return {
              "success": True,
              "message": f"Successfully updated charge 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 charge config: {str(e)}",
              "data": None
          }
      finally:
          if client:
              await client.close()

• main.py:805-805 (registration)

  The @mcp.tool() decorator registers the set_battery_charge function as an MCP tool.

  @mcp.tool()

• models.py:42-47 (schema)

  Dataclass defining the structure for ChargeConfig, which matches the input parameters of set_battery_charge (enabled, periods with start/end times, charge_limit_soc). Used in related get_charge_config tool for output structuring.

  class ChargeConfig:
      enabled: bool
      periods: List[ConfigPeriod]
      charge_limit_soc: int
      units: Dict[str, str]

• models.py:34-39 (schema)

  Dataclass for ConfigPeriod used in ChargeConfig periods, corresponding to dp1_start/end and dp2_start/end parameters.

  class ConfigPeriod:
      period: int
      start_time: str
      end_time: str
      active: bool

• main.py:240-310 (helper)

  Helper function called by set_battery_charge to auto-select serial number if not provided.

  async def get_default_serial() -> dict[str, Any]:
      """
      Get the default serial number to use. If only one system is registered,
      returns that serial. If multiple systems, returns list for user to choose.
      
      Returns:
          dict: Result with serial info
      """
      client = None
      try:
          app_id, app_secret = get_alpha_credentials()
          client = alphaess(app_id, app_secret)
  
          # Get ESS list
          ess_list = await client.getESSList()
  
          if not ess_list or len(ess_list) == 0:
              return {
                  "success": False,
                  "message": "No Alpha ESS systems found in your account",
                  "serial": None,
                  "systems": []
              }
  
          if len(ess_list) == 1:
              # Auto-select the only system
              system = ess_list[0]
              serial = system.get('sysSn') if isinstance(system, dict) else getattr(system, 'sysSn', None)
              return {
                  "success": True,
                  "message": f"Auto-selected single system: {serial}",
                  "serial": serial,
                  "systems": ess_list
              }
          else:
              # Multiple systems - return list for user choice
              systems_info = []
              for system in ess_list:
                  if isinstance(system, dict):
                      systems_info.append({
                          "serial": system.get('sysSn'),
                          "name": system.get('sysName', 'Unknown'),
                          "status": system.get('sysStatus', 'Unknown')
                      })
                  else:
                      systems_info.append({
                          "serial": getattr(system, 'sysSn', 'Unknown'),
                          "name": getattr(system, 'sysName', 'Unknown'),
                          "status": getattr(system, 'sysStatus', 'Unknown')
                      })
  
              return {
                  "success": True,
                  "message": f"Found {len(ess_list)} systems. Please specify which serial to use.",
                  "serial": None,
                  "systems": systems_info
              }
  
      except Exception as e:
          return {
              "success": False,
              "message": f"Error getting system list: {str(e)}",
              "serial": None,
              "systems": []
          }
      finally:
          if client:
              await client.close()
  
  
  @mcp.tool()