Alpha ESS MCP Server

Instructions

Implementation Reference

• main.py:735-802 (handler)

  The primary handler function for the 'get_discharge_config' MCP tool. Decorated with @mcp.tool() for automatic registration. Retrieves discharge configuration via Alpha ESS API, structures response using DischargeConfig model, handles serial auto-detection, and formats standardized output.
  @mcp.tool() async def get_discharge_config(serial: Optional[str] = None) -> dict[str, Any]: """ Get battery discharge configuration for a specific Alpha ESS system. Returns structured configuration with clear period definitions and status. If no serial provided, auto-selects if only one system exists. Args: serial: The serial number of the Alpha ESS system (optional) Returns: dict: Enhanced response with structured discharge configuration """ 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 create_enhanced_response( success=False, message=f"Serial auto-discovery failed: {serial_info['message']}", raw_data=None, data_type="config", metadata={"available_systems": serial_info.get('systems', [])} ) serial = serial_info['serial'] app_id, app_secret = get_alpha_credentials() client = alphaess(app_id, app_secret) # Get discharge config config = await client.getDisChargeConfigInfo(serial) # Structure the config data structured = structure_config_data(config, "discharge") return create_enhanced_response( success=True, message=f"Successfully retrieved discharge config for {serial}", raw_data=config, data_type="config", serial_used=serial, metadata={ "config_type": "battery_discharging", "total_periods": 2, "units": {"soc": "%", "time": "HH:MM"} }, structured_data=structured ) except ValueError as e: return create_enhanced_response( success=False, message=f"Configuration error: {str(e)}", raw_data=None, data_type="config" ) except Exception as e: return create_enhanced_response( success=False, message=f"Error retrieving discharge config: {str(e)}", raw_data=None, data_type="config" ) finally: if client: await client.close()
• models.py:50-55 (schema)

  Dataclass schema defining the structured DischargeConfig used in tool responses, including enable status, time periods (via ConfigPeriod), discharge limit SOC, and units.
  class DischargeConfig: enabled: bool periods: List[ConfigPeriod] discharge_limit_soc: int units: Dict[str, str]
• main.py:135-177 (helper)

  Utility function that transforms raw API discharge config data into structured DischargeConfig instance, mapping fields like ctrDis to enabled, timeDisf1/e1 to periods, batUseCap to discharge_limit_soc.
  def structure_config_data(raw_data: Dict[str, Any], config_type: str) -> Union[ChargeConfig, DischargeConfig, Dict]: """Structure configuration data with better field names""" if config_type == "charge": return ChargeConfig( enabled=bool(raw_data.get('gridCharge', 0)), periods=[ ConfigPeriod( period=1, start_time=raw_data.get('timeChaf1', '00:00'), end_time=raw_data.get('timeChae1', '00:00'), active=raw_data.get('timeChaf1', '00:00') != '00:00' or raw_data.get('timeChae1', '00:00') != '00:00' ), ConfigPeriod( period=2, start_time=raw_data.get('timeChaf2', '00:00'), end_time=raw_data.get('timeChae2', '00:00'), active=raw_data.get('timeChaf2', '00:00') != '00:00' or raw_data.get('timeChae2', '00:00') != '00:00' ) ], charge_limit_soc=raw_data.get('batHighCap', 100), units={"soc": "%", "time": "HH:MM"} ) elif config_type == "discharge": return DischargeConfig( enabled=bool(raw_data.get('ctrDis', 0)), periods=[ ConfigPeriod( period=1, start_time=raw_data.get('timeDisf1', '00:00'), end_time=raw_data.get('timeDise1', '00:00'), active=raw_data.get('timeDisf1', '00:00') != '00:00' or raw_data.get('timeDise1', '00:00') != '00:00' ), ConfigPeriod( period=2, start_time=raw_data.get('timeDisf2', '00:00'), end_time=raw_data.get('timeDise2', '00:00'), active=raw_data.get('timeDisf2', '00:00') != '00:00' or raw_data.get('timeDise2', '00:00') != '00:00' ) ], discharge_limit_soc=raw_data.get('batUseCap', 10), units={"soc": "%", "time": "HH:MM"} ) return raw_data
• models.py:34-39 (schema)

  Supporting schema for configuration periods used in both ChargeConfig and DischargeConfig, defining time windows for config activation.
  class ConfigPeriod: period: int start_time: str end_time: str active: bool