SmartThingsMCP

Un servidor y cliente FastMCP 2.0 completo para interactuar con dispositivos, ubicaciones, habitaciones, modos, escenas y reglas de automatización de SmartThings a través de la API de SmartThings.

GitHubPrueba este MCPPatrocinado

Documentación

Servidor y Cliente SmartThingsMCP

Un servidor y cliente FastMCP 2.0 completo para interactuar con dispositivos, ubicaciones, habitaciones, modos, escenas y reglas de automatización de SmartThings a través de la API de SmartThings.

Descripción General

SmartThingsMCP proporciona:

Servidor FastMCP 2.0: Expone la funcionalidad de la API de SmartThings como herramientas MCP
Cliente Inteligente: Cliente Python con caché inteligente, soporte asíncrono y múltiples opciones de transporte
Arquitectura Modular: Organizado por funcionalidad (dispositivos, ubicaciones, habitaciones, modos, escenas, reglas)
Caché de Dos Niveles: Caché tanto en el cliente como en el servidor para un rendimiento óptimo
Múltiples Transportes: Soporte para HTTP, SSE (Server-Sent Events) y STDIO
Autenticación OAuth 2.0: Autenticación segura basada en tokens con la API de SmartThings

Componentes

Servidor

SmartThingsMCPServer.py: Servidor FastMCP 2.0 que expone la API de SmartThings como herramientas MCP
modules/server/: Implementaciones de herramientas del servidor
- devices.py: Herramientas de gestión de dispositivos (listar, obtener, actualizar, eliminar, ejecutar comandos, etc.)
- locations.py: Herramientas de gestión de ubicaciones (crear, leer, actualizar, eliminar ubicaciones y habitaciones)
- rooms.py: Herramientas de gestión de habitaciones (listar, crear, actualizar, eliminar habitaciones)
- modes.py: Herramientas de gestión de modos (listar, obtener, establecer modos de ubicación)
- scenes.py: Herramientas de gestión de escenas (listar, obtener, ejecutar, crear, actualizar, eliminar escenas)
- rules.py: Herramientas de reglas de automatización (listar, obtener, crear, actualizar, eliminar, ejecutar reglas)
- structure_tools.py: Herramientas de generación de estructuras para integración con LLM
- common.py: Utilidades compartidas para solicitudes API, construcción de URL y filtrado de parámetros

Cliente

SmartThingsMCPClient.py: CLI para interactuar con el servidor MCP
modules/client/: Implementación del cliente
- main.py: Clase principal SmartThingsMCPClient que combina todos los mixins
- base.py: BaseClient con manejo de transporte e invocación de herramientas
- cache.py: CacheMixin con caché LRU, gestión de TTL y estadísticas de caché
- devices.py: DevicesMixin con métodos de operación de dispositivos
- locations.py: LocationsMixin con métodos de ubicación y habitación
- rooms.py: RoomsMixin con métodos específicos de habitaciones
- modes.py: ModesMixin con métodos de gestión de modos
- rules.py: RulesMixin con métodos de gestión de reglas
- scenes.py: ScenesMixin con métodos de gestión de escenas
- utils.py: Funciones de utilidad para conversión de herramientas y ejecución de acciones
- utils_ext.py: Utilidades extendidas (nota: actualmente sin uso)

Endpoints de API

SmartThingsMCP expone los siguientes endpoints de API como herramientas MCP:

Gestión de Dispositivos

list_devices: Obtener una lista de todos los dispositivos (admite filtrado por capacidad, ubicación, habitación o ID de dispositivo)
get_device: Obtener detalles de un dispositivo específico
update_device: Actualizar la etiqueta de un dispositivo
delete_device: Eliminar un dispositivo
execute_command: Ejecutar un comando en un componente de dispositivo
get_device_status: Obtener el estado actual de un dispositivo
get_device_components: Obtener todos los componentes de un dispositivo
get_device_capabilities: Obtener las capacidades de un componente de dispositivo
get_device_health: Obtener el estado de salud/conectividad de un dispositivo
get_device_presentation: Obtener los detalles de presentación de UI de un dispositivo

Gestión de Ubicaciones

list_locations: Obtener una lista de todas las ubicaciones
get_location: Obtener detalles de una ubicación específica
create_location: Crear una nueva ubicación con coordenadas e información de dirección
update_location: Actualizar detalles de ubicación (nombre, coordenadas, dirección)
delete_location: Eliminar una ubicación
get_location_rooms: Obtener todas las habitaciones en una ubicación (método de conveniencia)

Gestión de Habitaciones

list_rooms: Obtener todas las habitaciones en una ubicación
get_room: Obtener detalles de una habitación específica
create_room: Crear una nueva habitación en una ubicación
update_room: Actualizar el nombre de una habitación
delete_room: Eliminar una habitación de una ubicación

Gestión de Modos

list_modes: Obtener todos los modos disponibles para una ubicación
get_mode: Obtener detalles de un modo específico
get_current_mode: Obtener el modo actualmente activo para una ubicación
set_mode: Cambiar el modo actual para una ubicación

Gestión de Escenas

list_scenes: Obtener todas las escenas (opcionalmente filtradas por ubicación)
get_scene: Obtener detalles de una escena específica
execute_scene: Ejecutar/ejecutar una escena
create_scene: Crear una nueva escena con acciones y propiedades visuales
update_scene: Actualizar una escena existente (nombre, icono, colores, acciones)
delete_scene: Eliminar una escena

Gestión de Reglas

list_rules: Obtener todas las reglas de automatización (opcionalmente filtradas por ubicación)
get_rule: Obtener detalles de una regla específica
create_rule: Crear una nueva regla de automatización con condiciones y acciones
update_rule: Actualizar una regla existente (nombre, disparadores, acciones, estado habilitado)
delete_rule: Eliminar una regla de automatización
execute_rule: Activar manualmente la ejecución de una regla

Características

Caché Inteligente

Tanto SmartThingsMCPClient como SmartThingsMCPServer incluyen caché integral para mejorar el rendimiento:

Caché del Lado del Cliente

SmartThingsMCPClient proporciona:

Caché automática de operaciones de solo lectura (list_devices, list_locations, etc.)
Expiración basada en TTL (predeterminado: 5 minutos, configurable)
Invalidación inteligente de caché en operaciones de escritura (execute_command, update_device, etc.)
Expulsión LRU cuando la caché está llena
Seguimiento de estadísticas de caché (aciertos, fallos, tasa de aciertos)
Retroalimentación visual verde: ✓ Cache hit: list_locations

Consulte CACHING.md para documentación detallada.

Caché del Lado del Servidor

SmartThingsMCPServer proporciona:

Caché automática de todas las solicitudes GET a la API de SmartThings
Expiración basada en TTL (predeterminado: 5 minutos)
Invalidación completa de caché en operaciones de escritura (POST, PUT, DELETE)
Expulsión LRU cuando la caché está llena
Seguimiento de estadísticas de caché
Retroalimentación visual verde: ✓ Server cache hit: GET devices

Consulte SERVER_CACHING.md para documentación detallada.

Caché de Dos Niveles: Cuando tanto la caché del cliente como la del servidor están activas, ¡obtiene el máximo rendimiento con dos capas de caché!

Beneficios de Rendimiento:

Reducción del 60-80% en llamadas API
Tiempos de respuesta 5-10 veces más rápidos para datos en caché
Menor uso del límite de tasa

Gestión de Reglas

El servidor proporciona capacidades integrales de gestión de reglas:

list_rules: Listar todas las reglas de automatización para una ubicación
get_rule: Obtener detalles de una regla específica
create_rule: Crear una nueva regla de automatización con condiciones y acciones
update_rule: Actualizar una regla existente (nombre, disparadores, acciones o estado habilitado)
delete_rule: Eliminar una regla
execute_rule: Ejecutar manualmente una regla

