SmartThingsMCP

Um servidor e cliente FastMCP 2.0 abrangente para interagir com dispositivos SmartThings, locais, cômodos, modos, cenas e regras de automação através da API SmartThings.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor e Cliente SmartThingsMCP

Um servidor e cliente FastMCP 2.0 abrangente para interagir com dispositivos, locais, cômodos, modos, cenas e regras de automação do SmartThings por meio da API do SmartThings.

Visão Geral

O SmartThingsMCP fornece:

Servidor FastMCP 2.0: Expõe a funcionalidade da API do SmartThings como ferramentas MCP
Cliente Inteligente: Cliente Python com cache inteligente, suporte assíncrono e múltiplas opções de transporte
Arquitetura Modular: Organizado por funcionalidade (dispositivos, locais, cômodos, modos, cenas, regras)
Cache em Dois Níveis: Cache tanto no cliente quanto no servidor para desempenho ideal
Múltiplos Transportes: Suporte a HTTP, SSE (Server-Sent Events) e STDIO
Autenticação OAuth 2.0: Autenticação segura baseada em token com a API do SmartThings

Componentes

Servidor

SmartThingsMCPServer.py: Servidor FastMCP 2.0 que expõe a API do SmartThings como ferramentas MCP
modules/server/: Implementações das ferramentas do servidor
- devices.py: Ferramentas de gerenciamento de dispositivos (listar, obter, atualizar, excluir, executar comandos, etc.)
- locations.py: Ferramentas de gerenciamento de locais (criar, ler, atualizar, excluir locais e cômodos)
- rooms.py: Ferramentas de gerenciamento de cômodos (listar, criar, atualizar, excluir cômodos)
- modes.py: Ferramentas de gerenciamento de modos (listar, obter, definir modos de local)
- scenes.py: Ferramentas de gerenciamento de cenas (listar, obter, executar, criar, atualizar, excluir cenas)
- rules.py: Ferramentas de regras de automação (listar, obter, criar, atualizar, excluir, executar regras)
- structure_tools.py: Ferramentas de geração de estrutura para integração com LLM
- common.py: Utilitários compartilhados para requisições de API, construção de URLs e filtragem de parâmetros

Cliente

SmartThingsMCPClient.py: CLI para interagir com o servidor MCP
modules/client/: Implementação do cliente
- main.py: Classe principal SmartThingsMCPClient que combina todos os mixins
- base.py: BaseClient com tratamento de transporte e invocação de ferramentas
- cache.py: CacheMixin com cache LRU, gerenciamento de TTL e estatísticas de cache
- devices.py: DevicesMixin com métodos de operação de dispositivos
- locations.py: LocationsMixin com métodos de locais e cômodos
- rooms.py: RoomsMixin com métodos específicos de cômodos
- modes.py: ModesMixin com métodos de gerenciamento de modos
- rules.py: RulesMixin com métodos de gerenciamento de regras
- scenes.py: ScenesMixin com métodos de gerenciamento de cenas
- utils.py: Funções utilitárias para conversão de ferramentas e execução de ações
- utils_ext.py: Utilitários estendidos (nota: atualmente não utilizados)

Endpoints da API

O SmartThingsMCP expõe os seguintes endpoints da API como ferramentas MCP:

Gerenciamento de Dispositivos

list_devices: Obter uma lista de todos os dispositivos (suporta filtragem por capacidade, local, cômodo ou ID do dispositivo)
get_device: Obter detalhes de um dispositivo específico
update_device: Atualizar o rótulo de um dispositivo
delete_device: Excluir um dispositivo
execute_command: Executar um comando em um componente do dispositivo
get_device_status: Obter o status atual de um dispositivo
get_device_components: Obter todos os componentes de um dispositivo
get_device_capabilities: Obter capacidades de um componente do dispositivo
get_device_health: Obter o status de saúde/conectividade de um dispositivo
get_device_presentation: Obter os detalhes de apresentação da interface de um dispositivo

Gerenciamento de Locais

list_locations: Obter uma lista de todos os locais
get_location: Obter detalhes de um local específico
create_location: Criar um novo local com coordenadas e informações de endereço
update_location: Atualizar detalhes do local (nome, coordenadas, endereço)
delete_location: Excluir um local
get_location_rooms: Obter todos os cômodos em um local (método de conveniência)

