alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c42f981f55453dc53b7c14ed3d311da455780a63
homeassistant-mcp/docs/api/core.md
jango-blockchained 53a041921b docs: enhance documentation with comprehensive API, architecture, and installation guides 
- Add detailed API documentation for core functions, SSE, and WebSocket APIs
- Create comprehensive architecture overview with system design diagrams
- Develop in-depth installation and quick start guides
- Improve troubleshooting documentation with advanced debugging techniques
- Update site navigation and markdown configuration
2025-02-05 02:44:30 +01:00

5.1 KiB
Raw Blame History

layout, title, parent, nav_order
layout title parent nav_order
default Core Functions API Reference 3

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[];
}

Related Resources