Habilitar/Deshabilitar Reglas:

# Disable a rule
client.update_rule(auth=token, rule_id="abc-123", enabled=False)

# Enable a rule
client.update_rule(auth=token, rule_id="abc-123", enabled=True)

El parámetro enabled se agregó en diciembre de 2025 para admitir la alternancia del estado de la regla sin eliminar la regla.

Instalación

Requisitos Previos

Python 3.8 o superior
pip u otro gestor de paquetes de Python

Configuración

Instalar dependencias:

pip install -r requirements.txt

Paquetes requeridos:

fastmcp>=2.0.0: Marco FastMCP 2.0 para servidor/cliente MCP
requests>=2.28.0: Biblioteca HTTP para llamadas a la API de SmartThings

Obtener un Token de API de SmartThings:
- Visite Portal de Desarrolladores de SmartThings
- Cree un nuevo token de API con los siguientes alcances:
  - r:devices:* (leer dispositivos)
  - w:devices:* (controlar dispositivos)
  - r:locations:* (leer ubicaciones)
  - w:locations:* (crear/actualizar ubicaciones)
  - r:rules:* (leer reglas, requiere cuenta Enterprise)
  - w:rules:* (escribir reglas, requiere cuenta Enterprise)
  - r:scenes:* (leer escenas)
  - x:scenes:* (ejecutar escenas)

Autenticación

SmartThingsMCP utiliza tokens de portador OAuth 2.0 para la autenticación con la API de SmartThings.

Requisitos del Token

Debe ser un token de API de SmartThings válido (token de portador OAuth 2.0)
El token debe tener los alcances apropiados para las operaciones que desea realizar
El token nunca expira cuando se obtiene del Portal de Desarrolladores de SmartThings
Mantenga su token seguro y nunca lo envíe al control de versiones

Problemas Comunes de Autenticación

401 No Autorizado:

Error calling tool list_devices: 401 Unauthorized

Verifique que el token sea válido y no haya expirado
Compruebe que el token se haya generado desde el Portal de Desarrolladores de SmartThings
Asegúrese de estar pasando el token con la bandera --auth

403 Prohibido:

Error calling tool list_devices: 403 Forbidden

El token existe pero carece de los alcances requeridos
Algunas características (como Reglas) requieren una cuenta SmartThings Enterprise
Otorgue alcances adicionales al token en el Portal de Desarrolladores de SmartThings

Alcances Requeridos por Característica

Característica	Alcances Requeridos
Listar/Obtener Dispositivos	`r:devices:*`
Controlar Dispositivos	`w:devices:*`
Listar/Obtener Ubicaciones	`r:locations:*`
Crear/Actualizar/Eliminar Ubicaciones	`w:locations:*`
Listar/Obtener Escenas	`r:scenes:*`
Ejecutar Escenas	`x:scenes:*`
Crear/Actualizar/Eliminar Escenas	`w:scenes:*`
Listar/Obtener Reglas	`r:rules:*`
Crear/Actualizar/Eliminar Reglas	`w:rules:*`
Listar/Obtener/Establecer Modos	`r:locations:*`

Comenzando

Iniciar el Servidor

Inicie el servidor SmartThingsMCP:

# Start with HTTP transport (default) on port 8000
python SmartThingsMCPServer.py

# Custom port
python SmartThingsMCPServer.py -port 9000

# Using SSE transport
python SmartThingsMCPServer.py -transport sse

# Using STDIO transport
python SmartThingsMCPServer.py -transport stdio

# With auth token override (if needed)
python SmartThingsMCPServer.py -auth YOUR_TOKEN

Usar el Cliente de Línea de Comandos

SmartThingsMCPClient.py proporciona una interfaz CLI:

# List available tools
python SmartThingsMCPClient.py --transport http --port 8000 --action list_tools

# List all devices (requires auth token)
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_devices

# List devices with pretty-printed output
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_devices --pretty

# Get a specific device
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action get_device --params '{"device_id": "DEVICE_ID"}'

