# Hubitat MCP Server

MCP server for [Hubitat](https://hubitat.com/) Elevation hubs. Control devices through the documented **Maker API**, with optional gated access to undocumented local admin routes.

## Design claims

These constraints drive the architecture:

| # | Claim | Implication |
|---|-------|-------------|
| 1 | **Two API surfaces; only Maker API is supported** | First-class tools use Maker API (`/apps/api/{appId}/…`). Hub management (firmware, Z-Wave mesh, backups, reboot) lives on undocumented admin routes that break across firmware updates — gated behind `HUBITAT_ENABLE_ADMIN=true`. Run `task recon` against *your* hub before relying on admin tools. |
| 2 | **Cache + eventsocket is the scale solution** | Hitting `/devices/all` on every call is fine under ~50 devices (default). Set `HUBITAT_DEVICE_STORE=cached` to hydrate once and apply `ws://[hub]/eventsocket` deltas (with dedupe). |
| 3 | **Rule Machine has no API** | You cannot list, read, or trigger rules programmatically. Levers are **virtual switches** and **hub variables** only. |

## Quick start

1. Install the **Maker API** app on your hub, authorize the devices you want exposed, copy the app ID and access token.
2. Clone this repo and configure:

```bash
task env:create
# edit .env — HUBITAT_HOST, HUBITAT_APP_ID, HUBITAT_ACCESS_TOKEN
task setup          # build + hub-check + MCP client registration (when credentials are set)
```

3. Restart **Claude Desktop** and/or reload MCP in **Cursor**.
4. Optional: `task inspect` for the MCP Inspector UI.

### Maker API setup

1. Hubitat UI → **Apps** → **Add Built-In App** → **Maker API**
2. Select devices (or allow all)
3. Copy local URLs; note `apps/api/<APP_ID>/…?access_token=<TOKEN>`

## MCP clients

| Task | Target |
|------|--------|
| `task setup-cursor` | `~/.cursor/mcp.json` |
| `task setup-claude-code` | `claude mcp add hubitat --scope user` |
| `task setup-claude-desktop` | Claude Desktop `claude_desktop_config.json` |
| `task setup-mcp` | All of the above |

To refresh Claude Code after `.env` changes: `claude mcp remove hubitat` then `task setup-claude-code`.

## Tools

| Tool | Purpose |
|------|---------|
| `hubitat_list_devices` | Paginated/filterable device list |
| `hubitat_get_device` | Device detail + attributes |
| `hubitat_get_device_commands` | Commands for a device |
| `hubitat_send_command` | Generic command + optional value |
| `hubitat_set_color` | Hex → URL-encoded `setColor` JSON map |
| `hubitat_list_virtual_devices` | Virtual switch/button candidates (Rule Machine levers) |
| `hubitat_get_hub_variable` / `hubitat_set_hub_variable` | Hub variables (admin routes; firmware-sensitive) |

### Admin plane (`HUBITAT_ENABLE_ADMIN=true`)

Undocumented and firmware-sensitive. Read tools first; `hubitat_hub_reboot` requires `confirm=true`.

| Tool | Risk |
|------|------|
| `hubitat_hub_info` | read |
| `hubitat_backup_status` | read |
| `hubitat_list_apps` | read |
| `hubitat_zwave_status` | read |
| `hubitat_hub_reboot` | **destructive** |

### Resources

- `hubitat://capabilities` — static capability → common commands index

## Automating Rule Machine

Rule Machine has **no API**. To drive rules from this server:

1. Create a **virtual switch** (or button) and subscribe a rule to it, then `hubitat_send_command` with `on`/`off`/`push`, or
2. Create a **hub variable** subscription and use `hubitat_set_hub_variable`.

## Configuration

See [`.env.example`](.env.example).

| Variable | Default | Purpose |
|----------|---------|---------|
| `HUBITAT_HOST` | required | Hub IP/hostname |
| `HUBITAT_APP_ID` | required | Maker API app ID |
| `HUBITAT_ACCESS_TOKEN` | required | Maker API token |
| `HUBITAT_ENABLE_ADMIN` | `false` | Register admin tools |
| `HUBITAT_POLL_CACHE_TTL_MS` | `0` | Soft TTL for polling store (`0` = always fresh) |
| `HUBITAT_DEVICE_STORE` | `polling` | `polling` or `cached` (eventsocket) |

## Task reference

```bash
task --list
```

| Task | Purpose |
|------|---------|
| `build` / `dev` / `start` / `inspect` | Build and run |
| `env:create` / `hub-check` / `recon` | Credentials + hub probe |
| `test` / `typecheck` / `check` / `clean` | Quality |
| `commit` / `changelog` / `bump` | Commitizen releases |
| `pre-commit` / `pre-commit:install` | Hooks |
| `setup-cursor` / `setup-claude-*` / `setup` | MCP clients |

Prefer `task commit` for conventional commits. `task bump` updates `package.json`, changelog, and tags `v*`.

## Recon (Phase 0)

```bash
task recon   # writes docs/recon-{firmware}.yaml
```

Documents Maker API size, EventSocket samples, and which admin routes return JSON vs HTML/404 on your firmware.

## Streamable HTTP (optional)

```bash
npm install express
npm run build
node dist/index.js --http :3000
# POST http://localhost:3000/mcp
```

Default transport remains **stdio** for Cursor / Claude Desktop.

## License

MIT