Merge remote-tracking branch 'origin/master' into feat/ha-get-states-bulk

# Conflicts:
#	src/ha_mcp/tools/tools_search.py

Author: Sergey

.github/workflows/e2e-tests.yml

@@ -20,6 +20,8 @@ permissions:
 env:
   PYTHON_VERSION: "3.13"
   UV_CACHE_DIR: /tmp/.uv-cache
+  # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+  HA_IMAGE_GHCR: "ghcr.io/home-assistant/home-assistant:2026.1.3"
 
 jobs:
   # Comprehensive E2E validation for main branch
@@ -33,6 +35,8 @@ jobs:
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
+      with:
+        cache-binary: true
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7
@@ -45,6 +49,37 @@ jobs:
     - name: Install dependencies
       run: uv sync --all-extras --dev
 
+    - name: Cache HA Docker image
+      id: cache-ha-image
+      uses: actions/cache@v4
+      with:
+        path: /tmp/ha-image.tar
+        key: ha-image-${{ env.HA_IMAGE_GHCR }}-${{ runner.arch }}
+
+    - name: Load cached HA image
+      if: steps.cache-ha-image.outputs.cache-hit == 'true'
+      run: docker load -i /tmp/ha-image.tar
+
+    - name: Pull HA image (GHCR → Docker Hub fallback)
+      if: steps.cache-ha-image.outputs.cache-hit != 'true'
+      run: |
+        HA_VERSION="${HA_IMAGE_GHCR##*:}"
+        HA_IMAGE_DOCKERHUB="homeassistant/home-assistant:${HA_VERSION}"
+        for registry in "$HA_IMAGE_GHCR" "$HA_IMAGE_DOCKERHUB"; do
+          echo "Trying $registry..."
+          if docker pull "$registry"; then
+            if [ "$registry" != "$HA_IMAGE_GHCR" ]; then
+              docker tag "$registry" "$HA_IMAGE_GHCR"
+            fi
+            docker save "$HA_IMAGE_GHCR" -o /tmp/ha-image.tar
+            echo "Pulled and cached from $registry"
+            exit 0
+          fi
+          echo "Failed to pull from $registry, trying next..."
+          sleep 15
+        done
+        echo "All registries failed" && exit 1
+
     - name: Run full E2E test suite
       run: |
         echo "🚀 Running full E2E test suite with 3 workers..."

.github/workflows/notify-dev-channel.yml

@@ -32,8 +32,14 @@ jobs:
           # Extract PR number from commit message
           # GitHub merge commits have format: "Merge pull request #123 from user/branch"
           # GitHub squash merges have format: "Title with (#123)" in first line
