Merge branch 'homeassistant-ai:master' into master

Author: JohnBarton27

.env.example

@@ -32,6 +32,15 @@ LOG_LEVEL=INFO
 # top-level keys in configuration.yaml and packages/*.yaml.
 # ENABLE_YAML_CONFIG_EDITING=false
 
+# Tool visibility seed values (comma-separated tool names). On first start
+# these are written to tool_config.json; after that the web settings UI at
+# http://<server>/settings is the source of truth. See DOCS.md for details.
+# DISABLED_TOOLS=
+# PINNED_TOOLS=
+
+# Max results from ha_search_tools (2-10, default 5).
+# TOOL_SEARCH_MAX_RESULTS=5
+
 # Optional: MCP Server Configuration
 MCP_SERVER_NAME=ha-mcp
-# MCP_SERVER_VERSION defaults to the package version (e.g. 6.7.2)
+# MCP_SERVER_VERSION defaults to the package version (e.g. 6.7.2)

.github/workflows/hotfix-release.yml

@@ -28,14 +28,22 @@ jobs:
       issues: write
 
     steps:
-    - name: Checkout hotfix branch commit
+    - name: Checkout merged hotfix on master
       uses: actions/checkout@v6
       with:
-        # Checkout the original hotfix commit, not the merge commit
-        ref: ${{ github.event.pull_request.head.sha }}
+        # Check out the merge commit so the workspace matches master's history;
+        # then attach to a local master branch below. python-semantic-release
+        # matches the active branch against [tool.semantic_release].branch
+        # in pyproject.toml — a detached HEAD checkout (e.g., of head.sha)
+        # fails silently with "Detached HEAD state cannot match any release
+        # groups; no release will be made", which is what broke PR #1090.
+        ref: ${{ github.event.pull_request.merge_commit_sha }}
         fetch-depth: 0
         token: ${{ secrets.GITHUB_TOKEN }}
 
+    - name: Attach to master branch locally
+      run: git checkout -B master HEAD
+
     - name: Validate hotfix is based on stable
       run: |
         # Get the stable tag (moving tag that points to latest stable)

CHANGELOG.md

@@ -3,6 +3,19 @@
 <!-- version list -->
 
 
