### Project Setup and Build (npm)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Commands to clone the repository, install Node.js dependencies, and build the project using npm.

```bash
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
npm install
npm run build
```

--------------------------------

### Example curl Usage (Bash)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Examples of using curl to interact with the Home Assistant MCP API, demonstrating how to get the current state and execute an action.

```bash
# Get current state
curl -X GET \
  http://localhost:3000/api/state \
  -H 'Authorization: ApiKey your_api_key_here'
```

```bash
# 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
    }
  }'
```

--------------------------------

### List Available Add-ons

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

The GET /addons endpoint lists all available add-ons for Home Assistant. The response provides details for each add-on, including its name, slug, description, version, and installation status.

```json
{
  "success": true,
  "addons": [
    {
      "name": "File Editor",
      "slug": "core_configurator",
      "description": "Simple browser-based file editor",
      "version": "5.6.0",
      "installed": true,
      "available": true,
      "state": "started"
    }
  ]
}
```

--------------------------------

### Manage Add-ons Installation

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

The POST /addons endpoint manages add-ons, including installation. To install an add-on, the request body should specify the 'action' as 'install', along with the add-on's 'slug' and optionally the 'version'.

```json
{
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}
```

--------------------------------

### Docker Setup and Management

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Instructions for setting up, running, logging, and stopping the project using Docker Compose.

```bash
git clone https://github.com/jango-blockchained/homeassistant-mcp.git
cd homeassistant-mcp
cp .env.example .env
docker compose up -d
docker compose logs -f
docker compose down
git pull
docker compose up -d --build
```

--------------------------------

### Package Management - Install Package

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Install a package from HACS.

```APIDOC
## Package Management - Install Package

### Description
Install a package from HACS.

### Method
POST

### Endpoint
/api/package

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'package'
- **action** (string) - Required - Must be 'install'
- **category** (string) - Required - The category of the package
- **repository** (string) - Required - The repository name of the package (e.g., 'hacs/integration')
- **version** (string) - Optional - The specific version of the package to install

### Request Example
```json
{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the installation request was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Add-on Management - Install Add-on

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Install a specific add-on to your Home Assistant instance.

```APIDOC
## Add-on Management - Install Add-on

### Description
Install a specific add-on to your Home Assistant instance.

### Method
POST

### Endpoint
/api/addon

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'addon'
- **action** (string) - Required - Must be 'install'
- **slug** (string) - Required - The slug of the add-on to install
- **version** (string) - Optional - The specific version of the add-on to install

### Request Example
```json
{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the installation request was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Home Assistant Add-on Management API

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

JSON payloads for managing Home Assistant add-ons, including listing, installing with specific versions, and controlling their state (start, stop, restart).

```json
{
  "tool": "addon",
  "action": "list"
}
```

```json
{
  "tool": "addon",
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}
```

```json
{
  "tool": "addon",
  "action": "start",  // or "stop", "restart"
  "slug": "core_configurator"
}
```

--------------------------------

### Environment Configuration (.env)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Example environment variables for configuring Home Assistant and server settings. These are used in the .env file.

```env
# Home Assistant Configuration
HASS_HOST=http://homeassistant.local:8123
HASS_TOKEN=your_home_assistant_token
HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket

# Server Configuration
PORT=3000
NODE_ENV=production
DEBUG=false

# Test Configuration
TEST_HASS_HOST=http://localhost:8123
TEST_HASS_TOKEN=test_token
```

--------------------------------

### Get Available Actions

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Returns a list of all available actions and their parameters.

```APIDOC
## GET /api/actions

### Description
Retrieves a list of all available actions, including their names, required parameters, and descriptions.

### Method
GET

### Endpoint
/api/actions

### Response
#### Success Response (200)
- **actions** (array) - A list of available actions.
  - **name** (string) - The name of the action.
  - **parameters** (array) - List of parameter names for the action.
  - **description** (string) - Description of the action.

#### Response Example
```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"
    }
  ]
}
```
```

--------------------------------

### Add-ons API

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Provides endpoints to list available add-ons and manage their installation and state.

