[MOD] New installation method since HACS does not support GITEA
This commit is contained in:
Martin
parent
a826ef80ec
commit
ae56716a86
194
README.md
194
README.md
@ -1,7 +1,5 @@
|
||||
# MCP Bridge - Home Assistant Integration
|
||||
|
||||
[](https://github.com/custom-components/hacs)
|
||||
|
||||
Bridge integration between Home Assistant and MCP (Model Context Protocol) servers, enabling AI agents to control your smart home.
|
||||
|
||||
## Features
|
||||
@ -18,29 +16,79 @@ MCP (Model Context Protocol) is Anthropic's protocol for connecting AI agents to
|
||||
|
||||
## Installation
|
||||
|
||||
### Via HACS (Recommended)
|
||||
**Note:** This integration is hosted on Gitea (not GitHub), so it's not available via HACS. Instead, use one of the automated installation methods below.
|
||||
|
||||
1. **Add Custom Repository**
|
||||
- Open HACS in Home Assistant
|
||||
- Click the three dots (⋮) in top right
|
||||
- Select "Custom repositories"
|
||||
- Repository: `http://your-gitea-server/username/homeassistant-mcp-bridge`
|
||||
- Category: **Integration**
|
||||
- Click "Add"
|
||||
### Method 1: One-Line Install/Update (Easiest)
|
||||
|
||||
2. **Install**
|
||||
- HACS → Integrations
|
||||
- Click "+ Explore & Download Repositories"
|
||||
- Search for "MCP Bridge"
|
||||
- Click "Download"
|
||||
- Restart Home Assistant
|
||||
Run this command in your Home Assistant terminal (requires Terminal & SSH addon or SSH access):
|
||||
|
||||
### Manual Installation
|
||||
```bash
|
||||
curl -sSL http://your-gitea.local:3000/username/homeassistant-mcp-bridge/raw/branch/main/quick_install.sh | \
|
||||
GITEA_URL=http://your-gitea.local:3000 \
|
||||
REPO=username/homeassistant-mcp-bridge \
|
||||
bash
|
||||
```
|
||||
|
||||
1. Copy `custom_components/mcp_bridge` to your Home Assistant config directory
|
||||
2. Restart Home Assistant
|
||||
**Important:**
|
||||
- Replace `your-gitea.local:3000` with your Gitea server address
|
||||
- Replace `username` with your Gitea username
|
||||
- Replace `main` with your branch name if different
|
||||
|
||||
See [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) for detailed instructions.
|
||||
After installation completes, restart Home Assistant.
|
||||
|
||||
### Method 2: Home Assistant Auto-Update Button
|
||||
|
||||
Add this to your `configuration.yaml` to create an update button/service:
|
||||
|
||||
```yaml
|
||||
shell_command:
|
||||
update_mcp_bridge: >
|
||||
curl -fsSL http://your-gitea.local:3000/username/homeassistant-mcp-bridge/raw/branch/main/quick_install.sh |
|
||||
GITEA_URL=http://your-gitea.local:3000
|
||||
REPO=username/homeassistant-mcp-bridge
|
||||
bash
|
||||
|
||||
script:
|
||||
update_mcp_bridge:
|
||||
alias: "Update MCP Bridge Integration"
|
||||
sequence:
|
||||
- service: shell_command.update_mcp_bridge
|
||||
- delay:
|
||||
seconds: 5
|
||||
- service: persistent_notification.create
|
||||
data:
|
||||
title: "MCP Bridge Updated"
|
||||
message: "Integration updated from Gitea. Please restart Home Assistant."
|
||||
```
|
||||
|
||||
**Usage:**
|
||||
- Go to Developer Tools → Services
|
||||
- Select `script.update_mcp_bridge`
|
||||
- Click "Call Service"
|
||||
- Restart Home Assistant after update
|
||||
|
||||
**Optional Dashboard Button:**
|
||||
```yaml
|
||||
type: button
|
||||
name: Update MCP Bridge
|
||||
icon: mdi:download
|
||||
tap_action:
|
||||
action: call-service
|
||||
service: script.update_mcp_bridge
|
||||
```
|
||||
|
||||
### Method 3: Manual Installation
|
||||
|
||||
1. Download these files from your Gitea repository:
|
||||
- `custom_components/mcp_bridge/__init__.py`
|
||||
- `custom_components/mcp_bridge/manifest.json`
|
||||
- `custom_components/mcp_bridge/services.yaml`
|
||||
|
||||
2. Copy to `/config/custom_components/mcp_bridge/`
|
||||
|
||||
3. Restart Home Assistant
|
||||
|
||||
See [INSTALLATION_GUIDE.md](INSTALLATION_GUIDE.md) for detailed manual steps.
|
||||
|
||||
## Quick Start
|
||||
|
||||
@ -108,8 +156,7 @@ Returns scripts marked with `mcp_accessible` label, including their parameters.
|
||||
"speed": {
|
||||
"name": "Speed",
|
||||
"description": "0=off, 1=low, 2=medium, 3=high",
|
||||
"required": true,
|
||||
"selector": {"number": {"min": 0, "max": 3}}
|
||||
"required": true
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -125,6 +172,17 @@ Get detailed metadata for a specific entity.
|
||||
**Parameters:**
|
||||
- `entity_id`: The entity to query
|
||||
|
||||
## Updating the Integration
|
||||
|
||||
**Using Auto-Update Script/Button:**
|
||||
- Just run the install command again or call the `script.update_mcp_bridge` service
|
||||
- Restart Home Assistant after update
|
||||
|
||||
**Manual Update:**
|
||||
- Download the latest files from Gitea
|
||||
- Replace files in `/config/custom_components/mcp_bridge/`
|
||||
- Restart Home Assistant
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
@ -160,24 +218,46 @@ No configuration required! The integration automatically loads on Home Assistant
|
||||
## Compatibility
|
||||
|
||||
- **Home Assistant**: 2024.1.0 or newer
|
||||
- **HACS**: Any version
|
||||
- **Python**: 3.11+
|
||||
- **Installation**: Requires SSH/Terminal access or manual file management
|
||||
|
||||
## Documentation
|
||||
## Troubleshooting
|
||||
|
||||
- [Installation Guide](INSTALLATION_GUIDE.md) - Detailed setup instructions
|
||||
- [Integration README](custom_components/mcp_bridge/README.md) - Technical details
|
||||
- [Gitea Setup Guide](GITEA_SETUP_GUIDE.md) - For hosting on your own Gitea
|
||||
### Installation Script Fails
|
||||
|
||||
**Check:**
|
||||
- Home Assistant can reach your Gitea server
|
||||
- Terminal addon has network access
|
||||
- URLs are correct (server address, username, repo name)
|
||||
|
||||
**Test connectivity:**
|
||||
```bash
|
||||
curl http://your-gitea.local:3000/username/homeassistant-mcp-bridge
|
||||
```
|
||||
|
||||
### Integration Not Loading
|
||||
|
||||
**Check logs:**
|
||||
- Settings → System → Logs
|
||||
- Filter by "mcp_bridge"
|
||||
|
||||
**Common issues:**
|
||||
- Files not in correct location (`/config/custom_components/mcp_bridge/`)
|
||||
- Python syntax errors (check logs)
|
||||
- Didn't restart Home Assistant after installation
|
||||
|
||||
### Services Not Showing
|
||||
|
||||
**Verify installation:**
|
||||
```bash
|
||||
ls -la /config/custom_components/mcp_bridge/
|
||||
```
|
||||
|
||||
Should show: `__init__.py`, `manifest.json`, `services.yaml`
|
||||
|
||||
## Development
|
||||
|
||||
### Running Tests
|
||||
|
||||
```bash
|
||||
pytest custom_components/mcp_bridge/test_init.py
|
||||
```
|
||||
|
||||
### Project Structure
|
||||
### Repository Structure
|
||||
|
||||
```
|
||||
homeassistant-mcp-bridge/
|
||||
@ -186,31 +266,46 @@ homeassistant-mcp-bridge/
|
||||
│ ├── __init__.py # Core integration logic
|
||||
│ ├── manifest.json # Integration metadata
|
||||
│ ├── services.yaml # Service definitions
|
||||
│ └── README.md # Integration docs
|
||||
├── hacs.json # HACS configuration
|
||||
├── info.md # HACS UI description
|
||||
└── README.md # This file
|
||||
│ └── test_init.py # Unit tests
|
||||
├── quick_install.sh # One-line installer
|
||||
├── install_mcp_bridge.sh # Detailed installer
|
||||
├── ha_shell_command.yaml # HA shell command config
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Contributing
|
||||
### Running Tests
|
||||
|
||||
This is a personal project for homelab use, but suggestions and improvements are welcome!
|
||||
```bash
|
||||
pytest custom_components/mcp_bridge/test_init.py
|
||||
```
|
||||
|
||||
1. Fork the repository
|
||||
2. Create a feature branch
|
||||
3. Make your changes
|
||||
4. Test thoroughly
|
||||
5. Submit a pull request
|
||||
## Versioning
|
||||
|
||||
Check your installed version:
|
||||
```yaml
|
||||
service: mcp_bridge.get_entity_metadata
|
||||
data:
|
||||
entity_id: sensor.any_sensor # Any entity
|
||||
```
|
||||
|
||||
The response will show the integration version in logs.
|
||||
|
||||
Or check `manifest.json`:
|
||||
```bash
|
||||
cat /config/custom_components/mcp_bridge/manifest.json | grep version
|
||||
```
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [x] Basic entity exposure
|
||||
- [x] Script discovery with labels
|
||||
- [x] Complete metadata support
|
||||
- [x] Automated install/update script
|
||||
- [ ] Real-time state updates via WebSocket
|
||||
- [ ] Custom entity tags beyond voice assistant exposure
|
||||
- [ ] Integration config flow (UI-based setup)
|
||||
- [ ] Service call history/logging
|
||||
- [ ] Version checking and update notifications
|
||||
|
||||
## License
|
||||
|
||||
@ -218,13 +313,14 @@ MIT License - Use freely in your homelab!
|
||||
|
||||
## Support
|
||||
|
||||
- **Issues**: [Gitea Issues](http://your-gitea-server/username/homeassistant-mcp-bridge/issues)
|
||||
- **Issues**: Report on your Gitea instance
|
||||
- **Logs**: Settings → System → Logs (filter by "mcp_bridge")
|
||||
- **Questions**: Check the detailed guides in the repository
|
||||
|
||||
## Acknowledgments
|
||||
## Related Projects
|
||||
|
||||
- Built for use with [Anthropic's MCP](https://modelcontextprotocol.io/)
|
||||
- Designed to work with n8n workflows
|
||||
- **MCP Server**: Coming next - connects to this integration
|
||||
- **n8n Integration**: Workflow automation with AI agents
|
||||
|
||||
---
|
||||
|
||||
|
||||
0
ha_shell_command.yaml
Normal file
0
ha_shell_command.yaml
Normal file
@ -1,5 +0,0 @@
|
||||
{
|
||||
"name": "MCP Bridge",
|
||||
"content_in_root": false,
|
||||
"homeassistant": "2024.1.0"
|
||||
}
|
||||
35
info.md
35
info.md
@ -1,35 +0,0 @@
|
||||
# MCP Bridge
|
||||
|
||||
Bridge integration between Home Assistant and MCP (Model Context Protocol) servers for AI agent control.
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Expose entities to AI agents via voice assistant settings
|
||||
- ✅ Control which scripts are accessible using labels
|
||||
- ✅ Complete entity metadata including area, device class, and attributes
|
||||
- ✅ Secure: Only exposes what you explicitly mark
|
||||
|
||||
## Services
|
||||
|
||||
- `mcp_bridge.get_exposed_entities` - Get all exposed entities
|
||||
- `mcp_bridge.get_exposed_scripts` - Get MCP-accessible scripts
|
||||
- `mcp_bridge.get_entity_metadata` - Get detailed entity info
|
||||
|
||||
## Configuration
|
||||
|
||||
No configuration needed! The integration auto-loads after installation.
|
||||
|
||||
### Exposing Entities
|
||||
|
||||
Go to: **Settings → Voice Assistants → Expose**
|
||||
|
||||
Toggle the entities you want the AI agent to control.
|
||||
|
||||
### Exposing Scripts
|
||||
|
||||
1. Create or edit a script
|
||||
2. Click the settings icon ⚙️
|
||||
3. Add the label: `mcp_accessible`
|
||||
4. Save
|
||||
|
||||
That's it! The script is now accessible to AI agents.
|
||||
0
install_mcp_bridge.sh
Normal file
0
install_mcp_bridge.sh
Normal file
0
quick_install.sh
Normal file
0
quick_install.sh
Normal file
Loading…
x
Reference in New Issue
Block a user