alex/homeassistant-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6fa88be433e5ca83782fd25643c442689209b9e5
homeassistant-mcp/docs/tools/addons-packages/package.md
jango-blockchained e3256682ba docs: expand documentation with comprehensive tools and development guides 
- Add detailed documentation for various tools and management interfaces
- Create development best practices and interface documentation
- Expand tools section with device management, automation, and event subscription guides
- Include configuration, usage examples, and error handling for each tool
- Update MkDocs navigation to reflect new documentation structure
2025-02-05 03:02:17 +01:00

4.8 KiB
Raw Blame History

Package Management Tool

The Package Management tool provides functionality to manage Home Assistant Community Store (HACS) packages through the MCP interface.

Features

  • List available packages
  • Install/update/remove packages
  • Search packages
  • Get package information
  • Manage package repositories
  • Track package updates
  • View package documentation
  • Monitor package status

Usage

REST API

GET /api/packages
GET /api/packages/{package_id}
POST /api/packages/{package_id}/install
POST /api/packages/{package_id}/uninstall
POST /api/packages/{package_id}/update
GET /api/packages/search
GET /api/packages/categories
GET /api/packages/repositories

WebSocket

// List packages
{
    "type": "get_packages",
    "category": "optional_category"
}

// Search packages
{
    "type": "search_packages",
    "query": "search_query",
    "category": "optional_category"
}

// Install package
{
    "type": "install_package",
    "package_id": "required_package_id",
    "version": "optional_version"
}

Package Categories

  • Integrations
  • Frontend
  • Themes
  • AppDaemon Apps
  • NetDaemon Apps
  • Python Scripts
  • Plugins

Examples

List All Packages

const response = await fetch('http://your-ha-mcp/api/packages', {
    headers: {
        'Authorization': 'Bearer your_access_token'
    }
});
const packages = await response.json();

Search Packages

const response = await fetch('http://your-ha-mcp/api/packages/search?q=weather&category=integrations', {
    headers: {
        'Authorization': 'Bearer your_access_token'
    }
});
const searchResults = await response.json();

Install Package

const response = await fetch('http://your-ha-mcp/api/packages/custom-weather-card/install', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer your_access_token',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        "version": "latest"
    })
});

Response Format

Package List Response

{
    "success": true,
    "data": {
        "packages": [
            {
                "id": "package_id",
                "name": "Package Name",
                "category": "integrations",
                "description": "Package description",
                "version": "1.0.0",
                "installed": true,
                "update_available": false,
                "stars": 150,
                "downloads": 10000
            }
        ]
    }
}

Package Info Response

{
    "success": true,
    "data": {
        "package": {
            "id": "package_id",
            "name": "Package Name",
            "category": "integrations",
            "description": "Package description",
            "long_description": "Detailed description",
            "version": "1.0.0",
            "installed_version": "0.9.0",
            "available_version": "1.0.0",
            "installed": true,
            "update_available": true,
            "stars": 150,
            "downloads": 10000,
            "repository": "https://github.com/author/repo",
            "author": {
                "name": "Author Name",
                "url": "https://github.com/author"
            },
            "documentation": "https://github.com/author/repo/wiki",
            "dependencies": [
                "dependency1",
                "dependency2"
            ]
        }
    }
}

Search Response

{
    "success": true,
    "data": {
        "results": [
            {
                "id": "package_id",
                "name": "Package Name",
                "category": "integrations",
                "description": "Package description",
                "version": "1.0.0",
                "score": 0.95
            }
        ],
        "total": 42
    }
}

Error Handling

Common Error Codes

  • 404: Package not found
  • 401: Unauthorized
  • 400: Invalid request
  • 409: Package operation failed
  • 422: Invalid configuration
  • 424: Dependency error

Error Response Format

{
    "success": false,
    "message": "Error description",
    "error_code": "ERROR_CODE"
}

Rate Limiting

  • Default limit: 50 requests per 15 minutes
  • Configurable through environment variables:
    • PACKAGE_RATE_LIMIT
    • PACKAGE_RATE_WINDOW

Best Practices

  1. Check package compatibility
  2. Review package documentation
  3. Verify package dependencies
  4. Back up before updates
  5. Test in safe environment
  6. Monitor resource usage
  7. Keep packages updated
  8. Handle rate limiting gracefully

Package Security

  • Verify package sources
  • Review package permissions
  • Check package reputation
  • Monitor package activity
  • Keep dependencies updated
  • Follow security advisories

See Also