```APIDOC
## GET /addons

### Description
Lists all available add-ons for Home Assistant.

### Method
GET

### Endpoint
/addons

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **addons** (array) - A list of add-ons, each with details like name, slug, description, version, installation status, and state.

#### Response Example
```json
{
  "success": true,
  "addons": [
    {
      "name": "File Editor",
      "slug": "core_configurator",
      "description": "Simple browser-based file editor",
      "version": "5.6.0",
      "installed": true,
      "available": true,
      "state": "started"
    }
  ]
}
```

## POST /addons

### Description
Manages add-ons, including installation, removal, starting, and stopping.

### Method
POST

### Endpoint
/addons

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform (e.g., "install", "remove", "start", "stop").
- **slug** (string) - Required - The slug of the add-on.
- **version** (string) - Optional - The specific version of the add-on to install.

### Request Example (Install)
```json
{
  "action": "install",
  "slug": "core_configurator",
  "version": "5.6.0"
}
```

### Response
#### Success Response (200)
(Indicates if the add-on management action was successful.)
```

--------------------------------

### Project Development and Execution Commands (npm)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

A collection of npm scripts for managing the project's lifecycle. Includes commands for starting the development server with hot reloading, building the project for production, running tests using Jest, linting, and formatting the code.

```bash
# Development mode with hot reload
npm run dev
```

```bash
# Build project
npm run build
```

```bash
# Production mode
npm run start
```

```bash
# Run tests
npx jest --config=jest.config.cjs
```

```bash
# Run tests with coverage
npx jest --coverage
```

```bash
# Lint code
npm run lint
```

```bash
# Format code
npm run format
```

--------------------------------

### Add-on Management - Manage Add-on State

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Start, stop, or restart a Home Assistant add-on.

