# MCP Bridge - Home Assistant Custom Integration

This integration provides services to expose filtered entities and custom scripts to MCP (Model Context Protocol) servers, enabling AI agents to control your Home Assistant instance.

## Installation

### Via HACS (Recommended)

1. **Install HACS** (if not already installed): https://hacs.xyz/docs/setup/download

2. **Add this repository as a custom repository:**
   - Open HACS in Home Assistant
   - Click the three dots in the top right
   - Select "Custom repositories"
   - Add your Gitea URL: `http://your-gitea-server/username/homeassistant-mcp-bridge`
   - Category: Integration
   - Click "Add"

3. **Install the integration:**
   - Go to HACS → Integrations
   - Click "+ Explore & Download Repositories"
   - Search for "MCP Bridge"
   - Click "Download"
   - Restart Home Assistant

### Manual Installation

1. Copy the `mcp_bridge` folder to your Home Assistant `custom_components` directory:
   ```
   /config/custom_components/mcp_bridge/
   ```

2. Restart Home Assistant

3. The integration will be automatically loaded (no configuration needed)

## Services

### `mcp_bridge.get_exposed_entities`

Returns all entities that are exposed to voice assistants.

**Returns:**
```json
{
  "entities": [...],
  "count": 42
}
```

### `mcp_bridge.get_exposed_scripts`

Returns all custom scripts marked with the `mcp_accessible` label.

**Returns:**
```json
{
  "scripts": [...],
  "count": 1
}
```

### `mcp_bridge.get_entity_metadata`

Get detailed metadata for a specific entity.

**Parameters:**
- `entity_id` (required): The entity to query

**Returns:**
```json
{
  "entity_id": "light.living_room",
  "state": "on",
  ...
}
```

## Usage

### Exposing Entities to AI Agent

1. Go to Settings → Voice Assistants → Expose
2. Toggle entities you want the AI agent to control
3. These entities will be returned by `mcp_bridge.get_exposed_entities`

### Exposing Scripts to AI Agent

1. Create your custom script in HA
2. Add the label `mcp_accessible` to the script:
   - Go to Settings → Automations & Scenes → Scripts
   - Click on your script
   - Click the settings icon (top right)
   - Under "Labels", add `mcp_accessible`
3. The script will now be returned by `mcp_bridge.get_exposed_scripts`

## Example: Marking a Script as MCP-Accessible

```yaml
# In your scripts.yaml or via UI
set_master_bedroom_fan_speed:
  alias: "Set Master Bedroom Fan Speed"
  description: "[MCP] Set the speed of the master bedroom fan."
  # Add label via UI: Settings → Scripts → (your script) → Labels → mcp_accessible
  fields:
    fan_state:
      name: Fan speed
      description: "0=off, 1=low, 2=medium, 3=high"
      required: true
      selector:
        number:
          min: 0
          max: 3
          step: 1
  sequence:
    # Your script actions here
```

## Testing

You can test the services in Home Assistant's Developer Tools → Services:

1. Select `mcp_bridge.get_exposed_entities`
2. Click "Call Service"
3. View the response in the "Response" tab

## Troubleshooting

**No entities returned:**
- Make sure you've exposed entities via Settings → Voice Assistants → Expose

**No scripts returned:**
- Ensure your scripts have the `mcp_accessible` label
- Check Home Assistant logs for errors: Settings → System → Logs

**Integration not loading:**
- Check the logs for errors
- Ensure the folder structure is correct
- Restart Home Assistant

## Version

0.1.0 - Initial release