ThinQ Connect MCP Server

Instructions

Returns:
    String containing device control commands and parameter information

Implementation Reference

• thinqconnect_mcp/tools.py:111-252 (handler)

  Main handler function that retrieves device profile, creates device instance, lists available methods and writable properties, and returns a comprehensive formatted guide for controlling the device.

  async def get_device_available_controls(thinq_api: ThinQApi, device_type: str, device_id: str) -> str:
      """
      Get available control command information from device
      """
      try:
          global local_device_profiles
          thinq_api._session = ClientSession()
          if not local_device_profiles.get(device_id):
              device_profile = await thinq_api.async_get_device_profile(device_id=device_id)
              local_device_profiles[device_id] = device_profile
          else:
              device_profile = local_device_profiles[device_id]
  
          device_class = device_class_mapping.get(device_type)
          if not device_class:
              raise ValueError(f"Unsupported device type: {device_type}")
  
          # Create device object
          device = device_class(
              thinq_api=thinq_api,
              device_id="device_id",
              device_type=device_type,
              model_name="model_name",
              alias="alias",
              reportable=True,
              profile=device_profile,
          )
  
          device_methods = [
              (
                  name,
                  str(inspect.signature(getattr(device, name))).split(" -> ")[0],
              )  # (method name, parameter info)
              for name in dir(device)
              if callable(getattr(device, name))  # Check if it's a function
              and name not in dir(ConnectBaseDevice)  # Exclude inherited from parent class
              and not name.startswith("__")  # Exclude internal methods
          ]
          writable_properties = str(device.profiles.writable_properties)
          methods = "\n".join(map(str, device_methods))
          profile = str(device_profile)
          current_time = datetime.now()
          return f"""# Device Control Instruction Guide**
  This guide provides instructions for IoT device control using structured data formats:
  - **Profile**: JSON-based device capabilities and properties
  - **Writable Properties**: List of controllable device properties
  - **Methods**: List of available control methods
  
  ## Validation Rules (Critical)
  Before executing any control command, verify:
  1. **Property exists** in `Writable Properties` list
  2. **Method exists** in `Methods` list
  3. **Valid mapping** between method and property:
     - Standard format: `set_{{property_name}}`
     - Example: Method `set_air_con_operation_mode` maps to property `air_con_operation_mode`
     - Some methods handle multiple properties (e.g., `set_relative_time_to_start` for both `relative_hour_to_start` and `relative_minute_to_start`)
  4. **Both method AND property must be present** for control to be permitted
  
  **If validation fails**: Respond with `"This control is not supported on this device."`
  
  ## Naming Convention
  - **Profile JSON**: camelCase (`airConOperationMode`, `coolTargetTemperature`)
  - **Writable Properties & Methods**: snake_case (`air_con_operation_mode`, `cool_target_temperature`)
  Accurate camelCase ↔ snake_case mapping is essential for proper execution.
  
  ## Data Structures
  ### Writable Properties
  {writable_properties}
  ### Methods
  {methods}
  ### Profile
  {profile}
  
  ## Control Command Execution
  Use the `post_device_control` tool with these parameters:
  {{
    "device_type": "<DEVICE_TYPE>",
    "device_id": "<DEVICE_UNIQUE_ID>",
    "control_method": "<METHOD_NAME>",
    "control_params": {{
      "<param_name>": <param_value>
    }}
  }}
  
  ### Parameter Types & Validation
  Based on Profile `type` field:
  - **enum**: Must use exact values from Profile's `value` array
  - **boolean**: `true` or `false`
  - **number**: Numeric value
  - **range**: Value within `min`~`max` bounds, respecting `step` intervals
  
  ### Time-Based Controls
  **Current Time**: {current_time.strftime('%Y-%m-%d %H:%M:%S')}
  
  For time-related commands:
  - **Relative time requests** ("in 2 hours"): Calculate interval from current time
  - **Absolute time requests** ("turn on at 7 PM"): Convert to relative time if only relative control is supported
  - **Future time guarantee**: If requested time is past, assume next day
  - **Example calculation**:
    - Current: 15:20, Request: 19:00
    - Result: `{{"relative_hour_to_start": 3, "relative_minute_to_start": 40}}`
  
  ### Control Examples
  
  **Single parameter:**
  {{
    "control_method": "set_air_con_operation_mode",
    "control_params": {{"operation": "POWER_OFF"}}
  }}
  
  **Multiple parameters:**
  {{
    "control_method": "set_relative_time_to_start",
    "control_params": {{"hour": 10, "minute": 30}}
  }}
  ```
  
  ## Profile Structure Reference
  Profile JSON contains device capabilities with this structure:
  {{
    "propertyName": {{
      "type": "enum|boolean|number|range",
      "mode": ["r", "w"],  // r=readable, w=writable
      "value": {{
        "r": [/* readable values */],
        "w": [/* writable values */]
      }},
      "unit": "C|F|...",  // for temperature/measurement properties
      "min": 0,           // for range type
      "max": 100,         // for range type
      "step": 1           // for range type
    }}
  }}
  
  **Control Permission**: Property must have `"w"` in `mode` array to be controllable.
  ## Error Handling
  - **Power-off errors**: Check device status with `get_device_status` and turn on power first
  - **Invalid parameters**: Verify parameter values match Profile specifications
  - **Missing capabilities**: Use validation rules to confirm method/property support
  """
      except Exception as e:
          return f"An error occurred while retrieving device details: {str(e)}"

• thinqconnect_mcp/server.py:77-89 (registration)

  MCP tool registration using @mcp.tool decorator, includes tool description serving as schema (args: device_type str, device_id str), and thin wrapper handler that injects thinq_api and delegates to the core implementation in tools.py.

  @mcp.tool(
      description="""Retrieves available control commands and parameter information for a specific device
      Args:
          device_type: Device type (e.g., DEVICE_AIR_CONDITIONER, DEVICE_ROBOT_CLEANER, DEVICE_STYLER)
          device_id: Unique ID of the device to query
  
      Returns:
          String containing device control commands and parameter information
      """
  )
  async def get_device_available_controls(device_type: str, device_id: str) -> str:
      return await tools.get_device_available_controls(thinq_api=thinq_api, device_type=device_type, device_id=device_id)