```APIDOC
## Add-on Management - Manage Add-on State

### Description
Start, stop, or restart a Home Assistant add-on.

### Method
POST

### Endpoint
/api/addon

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'addon'
- **action** (string) - Required - 'start', 'stop', or 'restart'
- **slug** (string) - Required - The slug of the add-on to manage

### Request Example
```json
{
  "tool": "addon",
  "action": "start",
  "slug": "core_configurator"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the state management request was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### WebSocket Client Connection (JavaScript)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Example of establishing a WebSocket connection to the server for real-time updates. Includes an event listener for incoming messages.

```javascript
const ws = new WebSocket('ws://localhost:3000/ws');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received update:', data);
};
```

--------------------------------

### Install HACS Package

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Installs a specified HACS package by providing the action, category, repository, and desired version in the request body.

```json
{
  "action": "install",
  "category": "integration",
  "repository": "owner/repo",
  "version": "1.1.0"
}
```

--------------------------------

### Get SSE Connection Statistics

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/SSE_API.md

Bash example using curl to request statistics about current SSE connections. Requires your Home Assistant token for authentication.

```bash
curl -X POST http://localhost:3000/get_sse_stats \
  -H "Content-Type: application/json" \
  -d '{"token": "YOUR_HASS_TOKEN"}'
```

--------------------------------

### GET /packages

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Lists available HACS packages, optionally filtered by category.

```APIDOC
## GET /packages

### Description
Lists available HACS packages.

### Method
GET

### Endpoint
/packages

### Parameters
#### Query Parameters
- **category** (string) - Optional - One of ["integration", "plugin", "theme", "python_script", "appdaemon", "netdaemon"]

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **packages** (array) - A list of available packages.
  - **name** (string) - The name of the package.
  - **repository** (string) - The GitHub repository of the package (e.g., "owner/repo").
  - **category** (string) - The category of the package.
  - **installed_version** (string) - The currently installed version of the package.
  - **available_version** (string) - The latest available version of the package.

#### Response Example
```json
{
  "success": true,
  "packages": [
    {
      "name": "Custom Component",
      "repository": "owner/repo",
      "category": "integration",
      "installed_version": "1.0.0",
      "available_version": "1.1.0"
    }
  ]
}
```
```

--------------------------------

### Home Assistant Package Management API

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

JSON payloads for managing Home Assistant packages via HACS, including listing packages by category and installing specific versions from a repository.

```json
{
  "tool": "package",
  "action": "list",
  "category": "integration"  // or "plugin", "theme", "python_script", "appdaemon", "netdaemon"
}
```

```json
{
  "tool": "package",
  "action": "install",
  "category": "integration",
  "repository": "hacs/integration",
  "version": "1.32.0"
}
```

--------------------------------

### Get Available Actions (HTTP & JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Endpoint to retrieve a list of all available actions, including their parameters and descriptions. Returns a JSON response.

```http
GET /api/actions
```

```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"
    }
  ]
}
```

--------------------------------

### POST /packages

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Manages HACS packages, primarily used for installing new packages.

```APIDOC
## POST /packages

### Description
Manages HACS packages. This endpoint is typically used to install new packages.

### Method
POST

### Endpoint
/packages

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform, e.g., "install".
- **category** (string) - Required - The category of the package to install.
- **repository** (string) - Required - The GitHub repository of the package (e.g., "owner/repo").
- **version** (string) - Optional - The specific version to install. If not provided, the latest version is installed.

### Request Example
```json
{
  "action": "install",
  "category": "integration",
  "repository": "owner/repo",
  "version": "1.1.0"
}
```
```

--------------------------------

### Home Assistant Authentication Token

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/SSE_API.md

Example of how to define your Home Assistant authentication token.

```javascript
const token = 'YOUR_HASS_TOKEN';
```

--------------------------------

### Manage System State (HTTP)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Endpoints for managing the current state of the Home Assistant system. Supports retrieving state via GET and updating state via POST.

```http
GET /api/state
```

```http
POST /api/state
```

--------------------------------

### List Available Scenes

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

The GET /scenes endpoint lists all available scenes within Home Assistant. The response includes a success status and a list of scenes, each with an entity_id, name, and description.

```json
{
  "success": true,
  "scenes": [
    {
      "entity_id": "scene.movie_time",
      "name": "Movie Time",
      "description": "Dim lights and lower blinds"
    }
  ]
}
```

--------------------------------

### Node.js Version Management (nvm)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Instructions for updating Node.js using nvm (Node Version Manager) to resolve 'toSorted is not a function' errors, which typically indicate an outdated Node.js version. Specifies the command to install and use a specific Node.js version.

```bash
nvm install 20.10.0
nvm use 20.10.0
```

--------------------------------

### Get Context Information (HTTP & JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Endpoint to retrieve current context information, such as user, location, time, and activity. Requires a query parameter 'type=current'.

```http
GET /api/context?type=current
```

```json
{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}
```

--------------------------------

### List Available Automations

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

The GET /automations endpoint lists all configured automations in Home Assistant. The response includes a success status and a list of automations, detailing their entity_id, name, state, and last triggered time.

```json
{
  "success": true,
  "automations": [
    {
      "entity_id": "automation.morning_routine",
      "name": "Morning Routine",
      "state": "on",
      "last_triggered": "2024-03-20T06:00:00Z"
    }
  ]
}
```

--------------------------------

### Subscribe to Home Assistant Events via SSE

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/SSE_API.md

JavaScript example using EventSource to subscribe to Home Assistant events and state changes. It allows filtering by entity ID, domain, and event types. Includes handling for incoming messages and errors.

```javascript
const token = 'YOUR_HASS_TOKEN';
const eventSource = new EventSource(`http://localhost:3000/subscribe_events?token=${token}&entity_id=light.living_room&domain=switch&events=state_changed,automation_triggered`);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
};

eventSource.onerror = (error) => {
  console.error('SSE Error:', error);
  eventSource.close();
};
```

--------------------------------

### Retrieve Entity State History

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

The GET /history endpoint retrieves state history for specified entities. It accepts an entity_id and optional parameters like start_time, end_time, minimal_response, and significant_changes_only for filtering.

```http
GET /history?entity_id=light.living_room&start_time=2024-03-19T00:00:00Z&minimal_response=true
```

--------------------------------

### Add-on Management - List Available Add-ons

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Retrieve a list of all available add-ons for Home Assistant.

```APIDOC
## Add-on Management - List Available Add-ons

### Description
Retrieve a list of all available add-ons for Home Assistant.

### Method
POST

### Endpoint
/api/addon

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'addon'
- **action** (string) - Required - Must be 'list'

### Request Example
```json
{
  "tool": "addon",
  "action": "list"
}
```

### Response
#### Success Response (200)
- **addons** (array) - A list of available add-ons, each with details like slug, name, and description.

#### Response Example
```json
{
  "addons": [
    {
      "slug": "core_configurator",
      "name": "Configurator",
      "description": "A graphical user interface for editing configuration files."
    }
  ]
}
```
```

--------------------------------

### Batch Actions

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Executes multiple actions in sequence.

```APIDOC
## POST /api/actions/batch

### Description
Executes a list of actions in the specified order.

### Method
POST

### Endpoint
/api/actions/batch

### Parameters
#### Request Body
- **actions** (array) - Required - A list of actions to execute.
  - **action** (string) - Required - The name of the action.
  - **parameters** (object) - Optional - Parameters for the action.

### Request Example
```json
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- **results** (array) - The results of each executed action.

#### Response Example
```json
{
  "results": [
    "Lights in living_room turned on",
    "Temperature set to 22"
  ]
}
```
```

--------------------------------

### Create Automation

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Creates a new automation in Home Assistant with the specified configuration.

```APIDOC
## POST /api/automation/create

### Description
Creates a new automation with provided configuration.

### Method
POST

### Endpoint
/api/automation/create

### Parameters
#### Request Body
- **tool** (string) - Required - Specifies the tool to use ('automation_config').
- **action** (string) - Required - Specifies the action to perform ('create').
- **config** (object) - Required - Configuration for the automation.
  - **alias** (string) - Required - Name of the automation.
  - **description** (string) - Optional - Description of the automation.
  - **mode** (string) - Optional - Execution mode (e.g., 'single', 'restart').
  - **trigger** (array) - Required - List of triggers for the automation.
  - **action** (array) - Required - List of actions to perform when triggered.

### Request Example
```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"
        }
      }
    ]
  }
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Automation created successfully"
}
```
```

--------------------------------

### Package Management - List HACS Packages

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

List packages available through HACS, filtered by category.

```APIDOC
## Package Management - List HACS Packages

### Description
List packages available through HACS, filtered by category.

### Method
POST

### Endpoint
/api/package

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'package'
- **action** (string) - Required - Must be 'list'
- **category** (string) - Required - The category of packages to list (e.g., 'integration', 'plugin', 'theme')

### Request Example
```json
{
  "tool": "package",
  "action": "list",
  "category": "integration"
}
```

### Response
#### Success Response (200)
- **packages** (array) - A list of packages matching the specified category.

#### Response Example
```json
{
  "packages": [
    {
      "repository": "hacs/integration",
      "version": "1.32.0"
    }
  ]
}
```
```

--------------------------------

### Create Home Assistant Automation (JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Defines a new automation in Home Assistant. It includes a trigger (motion detection) and an action (turn on a light).

```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"
        }
      }
    ]
  }
}
```

--------------------------------

### Client Configuration (Claude Desktop)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

JSON configuration for integrating the MCP server with Claude Desktop or similar clients. This method does not use Docker.

```json
{
  "homeassistant": {
    "command": "node",
    "args": [<path/to/your/dist/folder>]
    "env": {
      NODE_ENV=development
      HASS_HOST=http://homeassistant.local:8123
      HASS_TOKEN=your_home_assistant_token
      PORT=3000
      HASS_SOCKET_URL=ws://homeassistant.local:8123/api/websocket
      LOG_LEVEL=debug
    }
  }
}
```

--------------------------------

### Context Query

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Retrieves current context information.

```APIDOC
## GET /api/context

### Description
Retrieves current context information, such as user, location, time, and activity.

### Method
GET

### Endpoint
/api/context

### Parameters
#### Query Parameters
- **type** (string) - Optional - Specifies the type of context to retrieve (e.g., 'current').

### Response
#### Success Response (200)
- **current_context** (object) - An object containing the current context details.
  - **user** (string) - The current user.
  - **location** (string) - The current location.
  - **time** (string) - The current time of day.
  - **activity** (string) - The current activity.

#### Response Example
```json
{
  "current_context": {
    "user": "john",
    "location": "kitchen",
    "time": "morning",
    "activity": "cooking"
  }
}
```
```

--------------------------------

### Real-time SSE Updates from Home Assistant

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

This JavaScript code snippet demonstrates how to connect to the server's Server-Sent Events (SSE) endpoint to receive real-time updates for specific Home Assistant domains. It requires a server URL, an authentication token, and the domain to subscribe to. The received data is parsed as JSON and logged to the console.

```javascript
const eventSource = new EventSource(
  'http://localhost:3000/subscribe_events?token=YOUR_TOKEN&domain=light'
);

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Update received:', data);
};
```

--------------------------------

### Execute API Action with JavaScript

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

This snippet demonstrates how to send a POST request to a local Home Assistant API endpoint to execute an action. It includes setting the Authorization header with an API key and specifying the action and its parameters in the request body. Dependencies: `fetch` API.

```javascript
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);
}
```

--------------------------------

### Rate Limiting

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Information on API rate limiting policies.

```APIDOC
## Rate Limiting

### Description
The API implements rate limiting to prevent abuse and ensure stability.

### Limits
- **Regular Endpoints:** 100 requests per minute per IP.
- **WebSocket Connections:** 1000 requests per minute per IP.

### Rate Limit Exceeded Response
When the rate limit is exceeded, the server returns:
```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "reset_time": "2024-03-20T10:31:00Z"
  }
}
```
```

--------------------------------

### Home Assistant Device Control API

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

JSON payloads for controlling Home Assistant devices, including common commands and specific light controls with parameters like brightness and color.

```json
{
  "tool": "control",
  "command": "turn_on",  // or "turn_off", "toggle"
  "entity_id": "light.living_room"
}
```

```json
{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}
```

--------------------------------

### Error Handling

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Details standard HTTP status codes and error response formats.

```APIDOC
## Error Handling

### Description
All API endpoints return standard HTTP status codes for success and error conditions. The error response format provides details about the issue.

### 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"]
    }
  }
}
```
```

--------------------------------

### State Management

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Manages the current state of the system.

```APIDOC
## State Management API

### Description
Manages the current state of the system, allowing for retrieval and updates.

### Method
GET, POST

### Endpoint
/api/state

### Parameters
#### Request Body (POST)
- **context** (string) - Required - The context of the state (e.g., 'living_room').
- **state** (object) - Required - The state data to set.
  - **lights** (string) - Example value: 'on'.
  - **temperature** (number) - Example value: 22.

### Request Example (POST)
```json
{
  "context": "living_room",
  "state": {
    "lights": "on",
    "temperature": 22
  }
}
```

### Response
#### Success Response (200)
- **current_state** (object) - The current state of the system.

#### Response Example
```json
{
  "current_state": {
    "lights": "on",
    "temperature": 22
  }
}
```
```

--------------------------------

### Execute Action

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Executes a specified action with given parameters.

```APIDOC
## POST /api/action

### Description
Executes a specified action with provided parameters.

### Method
POST

### Endpoint
/api/action

### Parameters
#### Request Body
- **action** (string) - Required - The name of the action to execute (e.g., 'turn_on_lights').
- **parameters** (object) - Optional - Parameters required for the action.
  - **room** (string) - Example parameter for 'turn_on_lights'.
  - **brightness** (number) - Example parameter for 'turn_on_lights'.

### Request Example
```json
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}
```

### Response
#### Success Response (200)
- **result** (object) - The result of the executed action.

#### Response Example
```json
{
  "result": "Lights in living_room turned on with 80 brightness"
}
```
```

--------------------------------

### WebSocket Events

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Connects to the WebSocket server for real-time updates.

```APIDOC
## WebSocket Connection

### Description
The server supports real-time updates via WebSocket connections. Clients can connect to receive event notifications.

### Endpoint
`ws://localhost:3000/ws`

### 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"
  }
}
```
```

--------------------------------

### List HACS Packages

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Retrieves a list of available HACS packages, with optional filtering by category. The response includes package details like name, repository, and installed/available versions.

```http
GET /packages?category=integration
```

--------------------------------

### Device Control - Light Control

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Control specific properties of lights, such as brightness and color.

```APIDOC
## Device Control - Light Control

### Description
Control specific properties of lights, such as brightness and color.

### Method
POST

### Endpoint
/api/control

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'control'
- **command** (string) - Required - 'turn_on' or 'turn_off'
- **entity_id** (string) - Required - The ID of the light entity
- **brightness** (integer) - Optional - Brightness level (0-255)
- **color_temp** (integer) - Optional - Color temperature in Kelvin
- **rgb_color** (array) - Optional - RGB color values [R, G, B]

### Request Example
```json
{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room",
  "brightness": 128,
  "color_temp": 4000,
  "rgb_color": [255, 0, 0]
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### Duplicate Automation

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Duplicates an existing automation in Home Assistant.

```APIDOC
## POST /api/automation/duplicate

### Description
Duplicates an existing automation.

### Method
POST

### Endpoint
/api/automation/duplicate

### Parameters
#### Request Body
- **tool** (string) - Required - Specifies the tool to use ('automation_config').
- **action** (string) - Required - Specifies the action to perform ('duplicate').
- **automation_id** (string) - Required - The ID of the automation to duplicate.

### Request Example
```json
{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates success.

#### Response Example
```json
{
  "status": "Automation duplicated successfully"
}
```
```

--------------------------------

### Duplicate Home Assistant Automation (JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Duplicates an existing automation in Home Assistant. Requires the automation's ID.

```json
{
  "tool": "automation_config",
  "action": "duplicate",
  "automation_id": "automation.motion_light"
}
```

--------------------------------

### Execute Batch Actions (HTTP & JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Endpoint for executing multiple actions sequentially. The actions are provided as an array of objects in a JSON payload.

```http
POST /api/actions/batch
```

```json
{
  "actions": [
    {
      "action": "turn_on_lights",
      "parameters": {
        "room": "living_room"
      }
    },
    {
      "action": "set_temperature",
      "parameters": {
        "temperature": 22
      }
    }
  ]
}
```

--------------------------------

### Scenes API

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Provides endpoints to list available scenes and activate specific scenes.

```APIDOC
## GET /scenes

### Description
Lists all available scenes configured in Home Assistant.

### Method
GET

### Endpoint
/scenes

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **scenes** (array) - A list of scenes, each with an entity ID, name, and description.

#### Response Example
```json
{
  "success": true,
  "scenes": [
    {
      "entity_id": "scene.movie_time",
      "name": "Movie Time",
      "description": "Dim lights and lower blinds"
    }
  ]
}
```

## POST /scenes/activate

### Description
Activates a specific scene in Home Assistant.

### Method
POST

### Endpoint
/scenes/activate

### Parameters
#### Request Body
- **scene_id** (string) - Required - The entity ID of the scene to activate.

### Request Example
```json
{
  "scene_id": "scene.movie_time"
}
```

### Response
#### Success Response (200)
(Indicates that the scene activation command was sent successfully.)
```

--------------------------------

### Context Updates

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Updates the current context with new information.

```APIDOC
## POST /api/context

### Description
Updates the current context with new information such as user, location, time, and activity.

### Method
POST

### Endpoint
/api/context

### Parameters
#### Request Body
- **user** (string) - Optional - The user associated with the context.
- **location** (string) - Optional - The location associated with the context.
- **time** (string) - Optional - The time of day associated with the context.
- **activity** (string) - Optional - The current activity associated with the context.

### Request Example
```json
{
  "user": "john",
  "location": "kitchen",
  "time": "morning",
  "activity": "cooking"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates successful update.

#### Response Example
```json
{
  "status": "Context updated successfully"
}
```
```

--------------------------------

### Execute Single Action (HTTP & JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Endpoint to execute a specific action with optional parameters. The action and its parameters are provided in a JSON payload.

```http
POST /api/action
```

```json
{
  "action": "turn_on_lights",
  "parameters": {
    "room": "living_room",
    "brightness": 80
  }
}
```

--------------------------------

### Device Control - Common Entity Controls

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Control common Home Assistant entities by turning them on, off, or toggling their state.

```APIDOC
## Device Control - Common Entity Controls

### Description
Control common Home Assistant entities by turning them on, off, or toggling their state.

### Method
POST

### Endpoint
/api/control

### Parameters
#### Request Body
- **tool** (string) - Required - Must be 'control'
- **command** (string) - Required - 'turn_on', 'turn_off', or 'toggle'
- **entity_id** (string) - Required - The ID of the entity to control

### Request Example
```json
{
  "tool": "control",
  "command": "turn_on",
  "entity_id": "light.living_room"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "success": true
}
```
```

--------------------------------

### JavaScript Home Assistant SSE Client Implementation

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/SSE_API.md

A JavaScript class for connecting to Home Assistant's Server-Sent Events (SSE) stream. It handles connection, event parsing, error management with exponential backoff, and disconnection. Dependencies include the browser's EventSource API.

```javascript
class HomeAssistantSSE {
  constructor(baseUrl, token) {
    this.baseUrl = baseUrl;
    this.token = token;
    this.eventSource = null;
    this.reconnectAttempts = 0;
    this.maxReconnectAttempts = 5;
    this.reconnectDelay = 1000;
  }

  connect(options = {}) {
    const params = new URLSearchParams({
      token: this.token,
      ...(options.events && { events: options.events.join(',') }),
      ...(options.entity_id && { entity_id: options.entity_id }),
      ...(options.domain && { domain: options.domain })
    });

    this.eventSource = new EventSource(`${this.baseUrl}/subscribe_events?${params}`);

    this.eventSource.onmessage = (event) => {
      const data = JSON.parse(event.data);
      this.handleEvent(data);
    };

    this.eventSource.onerror = (error) => {
      console.error('SSE Error:', error);
      this.handleError(error);
    };
  }

  handleEvent(data) {
    switch (data.type) {
      case 'connection':
        this.reconnectAttempts = 0;
        console.log('Connected:', data);
        break;
      case 'ping':
        // Connection is alive
        break;
      case 'error':
        console.error('Server Error:', data);
        break;
      default:
        // Handle other event types
        console.log('Event:', data);
    }
  }

  handleError(error) {
    this.eventSource?.close();
    
    if (this.reconnectAttempts < this.maxReconnectAttempts) {
      this.reconnectAttempts++;
      const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
      console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
      setTimeout(() => this.connect(), delay);
    } else {
      console.error('Max reconnection attempts reached');
    }
  }

  disconnect() {
    this.eventSource?.close();
    this.eventSource = null;
  }
}

// Usage example
const client = new HomeAssistantSSE('http://localhost:3000', 'YOUR_HASS_TOKEN');
client.connect({
  events: ['state_changed', 'automation_triggered'],
  domain: 'light'
});
```

--------------------------------

### Automations API

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

Provides endpoints to list automations and to create or modify them.

```APIDOC
## GET /automations

### Description
Lists all automations configured in Home Assistant.

### Method
GET

### Endpoint
/automations

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful.
- **automations** (array) - A list of automations, each with entity ID, name, state, and last triggered time.

#### Response Example
```json
{
  "success": true,
  "automations": [
    {
      "entity_id": "automation.morning_routine",
      "name": "Morning Routine",
      "state": "on",
      "last_triggered": "2024-03-20T06:00:00Z"
    }
  ]
}
```

## POST /automations

### Description
Creates or modifies automations in Home Assistant.

### Method
POST

### Endpoint
/automations

### Parameters
#### Request Body
- **action** (string) - Required - The action to perform ('create' or 'modify').
- **config** (object) - Required - The configuration for the automation.
  - **alias** (string) - Required - The alias for the automation.
  - **description** (string) - Optional - A description for the automation.
  - **trigger** (object) - Required - The trigger conditions for the automation.
  - **action** (object) - Required - The actions to perform when the trigger is met.

### Request Example (Create)
```json
{
  "action": "create",
  "config": {
    "alias": "Morning Routine",
    "description": "Turn on lights at sunrise",
    "trigger": {
      "platform": "sun",
      "event": "sunrise"
    },
    "action": {
      "service": "light.turn_on",
      "target": {
        "entity_id": "light.living_room"
      }
    }
  }
}
```

### Response
#### Success Response (200)
(Indicates if the automation creation or modification was successful.)
```

--------------------------------

### Error Response Format (JSON)

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/README.md

Standard format for error responses across API endpoints, including an error code, message, and optional details.

```json
{
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Missing required parameter: room",
    "details": {
      "missing_fields": ["room"]
    }
  }
}
```

--------------------------------

### Create or Modify Automations

Source: https://github.com/tevonsb/homeassistant-mcp/blob/main/docs/API.md

The POST /automations endpoint is used for creating or modifying automations. The request body includes an 'action' (e.g., 'create') and a 'config' object specifying the automation's details, including triggers and actions.

```json
{
  "action": "create",
  "config": {
    "alias": "Morning Routine",
    "description": "Turn on lights at sunrise",
    "trigger": {
      "platform": "sun",
      "event": "sunrise"
    },
    "action": {
      "service": "light.turn_on",
      "target": {
        "entity_id": "light.living_room"
      }
    }
  }
}
```