# Get device status
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action get_device_status --params '{"device_id": "DEVICE_ID"}'

# Execute a device command
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action execute_command --params '{
  "device_id": "DEVICE_ID",
  "component": "main",
  "capability": "switch",
  "command": "on"
}'

# List all locations
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_locations

# List all scenes
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_scenes

# Execute a scene
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action execute_scene --params '{"scene_id": "SCENE_ID"}'

# Create a new location
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action create_location --params '{
  "name": "Office",
  "country_code": "US",
  "region_code": "CA",
  "locality": "San Francisco"
}'

# List all modes for a location
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_modes --params '{"location_id": "LOCATION_ID"}'

# Set mode for a location
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action set_mode --params '{
  "location_id": "LOCATION_ID",
  "mode_id": "MODE_ID"
}'

# List all rules
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action list_rules

# Enable/disable a rule
python SmartThingsMCPClient.py --auth YOUR_TOKEN --action update_rule --params '{
  "rule_id": "RULE_ID",
  "enabled": false
}'

Opciones del Cliente

--host: MCP server host (default: localhost)
--port: MCP server port (default: 8000)
--auth: SmartThings API authentication token (required for most operations)
--transport: Transport type - http, sse, or stdio (default: http)
--action: Action/tool to execute (required)
--params: JSON string of parameters for the action (default: {})
--pretty: Pretty-print JSON output (flag)

Usar el Cliente Python Programáticamente

import asyncio
from modules.client.main import SmartThingsMCPClient

async def main():
    # Create client with caching enabled (default)
    client = SmartThingsMCPClient(
        host="localhost",
        port=8000,
        auth_token="YOUR_TOKEN",
        transport="http",
        enable_cache=True,        # Enable automatic caching
        cache_ttl=300,            # Cache for 5 minutes
        max_cache_size=1000       # Store up to 1000 cache entries
    )
    
    # List all devices
    devices = await client.list_devices(auth="YOUR_TOKEN")
    print(f"Found {len(devices['items'])} devices")
    
    # Get specific device
    device = await client.get_device(auth="YOUR_TOKEN", device_id="DEVICE_ID")
    print(f"Device: {device['label']}")
    
    # Execute device command
    result = await client.execute_command(
        auth="YOUR_TOKEN",
        device_id="DEVICE_ID",
        component="main",
        capability="switch",
        command="on"
    )
    
    # List locations
    locations = await client.list_locations(auth="YOUR_TOKEN")
    for loc in locations['items']:
        print(f"Location: {loc['name']}")
    
    # List and execute scenes
    scenes = await client.list_scenes(auth="YOUR_TOKEN")
    if scenes['items']:
        scene_id = scenes['items'][0]['sceneId']
        await client.execute_scene(auth="YOUR_TOKEN", scene_id=scene_id)
    
    # Manage rules
    rules = await client.list_rules(auth="YOUR_TOKEN")
    for rule in rules['items']:
        print(f"Rule: {rule['name']} - Enabled: {rule.get('enabled', True)}")
    
    # Check cache statistics (when caching is enabled)
    if hasattr(client, 'get_cache_stats'):
        stats = client.get_cache_stats()
        print(f"Cache hits: {stats['hits']}, misses: {stats['misses']}")

if __name__ == "__main__":
    asyncio.run(main())

Solución de Problemas

Configuración de Transporte

SmartThingsMCP admite tres mecanismos de transporte para la comunicación cliente-servidor:

Transporte HTTP (Recomendado para la mayoría de los casos de uso)

Puerto predeterminado: 8000
Patrón de URL: http://localhost:8000/mcp
Mejor para: Integraciones externas, herramientas LLM, servicios web
Ventajas:
- Interfaz HTTP/REST simple
- Fácil de depurar con herramientas estándar
- Compatible con la mayoría de los firewalls
- Conexiones sin estado

# Server
python SmartThingsMCPServer.py -transport http -port 8000

# Client
python SmartThingsMCPClient.py --transport http --port 8000

Transporte SSE (Server-Sent Events)

Puerto predeterminado: 8000
Patrón de URL: http://localhost:8000/sse
Mejor para: Actualizaciones en tiempo real, transmisión de eventos, push del servidor
Ventajas:
- Comunicación bidireccional
- Arquitectura basada en eventos
- Menor latencia para actualizaciones

# Server
python SmartThingsMCPServer.py -transport sse -port 8000

# Client
python SmartThingsMCPClient.py --transport sse --port 8000

Transporte STDIO (Integración directa)

Sin sobrecarga de red
Mejor para: Integración directa con Python, sistemas embebidos
Ventajas:
- No se necesita configuración de puerto/red
- Comunicación directa entre procesos
- Menor latencia

# Server (runs in foreground)
python SmartThingsMCPServer.py -transport stdio

# Client
python SmartThingsMCPClient.py --transport stdio

Configuración del Cliente

Configuración de Caché

SmartThingsMCPClient incluye caché inteligente con control total:

client = SmartThingsMCPClient(
    host="localhost",
    port=8000,
    auth_token="YOUR_TOKEN",
    enable_cache=True,        # Enable caching
    cache_ttl=300,            # TTL in seconds (default: 5 min)
    max_cache_size=1000       # Max entries (default: 1000)
)

# Get cache statistics
stats = client.get_cache_stats()
print(f"Hit rate: {stats['hit_rate']:.2%}")

# Clear cache manually
client.clear_cache()

Operaciones Cacheables (caché automática):

list_devices
get_device
list_locations
get_location
list_rooms
get_room
list_modes
get_mode
get_current_mode
list_scenes
get_scene
list_rules
get_rule

Operaciones que Invalidan Caché (limpieza automática de caché):

update_device
delete_device
execute_command
create_location
update_location
delete_location
create_room
update_room
delete_room
set_mode
create_scene
update_scene
delete_scene
create_rule
update_rule
delete_rule
execute_rule
execute_scene

Registro

SmartThingsMCP utiliza el módulo de registro estándar de Python:

import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('smartthings_mcp')

# Create client - will now output detailed logs
client = SmartThingsMCPClient(...)

Niveles de registro:

DEBUG: Información de diagnóstico detallada
INFO: Mensajes informativos generales (predeterminado)
WARNING: Mensajes de advertencia
ERROR: Mensajes de error
CRITICAL: Errores críticos

Errores Comunes y Soluciones

Errores de Conexión

Error: Client failed to connect: Session terminated

Error calling tool list_devices: Client failed to connect: Session terminated

Causas y soluciones:

El servidor no está en ejecución: Inicie el servidor con python SmartThingsMCPServer.py
Tipo de transporte incorrecto: Asegúrese de que el cliente y el servidor usen el mismo transporte (http, sse o stdio)
Puerto incorrecto: Verifique que el puerto coincida entre el cliente y el servidor
Host incorrecto: Compruebe que el nombre de host/dirección IP sea correcto
Red/firewall: Asegúrese de que el puerto esté abierto y sea accesible

Depuración:

# Check if server is running on expected port
netstat -tuln | grep 8000

# Test HTTP connectivity
curl http://localhost:8000/mcp

# View server logs
python SmartThingsMCPServer.py 2>&1 | head -20

Errores de Autenticación

Error: 1 validation error for list_devicesArguments: auth: Field required

Error executing tool list_devices: 1 validation error for list_devicesArguments
auth: Field required

Soluciones:

Proporcione el token de autenticación con la bandera --auth YOUR_TOKEN
Asegúrese de que el token sea válido: verifíquelo en el Portal de Desarrolladores de SmartThings
Compruebe que el token no haya expirado
Verifique que el token tenga los alcances requeridos

Ejemplo:

python SmartThingsMCPClient.py --auth "YOUR_VALID_TOKEN" --action list_devices

Error: 401 Unauthorized

Error calling tool list_devices: 401 Unauthorized