Gerenciamento de Cômodos

list_rooms: Obter todos os cômodos em um local
get_room: Obter detalhes de um cômodo específico
create_room: Criar um novo cômodo em um local
update_room: Atualizar o nome de um cômodo
delete_room: Excluir um cômodo de um local

Gerenciamento de Modos

list_modes: Obter todos os modos disponíveis para um local
get_mode: Obter detalhes de um modo específico
get_current_mode: Obter o modo atualmente ativo para um local
set_mode: Alterar o modo atual para um local

Gerenciamento de Cenas

list_scenes: Obter todas as cenas (opcionalmente filtradas por local)
get_scene: Obter detalhes de uma cena específica
execute_scene: Executar/rodar uma cena
create_scene: Criar uma nova cena com ações e propriedades visuais
update_scene: Atualizar uma cena existente (nome, ícone, cores, ações)
delete_scene: Excluir uma cena

Gerenciamento de Regras

list_rules: Obter todas as regras de automação (opcionalmente filtradas por local)
get_rule: Obter detalhes de uma regra específica
create_rule: Criar uma nova regra de automação com condições e ações
update_rule: Atualizar uma regra existente (nome, gatilhos, ações, estado habilitado)
delete_rule: Excluir uma regra de automação
execute_rule: Acionar manualmente a execução de uma regra

Recursos

Cache Inteligente

Tanto o SmartThingsMCPClient quanto o SmartThingsMCPServer incluem cache abrangente para melhorar o desempenho:

Cache no Lado do Cliente

O SmartThingsMCPClient fornece:

Cache automático de operações somente leitura (list_devices, list_locations, etc.)
Expiração baseada em TTL (padrão: 5 minutos, configurável)
Invalidação inteligente de cache em operações de escrita (execute_command, update_device, etc.)
Despejo LRU quando o cache está cheio
Estatísticas de cache (acessos, erros, taxa de acertos)
Feedback visual verde: ✓ Cache hit: list_locations

Consulte CACHING.md para documentação detalhada.

Cache no Lado do Servidor

O SmartThingsMCPServer fornece:

Cache automático de todas as requisições GET para a API do SmartThings
Expiração baseada em TTL (padrão: 5 minutos)
Invalidação completa do cache em operações de escrita (POST, PUT, DELETE)
Despejo LRU quando o cache está cheio
Estatísticas de cache
Feedback visual verde: ✓ Server cache hit: GET devices

Consulte SERVER_CACHING.md para documentação detalhada.

Cache em Dois Níveis: Quando o cache do cliente e do servidor estão ativos, você obtém desempenho máximo com duas camadas de cache!

Benefícios de Desempenho:

Redução de 60-80% nas chamadas de API
Tempos de resposta 5-10x mais rápidos para dados em cache
Menor uso do limite de taxa

Gerenciamento de Regras

O servidor fornece capacidades abrangentes de gerenciamento de regras:

list_rules: Listar todas as regras de automação para um local
get_rule: Obter detalhes de uma regra específica
create_rule: Criar uma nova regra de automação com condições e ações
update_rule: Atualizar uma regra existente (nome, gatilhos, ações ou estado habilitado)
delete_rule: Excluir uma regra
execute_rule: Executar manualmente uma regra

Habilitar/Desabilitar Regras:

# 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)

O parâmetro enabled foi adicionado em dezembro de 2025 para suportar a alternância do estado da regra sem excluí-la.

Instalação

Pré-requisitos

Python 3.8 ou superior
pip ou outro gerenciador de pacotes Python

Configuração

Instale as dependências:

pip install -r requirements.txt

Pacotes necessários:

fastmcp>=2.0.0: Framework FastMCP 2.0 para servidor/cliente MCP
requests>=2.28.0: Biblioteca HTTP para chamadas à API do SmartThings

Obtenha um Token da API do SmartThings:
- Visite o Portal do Desenvolvedor SmartThings
- Crie um novo token de API com os seguintes escopos:
  - r:devices:* (ler dispositivos)
  - w:devices:* (controlar dispositivos)
  - r:locations:* (ler locais)
  - w:locations:* (criar/atualizar locais)
  - r:rules:* (ler regras, requer conta Enterprise)
  - w:rules:* (escrever regras, requer conta Enterprise)
  - r:scenes:* (ler cenas)
  - x:scenes:* (executar cenas)

