alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Simplify README by removing detailed API and CLI documentation

Browse Source 
- Removed extensive Home Assistant Analyzer CLI section
- Condensed API Reference to point to external documentation files
- Simplified development commands section
- Kept core sections like OpenAI Integration and Troubleshooting
- Improved overall readability by reducing technical depth in README
This commit is contained in:
jango-blockchained
2025-02-03 00:29:38 +01:00
parent cb6b16546b
commit f81cb1af62
1 changed files with 22 additions and 558 deletions
Download Patch File Download Diff File Expand all files Collapse all files

580
README.md
View File

@@ -54,14 +54,7 @@ See [SSE_API.md](docs/SSE_API.md) for complete documentation of the SSE system.
- [Configuration](#configuration)
- [Development](#development)
- [API Reference](#api-reference)
- [MCP Schema](#mcp-schema-endpoint)
- [Device Control](#device-control)
- [Add-on Management](#add-on-management)
- [Package Management](#package-management)
- [Automation Management](#automation-management)
- [OpenAI Integration](#openai-integration)
- [Standard Analysis](#1-standard-analysis)
- [Custom Prompt Analysis](#2-custom-prompt-analysis)
- [Natural Language Integration](#natural-language-integration)
- [Troubleshooting](#troubleshooting)
- [Project Status](#project-status)
@@ -250,511 +243,36 @@ TEST_HASS_TOKEN=test_token # Test token
2. **Production**: Copy `.env.example` to `.env.production`
3. **Testing**: Copy `.env.example` to `.env.test`
## Home Assistant Analyzer CLI
## Development
The project includes a powerful command-line tool (`ha-analyzer-cli.ts`) for analyzing and optimizing your Home Assistant setup. This tool provides comprehensive system analysis, automation optimization, and custom querying capabilities.
### Features
- 🔍 **System Analysis**
- Device state monitoring
- Health checks
- Configuration analysis
- Integration status
- Performance metrics
- Security assessment
- 🤖 **Automation Analysis**
- Inefficient automation detection
- Optimization suggestions
- Blueprint recommendations
- Condition optimizations
- ⚡ **Performance Optimization**
- Resource usage analysis
- Response time monitoring
- Configuration optimization suggestions
- Integration improvement recommendations
- 🔐 **Security Analysis**
- Current security measures assessment
- Vulnerability detection
- Security recommendations
- 📊 **Entity Usage Analysis**
- Most active entities tracking
- Rarely used entity detection
- Potential duplicate identification
- 💡 **Energy Management**
- High consumption detection
- Monitoring suggestions
- Tariff optimization recommendations
### Configuration
The analyzer requires the following environment variables:
```env
OPENAI_API_KEY=your_openai_api_key # Required for analysis
HASS_TOKEN=your_hass_token # Home Assistant access token
MCP_SERVER=http://localhost:3000 # MCP server URL (default)
OPENAI_MODEL=gpt-4o # Default model (optional)
MAX_RETRIES=3 # Max retry attempts (optional)
ANALYSIS_TIMEOUT=30000 # Analysis timeout in ms (optional)
```
### Available Models
The analyzer supports multiple language models:
- GPT-4 Models:
- `gpt-4o`: Standard GPT-4
- `gpt-4-turbo`: GPT-4 Turbo
- `gpt-4`: Original GPT-4
- GPT-3.5 Models:
- `gpt-3.5-turbo`: Standard GPT-3.5
- `gpt-3.5-turbo-16k`: Extended context GPT-3.5
- DeepSeek Models (requires DEEPSEEK_API_KEY):
- `deepseek-v3`: DeepSeek v3
- `deepseek-r1`: DeepSeek R1
### Usage
1. **Standard Analysis**
```bash
npx ts-node ha-analyzer-cli.ts analyze
```
# Development mode with hot reload
npm run dev
2. **Custom Prompt Analysis**
```bash
npx ts-node ha-analyzer-cli.ts custom
```
# Build project
npm run build
3. **Automation Optimization**
```bash
npx ts-node ha-analyzer-cli.ts optimize
```
# Production mode
npm run start
The analysis results will be displayed in a structured format, organized by categories such as system overview, performance, security, optimization suggestions, and more.
# Run tests
npx jest --config=jest.config.cjs
# Run tests with coverage
npx jest --coverage
# Lint code
npm run lint
# Format code
npm run format
```
## API Reference
### MCP Schema Endpoint
The server exposes an MCP (Model Context Protocol) schema endpoint that describes all available tools and their parameters:
```http
GET /mcp
```
This endpoint returns a JSON schema describing all available tools, their parameters, and documentation resources. The schema follows the MCP specification and can be used by LLM clients to understand the server's capabilities.
Example response:
```json
{
"tools": [
{
"name": "list_devices",
"description": "List all devices connected to Home Assistant",
"parameters": {
"type": "object",
"properties": {
"domain": {
"type": "string",
"enum": ["light", "climate", "alarm_control_panel", ...]
},
"area": { "type": "string" },
"floor": { "type": "string" }
}
}
},
// ... other tools
],
"prompts": [],
"resources": [
{
"name": "Home Assistant API",
"url": "https://developers.home-assistant.io/docs/api/rest/"
}
]
}
```
Note: The `/mcp` endpoint is publicly accessible and does not require authentication, as it only provides schema information.
### Device Control
#### Common Entity Controls
```json
{
"tool": "control",
"command": "turn_on", // or "turn_off", "toggle"
"entity_id": "light.living_room"
}
```
#### Light Control
```json
{
"tool": "control",
"command": "turn_on",
"entity_id": "light.living_room",
"brightness": 128,
"color_temp": 4000,
"rgb_color": [255, 0, 0]
}
```
### Add-on Management
#### List Available Add-ons
```json
{
"tool": "addon",
"action": "list"
}
```
#### Install Add-on
```json
{
"tool": "addon",
"action": "install",
"slug": "core_configurator",
"version": "5.6.0"
}
```
#### Manage Add-on State
```json
{
"tool": "addon",
"action": "start", // or "stop", "restart"
"slug": "core_configurator"
}
```
### Package Management
#### List HACS Packages
```json
{
"tool": "package",
"action": "list",
"category": "integration" // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
```
#### Install Package
```json
{
"tool": "package",
"action": "install",
"category": "integration",
"repository": "hacs/integration",
"version": "1.32.0"
}
```
### Automation Management
#### Create Automation
```json
{
"tool": "automation_config",
"action": "create",
"config": {
"alias": "Motion Light",
"description": "Turn on light when motion detected",
"mode": "single",
"trigger": [
{
"platform": "state",
"entity_id": "binary_sensor.motion",
"to": "on"
}
],
"action": [
{
"service": "light.turn_on",
"target": {
"entity_id": "light.living_room"
}
}
]
}
}
```
#### Duplicate Automation
```json
{
"tool": "automation_config",
"action": "duplicate",
"automation_id": "automation.motion_light"
}
```
### Core Functions
#### State Management
```http
GET /api/state
POST /api/state
```
Manages the current state of the system.
**Example Request:**
```json
POST /api/state
{
"context": "living_room",
"state": {
"lights": "on",
"temperature": 22
}
}
```
#### Context Updates
```http
POST /api/context
```
Updates the current context with new information.
**Example Request:**
```json
POST /api/context
{
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
```
### Action Endpoints
#### Execute Action
```http
POST /api/action
```
Executes a specified action with given parameters.
**Example Request:**
```json
POST /api/action
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}
```
#### Batch Actions
```http
POST /api/actions/batch
```
Executes multiple actions in sequence.
**Example Request:**
```json
POST /api/actions/batch
{
"actions": [
{
"action": "turn_on_lights",
"parameters": {
"room": "living_room"
}
},
{
"action": "set_temperature",
"parameters": {
"temperature": 22
}
}
]
}
```
### Query Functions
#### Get Available Actions
```http
GET /api/actions
```
Returns a list of all available actions.
**Example Response:**
```json
{
"actions": [
{
"name": "turn_on_lights",
"parameters": ["room", "brightness"],
"description": "Turns on lights in specified room"
},
{
"name": "set_temperature",
"parameters": ["temperature"],
"description": "Sets temperature in current context"
}
]
}
```
#### Context Query
```http
GET /api/context?type=current
```
Retrieves context information.
**Example Response:**
```json
{
"current_context": {
"user": "john",
"location": "kitchen",
"time": "morning",
"activity": "cooking"
}
}
```
### WebSocket Events
The server supports real-time updates via WebSocket connections.
```javascript
// Client-side connection example
const ws = new WebSocket('ws://localhost:3000/ws');
ws.onmessage = (event) => {
const data = JSON.parse(event.data);
console.log('Received update:', data);
};
```
#### Supported Events
- `state_change`: Emitted when system state changes
- `context_update`: Emitted when context is updated
- `action_executed`: Emitted when an action is completed
- `error`: Emitted when an error occurs
**Example Event Data:**
```json
{
"event": "state_change",
"data": {
"previous_state": {
"lights": "off"
},
"current_state": {
"lights": "on"
},
"timestamp": "2024-03-20T10:30:00Z"
}
}
```
### Error Handling
All endpoints return standard HTTP status codes:
- 200: Success
- 400: Bad Request
- 401: Unauthorized
- 403: Forbidden
- 404: Not Found
- 500: Internal Server Error
**Error Response Format:**
```json
{
"error": {
"code": "INVALID_PARAMETERS",
"message": "Missing required parameter: room",
"details": {
"missing_fields": ["room"]
}
}
}
```
### Rate Limiting
The API implements rate limiting to prevent abuse:
- 100 requests per minute per IP for regular endpoints
- 1000 requests per minute per IP for WebSocket connections
When rate limit is exceeded, the server returns:
```json
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"reset_time": "2024-03-20T10:31:00Z"
}
}
```
### Example Usage
#### Using curl
```bash
# Get current state
curl -X GET \
http://localhost:3000/api/state \
-H 'Authorization: ApiKey your_api_key_here'
# Execute action
curl -X POST \
http://localhost:3000/api/action \
-H 'Authorization: ApiKey your_api_key_here' \
-H 'Content-Type: application/json' \
-d '{
"action": "turn_on_lights",
"parameters": {
"room": "living_room",
"brightness": 80
}
}'
```
#### Using JavaScript
```javascript
// Execute action
async function executeAction() {
const response = await fetch('http://localhost:3000/api/action', {
method: 'POST',
headers: {
'Authorization': 'ApiKey your_api_key_here',
'Content-Type': 'application/json'
},
body: JSON.stringify({
action: 'turn_on_lights',
parameters: {
room: 'living_room',
brightness: 80
}
})
});
const data = await response.json();
console.log('Action result:', data);
}
```
For detailed API documentation, please refer to:
- [API Documentation](docs/API.md) - Complete API reference
- [SSE API Documentation](docs/SSE_API.md) - Server-Sent Events documentation
## OpenAI Integration
@@ -789,20 +307,6 @@ npm run test:openai
# Select option 2 when prompted
```
#### Available Variables
When using custom prompts, you can use these variables:
- `{device_count}`: Total number of devices
- `{device_types}`: List of device types
- `{device_states}`: Current states of devices
- `{device_examples}`: Example devices and their states
#### Example Custom Prompts
```
"Show me all active lights"
"Which devices in {device_types} need maintenance?"
"Analyze my {device_count} devices and suggest automations"
```
### Configuration
To use the OpenAI integration, you need to set up your OpenAI API key in the `.env` file:
@@ -810,46 +314,6 @@ To use the OpenAI integration, you need to set up your OpenAI API key in the `.e
OPENAI_API_KEY=your_openai_api_key
```
### Features
- 🔍 Intelligent device state analysis
- 📊 System health assessment
- 🤖 Smart automation suggestions
- 🔧 Maintenance recommendations
- 💡 Custom query support
- 🔄 Real-time device state information
### Token Usage Optimization
The analysis tool includes smart token usage optimization:
- Automatic filtering of relevant devices based on query
- Fallback to summarized data for large systems
- Intelligent attribute selection based on device types
- Automatic retry with condensed information if token limit is reached
## Development
```bash
# Development mode with hot reload
npm run dev
# Build project
npm run build
# Production mode
npm run start
# Run tests
npx jest --config=jest.config.cjs
# Run tests with coverage
npx jest --coverage
# Lint code
npm run lint
# Format code
npm run format
```
## Troubleshooting
### Common Issues