Alpha ESS MCP Server

Instructions

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()