Soluciones:

El token es inválido o ha expirado
El formato del token es incorrecto (debe ser un token de portador OAuth 2.0)
Genere un nuevo token desde el Portal de Desarrolladores de SmartThings

Error: 403 Forbidden

Error calling tool create_rule: 403 Forbidden - Access Denied

Soluciones:

El token carece de los alcances requeridos para la operación
La cuenta de SmartThings no tiene acceso a la función (por ejemplo, la API de Reglas requiere Enterprise)
Otorgue alcances adicionales en el Portal de Desarrolladores de SmartThings

Errores de Respuesta de la API

Error: Device not found

{
  "error": "Device not found",
  "message": "No device found with ID: invalid-id"
}

Soluciones:

El ID del dispositivo no existe
El dispositivo ha sido eliminado
Liste los dispositivos primero para obtener IDs válidos: acción list_devices

Error: Invalid component or capability

{
  "error": "Component not found",
  "message": "Component 'main' not found on device"
}

Soluciones:

Verifique los componentes válidos: Use get_device_components para listar los componentes disponibles
Verifique las capacidades válidas: Use get_device_capabilities con el component_id correcto
El dispositivo no admite el comando que intenta ejecutar

Limitación de Velocidad

Error: 429 Too Many Requests

Error calling tool list_devices: 429 Too Many Requests

Soluciones:

Se excedió el límite de velocidad de la API de SmartThings
Habilite el almacenamiento en caché para reducir las llamadas a la API (habilitado por defecto)
Aumente el TTL de la caché para mantener los datos por más tiempo
Implemente la limitación de solicitudes en su código

Verifique la efectividad de la caché:

stats = client.get_cache_stats()
print(f"Cache hits: {stats['hits']}")
print(f"Cache misses: {stats['misses']}")
print(f"Hit rate: {stats['hit_rate']:.2%}")

Problemas de Caché

Problema: Datos obsoletos en la caché

Soluciones:

Reduzca el TTL de la caché: cache_ttl=60 (1 minuto)
Limpie la caché manualmente: client.clear_cache()
Desactive la caché si los datos deben ser en tiempo real: enable_cache=False

Problema: La caché causa alto uso de memoria

Soluciones:

Reduzca el tamaño máximo de la caché: max_cache_size=100
Reduzca el TTL de la caché para que las entradas expiren antes
Limpie la caché periódicamente: client.clear_cache()

Uso Avanzado

Implementación de Herramientas Personalizadas

Puede extender SmartThingsMCP con herramientas personalizadas modificando los módulos del servidor:

# In modules/server/devices.py, add:
@server_instance.tool()
def custom_device_operation(auth: str, device_id: str) -> Dict[str, Any]:
    """Your custom operation description"""
    # Your implementation here
    return make_request(auth, "GET", build_device_url(device_id))

Integración con LLMs

Las herramientas de SmartThingsMCP están diseñadas para funcionar con Modelos de Lenguaje:

# Get formatted tool descriptions for LLM
tools = await client.list_tools()
tool_descriptions = [
    {
        "name": tool["name"],
        "description": tool["description"],
        "params": tool["parameters"]
    }
    for tool in tools
]

Manejo de Errores

import asyncio

async def safe_device_operation():
    client = SmartThingsMCPClient(
        host="localhost",
        port=8000,
        auth_token="YOUR_TOKEN"
    )
    
    try:
        result = await client.get_device(
            auth="YOUR_TOKEN",
            device_id="DEVICE_ID"
        )
        return result
    except ValueError as e:
        print(f"Invalid input: {e}")
    except ConnectionError as e:
        print(f"Connection failed: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")
        
asyncio.run(safe_device_operation())

Optimización del Rendimiento

Habilite el almacenamiento en caché (por defecto: habilitado):

# Already enabled by default
client = SmartThingsMCPClient(enable_cache=True)

Ajuste el TTL de la caché según su caso de uso:

# More frequent updates needed
client = SmartThingsMCPClient(cache_ttl=60)  # 1 minute

