# SmartThingsMCP Server Caching
The SmartThingsMCP Server includes server-side caching to reduce SmartThings API calls and improve performance.
## Features
- **Automatic caching** of GET requests to SmartThings API
- **TTL-based expiration** (default: 5 minutes)
- **LRU eviction** when cache is full (default: 1000 entries)
- **Automatic cache invalidation** on write operations (POST, PUT, DELETE, PATCH)
- **Cache statistics** tracking (hits, misses, hit rate)
- **Green visual feedback** in console for cache hits
## How It Works
### Cached Requests
All GET requests to the SmartThings API are automatically cached:
- `GET /devices` - List devices
- `GET /devices/{deviceId}` - Get device details
- `GET /devices/{deviceId}/status` - Get device status
- `GET /locations` - List locations
- `GET /locations/{locationId}` - Get location details
- `GET /locations/{locationId}/rooms` - List rooms
- And all other GET endpoints
### Not Cached
- Write operations (POST, PUT, DELETE, PATCH)
- Non-GET requests
### Cache Invalidation
**All cache is cleared** when a write operation occurs:
- `POST` - Create operations
- `PUT` - Update operations
- `DELETE` - Delete operations
- `PATCH` - Patch operations
This ensures data consistency after any changes.
## Visual Feedback
Cache hits are displayed in **green** in the server console:
```
✓ Server cache hit: GET devices
✓ Server cache hit: GET locations
```
This provides immediate visual confirmation that data is being served from cache.
## Example
### First Request (Cache Miss)
```
INFO: Making GET request to: https://api.smartthings.com/v1/devices
INFO: Sending request to SmartThings API...
INFO: Response status code: 200
INFO: Successfully processed API response
INFO: Cached response for GET https://api.smartthings.com/v1/devices
```
### Second Request (Cache Hit)
```
✓ Server cache hit: GET devices <-- IN GREEN!
INFO: Cache hit for GET https://api.smartthings.com/v1/devices
```
## Configuration
The cache is configured in `modules/server/common.py`:
```python
# Default settings
_cache_ttl = 300 # 5 minutes
_cache_max_size = 1000 # Max 1000 entries
_cache_enabled = True # Enabled by default
```
To customize, modify these values in `common.py`:
```python
# Example: 10 minute TTL, 5000 entry cache
_cache_ttl = 600
_cache_max_size = 5000
```
## Cache Statistics
The server tracks cache statistics accessible via the `get_cache_stats()` function:
```python
from modules.server.common import get_cache_stats
stats = get_cache_stats()
# Returns:
# {
# 'enabled': True,
# 'size': 45,
# 'max_size': 1000,
# 'ttl_seconds': 300,
# 'hits': 234,
# 'misses': 45,
# 'total_requests': 279,
# 'hit_rate_percent': 83.87
# }
```
## Performance Impact
### Expected Improvements
With typical usage patterns, server-side caching provides:
- **60-80% reduction** in SmartThings API calls
- **5-10x faster** response times for cached data
- **Lower rate limit usage** on SmartThings API
- **Better response times** for MCP clients
### Example Session
```
Client: list_devices
├─ First call: SmartThings API (0.234s)
└─ Cached for 5 minutes
Client: list_devices (again)
├─ Cache hit: Server cache (0.021s) [11x faster!]
└─ Green output shown
Client: list_devices (third time)
├─ Cache hit: Server cache (0.019s) [12x faster!]
└─ Green output shown
Client: execute_command on device
├─ Write operation: Cache cleared
└─ Next list_devices will hit API again
```
## Benefits
### For MCP Clients
MCP clients (like SmartThingsAssistant) automatically benefit from server-side caching:
1. **Faster responses** - cached data returns instantly
2. **Lower latency** - no network round-trip to SmartThings API
3. **Better reliability** - less dependent on SmartThings API availability
4. **Rate limit protection** - fewer API calls = less risk of hitting limits
### Combined with Client-Side Caching
When both server-side and client-side caching are active:
- **Level 1**: Client cache (SmartThingsMCPClient)
- **Level 2**: Server cache (SmartThingsMCPServer)
This provides **two layers of caching** for maximum performance!
## Monitoring
### Console Output
Watch for green cache hit messages:
```
✓ Server cache hit: GET devices
✓ Server cache hit: GET locations
✓ Server cache hit: GET devices/abc123/status
```
### Log Messages
Check server logs for cache activity:
```
INFO: Cache hit for GET https://api.smartthings.com/v1/devices
INFO: Cached response for GET https://api.smartthings.com/v1/locations
INFO: Cache cleared due to POST operation
```
## Best Practices
### 1. Let Cache Work Automatically
The cache is designed to work transparently:
- No code changes needed
- No configuration required
- Automatic invalidation on writes
### 2. Monitor Cache Performance
Check hit rates to verify caching is effective:
- **Good**: >60% hit rate
- **Excellent**: >80% hit rate
### 3. Adjust TTL Based on Usage
- **Stable environments**: Increase TTL (10-30 min)
- **Dynamic environments**: Keep default (5 min)
- **Development/testing**: Lower TTL (1-2 min)
### 4. Understand Cache Clearing
Write operations clear **all cache**:
- This ensures data consistency
- Next GET request will refresh cache
- Consider batching write operations
## Troubleshooting
### Cache Not Working
Check if:
1. `_cache_enabled` is `True` in `common.py`
2. Requests are GET methods
3. TTL hasn't expired
### Low Hit Rate
Possible causes:
- TTL too short
- Too many write operations
- Cache size too small
- Request parameters vary
### Stale Data
If you need absolutely fresh data:
1. Perform a write operation (clears cache)
2. Or restart the server
3. Or modify `_cache_ttl` to lower value
## Technical Details
### Implementation
- **Module**: `modules/server/common.py`
- **Storage**: `OrderedDict` (LRU eviction)
- **Cache Key**: MD5 hash of (method, url, params)
- **TTL Check**: On every cache access
- **Thread-safe**: No (async single-threaded)
### Cache Key Generation
```python
cache_data = {
'method': 'GET',
'url': 'https://api.smartthings.com/v1/devices',
'params': {'capability': 'switch'}
}
cache_key = f"GET:{md5_hash(json.dumps(cache_data))}"
# Example: "GET:a3f2b1c8e4d5"
```
### LRU Eviction
When cache reaches `_cache_max_size`:
1. Oldest (least recently used) entry is removed
2. New entry is added
3. Maintains max size limit
### Visual Output
ANSI color codes for green text:
- Green: `\033[92m`
- Reset: `\033[0m`
Format: `\033[92m✓ Server cache hit: {method} {endpoint}\033[0m`
## Comparison: Client vs Server Caching
| Aspect | Client Cache | Server Cache |
|--------|-------------|--------------|
| **Location** | SmartThingsMCPClient | SmartThingsMCPServer |
| **Scope** | Single client | All clients |
| **Benefits** | Client-specific | Shared across clients |
| **Invalidation** | Smart per-operation | Full on any write |
| **TTL** | 5 min (configurable) | 5 min (configurable) |
| **Green Output** | `✓ Cache hit: list_locations` | `✓ Server cache hit: GET devices` |
**Best Performance**: Enable both for two-level caching!
## Summary
- ✅ **Server-side caching implemented** in `common.py`
- ✅ **Automatic for all GET requests**
- ✅ **Green visual feedback** for cache hits
- ✅ **60-80% reduction** in API calls expected
- ✅ **5-10x faster** responses for cached data
- ✅ **Zero client changes** needed
- ✅ **Works alongside** client-side caching
**SmartThingsMCP Server now has intelligent caching with visual feedback!** 🚀
