docs: enhance documentation with comprehensive API, architecture, and installation guides
- Add detailed API documentation for core functions, SSE, and WebSocket APIs - Create comprehensive architecture overview with system design diagrams - Develop in-depth installation and quick start guides - Improve troubleshooting documentation with advanced debugging techniques - Update site navigation and markdown configuration
This commit is contained in:
jango-blockchained
@@ -1,124 +1,171 @@
|
||||
# Installation Guide
|
||||
---
|
||||
layout: default
|
||||
title: Installation
|
||||
parent: Getting Started
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Installation Guide 🛠️
|
||||
|
||||
This guide covers different methods to install and set up the MCP Server for Home Assistant. Choose the installation method that best suits your needs.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
- **Operating System:** Linux, macOS, or Windows (Docker recommended)
|
||||
- **Runtime:** Bun v1.0.26 or higher
|
||||
- **Home Assistant:** v2023.11 or higher
|
||||
- **Minimum Hardware:**
|
||||
- 2 CPU cores
|
||||
- 2GB RAM
|
||||
- 10GB free disk space
|
||||
Before installing MCP Server, ensure you have:
|
||||
|
||||
### Software Dependencies
|
||||
- Bun runtime
|
||||
- Docker (optional, recommended for deployment)
|
||||
- Git
|
||||
- Node.js (for some development tasks)
|
||||
- Home Assistant instance running and accessible
|
||||
- Node.js 18+ or Docker installed
|
||||
- Home Assistant Long-Lived Access Token ([How to get one](https://developers.home-assistant.io/docs/auth_api/#long-lived-access-token))
|
||||
|
||||
## Installation Methods
|
||||
|
||||
### 1. Basic Setup
|
||||
### 1. 🔧 Smithery Installation (Recommended)
|
||||
|
||||
The easiest way to install MCP Server is through Smithery:
|
||||
|
||||
#### Install Bun
|
||||
```bash
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
npx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude
|
||||
```
|
||||
|
||||
#### Clone Repository
|
||||
```bash
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
```
|
||||
### 2. 🐳 Docker Installation
|
||||
|
||||
#### Install Dependencies
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
For a containerized deployment:
|
||||
|
||||
#### Configure Environment
|
||||
1. Copy environment template
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone --depth 1 https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
|
||||
cd advanced-homeassistant-mcp
|
||||
|
||||
# Configure environment variables
|
||||
cp .env.example .env
|
||||
```
|
||||
2. Edit `.env` file with your Home Assistant configuration
|
||||
- Set `HASS_HOST`
|
||||
- Configure authentication tokens
|
||||
- Adjust other settings as needed
|
||||
# Edit .env with your Home Assistant details:
|
||||
# - HA_URL: Your Home Assistant URL
|
||||
# - HA_TOKEN: Your Long-Lived Access Token
|
||||
# - Other configuration options
|
||||
|
||||
#### Build and Start
|
||||
```bash
|
||||
bun run build
|
||||
bun start
|
||||
# Build and start containers
|
||||
docker compose up -d --build
|
||||
|
||||
# View logs (optional)
|
||||
docker compose logs -f --tail=50
|
||||
```
|
||||
|
||||
### 2. Docker Setup (Recommended)
|
||||
### 3. 💻 Manual Installation
|
||||
|
||||
#### Prerequisites
|
||||
- Docker
|
||||
- Docker Compose
|
||||
For direct installation on your system:
|
||||
|
||||
#### Deployment Steps
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
|
||||
cd homeassistant-mcp
|
||||
# Install Bun runtime
|
||||
curl -fsSL https://bun.sh/install | bash
|
||||
|
||||
# Clone and install
|
||||
git clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git
|
||||
cd advanced-homeassistant-mcp
|
||||
bun install --frozen-lockfile
|
||||
|
||||
# Configure environment
|
||||
cp .env.example .env
|
||||
# Edit .env file with your settings
|
||||
# Edit .env with your configuration
|
||||
|
||||
# Deploy with Docker Compose
|
||||
docker compose up -d
|
||||
# Start the server
|
||||
bun run dev --watch
|
||||
```
|
||||
|
||||
### 3. Home Assistant Add-on (Coming Soon)
|
||||
We're working on a direct Home Assistant add-on for even easier installation.
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Key configuration options in your `.env` file:
|
||||
|
||||
```env
|
||||
# Home Assistant Configuration
|
||||
HA_URL=http://your-homeassistant:8123
|
||||
HA_TOKEN=your_long_lived_access_token
|
||||
|
||||
# Server Configuration
|
||||
PORT=3000
|
||||
HOST=0.0.0.0
|
||||
NODE_ENV=production
|
||||
|
||||
# Security Settings
|
||||
JWT_SECRET=your_secure_jwt_secret
|
||||
RATE_LIMIT=100
|
||||
```
|
||||
|
||||
### Client Integration
|
||||
|
||||
#### Cursor Integration
|
||||
|
||||
Add to `.cursor/config/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": ["run", "start"],
|
||||
"cwd": "${workspaceRoot}",
|
||||
"env": {
|
||||
"NODE_ENV": "development"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Claude Desktop Integration
|
||||
|
||||
Add to your Claude configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"homeassistant-mcp": {
|
||||
"command": "bun",
|
||||
"args": ["run", "start", "--port", "8080"],
|
||||
"env": {
|
||||
"NODE_ENV": "production"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
### Check Installation
|
||||
- Web Interface: [http://localhost:3000](http://localhost:3000)
|
||||
- Logs: `docker compose logs` or check `logs/` directory
|
||||
To verify your installation:
|
||||
|
||||
### Troubleshooting
|
||||
- Ensure all environment variables are correctly set
|
||||
- Check network connectivity to Home Assistant
|
||||
- Verify authentication tokens
|
||||
1. Check server status:
|
||||
```bash
|
||||
curl http://localhost:3000/health
|
||||
```
|
||||
|
||||
## Updating
|
||||
2. Test Home Assistant connection:
|
||||
```bash
|
||||
curl http://localhost:3000/api/state
|
||||
```
|
||||
|
||||
### Basic Setup
|
||||
```bash
|
||||
git pull
|
||||
bun install
|
||||
bun run build
|
||||
bun start
|
||||
```
|
||||
## Troubleshooting
|
||||
|
||||
### Docker
|
||||
```bash
|
||||
git pull
|
||||
docker compose up -d --build
|
||||
```
|
||||
If you encounter issues:
|
||||
|
||||
## Uninstallation
|
||||
|
||||
### Basic Setup
|
||||
```bash
|
||||
cd homeassistant-mcp
|
||||
bun stop # Stop the application
|
||||
rm -rf node_modules dist
|
||||
```
|
||||
|
||||
### Docker
|
||||
```bash
|
||||
docker compose down
|
||||
docker rmi homeassistant-mcp # Remove image
|
||||
```
|
||||
1. Check the [Troubleshooting Guide](../troubleshooting.md)
|
||||
2. Verify your environment variables
|
||||
3. Check server logs:
|
||||
```bash
|
||||
# For Docker installation
|
||||
docker compose logs -f
|
||||
|
||||
# For manual installation
|
||||
bun run dev
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
- [Configuration Guide](configuration.md)
|
||||
- [Usage Instructions](../usage.md)
|
||||
- [Troubleshooting](../troubleshooting.md)
|
||||
|
||||
- Follow the [Quick Start Guide](quickstart.md) to begin using MCP Server
|
||||
- Read the [API Documentation](../api/index.md) for integration details
|
||||
- Check the [Architecture Overview](../architecture.md) to understand the system
|
||||
|
||||
## Support
|
||||
|
||||
Need help? Check our [Support Resources](../index.md#support) or [open an issue](https://github.com/jango-blockchained/advanced-homeassistant-mcp/issues).
|
||||
219
docs/getting-started/quickstart.md
Normal file
219
docs/getting-started/quickstart.md
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
layout: default
|
||||
title: Quick Start
|
||||
parent: Getting Started
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```javascript
|
||||
// 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):
|
||||
|
||||
```javascript
|
||||
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:
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```typescript
|
||||
// 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**
|
||||
```javascript
|
||||
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**
|
||||
```javascript
|
||||
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](../api/index.md) for advanced features
|
||||
- Learn about [SSE API](../api/sse.md) for real-time updates
|
||||
- Check out [Architecture](../architecture.md) for system design details
|
||||
- Read the [Contributing Guide](../contributing.md) 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](../troubleshooting.md)
|
||||
|
||||
Need more help? Visit our [Support Resources](../index.md#support).
|
||||
Reference in New Issue
Block a user