-          # Take only the first match to avoid capturing PR references in the title
-          PR_NUM=$(echo "$COMMIT_MSG" | head -1 | grep -oP '(?:Merge pull request #|[[(]#)\K\d+' | head -1 || echo "")
+          # For merge commits, always use the "Merge pull request #" pattern (handles branch names with #)
+          # For squash merges with multiple refs like "(#591) (#592)", use the last one (merged PR)
+          FIRST_LINE=$(echo "$COMMIT_MSG" | head -1)
+          if [[ "$FIRST_LINE" =~ ^Merge\ pull\ request\ \#([0-9]+) ]]; then
+            PR_NUM="${BASH_REMATCH[1]}"
+          else
+            PR_NUM=$(echo "$FIRST_LINE" | grep -oP '\(#\K\d+' | tail -1 || echo "")
+          fi
 
           if [ -z "$PR_NUM" ]; then
             echo "No PR number found in commit message. Skipping notification."

.github/workflows/pr.yml

@@ -10,8 +10,43 @@ on:
 env:
   PYTHON_VERSION: "3.13"
   UV_CACHE_DIR: /tmp/.uv-cache
+  # renovate: datasource=docker depName=ghcr.io/home-assistant/home-assistant
+  HA_IMAGE_GHCR: "ghcr.io/home-assistant/home-assistant:2026.1.3"
 
 jobs:
+  lint:
+    name: Ruff Lint
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:0.9.30-python3.13-bookworm-slim
+    timeout-minutes: 5
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install dependencies
+      run: uv sync --dev
+
+    - name: Run ruff check
+      run: uv run ruff check src/ tests/
+
+  # Fast unit tests (no Docker, no HA instance needed)
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/astral-sh/uv:0.9.30-python3.13-bookworm-slim
+    timeout-minutes: 5
+
+    steps:
+    - uses: actions/checkout@v6
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run unit tests
+      run: uv run pytest tests/src/unit/ -n auto --tb=short -v
+
   # Comprehensive E2E validation for all PRs
   e2e-validation:
     name: E2E Validation (${{ matrix.os }})
@@ -34,6 +69,8 @@ jobs:
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
+      with:
+        cache-binary: true
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7
@@ -46,6 +83,37 @@ jobs:
     - name: Install dependencies
       run: uv sync --all-extras --dev
 
+    - name: Cache HA Docker image
+      id: cache-ha-image
+      uses: actions/cache@v4
+      with:
+        path: /tmp/ha-image.tar
+        key: ha-image-${{ env.HA_IMAGE_GHCR }}-${{ runner.arch }}
+
+    - name: Load cached HA image
+      if: steps.cache-ha-image.outputs.cache-hit == 'true'
+      run: docker load -i /tmp/ha-image.tar
+
+    - name: Pull HA image (GHCR → Docker Hub fallback)
+      if: steps.cache-ha-image.outputs.cache-hit != 'true'
+      run: |
+        HA_VERSION="${HA_IMAGE_GHCR##*:}"
+        HA_IMAGE_DOCKERHUB="homeassistant/home-assistant:${HA_VERSION}"
+        for registry in "$HA_IMAGE_GHCR" "$HA_IMAGE_DOCKERHUB"; do
+          echo "Trying $registry..."
+          if docker pull "$registry"; then
+            if [ "$registry" != "$HA_IMAGE_GHCR" ]; then
+              docker tag "$registry" "$HA_IMAGE_GHCR"
+            fi
+            docker save "$HA_IMAGE_GHCR" -o /tmp/ha-image.tar
+            echo "Pulled and cached from $registry"
+            exit 0
+          fi
+          echo "Failed to pull from $registry, trying next..."
+          sleep 15
+        done
+        echo "All registries failed" && exit 1
+
     - name: Run full E2E test suite
       run: |
         echo "🚀 Running full E2E test suite with ${{ matrix.pytest_workers }} workers..."
@@ -68,6 +136,8 @@ jobs:
 
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
+      with:
+        cache-binary: true
 
     - name: Install uv
       uses: astral-sh/setup-uv@v7

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+  - repo: local
+    hooks:
+      - id: unit-tests
+        name: unit tests
+        entry: uv run pytest tests/src/unit/ -n auto -m "not slow" --tb=short -q
+        language: system
+        pass_filenames: false
+        files: ^(src/|tests/|pyproject\.toml)

AGENTS.md

@@ -437,6 +437,20 @@ Balance improvement against regression risk. Consider:
 | **Tests exist, quality is low** | Improve test quality if it's straightforward (better assertions, clearer names, remove duplication) |
 | **Code quality is really low** | Open an issue describing the technical debt instead of fixing it inline |
 
+### Test Coverage Requirements
+
+**When tests ARE required:**
+- New MCP tools in `src/ha_mcp/tools/` without any E2E tests
+- Tools that previously had NO tests — add E2E tests even if not part of current PR
+- Core functionality changes in `client/`, `server.py`, or `errors.py` without coverage
+- Bug fixes without regression tests
+
+**When tests may NOT be required:**
+- Refactoring with existing comprehensive test coverage
+- Documentation-only changes (`*.md` files)
+- Minor parameter additions to well-tested tools
+- Internal utilities already covered by E2E tests
+
 **Examples:**
 
 ```python
@@ -598,11 +612,11 @@ def register_<domain>_tools(mcp, client, **kwargs):
 ```
 
 ### Safety Annotations
-| Annotation | Use For |
-|------------|---------|
-| `readOnlyHint: True` | No side effects |
-| `idempotentHint: True` | Safe to retry |
-| `destructiveHint: True` | Deletes data |
+| Annotation | Default | Use For |
+|------------|---------|--------|
+| `readOnlyHint: True` | `False` | Tool does not modify its environment |
+| `destructiveHint: True` | `True` | Tool may perform destructive updates (only meaningful when `readOnlyHint` is false). Set to `False` for non-destructive writes (e.g., creating a record) |
+| `idempotentHint: True` | `False` | Repeated calls with same args have no additional effect (only meaningful when `readOnlyHint` is false) |
 
 ### Error Handling
 
@@ -674,9 +688,7 @@ A change is **BREAKING** only if it removes functionality that users depend on w
 
 **Principle**: MCP tools should wait for operations to complete before returning, not just acknowledge API success.
 
-**Current State (#365)**: Tests use polling helpers to wait for completion after tool calls.
-
-**Future State (#381)**: Tools will have optional `wait` parameter (default `True`) to handle waiting internally:
+**Implementation (#381)**: Tools have an optional `wait` parameter (default `True`) that controls whether they poll for completion:
 
 ```python
 # Config operations wait by default
@@ -689,12 +701,15 @@ await _verify_all_created(entity_ids)  # Batch verification
 ```
 
 **Tool Categories**:
-- **Config ops** (automations, helpers, scripts): MUST wait by default
-- **Service calls** (lights, switches): SHOULD wait for state change
-- **Async ops** (automation triggers, external integrations): Return immediately, users poll
-- **Query ops** (get_state, search): Return immediately
-
-See issue #381 for implementation plan.
+- **Config ops** (automations, helpers, scripts): Wait by default (poll until entity queryable/removed)
+- **Service calls** (lights, switches): Wait for state change on state-changing services (turn_on, turn_off, toggle, etc.)
+- **Async ops** (automation triggers, external integrations): Return immediately (not state-changing)
+- **Query ops** (get_state, search): Return immediately (no `wait` parameter)
+
+**Shared utilities** in `src/ha_mcp/tools/util_helpers.py`:
+- `wait_for_entity_registered(client, entity_id)` — polls until entity accessible via state API
+- `wait_for_entity_removed(client, entity_id)` — polls until entity no longer accessible
+- `wait_for_state_change(client, entity_id, expected_state)` — polls until state changes
 
 ## Context Engineering & Progressive Disclosure
 

CONTRIBUTING.md

@@ -6,9 +6,10 @@ Thank you for your interest in contributing!
 
 1. **Fork and clone** the repository
 2. **Install**: `uv sync --group dev`
-3. **Test**: `uv run pytest tests/src/e2e/ -v` (requires Docker)
-4. **Make changes** and commit
-5. **Open Pull Request**
+3. **Install hooks**: `uv run pre-commit install`
+4. **Test**: `uv run pytest tests/src/e2e/ -v` (requires Docker)
+5. **Make changes** and commit
+6. **Open Pull Request**
 
 ## 🧪 Testing
 
@@ -20,6 +21,7 @@ See **[tests/README.md](tests/README.md)**.
 ```bash
 cp .env.example .env    # Edit with your HA details
 uv sync --group dev
+uv run pre-commit install  # Install pre-commit hooks
 ```
 
 **Code quality:**
@@ -29,6 +31,8 @@ uv run ruff check --fix src/ tests/ # Lint
 uv run mypy src/                   # Type check
 ```
 
+On every commit, a `pre-commit` hook runs `ruff check --fix` to auto-fix and catch lint violations. The **Ruff Lint** CI job also enforces this on pull requests.
+
 ## 📋 Guidelines
 
 - **Code**: Follow existing patterns, add type hints, test new features

README.md

@@ -192,14 +192,22 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ## 👥 Contributors
 
-- **[@julienld](https://github.com/julienld)** — Project maintainer & core contributor.
-- **[@kingbear2](https://github.com/kingbear2)** — Windows UV setup guide.
-- **[@sergeykad](https://github.com/sergeykad)** — Dashboard card-level CRUD operations, better changelogs and removed the dependency to textdistance/numpy.
-- **[@konradwalsh](https://github.com/konradwalsh)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
-- **[@cj-elevate](https://github.com/cj-elevate)** — Integration & entity management tools (enable/disable/delete).
-- **[@kingpanther13](https://github.com/kingpanther13)** — Dev channel documentation, bulk control validation, OAuth 2.1 docs, tool consolidation, error handling improvements, and native solutions guidance.
+### Maintainers
+
+- **[@julienld](https://github.com/julienld)** — Project creator & core maintainer.
+- **[@sergeykad](https://github.com/sergeykad)** — Dashboard CRUD, search pagination, `__main__` security refactor, pre-commit hooks & CI lint, addon Docker fixes, `.gitattributes` enforcement, human-readable log timestamps, and removed the textdistance/numpy dependency.
+- **[@kingpanther13](https://github.com/kingpanther13)** — Dev channel documentation, bulk control validation, OAuth 2.1 docs, tool consolidation, error handling improvements, native solutions guidance, default dashboard editing fix, and search response optimization.
+
+### Contributors
+
+- **[@airlabno](https://github.com/airlabno)** — Support for `data` field in schedule time blocks.
+- **[@ryphez](https://github.com/ryphez)** — Codex Desktop UI MCP quick setup guide.
 - **[@Danm72](https://github.com/Danm72)** — Entity registry tools (`ha_set_entity`, `ha_get_entity`) for managing entity properties.
 - **[@Raygooo](https://github.com/Raygooo)** — SOCKS proxy support.
+- **[@cj-elevate](https://github.com/cj-elevate)** — Integration & entity management tools (enable/disable/delete).
+- **[@maxperron](https://github.com/maxperron)** — Beta testing.
+- **[@kingbear2](https://github.com/kingbear2)** — Windows UV setup guide.
+- **[@konradwalsh](https://github.com/konradwalsh)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
 
 ---
 

pyproject.toml

@@ -172,6 +172,7 @@ dev = [
     "pytest-cov>=5.0.0",
     "pytest-xdist>=3.8.0",
     "requests>=2.25.0",
+    "pre-commit>=4.0.0",
     "ruff>=0.12.12",
     "testcontainers>=4.13.0",
 ]

renovate.json

@@ -16,7 +16,8 @@
     {
       "customType": "regex",
       "managerFilePatterns": [
-        "/tests/.*\\.py$/"
+        "/tests/.*\\.py$/",
+        "/.github/workflows/.*\\.yml$/"
       ],
       "matchStrings": [
         "# renovate: datasource=(?<datasource>\\S+) depName=(?<depName>\\S+)\\s+.*?\\S+:(?<currentValue>[\\d.]+)"

site/src/content/clients/codex.md

@@ -61,6 +61,30 @@ codex mcp add homeassistant --env HOMEASSISTANT_URL={{HOMEASSISTANT_URL}} --env
 codex mcp add home-assistant --url {{MCP_SERVER_URL}}
 ```
 
+## Quick Setup with Codex Desktop UI
+
+Codex Desktop supports MCP servers via **STDIO** or **Streamable HTTP**.
+For local machine setup with `ha-mcp`, use **STDIO** so Codex launches `ha-mcp` as a subprocess.
+
+### Local Machine (STDIO)
+
+1. Open Codex Desktop
+2. Go to **Settings** → **MCP**
+3. Click **Add Server**
+4. Set:
+   - **Type:** `STDIO`
+   - **Name:** `home-assistant` (or `ha-mcp`)
+   - **Command:** `uvx`
+   - **Args:** `ha-mcp@latest`
+5. Add environment variables:
+   - `HOMEASSISTANT_URL={{HOMEASSISTANT_URL}}`
+   - `HOMEASSISTANT_TOKEN={{HOMEASSISTANT_TOKEN}}`
+
+### When to Use Streamable HTTP
+
+Use **Streamable HTTP** only when `ha-mcp` is running as a network HTTP server (for example behind a reverse proxy or tunnel).
+For local machine setup, use **STDIO**.
+
 ## Management Commands
 
 ```bash