Home Assistant için Model Context Protocol Sunucusu

Sunucu, yerel bir Home Assistant örneğine erişimi bir LLM uygulaması ile paylaşmak için MCP protokolünü kullanır.

Home Assistant örneğiniz ve Dil Öğrenme Modelleri (LLM'ler) arasında güçlü bir köprü, Model Context Protocol (MCP) aracılığıyla akıllı ev cihazlarınızı doğal dil ile kontrol etme ve izleme olanağı sunar. Bu sunucu, cihaz kontrolünden sistem yönetimine kadar tüm Home Assistant ekosistemini yönetmek için kapsamlı bir API sağlar.

Özellikler

• 🎮 Cihaz Kontrolü: Herhangi bir Home Assistant cihazını doğal dil ile kontrol edin
• 🔄 Gerçek Zamanlı Güncellemeler: Server-Sent Events (SSE) ile anında güncellemeler alın
• 🤖 Otomasyon Yönetimi: Otomasyonları oluşturun, güncelleyin ve yönetin
• 📊 Durum İzleme: Cihaz durumlarını takip edin ve sorgulayın
• 🔐 Güvenli: Token tabanlı kimlik doğrulama ve hız sınırlaması
• 📱 Mobil Uyumlu: HTTP destekleyen herhangi bir istemci ile çalışır

SSE ile Gerçek Zamanlı Güncellemeler

Sunucu, Home Assistant örneğinizden gerçek zamanlı güncellemeler sağlayan güçlü bir Server-Sent Events (SSE) sistemi içerir. Bu sayede şunları yapabilirsiniz:

• 🔄 Herhangi bir cihazın durum değişikliklerini anında alın
• 📡 Otomasyon tetikleyicilerini ve yürütmelerini izleyin
• 🎯 Belirli alan adlarına veya varlıklara abone olun
• 📊 Servis çağrılarını ve betik yürütmelerini takip edin

Hızlı SSE Örneği

const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};

SSE sistemi hakkında tam belgeler için SSE_API.md dosyasını inceleyin.

İçindekiler

• Ana Özellikler
• Ön Koşullar
• Kurulum
  • Temel Kurulum
  • Docker Kurulumu (Önerilir)
• Yapılandırma
• Geliştirme
• API Referansı
  • Cihaz Kontrolü
  • Eklenti Yönetimi
  • Paket Yönetimi
  • Otomasyon Yönetimi
• Doğal Dil Entegrasyonu
• Sorun Giderme
• Proje Durumu
• Katkıda Bulunma
• Kaynaklar
• Lisans

Ana Özellikler

Temel İşlevsellik 🎮

• Akıllı Cihaz Kontrolü
  • 💡 Işıklar: Parlaklık, renk sıcaklığı, RGB renk
  • 🌡️ İklim: Sıcaklık, HVAC modları, fan modları, nem
  • 🚪 Perdeler: Konumu ve eğim kontrolü
  • 🔌 Anahtarlar: Açma/kapama kontrolü
  • 🚨 Sensörler & Kontaklar: Durum izleme
  • 🎵 Medya Oynatıcılar: Oynatma kontrolü, ses, kaynak seçimi
  • 🌪️ Fanlar: Hız, salınım, yön
  • 🔒 Kilitler: Kilit açma/kilitleme kontrolü
  • 🧹 Elektrikli Süpürgeler: Başlatma, durdurma, temele dönüş
  • 📹 Kameralar: Hareket algılama, anlık görüntüler

Sistem Yönetimi 🛠️

• Eklenti Yönetimi

  • Mevcut eklentileri listeleyin
  • Eklentileri yükleyin/kaldırın
  • Eklentileri başlatın/durdurun/yeniden başlatın
  • Sürüm yönetimi
  • Yapılandırma erişimi

• Paket Yönetimi (HACS)

  • Home Assistant Community Store entegrasyonu
  • Birden fazla paket türü desteği:
    • Özel entegrasyonlar
    • Ön uç temalar
    • Python betikleri
    • AppDaemon uygulamaları
    • NetDaemon uygulamaları
  • Sürüm kontrolü ve güncellemeler
  • Depo yönetimi

