ThinQ Connect MCP Server

Instructions

Implementation Reference

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

  Core handler function that retrieves the device profile, instantiates the appropriate device class, extracts writable properties and available control methods, and returns a formatted instruction 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, including description/schema-like args, with a thin wrapper handler that 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)
• thinqconnect_mcp/server.py:87-89 (handler)

  Thin wrapper handler registered with MCP that injects the ThinQApi instance and forwards the call to the core logic in tools.py.
  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)