+## v7.4.1 (2026-05-02)
+
+### Fixed
+
+- **addon**: Propagate `BUILD_VERSION` to runtime so the production add-on
+  reports the correct version in startup logs instead of the stale value
+  from `pyproject.toml` at build time
+  ([#1090](https://github.com/homeassistant-ai/ha-mcp/pull/1090)).
+- **ci**: Unbreak `hotfix-release.yml` semantic-release run; the previous
+  detached-HEAD checkout silently no-op'd every hotfix merge
+  ([#1091](https://github.com/homeassistant-ai/ha-mcp/pull/1091)).
+
+
 ## v7.4.0 (2026-04-29)
 
 ### Added

homeassistant-addon-dev/DOCS.md

@@ -14,12 +14,41 @@ The dev add-on uses the same configuration as the stable version. See the main a
 |--------|-------------|---------|
 | `backup_hint` | Backup strength preference | `normal` |
 | `secret_path` | Custom secret path (optional) | auto-generated |
+| `enable_skills` | Serve bundled HA best-practice skills as MCP resources | `true` |
+| `enable_skills_as_tools` | Expose skills via list_resources/read_resource tools | `true` |
+| `enable_tool_search` | Replace full tool catalog with search-based discovery (~46K → ~5K tokens) | `false` |
 | `enable_yaml_config_editing` *(beta)* | Enables `ha_config_set_yaml` for editing `configuration.yaml` directly. Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_filesystem_tools` *(beta)* | Enables file read/write tools (`ha_list_files`, `ha_read_file`, `ha_write_file`, `ha_delete_file`). Requires `ha_mcp_tools` custom component. | `false` |
 | `enable_custom_component_integration` *(beta)* | Enables `ha_install_mcp_tools` installer tool for the `ha_mcp_tools` custom component. | `false` |
+| `tool_search_max_results` | Max results from `ha_search_tools` (range 2-10) | `5` |
+| `disabled_tools` | Comma-separated list of tool names to disable (seed value; web UI is primary) | empty |
+| `pinned_tools` | Comma-separated list of tool names to pin when tool search is enabled (seed value; web UI is primary) | empty |
 
 Beta options are hidden under "Show unused optional configuration options" in the add-on Configuration tab. See [beta.md](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md) for details.
 
+## Tool Settings Web UI
+
+The add-on exposes a web-based settings page for managing which tools are available to AI assistants. Click **"Open Web UI"** on the add-on info page to access it.
+
+Features:
+- **Enable/disable individual tools** — toggle each tool on or off
+- **Pin tools** — keep tools always visible when `enable_tool_search` is on
+- **Per-group master toggle** — enable/disable all tools in a group (HACS, System, etc.) with one click
+- **Search** — filter tools by name or title
+- **Mandatory tools** — `ha_search_entities`, `ha_get_overview`, `ha_get_state`, `ha_report_issue` are always enabled and cannot be disabled
+- **Feature-gated tools** — `ha_config_set_yaml` (requires `enable_yaml_config_editing`), filesystem tools (require `enable_filesystem_tools`), and `ha_install_mcp_tools` (requires `enable_custom_component_integration`) appear in the list with a note if their feature flag is off
+- **In-UI restart** — a "Restart Add-on" button appears after saving to apply changes with one click
+
+**Important:** Tool configuration changes require an add-on restart to take effect. The UI will prompt you to restart after saving.
+
+### Non-add-on installations
+
+In Docker (`ha-mcp-web`) and standalone HTTP installations, the settings UI is mounted under your MCP secret path. Open `http://<host>:<port>/<secret_path>/settings` (the same URL prefix that protects your MCP endpoint). This keeps the auth posture consistent — anyone who can reach your MCP endpoint can also use the settings UI; anyone who can't, can't.
+
+### Text-field fallback
+
+If you prefer not to use the web UI (or want to set these before first start), the `disabled_tools` and `pinned_tools` options accept comma-separated tool names as seed values. On first start, the add-on creates `/data/tool_config.json` from these values. After that, the web UI is the source of truth.
+
 ## Updates
 
 The dev channel updates automatically with every commit to master. You may receive multiple updates per day.

homeassistant-addon-dev/config.yaml

@@ -1,6 +1,6 @@
 name: "Home Assistant MCP Server (Dev)"
 description: "Development channel - AI assistant integration via MCP (unstable)"
-version: "7.4.0.dev241"
+version: "7.4.1.dev246"
 slug: "ha_mcp_dev"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 stage: experimental
@@ -10,6 +10,9 @@ arch:
 init: false
 startup: application
 boot: manual
+ingress: true
+ingress_port: 9583
+ingress_stream: true
 hassio_api: true
 hassio_role: default
 homeassistant_api: true
@@ -21,6 +24,9 @@ options:
   enable_skills_as_tools: true
   enable_tool_search: false
   enable_yaml_config_editing: false
+  tool_search_max_results: 5
+  disabled_tools: ""
+  pinned_tools: ""
 schema:
   backup_hint: list(strong|normal|weak|auto)
   secret_path: str?
@@ -30,5 +36,8 @@ schema:
   enable_yaml_config_editing: bool?
   enable_filesystem_tools: bool?
   enable_custom_component_integration: bool?
+  tool_search_max_results: int(2,10)?
+  disabled_tools: str?
+  pinned_tools: str?
 ports:
   9583/tcp: 9583

homeassistant-addon-dev/translations/en.yaml

@@ -56,3 +56,22 @@ configuration:
       required for filesystem tools to function. Only enable if you want to
       allow the AI assistant to use the installer tool. Requires restart to
       take effect.
+  tool_search_max_results:
+    name: Tool search max results
+    description: >-
+      Maximum number of tools returned by ha_search_tools when tool
+      search is enabled. Lower values (2-3) save context tokens but
+      may miss relevant tools. Range: 2-10. Requires restart.
+  disabled_tools:
+    name: Disabled tools (text fallback)
+    description: >-
+      Comma-separated tool names to disable. For a visual interface,
+      click "Open Web UI" on the addon info page. This field seeds the initial config
+      when the web UI hasn't been used yet. Requires restart.
+  pinned_tools:
+    name: Pinned tools (text fallback)
+    description: >-
+      Comma-separated tool names to pin (always visible in tool search).
+      For a visual interface, click "Open Web UI" on the addon info page. This field
+      seeds the initial config when the web UI hasn't been used yet.
+      Requires restart.

homeassistant-addon/CHANGELOG.md

@@ -3,6 +3,19 @@
 <!-- version list -->
 
 
+## v7.4.1 (2026-05-02)
+
+### Fixed
+
+- **addon**: Propagate `BUILD_VERSION` to runtime so the production add-on
+  reports the correct version in startup logs instead of the stale value
+  from `pyproject.toml` at build time
+  ([#1090](https://github.com/homeassistant-ai/ha-mcp/pull/1090)).
+- **ci**: Unbreak `hotfix-release.yml` semantic-release run; the previous
+  detached-HEAD checkout silently no-op'd every hotfix merge
+  ([#1091](https://github.com/homeassistant-ai/ha-mcp/pull/1091)).
+
+
 ## v7.4.0 (2026-04-29)
 
 ### Added

homeassistant-addon/config.yaml

@@ -1,6 +1,6 @@
 name: "Home Assistant MCP Server"
 description: "AI assistant integration for Home Assistant via Model Context Protocol (MCP)"
-version: "7.4.0"
+version: "7.4.1"
 slug: "ha_mcp"
 url: "https://github.com/homeassistant-ai/ha-mcp"
 arch:

homeassistant-addon/start.py

@@ -263,6 +263,9 @@ def main() -> int:
     enable_yaml_config_editing = False  # default
     enable_filesystem_tools = False  # default
     enable_custom_component_integration = False  # default
+    tool_search_max_results = 5  # default
+    disabled_tools_raw = ""  # default
+    pinned_tools_raw = ""  # default
     config_read_ok = True
 
     if config_file.exists():
@@ -283,6 +286,12 @@ def main() -> int:
             enable_filesystem_tools = raw_filesystem_tools if isinstance(raw_filesystem_tools, bool) else False
             raw_custom_component = config.get("enable_custom_component_integration", False)
             enable_custom_component_integration = raw_custom_component if isinstance(raw_custom_component, bool) else False
+            raw_max_results = config.get("tool_search_max_results", 5)
+            tool_search_max_results = raw_max_results if isinstance(raw_max_results, int) else 5
+            raw_disabled = config.get("disabled_tools", "")
+            disabled_tools_raw = raw_disabled if isinstance(raw_disabled, str) else ""
+            raw_pinned = config.get("pinned_tools", "")
+            pinned_tools_raw = raw_pinned if isinstance(raw_pinned, str) else ""
         except Exception as e:
             log_error(f"Failed to read config: {e}, using defaults")
             config_read_ok = False
@@ -323,6 +332,9 @@ def main() -> int:
     os.environ["ENABLE_YAML_CONFIG_EDITING"] = str(enable_yaml_config_editing).lower()
     os.environ["HAMCP_ENABLE_FILESYSTEM_TOOLS"] = str(enable_filesystem_tools).lower()
     os.environ["HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"] = str(enable_custom_component_integration).lower()
+    os.environ["TOOL_SEARCH_MAX_RESULTS"] = str(tool_search_max_results)
+    os.environ["DISABLED_TOOLS"] = disabled_tools_raw
+    os.environ["PINNED_TOOLS"] = pinned_tools_raw
 
     os.environ["HOMEASSISTANT_TOKEN"] = supervisor_token
 
@@ -351,12 +363,21 @@ def main() -> int:
     log_info("Importing ha_mcp module...")
     from ha_mcp.__main__ import (
         StatelessSessionLogFilter,
+        _get_server,
         _get_timestamped_uvicorn_log_config,
         mcp,
         register_browser_landing,
     )
+    from ha_mcp.settings_ui import register_settings_routes
 
     register_browser_landing(mcp, secret_path)
+    # Mount settings UI routes both at root (for HA ingress proxy) and
+    # under the secret path (for direct port access). See
+    # register_settings_routes docstring for the auth model. Use the
+    # server's actual FastMCP instance (not the _DeferredMCP wrapper)
+    # so mypy doesn't trip over the duck-typed __getattr__ forwarding.
+    server_instance = _get_server()
+    register_settings_routes(server_instance.mcp, server_instance, secret_path=secret_path)
     logging.getLogger("mcp.server.streamable_http").addFilter(
         StatelessSessionLogFilter()
     )

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp"
-version = "7.4.0"
+version = "7.4.1"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"