Alpha ESS MCP Server

Instructions

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

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