Alpha ESS MCP Server

Instructions

Implementation Reference

• main.py:405-449 (handler)

  MCP tool handler for get_ess_list. Fetches ESS systems list via helper, structures with models, and returns enhanced response. Includes @mcp.tool() registration.
  @mcp.tool() async def get_ess_list() -> dict[str, Any]: """ Get list of registered Alpha ESS systems with auto-selection logic. Returns enhanced system information with structured metadata. Returns: dict: Enhanced response with system list and auto-selection recommendations """ serial_info = await get_default_serial() if serial_info['success']: systems = [SystemInfo( serial=s.get('sysSn'), name=s.get('sysName', 'Unknown'), status=s.get('sysStatus', 'Unknown') ) for s in serial_info['systems']] structured = SystemList( recommended_serial=serial_info.get('serial'), systems=systems, requires_selection=serial_info.get('serial') is None ) return create_enhanced_response( success=True, message=serial_info['message'], raw_data=serial_info['systems'], data_type="system_list", metadata={ "total_systems": len(serial_info['systems']), "auto_selected_serial": serial_info.get('serial'), "selection_strategy": "single_system_auto" if serial_info.get('serial') else "multiple_systems_manual" }, structured_data=structured ) else: return create_enhanced_response( success=False, message=serial_info['message'], raw_data=None, data_type="system_list", metadata={"error_type": "no_systems_found"} )
• main.py:240-308 (helper)

  Core helper function that authenticates with AlphaESS API, calls getESSList(), and implements auto-selection logic for single/multiple systems.
  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()
• models.py:67-79 (schema)

  Dataclasses defining structured output types for ESS systems list: SystemInfo (individual system) and SystemList (list with recommendations). Used in get_ess_list response.
  @dataclass class SystemInfo: serial: str name: str status: str @dataclass class SystemList: recommended_serial: Optional[str] systems: List[SystemInfo] requires_selection: bool
• main.py:24-52 (helper)

  Utility function to create standardized enhanced responses used by get_ess_list and other tools.
  def create_enhanced_response( success: bool, message: str, raw_data: Any, data_type: DataType, serial_used: Optional[str] = None, metadata: Optional[Dict[str, Any]] = None, structured_data: Optional[Any] = None ) -> Dict[str, Any]: """Create a standardized response with enhanced structure""" response = { "success": success, "message": message, "data_type": data_type, "metadata": { "timestamp": datetime.now().isoformat(), **({"serial_used": serial_used} if serial_used else {}), **(metadata or {}) }, "data": raw_data } if structured_data is not None: if is_dataclass(structured_data): response["structured"] = asdict(structured_data) else: response["structured"] = structured_data return response