ThinQ Connect MCP Server

Instructions

Implementation Reference

• thinqconnect_mcp/tools.py:255-316 (handler)

  Core handler function that implements the post_device_control tool logic: fetches device profile, instantiates the appropriate device class, dynamically invokes the specified control method with parameter type conversion, and handles errors.
  async def post_device_control( thinq_api: ThinQApi, device_type: str, device_id: str, control_method: str, control_params: dict, ) -> str: """ Device Control """ 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, ) # Call device control method if hasattr(device, control_method): method = getattr(device, control_method) sig = inspect.signature(method) # Get method signature (parameter information) # Prepare arguments for each method parameter kwargs = {} for param_name, param in sig.parameters.items(): if param_name in control_params: param_type = param.annotation value = control_params[param_name] # Convert based on parameter type if param_type == int or param_type == "int": kwargs[param_name] = int(value) elif param_type == str or param_type == "str": kwargs[param_name] = str(value) else: kwargs[param_name] = value await method(**kwargs) else: return f"Command '{control_method}' not found." return f"Device control completed. Please relay appropriately to the user. Command: {control_method}, Parameters: {control_params}" except Exception as e: return f"An error occurred during device control: {str(e)}, Command: {control_method}, Parameters: {control_params}"
• thinqconnect_mcp/server.py:104-129 (registration)

  MCP tool registration decorator (@mcp.tool) with schema description and thin wrapper handler that delegates to the core implementation in tools.post_device_control, passing the ThinQApi instance.
  @mcp.tool( description="""Send control commands to a specific device on the ThinQ Connect platform to change its settings or state Args: device_type: Device type (e.g., DEVICE_AIR_CONDITIONER, DEVICE_ROBOT_CLEANER, DEVICE_STYLER) device_id: Unique ID of the device to control control_method: Co ntrol method name to execute (e.g., set_air_con_operation_mode, set_target_temperature, set_wind_strength) control_params: Parameter dictionary to pass to the control method (e.g., {'operation': 'POWER_OFF'}, {'temperature': 25}, {'wind_strength': 'HIGH'}) Returns: String containing device control result message """ ) async def post_device_control( device_type: str, device_id: str, control_method: str, control_params: dict, ) -> str: return await tools.post_device_control( thinq_api=thinq_api, device_type=device_type, device_id=device_id, control_method=control_method, control_params=control_params, )
• thinqconnect_mcp/tools.py:185-250 (schema)

  Detailed usage instructions and parameter validation schema for post_device_control tool embedded in the get_device_available_controls function docstring.
  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 """