Cache Examples
Overview
This document provides practical examples for configuring and using the Hass-MCP caching system.
Basic Configuration Examples
Example 1: Default Configuration (Memory Backend)
# No configuration needed - uses defaults
# Backend: memory
# TTL: 300 seconds (5 minutes)
# Max size: 1000 entries
Example 2: Redis Backend Configuration
# Install Redis package
pip install redis
# Start Redis server
docker run -d -p 6379:6379 redis:latest
# Configure Hass-MCP
export HASS_MCP_CACHE_BACKEND=redis
export HASS_MCP_CACHE_REDIS_URL=redis://localhost:6379/0
export HASS_MCP_CACHE_DEFAULT_TTL=300
export HASS_MCP_CACHE_MAX_SIZE=10000
Example 3: File Backend Configuration
# Install aiofiles package
pip install aiofiles
# Create cache directory
mkdir -p /var/cache/hass-mcp
chmod 755 /var/cache/hass-mcp
# Configure Hass-MCP
export HASS_MCP_CACHE_BACKEND=file
export HASS_MCP_CACHE_DIR=/var/cache/hass-mcp
export HASS_MCP_CACHE_DEFAULT_TTL=300
Example 4: Custom TTL Configuration
{
"enabled": true,
"backend": "memory",
"default_ttl": 300,
"endpoints": {
"entities": {
"get_state": {
"ttl": 60
},
"get_entities": {
"ttl": 1800
}
},
"automations": {
"ttl": 1800
},
"areas": {
"ttl": 3600
}
}
}
Configuration File Examples
Example 1: JSON Configuration File
Create ~/.hass-mcp/cache_config.json:
{
"enabled": true,
"backend": "memory",
"default_ttl": 300,
"max_size": 1000,
"endpoints": {
"entities": {
"get_state": {
"ttl": 60
},
"get_entities": {
"ttl": 1800
}
},
"automations": {
"ttl": 1800
},
"areas": {
"ttl": 3600
}
}
}
Example 2: YAML Configuration File
Create ~/.hass-mcp/cache_config.yaml:
enabled: true
backend: memory
default_ttl: 300
max_size: 1000
endpoints:
entities:
get_state:
ttl: 60
get_entities:
ttl: 1800
automations:
ttl: 1800
areas:
ttl: 3600
Example 3: Production Configuration (Redis)
Create ~/.hass-mcp/cache_config.json:
{
"enabled": true,
"backend": "redis",
"redis_url": "redis://redis.example.com:6379/0",
"default_ttl": 300,
"max_size": 10000,
"endpoints": {
"entities": {
"get_state": {
"ttl": 60
},
"get_entities": {
"ttl": 1800
}
},
"automations": {
"ttl": 1800
},
"areas": {
"ttl": 3600
}
}
}
Usage Examples
Example 1: Check Cache Status
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
print(f"Cache enabled: {stats['enabled']}")
print(f"Backend: {stats['backend']}")
print(f"Hit rate: {stats['statistics']['hit_rate']:.2%}")
Example 2: Clear Cache
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
await manager.clear()
print("Cache cleared")
Example 3: Invalidate Specific Cache
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
# Invalidate all entity caches
result = await manager.invalidate("entities:*")
print(f"Invalidated {result['total_invalidated']} entries")
Example 4: Get Cache Size
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
backend = await manager._get_backend()
if hasattr(backend, "async_size"):
size = await backend.async_size()
print(f"Cache size: {size} entries")
Docker Configuration Examples
Example 1: Docker with Memory Backend
version: '3.8'
services:
hass-mcp:
image: mmornati/hass-mcp:latest
environment:
- HA_URL=http://homeassistant.local:8123
- HA_TOKEN=${HA_TOKEN}
- HASS_MCP_CACHE_ENABLED=true
- HASS_MCP_CACHE_BACKEND=memory
- HASS_MCP_CACHE_MAX_SIZE=1000
Example 2: Docker with Redis Backend
version: '3.8'
services:
redis:
image: redis:latest
ports:
- "6379:6379"
hass-mcp:
image: mmornati/hass-mcp:latest
depends_on:
- redis
environment:
- HA_URL=http://homeassistant.local:8123
- HA_TOKEN=${HA_TOKEN}
- HASS_MCP_CACHE_ENABLED=true
- HASS_MCP_CACHE_BACKEND=redis
- HASS_MCP_CACHE_REDIS_URL=redis://redis:6379/0
- HASS_MCP_CACHE_MAX_SIZE=10000
Example 3: Docker with File Backend
version: '3.8'
services:
hass-mcp:
image: mmornati/hass-mcp:latest
volumes:
- ./cache:/app/.cache
environment:
- HA_URL=http://homeassistant.local:8123
- HA_TOKEN=${HA_TOKEN}
- HASS_MCP_CACHE_ENABLED=true
- HASS_MCP_CACHE_BACKEND=file
- HASS_MCP_CACHE_DIR=/app/.cache
Development Examples
Example 1: Disable Caching for Testing
Example 2: Use Memory Backend for Development
Example 3: Clear Cache Before Tests
import pytest
from app.core.cache.manager import get_cache_manager
@pytest.fixture(autouse=True)
async def clear_cache():
"""Clear cache before each test."""
manager = await get_cache_manager()
await manager.clear()
yield
await manager.clear()
Production Examples
Example 1: Production with Redis
# Environment variables
export HASS_MCP_CACHE_ENABLED=true
export HASS_MCP_CACHE_BACKEND=redis
export HASS_MCP_CACHE_REDIS_URL=redis://redis.example.com:6379/0
export HASS_MCP_CACHE_DEFAULT_TTL=300
export HASS_MCP_CACHE_MAX_SIZE=50000
Example 2: Production with File Backend
# Environment variables
export HASS_MCP_CACHE_ENABLED=true
export HASS_MCP_CACHE_BACKEND=file
export HASS_MCP_CACHE_DIR=/var/cache/hass-mcp
export HASS_MCP_CACHE_DEFAULT_TTL=300
Example 3: Production with Custom TTL
{
"enabled": true,
"backend": "redis",
"redis_url": "redis://redis.example.com:6379/0",
"default_ttl": 300,
"max_size": 50000,
"endpoints": {
"entities": {
"get_state": {
"ttl": 30
},
"get_entities": {
"ttl": 600
}
},
"automations": {
"ttl": 3600
}
}
}
Monitoring Examples
Example 1: Monitor Cache Performance
from app.api.system import get_cache_statistics
import time
while True:
stats = await get_cache_statistics()
print(f"Hit rate: {stats['statistics']['hit_rate']:.2%}")
print(f"Time saved: {stats['performance']['time_saved_ms']}ms")
time.sleep(60) # Check every minute
Example 2: Monitor Per-Endpoint Performance
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
for endpoint, endpoint_stats in stats['per_endpoint'].items():
hit_rate = endpoint_stats['hit_rate']
if hit_rate < 0.70:
print(f"Warning: {endpoint} has low hit rate: {hit_rate:.2%}")
Example 3: Alert on Low Hit Rate
from app.api.system import get_cache_statistics
stats = await get_cache_statistics()
hit_rate = stats['statistics']['hit_rate']
if hit_rate < 0.70:
print(f"Alert: Cache hit rate is low: {hit_rate:.2%}")
# Send alert notification
Troubleshooting Examples
Example 1: Debug Cache Issues
import logging
from app.core.cache.manager import get_cache_manager
# Enable debug logging
logging.getLogger("app.core.cache").setLevel(logging.DEBUG)
# Check cache status
manager = await get_cache_manager()
backend = await manager._get_backend()
print(f"Backend: {backend.__class__.__name__}")
# Check cache keys
keys = await manager.keys("entities:*")
print(f"Entity cache keys: {keys[:10]}") # First 10 keys
Example 2: Test Cache Operations
from app.core.cache.manager import get_cache_manager
manager = await get_cache_manager()
# Test set
await manager.set("test_key", "test_value", ttl=60)
print("Set test_key")
# Test get
value = await manager.get("test_key")
print(f"Got value: {value}")
# Test delete
await manager.delete("test_key")
print("Deleted test_key")
# Verify deleted
value = await manager.get("test_key")
print(f"Value after delete: {value}") # Should be None