# Stable data, longer TTL
client = SmartThingsMCPClient(cache_ttl=900)  # 15 minutes

Use el transporte adecuado:
- HTTP: Mejor para la mayoría de los escenarios
- STDIO: Mejor latencia para integración local
- SSE: Mejor para actualizaciones en tiempo real

Operaciones por lotes:

# Get all data at once rather than in loops
devices = await client.list_devices(auth=token)
for device in devices['items']:
    # Use data from the single list_devices call
    # Don't call get_device for each one if not needed

Formato de Respuesta de la API

Todas las respuestas de la API siguen una estructura consistente:

Respuesta de éxito:

{
  "items": [...],
  "pageProperties": {
    "currentPage": 1,
    "pageSize": 50,
    "totalCount": 100
  }
}

Respuesta de un solo elemento:

{
  "id": "unique-id",
  "label": "Device Name",
  "deviceTypeId": "type-id"
}

Respuesta de error:

{
  "requestId": "request-id",
  "errors": [
    {
      "code": "INVALID_PARAMETER",
      "message": "Detailed error message"
    }
  ]
}

Scripts de Ejemplo

Monitorear el Estado del Dispositivo

import asyncio
from modules.client.main import SmartThingsMCPClient

async def monitor_devices(token):
    client = SmartThingsMCPClient(auth_token=token)
    
    # Get all devices
    devices = await client.list_devices(auth=token)
    
    for device in devices['items']:
        try:
            status = await client.get_device_status(
                auth=token,
                device_id=device['deviceId']
            )
            print(f"{device['label']}: {status}")
        except Exception as e:
            print(f"Error getting status for {device['label']}: {e}")

asyncio.run(monitor_devices("YOUR_TOKEN"))

Controlar Múltiples Dispositivos

import asyncio
from modules.client.main import SmartThingsMCPClient

async def control_devices(token, device_ids, command):
    client = SmartThingsMCPClient(auth_token=token)
    
    for device_id in device_ids:
        try:
            result = await client.execute_command(
                auth=token,
                device_id=device_id,
                component="main",
                capability="switch",
                command=command
            )
            print(f"Device {device_id}: {result}")
        except Exception as e:
            print(f"Error controlling {device_id}: {e}")

asyncio.run(control_devices("YOUR_TOKEN", ["device1", "device2"], "on"))

Ejecución de Escenas

import asyncio
from modules.client.main import SmartThingsMCPClient

async def execute_morning_routine(token):
    client = SmartThingsMCPClient(auth_token=token)
    
    # Get morning scene
    scenes = await client.list_scenes(auth=token)
    morning_scene = next(
        (s for s in scenes['items'] if 'morning' in s.get('sceneName', '').lower()),
        None
    )
    
    if morning_scene:
        result = await client.execute_scene(
            auth=token,
            scene_id=morning_scene['sceneId']
        )
        print(f"Executed scene: {result}")

asyncio.run(execute_morning_routine("YOUR_TOKEN"))

Variables de Entorno

Opcionalmente, puede usar variables de entorno para configuraciones comunes:

export SMARTTHINGS_TOKEN="your-token-here"
export MCP_SERVER_HOST="localhost"
export MCP_SERVER_PORT="8000"
export MCP_TRANSPORT="http"

Referencia de la API

La referencia completa de la API está disponible a través del sistema de herramientas MCP. Liste todas las herramientas disponibles:

python SmartThingsMCPClient.py --action list_tools --pretty

Esto mostrará todas las herramientas disponibles con sus parámetros y descripciones.

Contribuciones

Al extender SmartThingsMCP:

Siga la estructura de módulos existente
Agregue herramientas al módulo apropiado (devices.py, locations.py, etc.)
Incluya docstrings adecuados con descripciones de parámetros y retornos
Pruebe con el cliente
Actualice README.md con la documentación de la nueva herramienta

Licencia

Consulte el archivo LICENSE para obtener información sobre la licencia.