Autenticação

O SmartThingsMCP usa tokens de portador OAuth 2.0 para autenticação com a API do SmartThings.

Requisitos do Token

Deve ser um token válido da API do SmartThings (token de portador OAuth 2.0)
O token deve ter os escopos apropriados para as operações que você deseja realizar
O token nunca expira quando obtido no Portal do Desenvolvedor SmartThings
Mantenha seu token seguro e nunca o envie para o controle de versão

Problemas Comuns de Autenticação

401 Não Autorizado:

Error calling tool list_devices: 401 Unauthorized

Verifique se o token é válido e não expirou
Confirme que o token foi gerado no Portal do Desenvolvedor SmartThings
Certifique-se de estar passando o token com a flag --auth

403 Proibido:

Error calling tool list_devices: 403 Forbidden

O token existe, mas não possui os escopos necessários
Alguns recursos (como Regras) exigem uma conta SmartThings Enterprise
Conceda escopos adicionais ao token no Portal do Desenvolvedor SmartThings

Escopos Necessários por Recurso

Recurso	Escopos Necessários
Listar/Obter Dispositivos	`r:devices:*`
Controlar Dispositivos	`w:devices:*`
Listar/Obter Locais	`r:locations:*`
Criar/Atualizar/Excluir Locais	`w:locations:*`
Listar/Obter Cenas	`r:scenes:*`
Executar Cenas	`x:scenes:*`
Criar/Atualizar/Excluir Cenas	`w:scenes:*`
Listar/Obter Regras	`r:rules:*`
Criar/Atualizar/Excluir Regras	`w:rules:*`
Listar/Obter/Definir Modos	`r:locations:*`

Primeiros Passos

Iniciando o Servidor

Inicie o 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

Usando o Cliente de Linha de Comando

O SmartThingsMCPClient.py fornece uma interface 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
}'

Opções do 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)

Usando o Cliente Python Programaticamente

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())

Solução de Problemas

Configuração de Transporte

O SmartThingsMCP suporta três mecanismos de transporte para comunicação cliente-servidor:

Transporte HTTP (Recomendado para a maioria dos casos de uso)

Porta padrão: 8000
Padrão de URL: http://localhost:8000/mcp
Melhor para: Integrações externas, ferramentas LLM, serviços web
Vantagens:
- Interface HTTP/REST simples
- Fácil de depurar com ferramentas padrão
- Compatível com a maioria dos firewalls
- Conexões sem estado

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

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

Transporte SSE (Server-Sent Events)

Porta padrão: 8000
Padrão de URL: http://localhost:8000/sse
Melhor para: Atualizações em tempo real, streaming de eventos, push do servidor
Vantagens:
- Comunicação bidirecional
- Arquitetura orientada a eventos
- Menor latência para atualizações

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

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

Transporte STDIO (Integração direta)

Sem sobrecarga de rede
Melhor para: Integração direta com Python, sistemas embarcados
Vantagens:
- Nenhuma configuração de porta/rede necessária
- Comunicação direta entre processos
- Menor latência

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

# Client
python SmartThingsMCPClient.py --transport stdio

Configuração do Cliente

Configuração de Cache

O SmartThingsMCPClient inclui cache inteligente com controle 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()

Operações com Cache (cache automático):

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

Operações que Invalidam o Cache (limpeza automática do cache):

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 de Logs

O SmartThingsMCP usa o módulo de logging padrão do 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(...)

Níveis de log:

DEBUG: Informações detalhadas de diagnóstico
INFO: Mensagens informativas gerais (padrão)
WARNING: Mensagens de aviso
ERROR: Mensagens de erro
CRITICAL: Erros críticos

Erros Comuns e Soluções

Erros de Conexão

Erro: Client failed to connect: Session terminated

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

Causas e soluções:

Servidor não está em execução: Inicie o servidor com python SmartThingsMCPServer.py
Tipo de transporte incorreto: Garanta que cliente e servidor usem o mesmo transporte (http, sse ou stdio)
Porta incorreta: Verifique se a porta corresponde entre cliente e servidor
Host incorreto: Verifique se o nome do host/endereço IP está correto
Rede/firewall: Garanta que a porta esteja aberta e acessível

Depuração:

# 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

Erros de Autenticação

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

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

Soluções:

Forneça o token de autenticação com a flag --auth YOUR_TOKEN
Garanta que o token seja válido: verifique no SmartThings Developer Portal
Verifique se o token não expirou
Verifique se o token possui os escopos necessários

Exemplo:

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

Erro: 401 Unauthorized

Error calling tool list_devices: 401 Unauthorized

Soluções:

Token inválido ou expirado
Formato do token incorreto (deve ser um token bearer OAuth 2.0)
Gere um novo token no SmartThings Developer Portal

Erro: 403 Forbidden

Error calling tool create_rule: 403 Forbidden - Access Denied

Soluções:

O token não possui os escopos necessários para a operação
A conta SmartThings não tem acesso ao recurso (ex.: Rules API requer Enterprise)
Conceda escopos adicionais no SmartThings Developer Portal

Erros de Resposta da API

Erro: Device not found

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

Soluções:

O ID do dispositivo não existe
O dispositivo foi excluído
Liste os dispositivos primeiro para obter IDs válidos: ação list_devices

Erro: Invalid component or capability

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

Soluções:

Verifique componentes válidos: Use get_device_components para listar componentes disponíveis
Verifique capacidades válidas: Use get_device_capabilities com o component_id correto
O dispositivo não suporta o comando que você está tentando executar

Limitação de Taxa

Erro: 429 Too Many Requests

Error calling tool list_devices: 429 Too Many Requests

Soluções:

Limite de taxa da API SmartThings excedido
Ative o cache para reduzir chamadas de API (ativado por padrão)
Aumente o TTL do cache para manter os dados por mais tempo
Implemente limitação de requisições no seu código

Verifique a eficácia do cache:

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 Cache

Problema: Dados desatualizados no cache

Soluções:

Reduza o TTL do cache: cache_ttl=60 (1 minuto)
Limpe o cache manualmente: client.clear_cache()
Desative o cache se os dados precisarem ser em tempo real: enable_cache=False

Problema: Cache causando alto uso de memória

Soluções:

Reduza o tamanho máximo do cache: max_cache_size=100
Reduza o TTL do cache para expirar entradas mais cedo
Limpe o cache periodicamente: client.clear_cache()

Uso Avançado

Implementação de Ferramentas Personalizadas

Você pode estender o SmartThingsMCP com ferramentas personalizadas modificando os módulos do 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))

Integração com LLMs

As ferramentas do SmartThingsMCP são projetadas para funcionar com Modelos de Linguagem:

# 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
]

Tratamento de Erros

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())

Otimização de Desempenho

Ative o cache (padrão: ativado):

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

Ajuste o TTL do cache para o seu 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 o transporte apropriado:
- HTTP: Melhor para a maioria dos cenários
- STDIO: Melhor latência para integração local
- SSE: Melhor para atualizações em tempo real

Operações em lote:

# 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 Resposta da API

Todas as respostas da API seguem uma estrutura consistente:

Resposta de sucesso:

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

Resposta de item único:

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

Resposta de erro:

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

Scripts de Exemplo

Monitorar Status do 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últiplos 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"))

Execução de Cenas

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"))

Variáveis de Ambiente

Você pode opcionalmente usar variáveis de ambiente para configurações comuns:

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

Referência da API

A referência completa da API está disponível através do sistema de ferramentas MCP. Liste todas as ferramentas disponíveis:

python SmartThingsMCPClient.py --action list_tools --pretty

Isso exibirá todas as ferramentas disponíveis com seus parâmetros e descrições.

Contribuindo

Ao estender o SmartThingsMCP:

Siga a estrutura de módulos existente
Adicione ferramentas ao módulo apropriado (devices.py, locations.py, etc.)
Inclua docstrings adequadas com descrições de parâmetros e retornos
Teste com o cliente
Atualize o README.md com a documentação da nova ferramenta

Licença

Consulte o arquivo LICENSE para informações sobre a licença.