Skip to content

# Interface Documentation

This document describes the core interfaces used throughout the Home Assistant MCP.

## Core Interfaces

### Tool Interface

    interface Tool {
        /** Unique identifier for the tool */
        id: string;

        /** Human-readable name */
        name: string;

        /** Detailed description */
        description: string;

        /** Semantic version */
        version: string;

        /** Tool category */
        category: ToolCategory;

        /** Execute tool functionality */
        execute(params: any): Promise<ToolResult>;
    }

### Tool Result

    interface ToolResult {
        /** Operation success status */
        success: boolean;

        /** Response data */
        data?: any;

        /** Error message if failed */
        message?: string;

        /** Error code if failed */
        error_code?: string;
    }

### Tool Category

    enum ToolCategory {
        DeviceManagement = 'device_management',
        HistoryState = 'history_state',
        Automation = 'automation',
        AddonsPackages = 'addons_packages',
        Notifications = 'notifications',
        Events = 'events',
        Utility = 'utility'
    }

## Event Interfaces

### Event Subscription

    interface EventSubscription {
        /** Unique subscription ID */
        id: string;

        /** Event type to subscribe to */
        event_type: string;

        /** Optional entity ID filter */
        entity_id?: string;

        /** Optional domain filter */
        domain?: string;

        /** Subscription creation timestamp */
        created_at: string;

        /** Last event timestamp */
        last_event?: string;
    }

### Event Message

    interface EventMessage {
        /** Event type */
        event_type: string;

        /** Entity ID if applicable */
        entity_id?: string;

        /** Event data */
        data: any;

        /** Event origin */
        origin: 'LOCAL' | 'REMOTE';

        /** Event timestamp */
        time_fired: string;

        /** Event context */
        context: EventContext;
    }

## Device Interfaces

### Device

    interface Device {
        /** Device ID */
        id: string;

        /** Device name */
        name: string;

        /** Device domain */
        domain: string;

        /** Current state */
        state: string;

        /** Device attributes */
        attributes: Record<string, any>;

        /** Device capabilities */
        capabilities: DeviceCapabilities;
    }

### Device Capabilities

    interface DeviceCapabilities {
        /** Supported features */
        features: string[];

        /** Supported commands */
        commands: string[];

        /** State attributes */
        attributes: {
            /** Attribute name */
            [key: string]: {
                /** Attribute type */
                type: 'string' | 'number' | 'boolean' | 'object';
                /** Attribute description */
                description: string;
                /** Optional value constraints */
                constraints?: {
                    min?: number;
                    max?: number;
                    enum?: any[];
                };
            };
        };
    }

## Authentication Interfaces

### Auth Token

    interface AuthToken {
        /** Token value */
        token: string;

        /** Token type */
        type: 'bearer' | 'jwt';

        /** Expiration timestamp */
        expires_at: string;

        /** Token refresh info */
        refresh?: {
            token: string;
            expires_at: string;
        };
    }

### User

    interface User {
        /** User ID */
        id: string;

        /** Username */
        username: string;

        /** User type */
        type: 'admin' | 'user' | 'service';

        /** User permissions */
        permissions: string[];
    }

## Error Interfaces

### Tool Error

    interface ToolError extends Error {
        /** Error code */
        code: string;

        /** HTTP status code */
        status: number;

        /** Error details */
        details?: Record<string, any>;
    }

### Validation Error

    interface ValidationError {
        /** Error path */
        path: string;

        /** Error message */
        message: string;

        /** Error code */
        code: string;
    }

## Configuration Interfaces

### Tool Configuration

    interface ToolConfig {
        /** Enable/disable tool */
        enabled: boolean;

        /** Tool-specific settings */
        settings: Record<string, any>;

        /** Rate limiting */
        rate_limit?: {
            /** Max requests */
            max: number;
            /** Time window in seconds */
            window: number;
        };
    }

### System Configuration

    interface SystemConfig {
        /** System name */
        name: string;

        /** Environment */
        environment: 'development' | 'production';

        /** Log level */
        log_level: 'debug' | 'info' | 'warn' | 'error';

        /** Tool configurations */
        tools: Record<string, ToolConfig>;
    }

## Best Practices

1. Use TypeScript for all interfaces
2. Include JSDoc comments
3. Use strict typing
4. Keep interfaces focused
5. Use consistent naming
6. Document constraints
7. Version interfaces
8. Include examples

## See Also

- Tool Development Guide
- Best Practices
- Testing Guide

February 5, 2025
February 5, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings