Skip to content

# Quick Start Guide 🚀

This guide will help you get started with MCP Server after installation. We'll cover basic usage, common commands, and simple integrations.

## First Steps

### 1. Verify Connection

After installation, verify your MCP Server is running and connected to Home Assistant:

    # Check server health
    curl http://localhost:3000/health

    # Verify Home Assistant connection
    curl http://localhost:3000/api/state

### 2. Basic Voice Commands

Try these basic voice commands to test your setup:

    # Example using curl for testing
    curl -X POST http://localhost:3000/api/command \
      -H "Content-Type: application/json" \
      -d '{"command": "Turn on the living room lights"}'

Common voice commands: - "Turn on/off [device name]" - "Set [device] to [value]" - "What's the temperature in [room]?" - "Is [device] on or off?"

## Real-World Examples

### 1. Smart Lighting Control

    // Browser example using fetch
    const response = await fetch('http://localhost:3000/api/command', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        command: 'Set living room lights to 50% brightness and warm white color'
      })
    });

### 2. Real-Time Updates

Subscribe to device state changes using Server-Sent Events (SSE):

    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('Device state changed:', data);
        // Update your UI here
    };

### 3. Scene Automation

Create and trigger scenes for different activities:

    // Create a "Movie Night" scene
    const createScene = async () => {
      await fetch('http://localhost:3000/api/scene', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          name: 'Movie Night',
          actions: [
            { device: 'living_room_lights', action: 'dim', value: 20 },
            { device: 'tv', action: 'on' },
            { device: 'soundbar', action: 'on' }
          ]
        })
      });
    };

    // Trigger the scene with voice command:
    // "Hey MCP, activate movie night scene"

## Integration Examples

### 1. Web Dashboard Integration

    // React component example
    function SmartHomeControl() {
        const [devices, setDevices] = useState([]);

        useEffect(() => {
            // Subscribe to device updates
            const events = new EventSource('http://localhost:3000/subscribe_events');
            events.onmessage = (event) => {
                const data = JSON.parse(event.data);
                setDevices(currentDevices =>
                    currentDevices.map(device =>
                        device.id === data.id ? {...device, ...data} : device
                    )
                );
            };

            return () => events.close();
        }, []);

        return (
            <div className="dashboard">
                {devices.map(device => (
                    <DeviceCard key={device.id} device={device} />
                ))}
            </div>
        );
    }

### 2. Voice Assistant Integration

    // Example using speech-to-text with MCP
    async function handleVoiceCommand(audioBlob: Blob) {
        // First, convert speech to text
        const text = await speechToText(audioBlob);

        // Then send command to MCP
        const response = await fetch('http://localhost:3000/api/command', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({ command: text })
        });

        return response.json();
    }

## Best Practices

1. Error Handling

       try {
           const response = await fetch('http://localhost:3000/api/command', {
               method: 'POST',
               headers: {
                   'Content-Type': 'application/json',
               },
               body: JSON.stringify({ command: 'Turn on lights' })
           });

           if (!response.ok) {
               throw new Error(`HTTP error! status: ${response.status}`);
           }

           const data = await response.json();
       } catch (error) {
           console.error('Error:', error);
           // Handle error appropriately
       }

2. Connection Management

       class MCPConnection {
           constructor() {
               this.eventSource = null;
               this.reconnectAttempts = 0;
           }

           connect() {
               this.eventSource = new EventSource('http://localhost:3000/subscribe_events');
               this.eventSource.onerror = this.handleError.bind(this);
           }

           handleError() {
               if (this.reconnectAttempts < 3) {
                   setTimeout(() => {
                       this.reconnectAttempts++;
                       this.connect();
                   }, 1000 * this.reconnectAttempts);
               }
           }
       }

## Next Steps

- Explore the API Documentation for advanced features
- Learn about SSE API for real-time updates
- Check out Architecture for system design details
- Read the Contributing Guide to get involved

## Troubleshooting

If you encounter issues: - Verify your authentication token - Check server logs for errors - Ensure Home Assistant is accessible - Review the Troubleshooting Guide

Need more help? Visit our Support Resources.

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings