Skip to content

Core Functions API 🔧

The Core Functions API provides the fundamental operations for interacting with Home Assistant devices and services through MCP Server.

Device Control

Get Device State

Retrieve the current state of devices.

GET /api/state
GET /api/state/{entity_id}

Parameters: - entity_id (optional): Specific device ID to query

# Get all states
curl http://localhost:3000/api/state

# Get specific device state
curl http://localhost:3000/api/state/light.living_room

Response: 

{
  "entity_id": "light.living_room",
  "state": "on",
  "attributes": {
    "brightness": 255,
    "color_temp": 370,
    "friendly_name": "Living Room Light"
  },
  "last_changed": "2024-01-20T15:30:00Z"
}

Control Device

Execute device commands.

POST /api/device/control

Request body: 

{
  "entity_id": "light.living_room",
  "action": "turn_on",
  "parameters": {
    "brightness": 200,
    "color_temp": 400
  }
}

Available actions: - turn_on - turn_off - toggle - set_value

Example with curl: 

curl -X POST http://localhost:3000/api/device/control \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "entity_id": "light.living_room",
    "action": "turn_on",
    "parameters": {
      "brightness": 200
    }
  }'

Natural Language Commands

Execute Command

Process natural language commands.

POST /api/command

Request body: 

{
  "command": "Turn on the living room lights and set them to 50% brightness"
}

Example usage: 

curl -X POST http://localhost:3000/api/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "command": "Turn on the living room lights and set them to 50% brightness"
  }'

Response: 

{
  "success": true,
  "actions": [
    {
      "entity_id": "light.living_room",
      "action": "turn_on",
      "parameters": {
        "brightness": 127
      },
      "status": "completed"
    }
  ],
  "message": "Command executed successfully"
}

Scene Management

Create Scene

Define a new scene with multiple actions.

POST /api/scene

Request body: 

{
  "name": "Movie Night",
  "description": "Perfect lighting for movie watching",
  "actions": [
    {
      "entity_id": "light.living_room",
      "action": "turn_on",
      "parameters": {
        "brightness": 50,
        "color_temp": 500
      }
    },
    {
      "entity_id": "cover.living_room",
      "action": "close"
    }
  ]
}

Activate Scene

Trigger a predefined scene.

POST /api/scene/{scene_name}/activate

Example: 

curl -X POST http://localhost:3000/api/scene/movie_night/activate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Groups

Create Device Group

Create a group of devices for collective control.

POST /api/group

Request body: 

{
  "name": "Living Room",
  "entities": [
    "light.living_room_main",
    "light.living_room_accent",
    "switch.living_room_fan"
  ]
}

Control Group

Control multiple devices in a group.

POST /api/group/{group_name}/control

Request body: 

{
  "action": "turn_off"
}

System Operations

Health Check

Check server status and connectivity.

GET /health

Response: 

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "homeAssistant": {
    "connected": true,
    "version": "2024.1.0"
  }
}

Configuration

Get current server configuration.

GET /api/config

Response: 

{
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "version": "1.0.0"
  },
  "homeAssistant": {
    "url": "http://homeassistant:8123",
    "connected": true
  },
  "features": {
    "nlp": true,
    "scenes": true,
    "groups": true
  }
}

Error Handling

All endpoints follow standard HTTP status codes and return detailed error messages:

{
  "error": true,
  "code": "INVALID_ENTITY",
  "message": "Device 'light.nonexistent' not found",
  "details": {
    "entity_id": "light.nonexistent",
    "available_entities": [
      "light.living_room",
      "light.kitchen"
    ]
  }
}

Common 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

TypeScript Interfaces

interface DeviceState {
  entity_id: string;
  state: string;
  attributes: Record<string, any>;
  last_changed: string;
}

interface DeviceCommand {
  entity_id: string;
  action: 'turn_on' | 'turn_off' | 'toggle' | 'set_value';
  parameters?: Record<string, any>;
}

interface Scene {
  name: string;
  description?: string;
  actions: DeviceCommand[];
}

interface Group {
  name: string;
  entities: string[];
}