From ae56716a86e9352e7f8046d2c79614ffd6379882 Mon Sep 17 00:00:00 2001 From: Martin Date: Tue, 10 Feb 2026 15:23:14 -0500 Subject: [PATCH] [MOD] New installation method since HACS does not support GITEA --- README.md | 194 +++++++++++++++++++++++++++++++----------- ha_shell_command.yaml | 0 hacs.json | 5 -- info.md | 35 -------- install_mcp_bridge.sh | 0 quick_install.sh | 0 6 files changed, 145 insertions(+), 89 deletions(-) create mode 100644 ha_shell_command.yaml delete mode 100644 hacs.json delete mode 100644 info.md create mode 100644 install_mcp_bridge.sh create mode 100644 quick_install.sh diff --git a/README.md b/README.md index 2bc13ae..ab4e32d 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,5 @@ # MCP Bridge - Home Assistant Integration -[![hacs_badge](https://img.shields.io/badge/HACS-Custom-orange.svg)](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 --- diff --git a/ha_shell_command.yaml b/ha_shell_command.yaml new file mode 100644 index 0000000..e69de29 diff --git a/hacs.json b/hacs.json deleted file mode 100644 index 6272e23..0000000 --- a/hacs.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "name": "MCP Bridge", - "content_in_root": false, - "homeassistant": "2024.1.0" -} \ No newline at end of file diff --git a/info.md b/info.md deleted file mode 100644 index fa749a8..0000000 --- a/info.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/install_mcp_bridge.sh b/install_mcp_bridge.sh new file mode 100644 index 0000000..e69de29 diff --git a/quick_install.sh b/quick_install.sh new file mode 100644 index 0000000..e69de29