refactor: improve Docker speech container audio configuration and user permissions

- Update Dockerfile to enhance audio setup and user management
- Modify setup-audio.sh to add robust PulseAudio socket and device checks
- Add proper user and directory permissions for audio and model directories
- Simplify container startup process and improve audio device detection

.gitignore

@@ -88,3 +88,5 @@ site/
 __pycache__/
 *.py[cod]
 *$py.class
+
+models/

README.md

@@ -58,17 +58,17 @@ Our architecture is engineered for performance, scalability, and security. The f
 ```mermaid
 graph TD
     subgraph Client
-       A[Client Application<br>(Web / Mobile / Voice)]
+        A["Client Application (Web/Mobile/Voice)"]
     end
     subgraph CDN
-       B[CDN / Cache]
+        B["CDN / Cache"]
     end
     subgraph Server
-       C[Bun Native Server]
-       E[NLP Engine &<br>Language Processing Module]
+        C["Bun Native Server"]
+        E["NLP Engine & Language Processing Module"]
     end
     subgraph Integration
-       D[Home Assistant<br>(Devices, Lights, Thermostats)]
+        D["Home Assistant (Devices, Lights, Thermostats)"]
     end
 
     A -->|HTTP Request| B

docker/speech/Dockerfile

@@ -33,36 +33,35 @@ RUN apt-get update && apt-get install -y \
     libasound2 \
     libasound2-plugins \
     pulseaudio \
-    && rm -rf /var/lib/apt/lists/*
+    pulseaudio-utils \
+    libpulse0 \
+    libportaudio2 \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p /var/run/pulse /var/lib/pulse
 
 # Create necessary directories
-RUN mkdir -p /models/wake_word /audio
+RUN mkdir -p /models/wake_word /audio && \
+    chown -R 1000:1000 /models /audio && \
+    mkdir -p /home/user/.config/pulse && \
+    chown -R 1000:1000 /home/user
 
 # Set working directory
 WORKDIR /app
 
-# Copy the wake word detection script
+# Copy the wake word detection script and audio setup script
 COPY wake_word_detector.py .
+COPY setup-audio.sh /setup-audio.sh
+RUN chmod +x /setup-audio.sh
 
 # Set environment variables
 ENV WHISPER_MODEL_PATH=/models \
     WAKEWORD_MODEL_PATH=/models/wake_word \
     PYTHONUNBUFFERED=1 \
-    ASR_MODEL=base.en \
-    ASR_MODEL_PATH=/models
+    PULSE_SERVER=unix:/run/user/1000/pulse/native \
+    HOME=/home/user
 
-# Add resource limits to Python
-ENV PYTHONMALLOC=malloc \
-    MALLOC_TRIM_THRESHOLD_=100000 \
-    PYTHONDEVMODE=1
+# Run as the host user
+USER 1000:1000
 
-# Add healthcheck
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD ps aux | grep '[p]ython' || exit 1
-
-# Copy audio setup script
-COPY setup-audio.sh /setup-audio.sh
-RUN chmod +x /setup-audio.sh
-
-# Start command
-CMD ["/bin/bash", "-c", "/setup-audio.sh && python -u wake_word_detector.py"] 
+# Start the application
+CMD ["/setup-audio.sh"] 

docker/speech/setup-audio.sh

@@ -1,7 +1,25 @@
 #!/bin/bash
 
-# Wait for PulseAudio to be ready
-sleep 2
+# Wait for PulseAudio socket to be available
+while [ ! -e /run/user/1000/pulse/native ]; do
+    echo "Waiting for PulseAudio socket..."
+    sleep 1
+done
+
+# Test PulseAudio connection
+pactl info || {
+    echo "Failed to connect to PulseAudio server"
+    exit 1
+}
+
+# List audio devices
+pactl list sources || {
+    echo "Failed to list audio devices"
+    exit 1
+}
+
+# Start the wake word detector
+python /app/wake_word_detector.py
 
 # Mute the monitor to prevent feedback
 pactl set-source-mute alsa_output.pci-0000_00_1b.0.analog-stereo.monitor 1

docs/getting-started.md

@@ -3,7 +3,7 @@
 Begin your journey with the Home Assistant MCP Server by following these steps:
 
 - **API Documentation:** Read the [API Documentation](api.md) for available endpoints.
-- **Real-Time Updates:** Learn about [Server-Sent Events](sse-api.md) for live communication.
+- **Real-Time Updates:** Learn about [Server-Sent Events](api/sse.md) for live communication.
 - **Tools:** Explore available [Tools](tools/tools.md) for device control and automation.
 - **Configuration:** Refer to the [Configuration Guide](getting-started/configuration.md) for setup and advanced settings.
 

docs/sse-api.md

@@ -1,364 +0,0 @@
-# Home Assistant MCP Server-Sent Events (SSE) API Documentation
-
-## Overview
-
-The SSE API provides real-time updates from Home Assistant through a persistent connection. This allows clients to receive instant notifications about state changes, events, and other activities without polling.
-
-## Quick Reference
-
-### Available Endpoints
-
-| Endpoint | Method | Description | Authentication |
-|----------|---------|-------------|----------------|
-| `/subscribe_events` | POST | Subscribe to real-time events and state changes | Required |
-| `/get_sse_stats` | POST | Get statistics about current SSE connections | Required |
-
-### Event Types Available
-
-| Event Type | Description | Example Subscription |
-|------------|-------------|---------------------|
-| `state_changed` | Entity state changes | `events=state_changed` |
-| `service_called` | Service call events | `events=service_called` |
-| `automation_triggered` | Automation trigger events | `events=automation_triggered` |
-| `script_executed` | Script execution events | `events=script_executed` |
-| `ping` | Connection keepalive (system) | Automatic |
-| `error` | Error notifications (system) | Automatic |
-
-### Subscription Options
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `entity_id` | Subscribe to specific entity | `entity_id=light.living_room` |
-| `domain` | Subscribe to entire domain | `domain=light` |
-| `events` | Subscribe to event types | `events=state_changed,automation_triggered` |
-
-## Authentication
-
-All SSE connections require authentication using your Home Assistant token.
-
-```javascript
-const token = 'YOUR_HASS_TOKEN';
-```
-
-## Endpoints
-
-### Subscribe to Events
-
-`POST /subscribe_events`
-
-Subscribe to Home Assistant events and state changes.
-
-#### Parameters
-
-| Parameter  | Type     | Required | Description |
-|------------|----------|----------|-------------|
-| token      | string   | Yes      | Your Home Assistant authentication token |
-| events     | string[] | No       | Array of event types to subscribe to |
-| entity_id  | string   | No       | Specific entity ID to monitor |
-| domain     | string   | No       | Domain to monitor (e.g., "light", "switch") |
-
-#### Example Request
-
-```javascript
-const eventSource = new EventSource(`http://localhost:3000/subscribe_events?token=${token}&entity_id=light.living_room&domain=switch&events=state_changed,automation_triggered`);
-
-eventSource.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  console.log('Received:', data);
-};
-
-eventSource.onerror = (error) => {
-  console.error('SSE Error:', error);
-  eventSource.close();
-};
-```
-
-### Get SSE Statistics
-
-`POST /get_sse_stats`
-
-Get current statistics about SSE connections and subscriptions.
-
-#### Parameters
-
-| Parameter | Type   | Required | Description |
-|-----------|--------|----------|-------------|
-| token     | string | Yes      | Your Home Assistant authentication token |
-
-#### Example Request
-
-```bash
-curl -X POST http://localhost:3000/get_sse_stats \
-  -H "Content-Type: application/json" \
-  -d '{"token": "YOUR_HASS_TOKEN"}'
-```
-
-## Event Types
-
-### Standard Events
-
-1. **connection**
-   - Sent when a client connects successfully
-   ```json
-   {
-     "type": "connection",
-     "status": "connected",
-     "id": "client_uuid",
-     "authenticated": true,
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-2. **state_changed**
-   - Sent when an entity's state changes
-   ```json
-   {
-     "type": "state_changed",
-     "data": {
-       "entity_id": "light.living_room",
-       "state": "on",
-       "attributes": {
-         "brightness": 255,
-         "color_temp": 370
-       },
-       "last_changed": "2024-02-10T12:00:00.000Z",
-       "last_updated": "2024-02-10T12:00:00.000Z"
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-3. **service_called**
-   - Sent when a Home Assistant service is called
-   ```json
-   {
-     "type": "service_called",
-     "data": {
-       "domain": "light",
-       "service": "turn_on",
-       "service_data": {
-         "entity_id": "light.living_room",
-         "brightness": 255
-       }
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-4. **automation_triggered**
-   - Sent when an automation is triggered
-   ```json
-   {
-     "type": "automation_triggered",
-     "data": {
-       "automation_id": "automation.morning_routine",
-       "trigger": {
-         "platform": "time",
-         "at": "07:00:00"
-       }
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-5. **script_executed**
-   - Sent when a script is executed
-   ```json
-   {
-     "type": "script_executed",
-     "data": {
-       "script_id": "script.welcome_home",
-       "execution_data": {
-         "status": "completed"
-       }
-     },
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-### System Events
-
-1. **ping**
-   - Sent every 30 seconds to keep the connection alive
-   ```json
-   {
-     "type": "ping",
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-2. **error**
-   - Sent when an error occurs
-   ```json
-   {
-     "type": "error",
-     "error": "rate_limit_exceeded",
-     "message": "Too many requests, please try again later",
-     "timestamp": "2024-02-10T12:00:00.000Z"
-   }
-   ```
-
-## Rate Limiting
-
-- Maximum 1000 requests per minute per client
-- Rate limits are reset every minute
-- Exceeding the rate limit will result in an error event
-
-## Connection Management
-
-- Maximum 100 concurrent clients
-- Connections timeout after 5 minutes of inactivity
-- Ping messages are sent every 30 seconds
-- Clients should handle reconnection on connection loss
-
-## Example Implementation
-
-```javascript
-class HomeAssistantSSE {
-  constructor(baseUrl, token) {
-    this.baseUrl = baseUrl;
-    this.token = token;
-    this.eventSource = null;
-    this.reconnectAttempts = 0;
-    this.maxReconnectAttempts = 5;
-    this.reconnectDelay = 1000;
-  }
-
-  connect(options = {}) {
-    const params = new URLSearchParams({
-      token: this.token,
-      ...(options.events && { events: options.events.join(',') }),
-      ...(options.entity_id && { entity_id: options.entity_id }),
-      ...(options.domain && { domain: options.domain })
-    });
-
-    this.eventSource = new EventSource(`${this.baseUrl}/subscribe_events?${params}`);
-
-    this.eventSource.onmessage = (event) => {
-      const data = JSON.parse(event.data);
-      this.handleEvent(data);
-    };
-
-    this.eventSource.onerror = (error) => {
-      console.error('SSE Error:', error);
-      this.handleError(error);
-    };
-  }
-
-  handleEvent(data) {
-    switch (data.type) {
-      case 'connection':
-        this.reconnectAttempts = 0;
-        console.log('Connected:', data);
-        break;
-      case 'ping':
-        // Connection is alive
-        break;
-      case 'error':
-        console.error('Server Error:', data);
-        break;
-      default:
-        // Handle other event types
-        console.log('Event:', data);
-    }
-  }
-
-  handleError(error) {
-    this.eventSource?.close();
-    
-    if (this.reconnectAttempts < this.maxReconnectAttempts) {
-      this.reconnectAttempts++;
-      const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
-      console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
-      setTimeout(() => this.connect(), delay);
-    } else {
-      console.error('Max reconnection attempts reached');
-    }
-  }
-
-  disconnect() {
-    this.eventSource?.close();
-    this.eventSource = null;
-  }
-}
-
-// Usage example
-const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
-client.connect({
-  events: ['state_changed', 'automation_triggered'],
-  domain: 'light'
-});
-```
-
-## Best Practices
-
-1. **Error Handling**
-   - Implement exponential backoff for reconnection attempts
-   - Handle connection timeouts gracefully
-   - Monitor for rate limit errors
-
-2. **Resource Management**
-   - Close EventSource when no longer needed
-   - Limit subscriptions to necessary events/entities
-   - Handle cleanup on page unload
-
-3. **Security**
-   - Never expose the authentication token in client-side code
-   - Use HTTPS in production
-   - Validate all incoming data
-
-4. **Performance**
-   - Subscribe only to needed events
-   - Implement client-side event filtering
-   - Monitor memory usage for long-running connections
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Connection Failures**
-   - Verify your authentication token is valid
-   - Check server URL is accessible
-   - Ensure proper network connectivity
-   - Verify SSL/TLS configuration if using HTTPS
-
-2. **Missing Events**
-   - Confirm subscription parameters are correct
-   - Check rate limiting status
-   - Verify entity/domain exists
-   - Monitor client-side event handlers
-
-3. **Performance Issues**
-   - Reduce number of subscriptions
-   - Implement client-side filtering
-   - Monitor memory usage
-   - Check network latency
-
-### Debugging Tips
-
-1. Enable console logging:
-```javascript
-const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
-client.debug = true; // Enables detailed logging
-```
-
-2. Monitor network traffic:
-```javascript
-// Add event listeners for connection states
-eventSource.addEventListener('open', () => {
-  console.log('Connection opened');
-});
-
-eventSource.addEventListener('error', (e) => {
-  console.log('Connection error:', e);
-});
-```
-
-3. Track subscription status:
-```javascript
-// Get current subscriptions
-const stats = await fetch('/get_sse_stats', {
-  headers: { 'Authorization': `Bearer ${token}` }
-}).then(r => r.json());
-
-console.log('Current subscriptions:', stats);
-``` 

docs/troubleshooting.md

@@ -313,3 +313,62 @@ tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
     config/ \
     data/
 ```
+
+## FAQ
+
+### General Questions
+
+#### Q: What is MCP Server?
+A: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.
+
+#### Q: What are the system requirements?
+A: MCP Server requires:
+- Node.js 16 or higher
+- Home Assistant instance
+- 1GB RAM minimum
+- 1GB disk space
+
+#### Q: How do I update MCP Server?
+A: For Docker installation:
+```bash
+docker compose pull
+docker compose up -d
+```
+For manual installation:
+```bash
+git pull
+bun install
+bun run build
+```
+
+### Integration Questions
+
+#### Q: Can I use MCP Server with any Home Assistant instance?
+A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.
+
+#### Q: Does MCP Server support all Home Assistant integrations?
+A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.
+
+### Security Questions
+
+#### Q: Is my Home Assistant token secure?
+A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.
+
+#### Q: Can I use MCP Server remotely?
+A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.
+
+### Troubleshooting Questions
+
+#### Q: Why are my device states not updating?
+A: Check:
+1. Home Assistant connection
+2. WebSocket connection status
+3. Device availability in Home Assistant
+4. Network connectivity
+
+#### Q: Why are my commands not working?
+A: Verify:
+1. Command syntax
+2. Device availability
+3. User permissions
+4. Home Assistant API access 

mkdocs.yml

@@ -91,7 +91,7 @@ nav:
   - API Reference:
     - Overview: api/index.md
     - Core API: api.md
-    - SSE API: sse-api.md
+    - SSE API: api/sse.md
     - Core Functions: api/core.md
   - Tools:
     - Overview: tools/tools.md
@@ -114,6 +114,9 @@ nav:
       - SSE Statistics: tools/events/sse-stats.md
   - Development:
     - Overview: development/development.md
+    - Best Practices: development/best-practices.md
+    - Interfaces: development/interfaces.md
+    - Tool Development: development/tools.md
     - Testing Guide: testing.md
   - Architecture: architecture.md
   - Contributing: contributing.md