Alpha ESS MCP Server

Instructions

Implementation Reference

• main.py:665-733 (handler)

  The primary handler function for the 'get_charge_config' tool. It handles serial auto-discovery, calls the Alpha ESS API via client.getChargeConfigInfo, structures the response using helpers, and returns an enhanced standardized response.
  @mcp.tool() async def get_charge_config(serial: Optional[str] = None) -> dict[str, Any]: """ Get battery charging 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 charging 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 charge config config = await client.getChargeConfigInfo(serial) # Structure the config data structured = structure_config_data(config, "charge") return create_enhanced_response( success=True, message=f"Successfully retrieved charge config for {serial}", raw_data=config, data_type="config", serial_used=serial, metadata={ "config_type": "battery_charging", "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 charge config: {str(e)}", raw_data=None, data_type="config" ) finally: if client: await client.close()
• models.py:42-47 (schema)

  Dataclass schema defining the structured output format for charge configuration, used in the tool's structured_data response.
  class ChargeConfig: enabled: bool periods: List[ConfigPeriod] charge_limit_soc: int units: Dict[str, str]
• main.py:665-665 (registration)

  FastMCP decorator registering the get_charge_config function as a tool, which also auto-generates input schema from function signature and docstring.
  @mcp.tool()
• main.py:135-177 (helper)

  Helper function that transforms raw API charge config data into the structured ChargeConfig dataclass instance used by the tool.
  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