• Otomasyon Yönetimi

  • Otomasyonları oluşturun ve düzenleyin
  • Gelişmiş yapılandırma seçenekleri:
    • Birden fazla tetikleyici türü
    • Karmaşık koşullar
    • İşlem dizileri
    • Yürütme modları
  • Mevcut otomasyonları çoğaltın ve değiştirin
  • Otomasyon kurallarını etkinleştirin/devre dışı bırakın
  • Otomasyonu manuel olarak tetikleyin

Mimari Özellikler 🏗️

• Akıllı Organizasyon

  • Alan ve kat tabanlı cihaz gruplandırması
  • Durum izleme ve sorgulaması
  • Akıllı bağlam farkındalığı
  • Geçmiş veri erişimi

• Sağlam Mimari

  • Kapsamlı hata işleme
  • Durum doğrulaması
  • Güvenli API entegrasyonu
  • TypeScript tür güvenliği
  • Geniş test kapsamı

Ön Koşullar

• Node.js 20.10.0 veya üstü
• NPM paket yöneticisi
• Docker Compose konteynerizasyon için
• Çalışan Home Assistant örneği
• Home Assistant uzun süreli erişim token'ı (Token nasıl alınır)
• Paket yönetimi özellikleri için HACS yüklü
• Eklenti yönetimi için Supervisor erişimi

Kurulum

Temel Kurulum

# Deposu klonlayın
git clone https://github.com/tevonsb/homeassistant-mcp.git
cd homeassistant-mcp

# Bağımlılıkları yükleyin
npm install

# Projeyi derleyin
npm run build

Docker Kurulumu (Önerilir)

Proje, kolay dağıtım ve farklı platformlar arasında tutarlı ortamlar için Docker desteği içerir.

1. Deposu klonlayın:

   git clone https://github.com/tevonsb/homeassistant-mcp.git
   cd homeassistant-mcp
   

2. Ortamı yapılandırın:

   cp .env.example .env
   

   .env dosyasını Home Assistant yapılandırmanız ile düzenleyin:

   # Home Assistant Yapılandırması
   HASS_HOST=http://homeassistant.local:8123
   HASS_TOKEN=your_home_assistant_token
   HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
   
   # Sunucu Yapılandırması
   PORT=3000
   NODE_ENV=production
   DEBUG=false
   

3. Docker Compose ile derleyin ve çalıştırın:

   # Konteyner'ları derleyin ve başlatın
   docker compose up -d
   
   # Günlükleri görüntüleyin
   docker compose logs -f
   
   # Servisi durdurun
   docker compose down
   

4. Kurulumu doğrulayın: Sunucu şimdi http://localhost:3000 adresinde çalışıyor olmalıdır. Health endpoint'i http://localhost:3000/health adresinde kontrol edebilirsiniz.

5. Uygulamayı güncelleyin:

   # En son değişiklikleri çekin
   git pull
   
   # Konteyner'ları yeniden derleyin ve başlatın
   docker compose up -d --build
   

Docker Yapılandırması

Docker kurulumu aşağıdakileri içerir:

• Optimal görüntü boyutu için çok aşamalı derleme
• Konteyner izleme için sağlık kontrolleri
• Ortam yapılandırması için birim bağlama
• Başarısızlıkta otomatik konteyner yeniden başlatma
• API erişimi için açılan port 3000

Docker Compose Ortam Değişkenleri

Tüm ortam değişkenleri .env dosyasında yapılandırılabilir. Aşağıdaki değişkenler desteklenir:

• HASS_HOST: Home Assistant örneğinizin URL'si
• HASS_TOKEN: Home Assistant için uzun süreli erişim token'ı
• HASS_SOCKET_URL: Home Assistant WebSocket URL'si
• PORT: Sunucu port'u (varsayılan: 3000)
• NODE_ENV: Ortam (production/development)
• DEBUG: Debug modunu etkinleştir (true/false)

Yapılandırma

Ortam Değişkenleri

# Home Assistant Yapılandırması
HASS_HOST=http://homeassistant.local:8123  # Home Assistant örneğinizin URL'si
HASS_TOKEN=your_home_assistant_token       # Uzun süreli erişim token'ı
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket  # WebSocket URL'si

# Sunucu Yapılandırması
PORT=3000                # Sunucu port'u (varsayılan: 3000)
NODE_ENV=production     # Ortam (production/development)
DEBUG=false            # Debug modunu etkinleştir

# Test Yapılandırması
TEST_HASS_HOST=http://localhost:8123  # Test örneği URL'si
TEST_HASS_TOKEN=test_token           # Test token'ı

