# MCP HA Extended

A Model Context Protocol (MCP) server that extends Home Assistant capabilities to support automation management. Available as both a standalone Python application and a Home Assistant addon.

## Features

- ✅ List all automations
- ✅ Get automation details
- ✅ Create new automations from YAML
- ✅ Update existing automations
- ✅ Delete automations
- ✅ Trigger automations manually
- ✅ Enable/disable automations

## Quick Start

### As a Home Assistant Addon (Recommended)

1. Add repository: `https://github.com/rios0rios0/mcp-home-assistant-extended`
2. Install "MCP HA Extended" from the addon store
3. Configure with your Home Assistant URL and access token
4. Use with any MCP-compatible client (like Cursor IDE)

See [Addon Installation Guide](.docs/ADDON_INSTALLATION.md) for detailed instructions.

### As a Standalone Python Application

1. Install dependencies: `pdm install`
2. Set environment variables: `HA_URL` and `HA_TOKEN`
3. Run: `pdm run python -m mcp_ha_extended.server`
4. Configure your MCP client to use the server

See [Quick Start Guide](.docs/QUICK_START.md) for a 5-minute setup, or [Setup Guide](.docs/SETUP.md) for detailed instructions.

## Documentation

All documentation is organized in the [`.docs`](.docs/) folder:

- **[Documentation Index](.docs/SUMMARY.md)** - Start here for navigation
- **[Quick Start](.docs/QUICK_START.md)** - Get running in 5 minutes
- **[Addon Installation](.docs/ADDON_INSTALLATION.md)** - Install as Home Assistant addon
- **[Setup Guide](.docs/SETUP.md)** - Detailed development setup
- **[Usage Examples](.docs/USAGE_EXAMPLES.md)** - Code examples and use cases
- **[Implementation Guide](.docs/IMPLEMENTATION_GUIDE.md)** - Technical details

## Architecture

```
┌─────────────────┐
│   MCP Client    │  (e.g., Cursor IDE)
│                 │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼─────────────────────────┐
│  MCP HA Extended Server          │
│  (Python - this project)         │
└────────┬─────────────────────────┘
         │ HTTP REST API
         │
┌────────▼────────┐
│ Home Assistant   │
│ REST API        │
│ /api/automation │
└─────────────────┘
```

## Requirements

- Python 3.10+
- Home Assistant instance with REST API enabled
- Long-lived access token from Home Assistant
- MCP-compatible client (e.g., Cursor IDE)

## Installation Methods

### Option 1: Home Assistant Addon (Recommended)

Easiest installation method. The addon is automatically built and published to GitHub Container Registry.

**Repository**: `https://github.com/rios0rios0/mcp-home-assistant-extended`

See [Addon Installation Guide](.docs/ADDON_INSTALLATION.md) for details.

### Option 2: Standalone Python Application

For development or when you don't want to use Home Assistant addons.

See [Setup Guide](.docs/SETUP.md) for installation instructions.

## MCP Tools

Once configured, you'll have access to these tools:

1. **list_automations** - List all automations
2. **get_automation** - Get details of a specific automation
3. **create_automation** - Create a new automation from YAML
4. **update_automation** - Update an existing automation
5. **delete_automation** - Delete an automation
6. **trigger_automation** - Manually trigger an automation
7. **enable_automation** - Enable an automation
8. **disable_automation** - Disable an automation

See [Usage Examples](.docs/USAGE_EXAMPLES.md) for detailed examples.

## Development

### Prerequisites

- Python 3.10+
- [PDM](https://pdm.fming.dev/) for dependency management

### Setup

```bash
# Install dependencies
pdm install

# Run tests
pdm run pytest

# Run the server
pdm run python -m mcp_ha_extended.server
```

See [Setup Guide](.docs/SETUP.md) and [PDM Setup](.docs/PDM_SETUP.md) for more details.

### Building the Addon

The addon is automatically built via GitHub Actions. See [Addon Build Guide](.docs/ADDON_BUILD.md) for manual build instructions and GitHub Actions setup.

## Contributing

Contributions are welcome! Please read the [Implementation Guide](.docs/IMPLEMENTATION_GUIDE.md) to understand the architecture before contributing.

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Links

- **GitHub Repository**: https://github.com/rios0rios0/mcp-home-assistant-extended
- **Container Registry**: ghcr.io/rios0rios0/mcp-home-assistant-extended
- **Documentation**: [.docs/SUMMARY.md](.docs/SUMMARY.md)

## Support

- Check the [troubleshooting sections](.docs/SETUP.md#troubleshooting) in the documentation
- Review [Usage Examples](.docs/USAGE_EXAMPLES.md) for common patterns
- Open an issue on GitHub for bugs or feature requests