Welcome to the Model Context Protocol (MCP) Server documentation! This guide will help you get started with integrating a lightweight automation tool with your Home Assistant setup.
"},{"location":"#what-is-mcp-server","title":"What is MCP Server?","text":"MCP Server is a bridge between Home Assistant and custom automation tools, enabling basic device control and real-time monitoring of your smart home environment. It provides a flexible interface for managing and interacting with your home automation setup.
"},{"location":"#key-features","title":"Key Features","text":""},{"location":"#device-control","title":"\ud83c\udfae Device Control","text":"Need help or want to report issues?
This project is licensed under the MIT License. See the LICENSE file for details.
"},{"location":"api/","title":"Home Assistant MCP Server API Documentation","text":""},{"location":"api/#overview","title":"Overview","text":"This document provides a reference for the MCP Server API, which offers basic device control and state management for Home Assistant.
"},{"location":"api/#authentication","title":"Authentication","text":"All API requests require a valid JWT token in the Authorization header:
Authorization: Bearer YOUR_TOKEN\nGET /api/state/{entity_id}\nResponse:
{\n \"entity_id\": \"light.living_room\",\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 128\n }\n}\nPOST /api/state\nContent-Type: application/json\n\n{\n \"entity_id\": \"light.living_room\",\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 128\n }\n}\nPOST /api/control\nContent-Type: application/json\n\n{\n \"entity_id\": \"light.living_room\",\n \"command\": \"turn_on\",\n \"parameters\": {\n \"brightness\": 50\n }\n}\nConnect to real-time updates:
const ws = new WebSocket('ws://localhost:3000/events');\nws.onmessage = (event) => {\n const deviceUpdate = JSON.parse(event.data);\n console.log('Device state changed:', deviceUpdate);\n};\n{\n \"error\": {\n \"code\": \"INVALID_REQUEST\",\n \"message\": \"Invalid request parameters\",\n \"details\": \"Entity ID not found or invalid command\"\n }\n}\nBasic rate limiting is implemented: - Maximum of 100 requests per minute - Excess requests will receive a 429 Too Many Requests response
"},{"location":"api/#supported-operations","title":"Supported Operations","text":""},{"location":"api/#supported-commands","title":"Supported Commands","text":"turn_onturn_offtoggleset_brightnessset_colorasync function controlDevice(entityId: string, command: string, params?: Record<string, unknown>) {\n try {\n const response = await fetch('/api/control', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': `Bearer ${token}`\n },\n body: JSON.stringify({\n entity_id: entityId,\n command,\n parameters: params\n })\n });\n\n if (!response.ok) {\n const error = await response.json();\n throw new Error(error.message);\n }\n\n return await response.json();\n} catch (error) {\n console.error('Device control failed:', error);\n throw error;\n }\n}\n\n// Usage example\ncontrolDevice('light.living_room', 'turn_on', { brightness: 50 })\n .then(result => console.log('Device controlled successfully'))\n .catch(error => console.error('Control failed', error));\nPlanned improvements: - Enhanced error handling - More comprehensive device support - Improved authentication mechanisms
API is subject to change. Always refer to the latest documentation.
"},{"location":"architecture/","title":"Architecture Overview \ud83c\udfd7\ufe0f","text":"This document describes the architecture of the MCP Server, explaining how different components work together to provide a bridge between Home Assistant and custom automation tools.
"},{"location":"architecture/#system-architecture","title":"System Architecture","text":"graph TD\n subgraph \"Client Layer\"\n WC[Web Clients]\n MC[Mobile Clients]\n end\n\n subgraph \"MCP Server\"\n API[API Gateway]\n SSE[SSE Manager]\n WS[WebSocket Server]\n CM[Command Manager]\n end\n\n subgraph \"Home Assistant\"\n HA[Home Assistant Core]\n Dev[Devices & Services]\n end\n\n WC --> |HTTP/WS| API\n MC --> |HTTP/WS| API\n\n API --> |Events| SSE\n API --> |Real-time| WS\n\n API --> HA\n HA --> API\nArchitecture is subject to change as the project evolves.
"},{"location":"contributing/","title":"Contributing Guide \ud83e\udd1d","text":"Thank you for your interest in contributing to the MCP Server project!
"},{"location":"contributing/#getting-started","title":"Getting Started","text":""},{"location":"contributing/#prerequisites","title":"Prerequisites","text":"Clone your fork:
git clone https://github.com/YOUR_USERNAME/homeassistant-mcp.git\ncd homeassistant-mcp\nInstall dependencies:
bun install\nConfigure environment:
cp .env.example .env\n# Edit .env with your Home Assistant details\nfeature/ - New featuresfix/ - Bug fixesdocs/ - Documentation updatesExample:
git checkout -b feature/device-control-improvements\nFollow simple, clear commit messages:
type: brief description\n\n[optional detailed explanation]\nTypes: - feat: - New feature - fix: - Bug fix - docs: - Documentation - chore: - Maintenance
Run tests before submitting:
# Run all tests\nbun test\n\n# Run specific test\nbun test test/api/control.test.ts\n## Description\nBrief explanation of the changes\n\n## Type of Change\n- [ ] Bug fix\n- [ ] New feature\n- [ ] Documentation update\n\n## Testing\nDescribe how you tested these changes\nThank you for contributing!
"},{"location":"getting-started/","title":"Getting Started","text":"Begin your journey with the Home Assistant MCP Server by following these steps:
If you encounter any issues: 1. Verify that your Home Assistant instance is accessible. 2. Ensure that all required environment variables are properly set. 3. Consult the Troubleshooting Guide for additional solutions.
"},{"location":"getting-started/#development","title":"Development","text":"For contributors: 1. Fork the repository. 2. Create a feature branch. 3. Follow the Development Guide for contribution guidelines. 4. Submit a pull request with your enhancements.
"},{"location":"getting-started/#support","title":"Support","text":"Need help? - Visit our GitHub Issues. - Review the Troubleshooting Guide. - Check the FAQ for common questions.
"},{"location":"roadmap/","title":"Roadmap for MCP Server","text":"The following roadmap outlines our planned enhancements and future directions for the Home Assistant MCP Server. This document is a living guide that will be updated as new features are developed.
"},{"location":"roadmap/#near-term-goals","title":"Near-Term Goals","text":"Develop more robust error handling
Security Enhancements:
Add basic logging for security events
Performance Optimizations:
Develop more flexible automation rule support
Developer Experience:
Establish a clear extension mechanism
Reliability:
This roadmap is intended as a guide and may evolve based on community needs, technological advancements, and strategic priorities.
"},{"location":"testing/","title":"Testing Documentation","text":""},{"location":"testing/#quick-reference","title":"Quick Reference","text":"# Most Common Commands\nbun test # Run all tests\nbun test --watch # Run tests in watch mode\nbun test --coverage # Run tests with coverage\nbun test path/to/test.ts # Run a specific test file\n\n# Additional Options\nDEBUG=true bun test # Run with debug output\nbun test --pattern \"auth\" # Run tests matching a pattern\nbun test --timeout 60000 # Run with a custom timeout\nThis document describes the testing setup and practices used in the Home Assistant MCP project. We use Bun's test runner for both unit and integration testing, ensuring comprehensive coverage across modules.
"},{"location":"testing/#test-structure","title":"Test Structure","text":"Tests are organized in two main locations:
/__tests__/):__tests__/\n\u251c\u2500\u2500 ai/ # AI/ML component tests\n\u251c\u2500\u2500 api/ # API integration tests\n\u251c\u2500\u2500 context/ # Context management tests\n\u251c\u2500\u2500 hass/ # Home Assistant integration tests\n\u251c\u2500\u2500 schemas/ # Schema validation tests\n\u251c\u2500\u2500 security/ # Security integration tests\n\u251c\u2500\u2500 tools/ # Tools and utilities tests\n\u251c\u2500\u2500 websocket/ # WebSocket integration tests\n\u251c\u2500\u2500 helpers.test.ts # Helper function tests\n\u251c\u2500\u2500 index.test.ts # Main application tests\n\u2514\u2500\u2500 server.test.ts # Server integration tests\nsrc/**/):src/\n\u251c\u2500\u2500 __tests__/ # Global test setup and utilities\n\u2502 \u2514\u2500\u2500 setup.ts # Global test configuration\n\u251c\u2500\u2500 component/\n\u2502 \u251c\u2500\u2500 __tests__/ # Component-specific unit tests\n\u2502 \u2514\u2500\u2500 component.ts\nbunfig.toml)","text":"[test]\npreload = [\"./src/__tests__/setup.ts\"] # Global test setup\ncoverage = true # Enable coverage by default\ntimeout = 30000 # Test timeout in milliseconds\ntestMatch = [\"**/__tests__/**/*.test.ts\"] # Test file patterns\nAvailable test commands in package.json:
# Run all tests\nbun test\n\n# Watch mode for development\nbun test --watch\n\n# Generate coverage report\nbun test --coverage\n\n# Run linting\nbun run lint\n\n# Format code\nbun run format\nA global test setup file (src/__tests__/setup.ts) provides: - Environment configuration - Mock utilities - Test helper functions - Global lifecycle hooks
.env.test.DEBUG=true.# Basic test run\nbun test\n\n# Run tests with coverage\nbun test --coverage\n\n# Run a specific test file\nbun test path/to/test.test.ts\n\n# Run tests in watch mode\nbun test --watch\n\n# Run tests with debug output\nDEBUG=true bun test\n\n# Run tests with increased timeout\nbun test --timeout 60000\n\n# Run tests matching a pattern\nbun test --pattern \"auth\"\n# Start tests with inspector\nbun test --inspect\n\n# Start tests with inspector and break on first line\nbun test --inspect-brk\nCreate a launch configuration in .vscode/launch.json:
{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"type\": \"bun\",\n \"request\": \"launch\",\n \"name\": \"Debug Tests\",\n \"program\": \"${workspaceFolder}/node_modules/bun/bin/bun\",\n \"args\": [\"test\", \"${file}\"],\n \"cwd\": \"${workspaceFolder}\",\n \"env\": { \"DEBUG\": \"true\" }\n }\n ]\n}\nTo run a single test in isolation:
describe.only(\"specific test suite\", () => {\n it.only(\"specific test case\", () => {\n // Only this test will run\n });\n});\n__tests__ directory adjacent to the code being tested.*.test.ts.describe(\"Security Features\", () => {\n it(\"should validate tokens correctly\", () => {\n const payload = { userId: \"123\", role: \"user\" };\n const token = jwt.sign(payload, validSecret, { expiresIn: \"1h\" });\n const result = TokenManager.validateToken(token, testIp);\n expect(result.valid).toBe(true);\n });\n});\nThe project maintains strict coverage: - Overall coverage: at least 80% - Critical paths: 90%+ - New features: \u226585% coverage
Generate a coverage report with:
bun test --coverage\nThe security middleware now uses a utility-first approach, which allows for more granular and comprehensive testing. Each security function is now independently testable, improving code reliability and maintainability.
"},{"location":"testing/#key-utility-functions","title":"Key Utility Functions","text":"checkRateLimit)// Example test\nit('should throw when requests exceed threshold', () => {\n const ip = '127.0.0.2';\n for (let i = 0; i < 11; i++) {\n if (i < 10) {\n expect(() => checkRateLimit(ip, 10)).not.toThrow();\n } else {\n expect(() => checkRateLimit(ip, 10)).toThrow('Too many requests from this IP');\n }\n }\n});\nvalidateRequestHeaders)it('should reject invalid content type', () => {\n const mockRequest = new Request('http://localhost', {\n method: 'POST',\n headers: { 'content-type': 'text/plain' }\n });\n expect(() => validateRequestHeaders(mockRequest)).toThrow('Content-Type must be application/json');\n});\nsanitizeValue)it('should sanitize HTML tags', () => {\n const input = '<script>alert(\"xss\")</script>Hello';\n const sanitized = sanitizeValue(input);\n expect(sanitized).toBe('<script>alert("xss")</script>Hello');\n});\napplySecurityHeaders)it('should apply security headers', () => {\n const mockRequest = new Request('http://localhost');\n const headers = applySecurityHeaders(mockRequest);\n expect(headers['content-security-policy']).toBeDefined();\n expect(headers['x-frame-options']).toBeDefined();\n});\nhandleError)it('should include error details in development mode', () => {\n const error = new Error('Test error');\n const result = handleError(error, 'development');\n expect(result).toEqual({\n error: true,\n message: 'Internal server error',\n error: 'Test error',\n stack: expect.any(String)\n });\n});\n# Run all tests\nbun test\n\n# Run specific security tests\nbun test __tests__/security/\nafterEach or afterAll hooks.beforeEach for common test setup to avoid repetition.The project aims for high test coverage, particularly focusing on: - Security-critical code paths - API endpoints - Data validation - Error handling - Event broadcasting
Run coverage reports using:
bun test --coverage\nTo debug tests: 1. Set DEBUG=true to enable console output during tests 2. Use the --watch flag for development 3. Add console.log() statements (they're only shown when DEBUG is true) 4. Use the test utilities' debugging helpers
Using Node Inspector:
# Start tests with inspector\nbun test --inspect\n\n# Start tests with inspector and break on first line\nbun test --inspect-brk\nUsing VS Code:
// .vscode/launch.json\n{\n \"version\": \"0.2.0\",\n \"configurations\": [\n {\n \"type\": \"bun\",\n \"request\": \"launch\",\n \"name\": \"Debug Tests\",\n \"program\": \"${workspaceFolder}/node_modules/bun/bin/bun\",\n \"args\": [\"test\", \"${file}\"],\n \"cwd\": \"${workspaceFolder}\",\n \"env\": { \"DEBUG\": \"true\" }\n }\n ]\n}\nTest Isolation: To run a single test in isolation:
describe.only(\"specific test suite\", () => {\n it.only(\"specific test case\", () => {\n // Only this test will run\n });\n});\nWhen contributing new code: 1. Add tests for new features 2. Ensure existing tests pass 3. Maintain or improve coverage 4. Follow the existing test patterns and naming conventions 5. Document any new test utilities or patterns
"},{"location":"testing/#coverage-requirements","title":"Coverage Requirements","text":"The project maintains strict coverage requirements:
Coverage reports are generated in multiple formats: - Console summary - HTML report (./coverage/index.html) - LCOV report (./coverage/lcov.info)
To view detailed coverage:
# Generate and open coverage report\nbun test --coverage && open coverage/index.html\nThis guide helps you diagnose and resolve common issues with MCP Server.
"},{"location":"troubleshooting/#quick-diagnostics","title":"Quick Diagnostics","text":""},{"location":"troubleshooting/#health-check","title":"Health Check","text":"First, verify the server's health:
curl http://localhost:3000/health\nExpected response:
{\n \"status\": \"healthy\",\n \"version\": \"1.0.0\",\n \"uptime\": 3600,\n \"homeAssistant\": {\n \"connected\": true,\n \"version\": \"2024.1.0\"\n }\n}\nSymptoms: - Server not responding - Connection refused errors - Timeout errors
Solutions:
Check if the server is running:
# For Docker installation\ndocker compose ps\n\n# For manual installation\nps aux | grep mcp\nVerify port availability:
# Check if port is in use\nnetstat -tuln | grep 3000\nCheck logs:
# Docker logs\ndocker compose logs mcp\n\n# Manual installation logs\nbun run dev\nSymptoms: - \"Connection Error\" in health check - Cannot control devices - State updates not working
Solutions:
Verify Home Assistant URL and token in .env:
HA_URL=http://homeassistant:8123\nHA_TOKEN=your_long_lived_access_token\nTest Home Assistant connection:
curl -H \"Authorization: Bearer YOUR_HA_TOKEN\" \\\n http://your-homeassistant:8123/api/\nCheck network connectivity:
# For Docker setup\ndocker compose exec mcp ping homeassistant\nSymptoms: - 401 Unauthorized responses - \"Invalid token\" errors
Solutions:
Generate a new token:
curl -X POST http://localhost:3000/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\"username\": \"your_username\", \"password\": \"your_password\"}'\nVerify token format:
// Token should be in format:\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\nSymptoms: - 429 Too Many Requests - \"Rate limit exceeded\" errors
Solutions:
Check current rate limit status:
curl -I http://localhost:3000/api/state\nAdjust rate limits in configuration:
security:\n rateLimit: 100 # Increase if needed\n rateLimitWindow: 60000 # Window in milliseconds\nSymptoms: - Frequent disconnections - Missing state updates - EventSource errors
Solutions:
Implement proper reconnection logic:
class SSEClient {\n constructor() {\n this.connect();\n }\n\n connect() {\n this.eventSource = new EventSource('/subscribe_events');\n this.eventSource.onerror = this.handleError.bind(this);\n }\n\n handleError(error) {\n console.error('SSE Error:', error);\n this.eventSource.close();\n setTimeout(() => this.connect(), 1000);\n }\n}\nCheck network stability:
# Monitor connection stability\nping -c 100 localhost\nSymptoms: - Slow response times - Command execution delays - UI lag
Solutions:
Enable Redis caching:
REDIS_ENABLED=true\nREDIS_URL=redis://localhost:6379\nMonitor system resources:
# Check CPU and memory usage\ndocker stats\n\n# Or for manual installation\ntop -p $(pgrep -f mcp)\nOptimize database queries and caching:
// Use batch operations\nconst results = await Promise.all([\n cache.get('key1'),\n cache.get('key2')\n]);\nSymptoms: - Commands appear successful but no device response - Inconsistent device states - Error messages from Home Assistant
Solutions:
Verify device availability:
curl http://localhost:3000/api/state/light.living_room\nCheck command syntax:
# Test basic command\ncurl -X POST http://localhost:3000/api/command \\\n -H \"Content-Type: application/json\" \\\n -d '{\"command\": \"Turn on living room lights\"}'\nReview Home Assistant logs:
docker compose exec homeassistant journalctl -f\nEnable debug logging:
LOG_LEVEL=debug\nDEBUG=mcp:*\nMonitor network traffic:
# TCP dump for API traffic\ntcpdump -i any port 3000 -w debug.pcap\nEnable performance monitoring:
ENABLE_METRICS=true\nMETRICS_PORT=9090\nIf you're still experiencing issues:
Run periodic health checks:
# Create a cron job\n*/5 * * * * curl -f http://localhost:3000/health || notify-admin\nConfigure log rotation:
logging:\n maxSize: \"100m\"\n maxFiles: \"7d\"\n compress: true\nRegularly backup your configuration:
# Backup script\ntar -czf mcp-backup-$(date +%Y%m%d).tar.gz \\\n .env \\\n config/ \\\n data/\nA: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.
"},{"location":"troubleshooting/#q-what-are-the-system-requirements","title":"Q: What are the system requirements?","text":"A: MCP Server requires: - Node.js 16 or higher - Home Assistant instance - 1GB RAM minimum - 1GB disk space
"},{"location":"troubleshooting/#q-how-do-i-update-mcp-server","title":"Q: How do I update MCP Server?","text":"A: For Docker installation:
docker compose pull\ndocker compose up -d\ngit pull\nbun install\nbun run build\nA: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.
"},{"location":"troubleshooting/#q-does-mcp-server-support-all-home-assistant-integrations","title":"Q: Does MCP Server support all Home Assistant integrations?","text":"A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.
"},{"location":"troubleshooting/#security-questions","title":"Security Questions","text":""},{"location":"troubleshooting/#q-is-my-home-assistant-token-secure","title":"Q: Is my Home Assistant token secure?","text":"A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.
"},{"location":"troubleshooting/#q-can-i-use-mcp-server-remotely","title":"Q: Can I use MCP Server remotely?","text":"A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.
"},{"location":"troubleshooting/#troubleshooting-questions","title":"Troubleshooting Questions","text":""},{"location":"troubleshooting/#q-why-are-my-device-states-not-updating","title":"Q: Why are my device states not updating?","text":"A: Check: 1. Home Assistant connection 2. WebSocket connection status 3. Device availability in Home Assistant 4. Network connectivity
"},{"location":"troubleshooting/#q-why-are-my-commands-not-working","title":"Q: Why are my commands not working?","text":"A: Verify: 1. Command syntax 2. Device availability 3. User permissions 4. Home Assistant API access
"},{"location":"usage/","title":"Usage Guide","text":"This guide explains how to use the Home Assistant MCP Server for basic device management and integration.
"},{"location":"usage/#basic-setup","title":"Basic Setup","text":"bun run devProduction mode: bun run start
Accessing the Server:
http://localhost:3000.envBasic device control can be performed via the REST API:
// Turn on a light\nfetch('http://localhost:3000/api/control', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n 'Authorization': `Bearer ${token}`\n },\n body: JSON.stringify({\n entity_id: 'light.living_room',\n command: 'turn_on',\n parameters: { brightness: 50 }\n })\n});\nturn_onturn_offtoggleset_brightnessSubscribe to real-time device state changes:
const ws = new WebSocket('ws://localhost:3000/events');\nws.onmessage = (event) => {\n const deviceUpdate = JSON.parse(event.data);\n console.log('Device state changed:', deviceUpdate);\n};\nAll API requests require a valid JWT token in the Authorization header.
"},{"location":"usage/#limitations","title":"Limitations","text":"Configure the server using environment variables in .env:
HA_URL=http://homeassistant:8123\nHA_TOKEN=your_home_assistant_token\nJWT_SECRET=your_jwt_secret\nWelcome to the MCP Server API documentation. This guide covers all available endpoints, authentication methods, and integration patterns.
"},{"location":"api/#api-overview","title":"API Overview","text":"The MCP Server provides several API categories:
All API endpoints require authentication using JWT tokens:
# Include the token in your requests\ncurl -H \"Authorization: Bearer YOUR_JWT_TOKEN\" http://localhost:3000/api/state\nTo obtain a token:
curl -X POST http://localhost:3000/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\"username\": \"your_username\", \"password\": \"your_password\"}'\nGET /api/state\nRetrieve the current state of all devices:
curl http://localhost:3000/api/state\nResponse:
{\n \"devices\": [\n {\n \"id\": \"light.living_room\",\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255,\n \"color_temp\": 370\n }\n }\n ]\n}\nPOST /api/command\nExecute a natural language command:
curl -X POST http://localhost:3000/api/command \\\n -H \"Content-Type: application/json\" \\\n -d '{\"command\": \"Turn on the kitchen lights\"}'\nResponse:
{\n \"success\": true,\n \"action\": \"turn_on\",\n \"device\": \"light.kitchen\",\n \"message\": \"Kitchen lights turned on\"\n}\nGET /subscribe_events\nSubscribe to device state changes:
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');\n\neventSource.onmessage = (event) => {\n const data = JSON.parse(event.data);\n console.log('State changed:', data);\n};\nSubscribe to specific device types:
GET /subscribe_events?domain=light\nGET /subscribe_events?entity_id=light.living_room\nPOST /api/scene\nCreate a new scene:
curl -X POST http://localhost:3000/api/scene \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"name\": \"Movie Night\",\n \"actions\": [\n {\"device\": \"light.living_room\", \"action\": \"dim\", \"value\": 20},\n {\"device\": \"media_player.tv\", \"action\": \"on\"}\n ]\n }'\nPOST /api/scene/activate\nActivate an existing scene:
curl -X POST http://localhost:3000/api/scene/activate \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Movie Night\"}'\nThe API uses standard HTTP status codes:
200 - Success400 - Bad Request401 - Unauthorized404 - Not Found500 - Server ErrorError responses include detailed messages:
{\n \"error\": true,\n \"message\": \"Device not found\",\n \"code\": \"DEVICE_NOT_FOUND\",\n \"details\": {\n \"device_id\": \"light.nonexistent\"\n }\n}\nAPI requests are rate-limited to prevent abuse:
X-RateLimit-Limit: 100\nX-RateLimit-Remaining: 99\nX-RateLimit-Reset: 1640995200\nWhen exceeded, returns 429 Too Many Requests:
{\n \"error\": true,\n \"message\": \"Rate limit exceeded\",\n \"reset\": 1640995200\n}\nFor bi-directional communication:
const ws = new WebSocket('ws://localhost:3000/ws');\n\nws.onmessage = (event) => {\n const data = JSON.parse(event.data);\n console.log('Received:', data);\n};\n\nws.send(JSON.stringify({\n type: 'command',\n payload: {\n command: 'Turn on lights'\n }\n}));\nThe current API version is v1. Include the version in the URL:
/api/v1/state\n/api/v1/command\nThe Core Functions API provides the fundamental operations for interacting with Home Assistant devices and services through MCP Server.
"},{"location":"api/core/#device-control","title":"Device Control","text":""},{"location":"api/core/#get-device-state","title":"Get Device State","text":"Retrieve the current state of devices.
GET /api/state\nGET /api/state/{entity_id}\nParameters: - entity_id (optional): Specific device ID to query
# Get all states\ncurl http://localhost:3000/api/state\n\n# Get specific device state\ncurl http://localhost:3000/api/state/light.living_room\nResponse:
{\n \"entity_id\": \"light.living_room\",\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255,\n \"color_temp\": 370,\n \"friendly_name\": \"Living Room Light\"\n },\n \"last_changed\": \"2024-01-20T15:30:00Z\"\n}\nExecute device commands.
POST /api/device/control\nRequest body:
{\n \"entity_id\": \"light.living_room\",\n \"action\": \"turn_on\",\n \"parameters\": {\n \"brightness\": 200,\n \"color_temp\": 400\n }\n}\nAvailable actions: - turn_on - turn_off - toggle - set_value
Example with curl:
curl -X POST http://localhost:3000/api/device/control \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer YOUR_JWT_TOKEN\" \\\n -d '{\n \"entity_id\": \"light.living_room\",\n \"action\": \"turn_on\",\n \"parameters\": {\n \"brightness\": 200\n }\n }'\nProcess natural language commands.
POST /api/command\nRequest body:
{\n \"command\": \"Turn on the living room lights and set them to 50% brightness\"\n}\nExample usage:
curl -X POST http://localhost:3000/api/command \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer YOUR_JWT_TOKEN\" \\\n -d '{\n \"command\": \"Turn on the living room lights and set them to 50% brightness\"\n }'\nResponse:
{\n \"success\": true,\n \"actions\": [\n {\n \"entity_id\": \"light.living_room\",\n \"action\": \"turn_on\",\n \"parameters\": {\n \"brightness\": 127\n },\n \"status\": \"completed\"\n }\n ],\n \"message\": \"Command executed successfully\"\n}\nDefine a new scene with multiple actions.
POST /api/scene\nRequest body:
{\n \"name\": \"Movie Night\",\n \"description\": \"Perfect lighting for movie watching\",\n \"actions\": [\n {\n \"entity_id\": \"light.living_room\",\n \"action\": \"turn_on\",\n \"parameters\": {\n \"brightness\": 50,\n \"color_temp\": 500\n }\n },\n {\n \"entity_id\": \"cover.living_room\",\n \"action\": \"close\"\n }\n ]\n}\nTrigger a predefined scene.
POST /api/scene/{scene_name}/activate\nExample:
curl -X POST http://localhost:3000/api/scene/movie_night/activate \\\n -H \"Authorization: Bearer YOUR_JWT_TOKEN\"\nCreate a group of devices for collective control.
POST /api/group\nRequest body:
{\n \"name\": \"Living Room\",\n \"entities\": [\n \"light.living_room_main\",\n \"light.living_room_accent\",\n \"switch.living_room_fan\"\n ]\n}\nControl multiple devices in a group.
POST /api/group/{group_name}/control\nRequest body:
{\n \"action\": \"turn_off\"\n}\nCheck server status and connectivity.
GET /health\nResponse:
{\n \"status\": \"healthy\",\n \"version\": \"1.0.0\",\n \"uptime\": 3600,\n \"homeAssistant\": {\n \"connected\": true,\n \"version\": \"2024.1.0\"\n }\n}\nGet current server configuration.
GET /api/config\nResponse:
{\n \"server\": {\n \"port\": 3000,\n \"host\": \"0.0.0.0\",\n \"version\": \"1.0.0\"\n },\n \"homeAssistant\": {\n \"url\": \"http://homeassistant:8123\",\n \"connected\": true\n },\n \"features\": {\n \"nlp\": true,\n \"scenes\": true,\n \"groups\": true\n }\n}\nAll endpoints follow standard HTTP status codes and return detailed error messages:
{\n \"error\": true,\n \"code\": \"INVALID_ENTITY\",\n \"message\": \"Device 'light.nonexistent' not found\",\n \"details\": {\n \"entity_id\": \"light.nonexistent\",\n \"available_entities\": [\n \"light.living_room\",\n \"light.kitchen\"\n ]\n }\n}\nCommon error codes: - INVALID_ENTITY: Device not found - INVALID_ACTION: Unsupported action - INVALID_PARAMETERS: Invalid command parameters - AUTHENTICATION_ERROR: Invalid or missing token - CONNECTION_ERROR: Home Assistant connection issue
interface DeviceState {\n entity_id: string;\n state: string;\n attributes: Record<string, any>;\n last_changed: string;\n}\n\ninterface DeviceCommand {\n entity_id: string;\n action: 'turn_on' | 'turn_off' | 'toggle' | 'set_value';\n parameters?: Record<string, any>;\n}\n\ninterface Scene {\n name: string;\n description?: string;\n actions: DeviceCommand[];\n}\n\ninterface Group {\n name: string;\n entities: string[];\n}\nThe SSE API provides real-time updates about device states and events from your Home Assistant setup. This guide covers how to use and implement SSE connections in your applications.
"},{"location":"api/sse/#overview","title":"Overview","text":"Server-Sent Events (SSE) is a standard that enables servers to push real-time updates to clients over HTTP connections. MCP Server uses SSE to provide:
Create an EventSource connection to receive updates:
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_JWT_TOKEN');\n\neventSource.onmessage = (event) => {\n const data = JSON.parse(event.data);\n console.log('Received update:', data);\n};\nHandle different connection states:
eventSource.onopen = () => {\n console.log('Connection established');\n};\n\neventSource.onerror = (error) => {\n console.error('Connection error:', error);\n // Implement reconnection logic if needed\n};\nSubscribe to all device state changes:
const stateEvents = new EventSource('http://localhost:3000/subscribe_events?type=state');\n\nstateEvents.onmessage = (event) => {\n const state = JSON.parse(event.data);\n console.log('Device state changed:', state);\n};\nExample state event:
{\n \"type\": \"state_changed\",\n \"entity_id\": \"light.living_room\",\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255,\n \"color_temp\": 370\n },\n \"timestamp\": \"2024-01-20T15:30:00Z\"\n}\nSubscribe to specific device types:
// Subscribe to only light events\nconst lightEvents = new EventSource('http://localhost:3000/subscribe_events?domain=light');\n\n// Subscribe to multiple domains\nconst multiEvents = new EventSource('http://localhost:3000/subscribe_events?domain=light,switch,sensor');\nSubscribe to specific devices:
// Single entity\nconst livingRoomLight = new EventSource(\n 'http://localhost:3000/subscribe_events?entity_id=light.living_room'\n);\n\n// Multiple entities\nconst kitchenDevices = new EventSource(\n 'http://localhost:3000/subscribe_events?entity_id=light.kitchen,switch.coffee_maker'\n);\nImplement robust connection handling:
class SSEManager {\n constructor(url, options = {}) {\n this.url = url;\n this.options = {\n maxRetries: 3,\n retryDelay: 1000,\n ...options\n };\n this.retryCount = 0;\n this.connect();\n }\n\n connect() {\n this.eventSource = new EventSource(this.url);\n\n this.eventSource.onopen = () => {\n this.retryCount = 0;\n console.log('Connected to SSE stream');\n };\n\n this.eventSource.onerror = (error) => {\n this.handleError(error);\n };\n\n this.eventSource.onmessage = (event) => {\n this.handleMessage(event);\n };\n }\n\n handleError(error) {\n console.error('SSE Error:', error);\n this.eventSource.close();\n\n if (this.retryCount < this.options.maxRetries) {\n this.retryCount++;\n setTimeout(() => {\n console.log(`Retrying connection (${this.retryCount}/${this.options.maxRetries})`);\n this.connect();\n }, this.options.retryDelay * this.retryCount);\n }\n }\n\n handleMessage(event) {\n try {\n const data = JSON.parse(event.data);\n // Handle the event data\n console.log('Received:', data);\n } catch (error) {\n console.error('Error parsing SSE data:', error);\n }\n }\n\n disconnect() {\n if (this.eventSource) {\n this.eventSource.close();\n }\n }\n}\n\n// Usage\nconst sseManager = new SSEManager('http://localhost:3000/subscribe_events?token=YOUR_TOKEN');\nFilter events on the client side:
class EventFilter {\n constructor(conditions) {\n this.conditions = conditions;\n }\n\n matches(event) {\n return Object.entries(this.conditions).every(([key, value]) => {\n if (Array.isArray(value)) {\n return value.includes(event[key]);\n }\n return event[key] === value;\n });\n }\n}\n\n// Usage\nconst filter = new EventFilter({\n domain: ['light', 'switch'],\n state: 'on'\n});\n\neventSource.onmessage = (event) => {\n const data = JSON.parse(event.data);\n if (filter.matches(data)) {\n console.log('Matched event:', data);\n }\n};\nHandle authentication errors gracefully
Error Handling
Notify users of connection status
Resource Management
Use filtered subscriptions when possible
Performance
If the connection drops, the EventSource will automatically attempt to reconnect. You can customize this behavior:
eventSource.addEventListener('error', (error) => {\n if (eventSource.readyState === EventSource.CLOSED) {\n // Connection closed, implement custom retry logic\n }\n});\nAlways clean up EventSource connections:
// In a React component\nuseEffect(() => {\n const eventSource = new EventSource('http://localhost:3000/subscribe_events');\n\n return () => {\n eventSource.close(); // Cleanup on unmount\n };\n}, []);\nThis guide outlines the best practices for developing tools and features for the Home Assistant MCP.
"},{"location":"development/best-practices/#code-style","title":"Code Style","text":""},{"location":"development/best-practices/#typescript","title":"TypeScript","text":"any type/** \n * Represents a device in the system.\n * @interface\n */\ninterface Device {\n /** Unique device identifier */\n id: string;\n\n /** Human-readable device name */\n name: string;\n\n /** Device state */\n state: DeviceState;\n}\nEnums
Use camelCase for:
Properties
Use UPPER_SNAKE_CASE for:
class DeviceManager {\n private readonly DEFAULT_TIMEOUT = 5000;\n\n async getDeviceState(deviceId: string): Promise<DeviceState> {\n // Implementation\n }\n}\nSplit complex functionality
Open/Closed
Closed for modification
Liskov Substitution
Use interfaces properly
Interface Segregation
Split large interfaces
Dependency Inversion
// Bad\nclass DeviceManager {\n async getState() { /* ... */ }\n async setState() { /* ... */ }\n async sendNotification() { /* ... */ } // Wrong responsibility\n}\n\n// Good\nclass DeviceManager {\n constructor(\n private notifier: NotificationService\n ) {}\n\n async getState() { /* ... */ }\n async setState() { /* ... */ }\n}\n\nclass NotificationService {\n async send() { /* ... */ }\n}\nclass DeviceError extends Error {\n constructor(\n message: string,\n public code: string,\n public context: Record<string, any>\n ) {\n super(message);\n this.name = 'DeviceError';\n }\n}\n\ntry {\n await device.connect();\n} catch (error) {\n throw new DeviceError(\n 'Failed to connect to device',\n 'DEVICE_CONNECTION_ERROR',\n { deviceId: device.id, attempt: 1 }\n );\n}\ndescribe('DeviceManager', () => {\n let manager: DeviceManager;\n let mockDevice: jest.Mocked<Device>;\n\n beforeEach(() => {\n mockDevice = {\n id: 'test_device',\n getState: jest.fn()\n };\n manager = new DeviceManager(mockDevice);\n });\n\n it('should get device state', async () => {\n mockDevice.getState.mockResolvedValue('on');\n const state = await manager.getDeviceState();\n expect(state).toBe('on');\n });\n});\nclass DeviceCache {\n private cache = new Map<string, CacheEntry>();\n private readonly TTL = 60000; // 1 minute\n\n async getDevice(id: string): Promise<Device> {\n const cached = this.cache.get(id);\n if (cached && Date.now() - cached.timestamp < this.TTL) {\n return cached.device;\n }\n\n const device = await this.fetchDevice(id);\n this.cache.set(id, {\n device,\n timestamp: Date.now()\n });\n\n return device;\n }\n}\nclass InputValidator {\n static validateDeviceId(id: string): boolean {\n return /^[a-zA-Z0-9_-]{1,64}$/.test(id);\n }\n\n static sanitizeOutput(data: any): any {\n // Implement output sanitization\n return data;\n }\n}\n/**\n * Manages device operations.\n * @class\n */\nclass DeviceManager {\n /**\n * Gets the current state of a device.\n * @param {string} deviceId - The device identifier.\n * @returns {Promise<DeviceState>} The current device state.\n * @throws {DeviceError} If device is not found or unavailable.\n * @example\n * const state = await deviceManager.getDeviceState('living_room_light');\n */\n async getDeviceState(deviceId: string): Promise<DeviceState> {\n // Implementation\n }\n}\nclass Logger {\n info(message: string, context: Record<string, any>) {\n console.log(JSON.stringify({\n level: 'info',\n message,\n context,\n timestamp: new Date().toISOString(),\n correlationId: context.correlationId\n }));\n }\n}\n# Good commit messages\ngit commit -m \"feat(device): add support for zigbee devices\"\ngit commit -m \"fix(api): handle timeout errors properly\"\nThis guide provides information for developers who want to contribute to or extend the Home Assistant MCP.
"},{"location":"development/development/#project-structure","title":"Project Structure","text":"homeassistant-mcp/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 __tests__/ # Test files\n\u2502 \u251c\u2500\u2500 __mocks__/ # Mock files\n\u2502 \u251c\u2500\u2500 api/ # API endpoints and route handlers\n\u2502 \u251c\u2500\u2500 config/ # Configuration management\n\u2502 \u251c\u2500\u2500 hass/ # Home Assistant integration\n\u2502 \u251c\u2500\u2500 interfaces/ # TypeScript interfaces\n\u2502 \u251c\u2500\u2500 mcp/ # MCP core functionality\n\u2502 \u251c\u2500\u2500 middleware/ # Express middleware\n\u2502 \u251c\u2500\u2500 routes/ # Route definitions\n\u2502 \u251c\u2500\u2500 security/ # Security utilities\n\u2502 \u251c\u2500\u2500 sse/ # Server-Sent Events handling\n\u2502 \u251c\u2500\u2500 tools/ # Tool implementations\n\u2502 \u251c\u2500\u2500 types/ # TypeScript type definitions\n\u2502 \u2514\u2500\u2500 utils/ # Utility functions\n\u251c\u2500\u2500 __tests__/ # Test files\n\u251c\u2500\u2500 docs/ # Documentation\n\u251c\u2500\u2500 dist/ # Compiled JavaScript\n\u2514\u2500\u2500 scripts/ # Build and utility scripts\nInstall dependencies:
npm install\nSet up development environment:
cp .env.example .env.development\nStart development server:
npm run dev\nWe follow these coding standards:
any typesDocument complex types
ESLint rules
npm run lint to checkRun npm run lint:fix to auto-fix
Code formatting
npm run format to format codeUnit tests:
npm run test\nIntegration tests:
npm run test:integration\nCoverage report:
npm run test:coverage\nCreate a new file in src/tools/:
import { z } from 'zod';\nimport { Tool } from '../types';\n\nexport const myTool: Tool = {\n name: 'my_tool',\n description: 'Description of my tool',\n parameters: z.object({\n // Define parameters\n }),\n execute: async (params) => {\n // Implement tool logic\n }\n};\nAdd to src/tools/index.ts
__tests__/tools/docs/tools/Development build:
npm run build:dev\nProduction build:
npm run build\nDevelopment debugging:
npm run dev:debug\nTest debugging:
npm run test:debug\nVSCode launch configurations provided
Build for production:
npm run build\nStart production server:
npm start\nDocker deployment:
docker-compose up -d\nNeed development help? 1. Check documentation 2. Search issues 3. Create new issue 4. Join discussions
"},{"location":"development/interfaces/","title":"Interface Documentation","text":"This document describes the core interfaces used throughout the Home Assistant MCP.
"},{"location":"development/interfaces/#core-interfaces","title":"Core Interfaces","text":""},{"location":"development/interfaces/#tool-interface","title":"Tool Interface","text":"interface Tool {\n /** Unique identifier for the tool */\n id: string;\n\n /** Human-readable name */\n name: string;\n\n /** Detailed description */\n description: string;\n\n /** Semantic version */\n version: string;\n\n /** Tool category */\n category: ToolCategory;\n\n /** Execute tool functionality */\n execute(params: any): Promise<ToolResult>;\n}\ninterface ToolResult {\n /** Operation success status */\n success: boolean;\n\n /** Response data */\n data?: any;\n\n /** Error message if failed */\n message?: string;\n\n /** Error code if failed */\n error_code?: string;\n}\nenum ToolCategory {\n DeviceManagement = 'device_management',\n HistoryState = 'history_state',\n Automation = 'automation',\n AddonsPackages = 'addons_packages',\n Notifications = 'notifications',\n Events = 'events',\n Utility = 'utility'\n}\ninterface EventSubscription {\n /** Unique subscription ID */\n id: string;\n\n /** Event type to subscribe to */\n event_type: string;\n\n /** Optional entity ID filter */\n entity_id?: string;\n\n /** Optional domain filter */\n domain?: string;\n\n /** Subscription creation timestamp */\n created_at: string;\n\n /** Last event timestamp */\n last_event?: string;\n}\ninterface EventMessage {\n /** Event type */\n event_type: string;\n\n /** Entity ID if applicable */\n entity_id?: string;\n\n /** Event data */\n data: any;\n\n /** Event origin */\n origin: 'LOCAL' | 'REMOTE';\n\n /** Event timestamp */\n time_fired: string;\n\n /** Event context */\n context: EventContext;\n}\ninterface Device {\n /** Device ID */\n id: string;\n\n /** Device name */\n name: string;\n\n /** Device domain */\n domain: string;\n\n /** Current state */\n state: string;\n\n /** Device attributes */\n attributes: Record<string, any>;\n\n /** Device capabilities */\n capabilities: DeviceCapabilities;\n}\ninterface DeviceCapabilities {\n /** Supported features */\n features: string[];\n\n /** Supported commands */\n commands: string[];\n\n /** State attributes */\n attributes: {\n /** Attribute name */\n [key: string]: {\n /** Attribute type */\n type: 'string' | 'number' | 'boolean' | 'object';\n /** Attribute description */\n description: string;\n /** Optional value constraints */\n constraints?: {\n min?: number;\n max?: number;\n enum?: any[];\n };\n };\n };\n}\ninterface AuthToken {\n /** Token value */\n token: string;\n\n /** Token type */\n type: 'bearer' | 'jwt';\n\n /** Expiration timestamp */\n expires_at: string;\n\n /** Token refresh info */\n refresh?: {\n token: string;\n expires_at: string;\n };\n}\ninterface User {\n /** User ID */\n id: string;\n\n /** Username */\n username: string;\n\n /** User type */\n type: 'admin' | 'user' | 'service';\n\n /** User permissions */\n permissions: string[];\n}\ninterface ToolError extends Error {\n /** Error code */\n code: string;\n\n /** HTTP status code */\n status: number;\n\n /** Error details */\n details?: Record<string, any>;\n}\ninterface ValidationError {\n /** Error path */\n path: string;\n\n /** Error message */\n message: string;\n\n /** Error code */\n code: string;\n}\ninterface ToolConfig {\n /** Enable/disable tool */\n enabled: boolean;\n\n /** Tool-specific settings */\n settings: Record<string, any>;\n\n /** Rate limiting */\n rate_limit?: {\n /** Max requests */\n max: number;\n /** Time window in seconds */\n window: number;\n };\n}\ninterface SystemConfig {\n /** System name */\n name: string;\n\n /** Environment */\n environment: 'development' | 'production';\n\n /** Log level */\n log_level: 'debug' | 'info' | 'warn' | 'error';\n\n /** Tool configurations */\n tools: Record<string, ToolConfig>;\n}\nThis guide provides instructions for migrating test files from Jest to Bun's test framework.
"},{"location":"development/test-migration-guide/#table-of-contents","title":"Table of Contents","text":"Remove Jest-related dependencies from package.json:
{\n \"devDependencies\": {\n \"@jest/globals\": \"...\",\n \"jest\": \"...\",\n \"ts-jest\": \"...\"\n }\n}\nRemove Jest configuration files:
jest.config.jsjest.setup.js
Update test scripts in package.json:
{\n \"scripts\": {\n \"test\": \"bun test\",\n \"test:watch\": \"bun test --watch\",\n \"test:coverage\": \"bun test --coverage\"\n }\n}\nimport { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals';\nimport { describe, expect, test, beforeEach, afterEach, mock } from \"bun:test\";\nimport type { Mock } from \"bun:test\";\nNote: it is replaced with test in Bun.
// Jest\ndescribe('Suite', () => {\n it('should do something', () => {\n // test\n });\n});\n\n// Bun\ndescribe('Suite', () => {\n test('should do something', () => {\n // test\n });\n});\nMost Jest assertions work the same in Bun:
// These work the same in both:\nexpect(value).toBe(expected);\nexpect(value).toEqual(expected);\nexpect(value).toBeDefined();\nexpect(value).toBeUndefined();\nexpect(value).toBeTruthy();\nexpect(value).toBeFalsy();\nexpect(array).toContain(item);\nexpect(value).toBeInstanceOf(Class);\nexpect(spy).toHaveBeenCalled();\nexpect(spy).toHaveBeenCalledWith(...args);\nconst mockFn = jest.fn();\nmockFn.mockImplementation(() => 'result');\nmockFn.mockResolvedValue('result');\nmockFn.mockRejectedValue(new Error());\nconst mockFn = mock(() => 'result');\nconst mockAsyncFn = mock(() => Promise.resolve('result'));\nconst mockErrorFn = mock(() => Promise.reject(new Error()));\njest.mock('module-name', () => ({\n default: jest.fn(),\n namedExport: jest.fn()\n}));\n// Option 1: Using vi.mock (if available)\nvi.mock('module-name', () => ({\n default: mock(() => {}),\n namedExport: mock(() => {})\n}));\n\n// Option 2: Using dynamic imports\nconst mockModule = {\n default: mock(() => {}),\n namedExport: mock(() => {})\n};\njest.clearAllMocks();\nmockFn.mockClear();\njest.resetModules();\nmockFn.mockReset();\n// or for specific calls\nmockFn.mock.calls = [];\njest.spyOn(object, 'method');\nconst spy = mock(((...args) => object.method(...args)));\nobject.method = spy;\n// Works the same in both Jest and Bun:\ntest('async test', async () => {\n const result = await someAsyncFunction();\n expect(result).toBe(expected);\n});\ndescribe('Suite', () => {\n beforeEach(() => {\n // setup\n });\n\n afterEach(() => {\n // cleanup\n });\n\n test('test', () => {\n // test\n });\n});\n// Before (Jest)\nglobal.fetch = jest.fn(() => Promise.resolve(new Response()));\n\n// After (Bun)\nconst mockFetch = mock(() => Promise.resolve(new Response()));\nglobal.fetch = mockFetch as unknown as typeof fetch;\n// Create a MockWebSocket class implementing WebSocket interface\nclass MockWebSocket implements WebSocket {\n public static readonly CONNECTING = 0;\n public static readonly OPEN = 1;\n public static readonly CLOSING = 2;\n public static readonly CLOSED = 3;\n\n public readyState: 0 | 1 | 2 | 3 = MockWebSocket.OPEN;\n public addEventListener = mock(() => undefined);\n public removeEventListener = mock(() => undefined);\n public send = mock(() => undefined);\n public close = mock(() => undefined);\n // ... implement other required methods\n}\n\n// Use it in tests\nglobal.WebSocket = MockWebSocket as unknown as typeof WebSocket;\nimport { describe, expect, test } from \"bun:test\";\n\ndescribe('formatToolCall', () => {\n test('should format an object into the correct structure', () => {\n const testObj = { name: 'test', value: 123 };\n const result = formatToolCall(testObj);\n\n expect(result).toEqual({\n content: [{\n type: 'text',\n text: JSON.stringify(testObj, null, 2),\n isError: false\n }]\n });\n });\n});\nimport { describe, expect, test, mock } from \"bun:test\";\n\ndescribe('API Client', () => {\n test('should fetch data', async () => {\n const mockResponse = { data: 'test' };\n const mockFetch = mock(() => Promise.resolve(new Response(\n JSON.stringify(mockResponse),\n { status: 200, headers: new Headers() }\n )));\n global.fetch = mockFetch as unknown as typeof fetch;\n\n const result = await apiClient.getData();\n expect(result).toEqual(mockResponse);\n });\n});\nimport { describe, expect, test, mock } from \"bun:test\";\nimport type { Mock } from \"bun:test\";\n\ninterface MockServices {\n light: {\n turn_on: Mock<() => Promise<{ success: boolean }>>;\n turn_off: Mock<() => Promise<{ success: boolean }>>;\n };\n}\n\nconst mockServices: MockServices = {\n light: {\n turn_on: mock(() => Promise.resolve({ success: true })),\n turn_off: mock(() => Promise.resolve({ success: true }))\n }\n};\n\ndescribe('Home Assistant Service', () => {\n test('should control lights', async () => {\n const result = await mockServices.light.turn_on();\n expect(result.success).toBe(true);\n });\n});\nafterEach blocksdescribe blocks// Solution: Use proper typing with Mock type\nimport type { Mock } from \"bun:test\";\nconst mockFn: Mock<() => string> = mock(() => \"result\");\n// Solution: Use type assertions carefully\nglobal.someGlobal = mockImplementation as unknown as typeof someGlobal;\n// Solution: Use dynamic imports or vi.mock if available\nconst mockModule = {\n default: mock(() => mockImplementation)\n};\nThis guide explains how to create new tools for the Home Assistant MCP.
"},{"location":"development/tools/#tool-structure","title":"Tool Structure","text":"Each tool should follow this basic structure:
interface Tool {\n id: string;\n name: string;\n description: string;\n version: string;\n category: ToolCategory;\n execute(params: any): Promise<ToolResult>;\n}\nimport { Tool, ToolCategory, ToolResult } from '../interfaces';\n\nexport class MyCustomTool implements Tool {\n id = 'my_custom_tool';\n name = 'My Custom Tool';\n description = 'Description of what the tool does';\n version = '1.0.0';\n category = ToolCategory.Utility;\n\n async execute(params: any): Promise<ToolResult> {\n // Tool implementation\n return {\n success: true,\n data: {\n // Tool-specific response data\n }\n };\n }\n}\nimport { Router } from 'express';\nimport { MyCustomTool } from './my-custom-tool';\n\nconst router = Router();\nconst tool = new MyCustomTool();\n\nrouter.post('/api/tools/custom', async (req, res) => {\n try {\n const result = await tool.execute(req.body);\n res.json(result);\n } catch (error) {\n res.status(500).json({\n success: false,\n message: error.message\n });\n }\n});\nimport { WebSocketServer } from 'ws';\nimport { MyCustomTool } from './my-custom-tool';\n\nconst tool = new MyCustomTool();\n\nwss.on('connection', (ws) => {\n ws.on('message', async (message) => {\n const { type, params } = JSON.parse(message);\n if (type === 'my_custom_tool') {\n const result = await tool.execute(params);\n ws.send(JSON.stringify(result));\n }\n });\n});\nclass ToolError extends Error {\n constructor(\n message: string,\n public code: string,\n public status: number = 500\n ) {\n super(message);\n this.name = 'ToolError';\n }\n}\n\n// Usage in tool\nasync execute(params: any): Promise<ToolResult> {\n try {\n // Tool implementation\n } catch (error) {\n throw new ToolError(\n 'Operation failed',\n 'TOOL_ERROR',\n 500\n );\n }\n}\nimport { MyCustomTool } from './my-custom-tool';\n\ndescribe('MyCustomTool', () => {\n let tool: MyCustomTool;\n\n beforeEach(() => {\n tool = new MyCustomTool();\n });\n\n it('should execute successfully', async () => {\n const result = await tool.execute({\n // Test parameters\n });\n expect(result.success).toBe(true);\n });\n\n it('should handle errors', async () => {\n // Error test cases\n });\n});\ndocs/tools/category/tool-name.mdtools/tools.md with tool referencemkdocs.yml# Tool Name\n\nDescription of the tool.\n\n## Features\n\n- Feature 1\n- Feature 2\n\n## Usage\n\n### REST API\n\n```typescript\n// API endpoints\n// WebSocket usage\n// Usage example\n{\n \"success\": true,\n \"data\": {\n // Response data structure\n }\n}\nThis section contains examples and tutorials for common MCP Server integrations.
"},{"location":"examples/#speech-to-text-integration","title":"Speech-to-Text Integration","text":"Example of integrating speech recognition with MCP Server:
// From examples/speech-to-text-example.ts\n// Add example code and explanation\n...
"},{"location":"getting-started/configuration/","title":"Configuration","text":""},{"location":"getting-started/configuration/#basic-configuration","title":"Basic Configuration","text":""},{"location":"getting-started/configuration/#advanced-settings","title":"Advanced Settings","text":""},{"location":"getting-started/docker/","title":"Docker Deployment Guide \ud83d\udc33","text":"Detailed guide for deploying MCP Server with Docker...
"},{"location":"getting-started/installation/","title":"Installation Guide \ud83d\udee0\ufe0f","text":"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.
"},{"location":"getting-started/installation/#prerequisites","title":"Prerequisites","text":"Before installing MCP Server, ensure you have:
The easiest way to install MCP Server is through Smithery:
"},{"location":"getting-started/installation/#smithery-configuration","title":"Smithery Configuration","text":"The project includes a smithery.yaml configuration:
# Add smithery.yaml contents and explanation\nnpx -y @smithery/cli install @jango-blockchained/advanced-homeassistant-mcp --client claude\nFor a containerized deployment:
# Clone the repository\ngit clone --depth 1 https://github.com/jango-blockchained/advanced-homeassistant-mcp.git\ncd advanced-homeassistant-mcp\n\n# Configure environment variables\ncp .env.example .env\n# Edit .env with your Home Assistant details:\n# - HA_URL: Your Home Assistant URL\n# - HA_TOKEN: Your Long-Lived Access Token\n# - Other configuration options\n\n# Build and start containers\ndocker compose up -d --build\n\n# View logs (optional)\ndocker compose logs -f --tail=50\nFor direct installation on your system:
# Install Bun runtime\ncurl -fsSL https://bun.sh/install | bash\n\n# Clone and install\ngit clone https://github.com/jango-blockchained/advanced-homeassistant-mcp.git\ncd advanced-homeassistant-mcp\nbun install --frozen-lockfile\n\n# Configure environment\ncp .env.example .env\n# Edit .env with your configuration\n\n# Start the server\nbun run dev --watch\nKey configuration options in your .env file:
# Home Assistant Configuration\nHA_URL=http://your-homeassistant:8123\nHA_TOKEN=your_long_lived_access_token\n\n# Server Configuration\nPORT=3000\nHOST=0.0.0.0\nNODE_ENV=production\n\n# Security Settings\nJWT_SECRET=your_secure_jwt_secret\nRATE_LIMIT=100\nAdd to .cursor/config/config.json:
{\n \"mcpServers\": {\n \"homeassistant-mcp\": {\n \"command\": \"bun\",\n \"args\": [\"run\", \"start\"],\n \"cwd\": \"${workspaceRoot}\",\n \"env\": {\n \"NODE_ENV\": \"development\"\n }\n }\n }\n}\nAdd to your Claude configuration:
{\n \"mcpServers\": {\n \"homeassistant-mcp\": {\n \"command\": \"bun\",\n \"args\": [\"run\", \"start\", \"--port\", \"8080\"],\n \"env\": {\n \"NODE_ENV\": \"production\"\n }\n }\n }\n}\nTo verify your installation:
Check server status:
curl http://localhost:3000/health\nTest Home Assistant connection:
curl http://localhost:3000/api/state\nIf you encounter issues:
# For Docker installation\ndocker compose logs -f\n\n# For manual installation\nbun run dev\nNeed help? Check our Support Resources or open an issue.
"},{"location":"getting-started/quickstart/","title":"Quick Start Guide \ud83d\ude80","text":"This guide will help you get started with MCP Server after installation. We'll cover basic usage, common commands, and simple integrations.
"},{"location":"getting-started/quickstart/#first-steps","title":"First Steps","text":""},{"location":"getting-started/quickstart/#1-verify-connection","title":"1. Verify Connection","text":"After installation, verify your MCP Server is running and connected to Home Assistant:
# Check server health\ncurl http://localhost:3000/health\n\n# Verify Home Assistant connection\ncurl http://localhost:3000/api/state\nTry these basic voice commands to test your setup:
# Example using curl for testing\ncurl -X POST http://localhost:3000/api/command \\\n -H \"Content-Type: application/json\" \\\n -d '{\"command\": \"Turn on the living room lights\"}'\nCommon voice commands: - \"Turn on/off [device name]\" - \"Set [device] to [value]\" - \"What's the temperature in [room]?\" - \"Is [device] on or off?\"
"},{"location":"getting-started/quickstart/#real-world-examples","title":"Real-World Examples","text":""},{"location":"getting-started/quickstart/#1-smart-lighting-control","title":"1. Smart Lighting Control","text":"// Browser example using fetch\nconst response = await fetch('http://localhost:3000/api/command', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n command: 'Set living room lights to 50% brightness and warm white color'\n })\n});\nSubscribe to device state changes using Server-Sent Events (SSE):
const eventSource = new EventSource('http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light');\n\neventSource.onmessage = (event) => {\n const data = JSON.parse(event.data);\n console.log('Device state changed:', data);\n // Update your UI here\n};\nCreate and trigger scenes for different activities:
// Create a \"Movie Night\" scene\nconst createScene = async () => {\n await fetch('http://localhost:3000/api/scene', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({\n name: 'Movie Night',\n actions: [\n { device: 'living_room_lights', action: 'dim', value: 20 },\n { device: 'tv', action: 'on' },\n { device: 'soundbar', action: 'on' }\n ]\n })\n });\n};\n\n// Trigger the scene with voice command:\n// \"Hey MCP, activate movie night scene\"\n// React component example\nfunction SmartHomeControl() {\n const [devices, setDevices] = useState([]);\n\n useEffect(() => {\n // Subscribe to device updates\n const events = new EventSource('http://localhost:3000/subscribe_events');\n events.onmessage = (event) => {\n const data = JSON.parse(event.data);\n setDevices(currentDevices => \n currentDevices.map(device => \n device.id === data.id ? {...device, ...data} : device\n )\n );\n };\n\n return () => events.close();\n }, []);\n\n return (\n <div className=\"dashboard\">\n {devices.map(device => (\n <DeviceCard key={device.id} device={device} />\n ))}\n </div>\n );\n}\n// Example using speech-to-text with MCP\nasync function handleVoiceCommand(audioBlob: Blob) {\n // First, convert speech to text\n const text = await speechToText(audioBlob);\n\n // Then send command to MCP\n const response = await fetch('http://localhost:3000/api/command', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ command: text })\n });\n\n return response.json();\n}\nError Handling
try {\n const response = await fetch('http://localhost:3000/api/command', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ command: 'Turn on lights' })\n });\n\n if (!response.ok) {\n throw new Error(`HTTP error! status: ${response.status}`);\n }\n\n const data = await response.json();\n} catch (error) {\n console.error('Error:', error);\n // Handle error appropriately\n}\nConnection Management
class MCPConnection {\n constructor() {\n this.eventSource = null;\n this.reconnectAttempts = 0;\n }\n\n connect() {\n this.eventSource = new EventSource('http://localhost:3000/subscribe_events');\n this.eventSource.onerror = this.handleError.bind(this);\n }\n\n handleError() {\n if (this.reconnectAttempts < 3) {\n setTimeout(() => {\n this.reconnectAttempts++;\n this.connect();\n }, 1000 * this.reconnectAttempts);\n }\n }\n}\nIf 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.
"},{"location":"tools/tools/","title":"Home Assistant MCP Tools","text":"This section documents all available tools in the Home Assistant MCP.
"},{"location":"tools/tools/#available-tools","title":"Available Tools","text":""},{"location":"tools/tools/#device-management","title":"Device Management","text":"Get device states and attributes
Device Control
Get significant changes
Scene Management
Trigger automations manually
Automation Configuration
Get add-on information
Package Management
Domain-based monitoring
SSE Statistics
All tools can be accessed through:
Tools require authentication using: - Home Assistant Long-Lived Access Token - JWT tokens for specific operations
"},{"location":"tools/tools/#error-handling","title":"Error Handling","text":"All tools follow a consistent error handling pattern:
{\n success: boolean;\n message?: string;\n data?: any;\n}\nTools are subject to rate limiting: - Default: 100 requests per 15 minutes - Configurable through environment variables
"},{"location":"tools/tools/#tool-development","title":"Tool Development","text":"Want to create a new tool? Check out: - Tool Development Guide - Tool Interface Documentation - Best Practices
"},{"location":"tools/tools/#examples","title":"Examples","text":"Each tool documentation includes: - Usage examples - Code snippets - Common use cases - Troubleshooting tips
"},{"location":"tools/tools/#support","title":"Support","text":"Need help with tools? - Check individual tool documentation - See Troubleshooting Guide - Create an issue on GitHub
"},{"location":"tools/addons-packages/addon/","title":"Add-on Management Tool","text":"The Add-on Management tool provides functionality to manage Home Assistant add-ons through the MCP interface.
"},{"location":"tools/addons-packages/addon/#features","title":"Features","text":"GET /api/addons\nGET /api/addons/{addon_slug}\nPOST /api/addons/{addon_slug}/install\nPOST /api/addons/{addon_slug}/uninstall\nPOST /api/addons/{addon_slug}/start\nPOST /api/addons/{addon_slug}/stop\nPOST /api/addons/{addon_slug}/restart\nGET /api/addons/{addon_slug}/logs\nPUT /api/addons/{addon_slug}/config\nGET /api/addons/{addon_slug}/stats\n// List add-ons\n{\n \"type\": \"get_addons\"\n}\n\n// Get add-on info\n{\n \"type\": \"get_addon_info\",\n \"addon_slug\": \"required_addon_slug\"\n}\n\n// Install add-on\n{\n \"type\": \"install_addon\",\n \"addon_slug\": \"required_addon_slug\",\n \"version\": \"optional_version\"\n}\n\n// Control add-on\n{\n \"type\": \"control_addon\",\n \"addon_slug\": \"required_addon_slug\",\n \"action\": \"start|stop|restart\"\n}\nconst response = await fetch('http://your-ha-mcp/api/addons', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst addons = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/addons/mosquitto/install', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"version\": \"latest\"\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/addons/mosquitto/config', {\n method: 'PUT',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"logins\": [\n {\n \"username\": \"mqtt_user\",\n \"password\": \"mqtt_password\"\n }\n ],\n \"customize\": {\n \"active\": true,\n \"folder\": \"mosquitto\"\n }\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"addons\": [\n {\n \"slug\": \"addon_slug\",\n \"name\": \"Add-on Name\",\n \"version\": \"1.0.0\",\n \"state\": \"started\",\n \"repository\": \"core\",\n \"installed\": true,\n \"update_available\": false\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"addon\": {\n \"slug\": \"addon_slug\",\n \"name\": \"Add-on Name\",\n \"version\": \"1.0.0\",\n \"description\": \"Add-on description\",\n \"long_description\": \"Detailed description\",\n \"repository\": \"core\",\n \"installed\": true,\n \"state\": \"started\",\n \"webui\": \"http://[HOST]:[PORT:80]\",\n \"boot\": \"auto\",\n \"options\": {\n // Add-on specific options\n },\n \"schema\": {\n // Add-on options schema\n },\n \"ports\": {\n \"80/tcp\": 8080\n },\n \"ingress\": true,\n \"ingress_port\": 8099\n }\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"stats\": {\n \"cpu_percent\": 2.5,\n \"memory_usage\": 128974848,\n \"memory_limit\": 536870912,\n \"network_rx\": 1234,\n \"network_tx\": 5678,\n \"blk_read\": 12345,\n \"blk_write\": 67890\n }\n }\n}\n404: Add-on not found401: Unauthorized400: Invalid request409: Add-on operation failed422: Invalid configuration{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nADDON_RATE_LIMITADDON_RATE_WINDOWThe Package Management tool provides functionality to manage Home Assistant Community Store (HACS) packages through the MCP interface.
"},{"location":"tools/addons-packages/package/#features","title":"Features","text":"GET /api/packages\nGET /api/packages/{package_id}\nPOST /api/packages/{package_id}/install\nPOST /api/packages/{package_id}/uninstall\nPOST /api/packages/{package_id}/update\nGET /api/packages/search\nGET /api/packages/categories\nGET /api/packages/repositories\n// List packages\n{\n \"type\": \"get_packages\",\n \"category\": \"optional_category\"\n}\n\n// Search packages\n{\n \"type\": \"search_packages\",\n \"query\": \"search_query\",\n \"category\": \"optional_category\"\n}\n\n// Install package\n{\n \"type\": \"install_package\",\n \"package_id\": \"required_package_id\",\n \"version\": \"optional_version\"\n}\nconst response = await fetch('http://your-ha-mcp/api/packages', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst packages = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/packages/search?q=weather&category=integrations', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst searchResults = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/packages/custom-weather-card/install', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"version\": \"latest\"\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"packages\": [\n {\n \"id\": \"package_id\",\n \"name\": \"Package Name\",\n \"category\": \"integrations\",\n \"description\": \"Package description\",\n \"version\": \"1.0.0\",\n \"installed\": true,\n \"update_available\": false,\n \"stars\": 150,\n \"downloads\": 10000\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"package\": {\n \"id\": \"package_id\",\n \"name\": \"Package Name\",\n \"category\": \"integrations\",\n \"description\": \"Package description\",\n \"long_description\": \"Detailed description\",\n \"version\": \"1.0.0\",\n \"installed_version\": \"0.9.0\",\n \"available_version\": \"1.0.0\",\n \"installed\": true,\n \"update_available\": true,\n \"stars\": 150,\n \"downloads\": 10000,\n \"repository\": \"https://github.com/author/repo\",\n \"author\": {\n \"name\": \"Author Name\",\n \"url\": \"https://github.com/author\"\n },\n \"documentation\": \"https://github.com/author/repo/wiki\",\n \"dependencies\": [\n \"dependency1\",\n \"dependency2\"\n ]\n }\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"results\": [\n {\n \"id\": \"package_id\",\n \"name\": \"Package Name\",\n \"category\": \"integrations\",\n \"description\": \"Package description\",\n \"version\": \"1.0.0\",\n \"score\": 0.95\n }\n ],\n \"total\": 42\n }\n}\n404: Package not found401: Unauthorized400: Invalid request409: Package operation failed422: Invalid configuration424: Dependency error{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nPACKAGE_RATE_LIMITPACKAGE_RATE_WINDOWThe Automation Configuration tool provides functionality to create, update, and manage Home Assistant automation configurations.
"},{"location":"tools/automation/automation-config/#features","title":"Features","text":"POST /api/automations\nPUT /api/automations/{automation_id}\nDELETE /api/automations/{automation_id}\nPOST /api/automations/{automation_id}/duplicate\nPOST /api/automations/validate\n// Create automation\n{\n \"type\": \"create_automation\",\n \"automation\": {\n // Automation configuration\n }\n}\n\n// Update automation\n{\n \"type\": \"update_automation\",\n \"automation_id\": \"required_automation_id\",\n \"automation\": {\n // Updated configuration\n }\n}\n\n// Delete automation\n{\n \"type\": \"delete_automation\",\n \"automation_id\": \"required_automation_id\"\n}\n{\n \"id\": \"morning_routine\",\n \"alias\": \"Morning Routine\",\n \"description\": \"Turn on lights and adjust temperature in the morning\",\n \"trigger\": [\n {\n \"platform\": \"time\",\n \"at\": \"07:00:00\"\n }\n ],\n \"condition\": [\n {\n \"condition\": \"time\",\n \"weekday\": [\"mon\", \"tue\", \"wed\", \"thu\", \"fri\"]\n }\n ],\n \"action\": [\n {\n \"service\": \"light.turn_on\",\n \"target\": {\n \"entity_id\": \"light.bedroom\"\n },\n \"data\": {\n \"brightness\": 255,\n \"transition\": 300\n }\n }\n ],\n \"mode\": \"single\"\n}\n// Time-based trigger\n{\n \"platform\": \"time\",\n \"at\": \"07:00:00\"\n}\n\n// State-based trigger\n{\n \"platform\": \"state\",\n \"entity_id\": \"binary_sensor.motion\",\n \"to\": \"on\"\n}\n\n// Event-based trigger\n{\n \"platform\": \"event\",\n \"event_type\": \"custom_event\"\n}\n\n// Numeric state trigger\n{\n \"platform\": \"numeric_state\",\n \"entity_id\": \"sensor.temperature\",\n \"above\": 25\n}\n// Time condition\n{\n \"condition\": \"time\",\n \"after\": \"07:00:00\",\n \"before\": \"22:00:00\"\n}\n\n// State condition\n{\n \"condition\": \"state\",\n \"entity_id\": \"device_tracker.phone\",\n \"state\": \"home\"\n}\n\n// Numeric state condition\n{\n \"condition\": \"numeric_state\",\n \"entity_id\": \"sensor.temperature\",\n \"below\": 25\n}\n// Service call action\n{\n \"service\": \"light.turn_on\",\n \"target\": {\n \"entity_id\": \"light.bedroom\"\n }\n}\n\n// Delay action\n{\n \"delay\": \"00:00:30\"\n}\n\n// Scene activation\n{\n \"scene\": \"scene.evening_mode\"\n}\n\n// Conditional action\n{\n \"choose\": [\n {\n \"conditions\": [\n {\n \"condition\": \"state\",\n \"entity_id\": \"sun.sun\",\n \"state\": \"below_horizon\"\n }\n ],\n \"sequence\": [\n {\n \"service\": \"light.turn_on\",\n \"target\": {\n \"entity_id\": \"light.living_room\"\n }\n }\n ]\n }\n ]\n}\nconst response = await fetch('http://your-ha-mcp/api/automations', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"alias\": \"Morning Routine\",\n \"description\": \"Turn on lights in the morning\",\n \"trigger\": [\n {\n \"platform\": \"time\",\n \"at\": \"07:00:00\"\n }\n ],\n \"action\": [\n {\n \"service\": \"light.turn_on\",\n \"target\": {\n \"entity_id\": \"light.bedroom\"\n }\n }\n ]\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/automations/morning_routine', {\n method: 'PUT',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"alias\": \"Morning Routine\",\n \"trigger\": [\n {\n \"platform\": \"time\",\n \"at\": \"07:30:00\" // Updated time\n }\n ],\n \"action\": [\n {\n \"service\": \"light.turn_on\",\n \"target\": {\n \"entity_id\": \"light.bedroom\"\n }\n }\n ]\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"automation\": {\n \"id\": \"created_automation_id\",\n // Full automation configuration\n }\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"valid\": true,\n \"warnings\": [\n \"No conditions specified\"\n ]\n }\n}\n404: Automation not found401: Unauthorized400: Invalid configuration409: Automation creation/update failed{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\",\n \"validation_errors\": [\n {\n \"path\": \"trigger[0].platform\",\n \"message\": \"Invalid trigger platform\"\n }\n ]\n}\nThe Automation Management tool provides functionality to manage and control Home Assistant automations.
"},{"location":"tools/automation/automation/#features","title":"Features","text":"GET /api/automations\nGET /api/automations/{automation_id}\nPOST /api/automations/{automation_id}/toggle\nPOST /api/automations/{automation_id}/trigger\nGET /api/automations/{automation_id}/history\n// List automations\n{\n \"type\": \"get_automations\"\n}\n\n// Toggle automation\n{\n \"type\": \"toggle_automation\",\n \"automation_id\": \"required_automation_id\"\n}\n\n// Trigger automation\n{\n \"type\": \"trigger_automation\",\n \"automation_id\": \"required_automation_id\",\n \"variables\": {\n // Optional variables\n }\n}\nconst response = await fetch('http://your-ha-mcp/api/automations', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst automations = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/automations/morning_routine/toggle', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst response = await fetch('http://your-ha-mcp/api/automations/morning_routine/trigger', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"variables\": {\n \"brightness\": 100,\n \"temperature\": 22\n }\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"automations\": [\n {\n \"id\": \"automation_id\",\n \"name\": \"Automation Name\",\n \"enabled\": true,\n \"last_triggered\": \"2024-02-05T12:00:00Z\",\n \"trigger_count\": 42\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"automation\": {\n \"id\": \"automation_id\",\n \"name\": \"Automation Name\",\n \"enabled\": true,\n \"triggers\": [\n {\n \"platform\": \"time\",\n \"at\": \"07:00:00\"\n }\n ],\n \"conditions\": [],\n \"actions\": [\n {\n \"service\": \"light.turn_on\",\n \"target\": {\n \"entity_id\": \"light.bedroom\"\n }\n }\n ],\n \"mode\": \"single\",\n \"max\": 10,\n \"last_triggered\": \"2024-02-05T12:00:00Z\",\n \"trigger_count\": 42\n }\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"history\": [\n {\n \"timestamp\": \"2024-02-05T12:00:00Z\",\n \"trigger\": {\n \"platform\": \"time\",\n \"at\": \"07:00:00\"\n },\n \"context\": {\n \"user_id\": \"user_123\",\n \"variables\": {}\n },\n \"result\": \"success\"\n }\n ]\n }\n}\n404: Automation not found401: Unauthorized400: Invalid request409: Automation execution failed{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nAUTOMATION_RATE_LIMITAUTOMATION_RATE_WINDOWThe Device Control tool provides functionality to control various types of devices in your Home Assistant instance.
"},{"location":"tools/device-management/control/#supported-device-types","title":"Supported Device Types","text":"POST /api/devices/{device_id}/control\n{\n \"type\": \"control_device\",\n \"device_id\": \"required_device_id\",\n \"domain\": \"required_domain\",\n \"service\": \"required_service\",\n \"data\": {\n // Service-specific data\n }\n}\n// Turn on/off\nPOST /api/devices/light/{device_id}/control\n{\n \"service\": \"turn_on\", // or \"turn_off\"\n}\n\n// Set brightness\n{\n \"service\": \"turn_on\",\n \"data\": {\n \"brightness\": 255 // 0-255\n }\n}\n\n// Set color\n{\n \"service\": \"turn_on\",\n \"data\": {\n \"rgb_color\": [255, 0, 0] // Red\n }\n}\n// Open/close\nPOST /api/devices/cover/{device_id}/control\n{\n \"service\": \"open_cover\", // or \"close_cover\"\n}\n\n// Set position\n{\n \"service\": \"set_cover_position\",\n \"data\": {\n \"position\": 50 // 0-100\n }\n}\n// Set temperature\nPOST /api/devices/climate/{device_id}/control\n{\n \"service\": \"set_temperature\",\n \"data\": {\n \"temperature\": 22.5\n }\n}\n\n// Set mode\n{\n \"service\": \"set_hvac_mode\",\n \"data\": {\n \"hvac_mode\": \"heat\" // heat, cool, auto, off\n }\n}\nconst response = await fetch('http://your-ha-mcp/api/devices/light/living_room/control', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"service\": \"turn_on\",\n \"data\": {\n \"brightness\": 128\n }\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/devices/cover/bedroom/control', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"service\": \"set_cover_position\",\n \"data\": {\n \"position\": 75\n }\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"state\": \"on\",\n \"attributes\": {\n // Updated device attributes\n }\n }\n}\n{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\n404: Device not found401: Unauthorized400: Invalid service or parameters409: Device unavailable or offlineDEVICE_CONTROL_RATE_LIMITDEVICE_CONTROL_RATE_WINDOWThe List Devices tool provides functionality to retrieve and manage device information from your Home Assistant instance.
"},{"location":"tools/device-management/list-devices/#features","title":"Features","text":"GET /api/devices\nGET /api/devices/{domain}\nGET /api/devices/{device_id}/state\n// List all devices\n{\n \"type\": \"list_devices\",\n \"domain\": \"optional_domain\"\n}\n\n// Get device state\n{\n \"type\": \"get_device_state\",\n \"device_id\": \"required_device_id\"\n}\nconst response = await fetch('http://your-ha-mcp/api/devices', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst devices = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/devices/light', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst lightDevices = await response.json();\n{\n \"success\": true,\n \"data\": {\n \"devices\": [\n {\n \"id\": \"device_id\",\n \"name\": \"Device Name\",\n \"domain\": \"light\",\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255,\n \"color_temp\": 370\n }\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255,\n \"color_temp\": 370\n },\n \"last_changed\": \"2024-02-05T12:00:00Z\",\n \"last_updated\": \"2024-02-05T12:00:00Z\"\n }\n}\n404: Device not found401: Unauthorized400: Invalid request parameters{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nDEVICE_LIST_RATE_LIMITDEVICE_LIST_RATE_WINDOWThe SSE Statistics tool provides functionality to monitor and analyze Server-Sent Events (SSE) connections and performance in your Home Assistant MCP instance.
"},{"location":"tools/events/sse-stats/#features","title":"Features","text":"GET /api/sse/stats\nGET /api/sse/connections\nGET /api/sse/connections/{connection_id}\nGET /api/sse/metrics\nGET /api/sse/history\n// Get SSE stats\n{\n \"type\": \"get_sse_stats\"\n}\n\n// Get connection details\n{\n \"type\": \"get_sse_connection\",\n \"connection_id\": \"required_connection_id\"\n}\n\n// Get performance metrics\n{\n \"type\": \"get_sse_metrics\",\n \"period\": \"1h|24h|7d|30d\"\n}\nconst response = await fetch('http://your-ha-mcp/api/sse/stats', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst stats = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/sse/connections/conn_123', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst connection = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/sse/metrics?period=24h', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst metrics = await response.json();\n{\n \"success\": true,\n \"data\": {\n \"active_connections\": 42,\n \"total_events_sent\": 12345,\n \"events_per_second\": 5.2,\n \"memory_usage\": 128974848,\n \"cpu_usage\": 2.5,\n \"uptime\": \"PT24H\",\n \"event_backlog\": 0\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"connection\": {\n \"id\": \"conn_123\",\n \"client_id\": \"client_456\",\n \"user_id\": \"user_789\",\n \"connected_at\": \"2024-02-05T12:00:00Z\",\n \"last_event_at\": \"2024-02-05T12:05:00Z\",\n \"events_sent\": 150,\n \"subscriptions\": [\n {\n \"event_type\": \"state_changed\",\n \"entity_id\": \"light.living_room\"\n }\n ],\n \"state\": \"active\",\n \"ip_address\": \"192.168.1.100\",\n \"user_agent\": \"Mozilla/5.0 ...\"\n }\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"metrics\": {\n \"connections\": {\n \"current\": 42,\n \"max\": 100,\n \"average\": 35.5\n },\n \"events\": {\n \"total\": 12345,\n \"rate\": {\n \"current\": 5.2,\n \"max\": 15.0,\n \"average\": 4.8\n }\n },\n \"latency\": {\n \"p50\": 15,\n \"p95\": 45,\n \"p99\": 100\n },\n \"resources\": {\n \"memory\": {\n \"current\": 128974848,\n \"max\": 536870912\n },\n \"cpu\": {\n \"current\": 2.5,\n \"max\": 10.0,\n \"average\": 3.2\n }\n }\n },\n \"period\": \"24h\",\n \"timestamp\": \"2024-02-05T12:00:00Z\"\n }\n}\n404: Connection not found401: Unauthorized400: Invalid request parameters503: Service overloaded{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nThe Event Subscription tool provides functionality to subscribe to and monitor real-time events from your Home Assistant instance.
"},{"location":"tools/events/subscribe-events/#features","title":"Features","text":"POST /api/events/subscribe\nDELETE /api/events/unsubscribe\nGET /api/events/subscriptions\nGET /api/events/history\n// Subscribe to events\n{\n \"type\": \"subscribe_events\",\n \"event_type\": \"optional_event_type\",\n \"entity_id\": \"optional_entity_id\",\n \"domain\": \"optional_domain\"\n}\n\n// Unsubscribe from events\n{\n \"type\": \"unsubscribe_events\",\n \"subscription_id\": \"required_subscription_id\"\n}\nGET /api/events/stream?event_type=state_changed&entity_id=light.living_room\nstate_changed: Entity state changesautomation_triggered: Automation executionsscene_activated: Scene activationsdevice_registered: New device registrationsservice_registered: New service registrationshomeassistant_start: System startuphomeassistant_stop: System shutdownconst response = await fetch('http://your-ha-mcp/api/events/subscribe', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"event_type\": \"state_changed\"\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/events/subscribe', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"event_type\": \"state_changed\",\n \"entity_id\": \"light.living_room\"\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/events/subscribe', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"event_type\": \"state_changed\",\n \"domain\": \"light\"\n })\n});\nconst eventSource = new EventSource(\n 'http://your-ha-mcp/api/events/stream?event_type=state_changed&entity_id=light.living_room',\n {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n }\n);\n\neventSource.onmessage = (event) => {\n const data = JSON.parse(event.data);\n console.log('Event received:', data);\n};\n\neventSource.onerror = (error) => {\n console.error('SSE error:', error);\n eventSource.close();\n};\n{\n \"success\": true,\n \"data\": {\n \"subscription_id\": \"sub_123\",\n \"event_type\": \"state_changed\",\n \"entity_id\": \"light.living_room\",\n \"created_at\": \"2024-02-05T12:00:00Z\"\n }\n}\n{\n \"event_type\": \"state_changed\",\n \"entity_id\": \"light.living_room\",\n \"data\": {\n \"old_state\": {\n \"state\": \"off\",\n \"attributes\": {},\n \"last_changed\": \"2024-02-05T11:55:00Z\"\n },\n \"new_state\": {\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255\n },\n \"last_changed\": \"2024-02-05T12:00:00Z\"\n }\n },\n \"origin\": \"LOCAL\",\n \"time_fired\": \"2024-02-05T12:00:00Z\",\n \"context\": {\n \"id\": \"context_123\",\n \"parent_id\": null,\n \"user_id\": \"user_123\"\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"subscriptions\": [\n {\n \"id\": \"sub_123\",\n \"event_type\": \"state_changed\",\n \"entity_id\": \"light.living_room\",\n \"created_at\": \"2024-02-05T12:00:00Z\",\n \"last_event\": \"2024-02-05T12:05:00Z\"\n }\n ]\n }\n}\n404: Event type not found401: Unauthorized400: Invalid subscription parameters409: Subscription already exists429: Too many subscriptions{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nEVENT_SUB_MAX_SUBSCRIPTIONSEVENT_SUB_RATE_LIMITEVENT_SUB_RATE_WINDOWThe Device History tool allows you to retrieve historical state information for devices in your Home Assistant instance.
"},{"location":"tools/history-state/history/#features","title":"Features","text":"GET /api/history/{device_id}\nGET /api/history/{device_id}/period/{start_time}\nGET /api/history/{device_id}/period/{start_time}/{end_time}\n{\n \"type\": \"get_history\",\n \"device_id\": \"required_device_id\",\n \"start_time\": \"optional_iso_timestamp\",\n \"end_time\": \"optional_iso_timestamp\",\n \"significant_changes_only\": false\n}\nstart_time ISO timestamp Start of the period to fetch history for end_time ISO timestamp End of the period to fetch history for significant_changes_only boolean Only return significant state changes minimal_response boolean Return minimal state information no_attributes boolean Exclude attribute data from response"},{"location":"tools/history-state/history/#examples","title":"Examples","text":""},{"location":"tools/history-state/history/#get-recent-history","title":"Get Recent History","text":"const response = await fetch('http://your-ha-mcp/api/history/light.living_room', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst history = await response.json();\nconst startTime = '2024-02-01T00:00:00Z';\nconst endTime = '2024-02-02T00:00:00Z';\nconst response = await fetch(\n `http://your-ha-mcp/api/history/light.living_room/period/${startTime}/${endTime}`, \n {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n }\n);\nconst history = await response.json();\n{\n \"success\": true,\n \"data\": {\n \"history\": [\n {\n \"state\": \"on\",\n \"attributes\": {\n \"brightness\": 255\n },\n \"last_changed\": \"2024-02-05T12:00:00Z\",\n \"last_updated\": \"2024-02-05T12:00:00Z\"\n },\n {\n \"state\": \"off\",\n \"last_changed\": \"2024-02-05T13:00:00Z\",\n \"last_updated\": \"2024-02-05T13:00:00Z\"\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"aggregates\": {\n \"daily\": [\n {\n \"date\": \"2024-02-05\",\n \"on_time\": \"PT5H30M\",\n \"off_time\": \"PT18H30M\",\n \"changes\": 10\n }\n ]\n }\n }\n}\n404: Device not found401: Unauthorized400: Invalid parameters416: Time range too large{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nHISTORY_RATE_LIMITHISTORY_RATE_WINDOWHISTORY_RETENTION_DAYSsignificant_changes_only for better performanceminimal_response when full state data isn't neededThe Scene Management tool provides functionality to manage and control scenes in your Home Assistant instance.
"},{"location":"tools/history-state/scene/#features","title":"Features","text":"GET /api/scenes\nGET /api/scenes/{scene_id}\nPOST /api/scenes/{scene_id}/activate\nPOST /api/scenes\nPUT /api/scenes/{scene_id}\nDELETE /api/scenes/{scene_id}\n// List scenes\n{\n \"type\": \"get_scenes\"\n}\n\n// Activate scene\n{\n \"type\": \"activate_scene\",\n \"scene_id\": \"required_scene_id\"\n}\n\n// Create/Update scene\n{\n \"type\": \"create_scene\",\n \"scene\": {\n \"name\": \"required_scene_name\",\n \"entities\": {\n // Entity states\n }\n }\n}\n{\n \"name\": \"Movie Night\",\n \"entities\": {\n \"light.living_room\": {\n \"state\": \"on\",\n \"brightness\": 50,\n \"color_temp\": 2700\n },\n \"cover.living_room\": {\n \"state\": \"closed\"\n },\n \"media_player.tv\": {\n \"state\": \"on\",\n \"source\": \"HDMI 1\"\n }\n }\n}\nconst response = await fetch('http://your-ha-mcp/api/scenes', {\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst scenes = await response.json();\nconst response = await fetch('http://your-ha-mcp/api/scenes/movie_night/activate', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token'\n }\n});\nconst response = await fetch('http://your-ha-mcp/api/scenes', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"name\": \"Movie Night\",\n \"entities\": {\n \"light.living_room\": {\n \"state\": \"on\",\n \"brightness\": 50\n },\n \"cover.living_room\": {\n \"state\": \"closed\"\n }\n }\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"scenes\": [\n {\n \"id\": \"scene_id\",\n \"name\": \"Scene Name\",\n \"entities\": {\n // Entity configurations\n }\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"scene_id\": \"activated_scene_id\",\n \"status\": \"activated\",\n \"timestamp\": \"2024-02-05T12:00:00Z\"\n }\n}\n404: Scene not found401: Unauthorized400: Invalid scene configuration409: Scene activation failed{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nSCENE_RATE_LIMITSCENE_RATE_WINDOWScenes can include transition settings for smooth state changes:
{\n \"name\": \"Sunset Mode\",\n \"entities\": {\n \"light.living_room\": {\n \"state\": \"on\",\n \"brightness\": 128,\n \"transition\": 5 // 5 seconds\n }\n }\n}\nThe Notification tool provides functionality to send notifications through various services in your Home Assistant instance.
"},{"location":"tools/notifications/notify/#features","title":"Features","text":"POST /api/notify\nPOST /api/notify/{service_id}\nGET /api/notify/services\nGET /api/notify/history\n// Send notification\n{\n \"type\": \"send_notification\",\n \"service\": \"required_service_id\",\n \"message\": \"required_message\",\n \"title\": \"optional_title\",\n \"data\": {\n // Service-specific data\n }\n}\n\n// Get notification services\n{\n \"type\": \"get_notification_services\"\n}\nconst response = await fetch('http://your-ha-mcp/api/notify/mobile_app', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"message\": \"Motion detected in living room\",\n \"title\": \"Security Alert\"\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/notify/mobile_app', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"message\": \"Motion detected in living room\",\n \"title\": \"Security Alert\",\n \"data\": {\n \"image\": \"https://your-camera-snapshot.jpg\",\n \"actions\": [\n {\n \"action\": \"view_camera\",\n \"title\": \"View Camera\"\n },\n {\n \"action\": \"dismiss\",\n \"title\": \"Dismiss\"\n }\n ],\n \"priority\": \"high\",\n \"ttl\": 3600,\n \"group\": \"security\"\n }\n })\n});\nconst response = await fetch('http://your-ha-mcp/api/notify/telegram', {\n method: 'POST',\n headers: {\n 'Authorization': 'Bearer your_access_token',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n \"message\": \"Temperature is too high!\",\n \"title\": \"Climate Alert\",\n \"data\": {\n \"parse_mode\": \"markdown\",\n \"inline_keyboard\": [\n [\n {\n \"text\": \"Turn On AC\",\n \"callback_data\": \"turn_on_ac\"\n }\n ]\n ]\n }\n })\n});\n{\n \"success\": true,\n \"data\": {\n \"notification_id\": \"notification_123\",\n \"status\": \"sent\",\n \"timestamp\": \"2024-02-05T12:00:00Z\",\n \"service\": \"mobile_app\"\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"services\": [\n {\n \"id\": \"mobile_app\",\n \"name\": \"Mobile App\",\n \"enabled\": true,\n \"features\": [\n \"actions\",\n \"images\",\n \"sound\"\n ]\n }\n ]\n }\n}\n{\n \"success\": true,\n \"data\": {\n \"history\": [\n {\n \"id\": \"notification_123\",\n \"service\": \"mobile_app\",\n \"message\": \"Motion detected\",\n \"title\": \"Security Alert\",\n \"timestamp\": \"2024-02-05T12:00:00Z\",\n \"status\": \"delivered\"\n }\n ]\n }\n}\n404: Service not found401: Unauthorized400: Invalid request408: Delivery timeout422: Invalid notification data{\n \"success\": false,\n \"message\": \"Error description\",\n \"error_code\": \"ERROR_CODE\"\n}\nNOTIFY_RATE_LIMITNOTIFY_RATE_WINDOW// Template example\n{\n \"template\": \"security_alert\",\n \"data\": {\n \"location\": \"living_room\",\n \"event_type\": \"motion\",\n \"timestamp\": \"2024-02-05T12:00:00Z\"\n }\n}\n