Yapılandırma Dosyaları

1. Geliştirme: .env.example dosyasını .env.development olarak kopyalayın
2. Üretim: .env.example dosyasını .env.production olarak kopyalayın
3. Test: .env.example dosyasını .env.test olarak kopyalayın

Claude Desktop'a (veya diğer istemcilere) Ekleme

Yeni Home Assistant MCP sunucusunu kullanmak için Claude Desktop'ı istemci olarak ekleyebilirsiniz. Aşağıdaki yapılandırmayı ekleyin. Bunun MCP'yi claude içinde çalıştıracağını ve Docker yöntemi ile çalışmayacağını unutmayın.

{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}

API Referansı

Cihaz Kontrolü

Ortak Entity Kontrolleri

{
  "tool": "control",
  "command": "turn_on",  // veya "turn_off", "toggle"
  "entity_id": "light.living_room"
}

Işık Kontrolü

{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}

Eklenti Yönetimi

Mevcut Eklentileri Listeleyin

{
  "tool": "addon",
  "action": "list"
}

Eklenti Yükleyin

{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}

Eklenti Durumunu Yönetin

{
  "tool": "addon",
  "action": "start",  // veya "stop", "restart"
  "slug": "core_configurator"
}

Paket Yönetimi

HACS Paketlerini Listeleyin

{
  "tool": "package",
  "action": "list",
  "category": "integration"  // veya "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}

Paket Yükleyin

{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}

Otomasyon Yönetimi

Otomasyon Oluşturun

{
  "tool": "automation_config",
  "action": "create",
  "config": {
    "alias": "Motion Light",
    "description": "Turn on light when motion detected",
    "mode": "single",
    "trigger": [
      {
        "platform": "state",
        "entity_id": "binary_sensor.motion",
        "to": "on"
      }
    ],
    "action": [
      {
        "service": "light.turn_on",
        "target": {
          "entity_id": "light.living_room"
        }
      }
    ]
  }
}

Otomasyonu Çoğaltın

{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}

Temel İşlevler

Durum Yönetimi

GET /api/state
POST /api/state

Sistemin mevcut durumunu yönetir.

Örnek İstek:

POST /api/state
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}

Bağlam Güncellemeleri

POST /api/context

Mevcut bağlamı yeni bilgiler ile günceller.

Örnek İstek:

POST /api/context
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}

İşlem Endpoint'leri

İşlemi Yürütün

POST /api/action

Belirtilen işlemi verilen parametreler ile yürütür.

Örnek İstek:

POST /api/action
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}

Toplu İşlemler

POST /api/actions/batch

Birden fazla işlemi sırayla yürütür.

Örnek İstek:

POST /api/actions/batch
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}

Sorgulama İşlevleri

Kullanılabilir İşlemleri Alın

GET /api/actions

Tüm kullanılabilir işlemlerin listesini döndürür.

Örnek Yanıt:

{
  "actions": [
    {
      "name": "turn_on_lights",
      "parameters": ["room", "brightness"],
      "description": "Turns on lights in specified room"
    },
    {
      "name": "set_temperature",
      "parameters": ["temperature"],
      "description": "Sets temperature in current context"
    }
  ]
}

Bağlam Sorgusu

GET /api/context?type=current

Bağlam bilgilerini alır.

Örnek Yanıt:

{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}

WebSocket Olayları

Sunucu, WebSocket bağlantıları aracılığıyla gerçek zamanlı güncellemeleri destekler.

// İstemci tarafı bağlantı örneği
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};

Desteklenen Olaylar

• state_change: Sistem durumu değiştiğinde yayınlanır
• context_update: Bağlam güncellendiğinde yayınlanır
• action_executed: İşlem tamamlandığında yayınlanır
• error: Bir hata oluştuğunda yayınlanır

Örnek Olay Verileri:

{
  "event": "state_change",
  "data": {
    "previous_state": {
      "lights": "off"
    },
    "current_state": {
      "lights": "on"
    },
    "timestamp": "2024-03-20T10:30:00Z"
  }
}

Hata İşleme

Tüm endpoint'ler standart HTTP durum kodlarını döndürür:

• 200: Başarılı
• 400: Kötü İstek
• 401: Yetkisiz
• 403: Yasak
• 404: Bulunamadı
• 500: İç Sunucu Hatası

Hata Yanıtı Biçimi:

{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}

Hız Sınırlaması

API, kötüye kullanımı önlemek için hız sınırlaması uygular:

• Normal endpoint'ler için IP başına dakika başına 100 istek
• WebSocket bağlantıları için IP başına dakika başına 1000 istek

Hız sınırı aşıldığında, sunucu şunu döndürür:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}

Örnek Kullanım

curl Kullanma

# Mevcut durumu alın
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'

# İşlemi yürütün
curl -X POST \
  http://localhost:3000/api/action \
  -H 'Authorization: ApiKey your_api_key_here' \
  -H 'Content-Type: application/json' \
  -d '{
    "action": "turn_on_lights",
    "parameters": {
      "room": "living_room",
      "brightness": 80
    }
  }'

JavaScript Kullanma

// İşlemi yürütün
async function executeAction() {
  const response = await fetch('http://localhost:3000/api/action', {
    method: 'POST',
    headers: {
      'Authorization': 'ApiKey your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      action: 'turn_on_lights',
      parameters: {
        room: 'living_room',
        brightness: 80
      }
    })
  });
  
  const data = await response.json();
  console.log('Action result:', data);
}

Geliştirme

# Sıcak yükleme ile geliştirme modu
npm run dev

# Projeyi derleyin
npm run build

# Üretim modu
npm run start

# Testleri çalıştırın
npx jest --config=jest.config.cjs

# Kapsama ile testleri çalıştırın
npx jest --coverage

# Kodu lint'leyin
npm run lint

# Kodu biçimlendir
npm run format

Sorun Giderme

Sık Karşılaşılan Sorunlar

1. Node.js Sürümü (toSorted is not a function)

   • Çözüm: Node.js 20.10.0+ sürümüne güncelleyin

   nvm install 20.10.0
   nvm use 20.10.0
   

2. Bağlantı Sorunları

   • Home Assistant'ın çalışıp çalışmadığını doğrulayın
   • HASS_HOST erişimini kontrol edin
   • Token izinlerini doğrulayın
   • Gerçek zamanlı güncellemeler için WebSocket bağlantısını sağlayın

3. Eklenti Yönetimi Sorunları

   • Supervisor erişimini doğrulayın
   • Eklenti uyumluluğunu kontrol edin
   • Sistem kaynaklarını doğrulayın

4. HACS Entegrasyon Sorunları

   • HACS yüklemesini doğrulayın
   • HACS entegrasyon durumunu kontrol edin
   • Depo erişimini doğrulayın

5. Otomasyon Sorunları

   • Varlık kullanılabilirliğini doğrulayın
   • Tetikleyici koşullarını kontrol edin
   • Servis çağrılarını doğrulayın
   • Yürütme günlüklerini izleyin

Proje Durumu

✅ Tamamlandı

• Entity, Floor ve Area erişimi
• Cihaz kontrolü (Işıklar, İklim, Perdeler, Anahtarlar, Kontaklar)
• Eklenti yönetim sistemi
• HACS aracılığıyla paket yönetimi
• Gelişmiş otomasyon yapılandırması
• Temel durum yönetimi
• Hata işleme ve doğrulama
• Docker konteynerizasyonu
• Jest test kurulumu
• TypeScript entegrasyonu
• Ortam değişkeni yönetimi
• Home Assistant API entegrasyonu
• Proje belgelendirmesi

🚧 Devam Ediyor

• Gerçek zamanlı güncellemeler için WebSocket uygulaması
• Gelişmiş güvenlik özellikleri
• Tool organizasyon optimizasyonu
• Performans optimizasyonu
• Kaynak bağlamı entegrasyonu
• API belgelendirme oluşturma
• Çok platformlu masaüstü entegrasyonu
• Gelişmiş hata kurtarma
• Özel prompt testi
• Gelişmiş macOS entegrasyonu
• Tür güvenliği iyileştirmeleri
• Test kapsamı genişletilmesi

Katkıda Bulunma

1. Depoyu fork edin
2. Bir feature branch oluşturun
3. Değişikliklerinizi gerçekleştirin
4. Yeni işlevler için testler ekleyin
5. Tüm testlerin geçtiğinden emin olun
6. Bir pull request gönderin

Kaynaklar

• MCP Belgeleri
• Home Assistant Dokümanları
• HA REST API
• HACS Belgeleri
• TypeScript Belgeleri

Lisans

MIT Lisansı - Ayrıntılar için LICENSE dosyasını inceleyin