PyPI - ha-mcp-dev - Versions diffs - 9.1.1.dev3380__tar.gz → 9.1.1.dev3386__tar.gz - Mend

ha-mcp-dev 9.1.1.dev3380tar.gz → 9.1.1.dev3386tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (847) hide show

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/PKG-INFO RENAMED Viewed

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.1.dev3380
-Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
+Version: 9.1.1.dev3386
+Summary: Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
 Author-email: Julien <github@qc-h.net>
@@ -64,7 +64,7 @@ Description-Content-Type: text/markdown
 <div align="center">
   <img src="https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/docs/img/ha-mcp-logo.png" alt="Home Assistant MCP Server Logo" width="300"/>
-  # The Unofficial and Awesome Home Assistant MCP Server
+  # HA-MCP — Manage Home Assistant with AI
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
@@ -82,8 +82,7 @@ Description-Content-Type: text/markdown
   </p>
   <p align="center">
-    <em>A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.<br>
-    Using natural language, control smart home devices, query states, execute services and manage your automations.</em>
+    <em>Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.</em>
   </p>
 </div>
@@ -95,7 +94,7 @@ Description-Content-Type: text/markdown
 ## 🚀 Get Started
-The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
+The recommended way to run ha-mcp is the **HA-MCP integration**. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
 **Add it to Home Assistant via HACS or, on Home Assistant 2026.11+, the Marketplace (the preferred install):**
@@ -105,13 +104,14 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 > The setup below is for version 9.0.0 (October 28, 2026) and later; earlier versions show a shorter setup form without the administrator account step.
-1. Install the **HA-MCP Custom Component**. On **Home Assistant 2026.10 or older**, from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp` (category: **Integration**), then **Download**.
-   On **Home Assistant 2026.11 or newer**, HACS is built in as the **Marketplace**: open **Settings → Marketplace** and accept its first-run warning, then **Connect GitHub** (a device sign-in). Adding a custom repository needs it, and until HA-MCP is in the Marketplace catalog it is also what makes the Marketplace check HA-MCP for updates in the background; without it, **Refresh information** on HA-MCP's Marketplace page checks by hand. Then click the badge above, or open the **Add from link** tab and add `https://github.com/homeassistant-ai/ha-mcp` as an **Integration**, and **Install**.
-   Already installed from the earlier `homeassistant-ai/ha-mcp-integration` repository? It keeps receiving the same releases; nothing to change.
+1. Install the **HA-MCP integration** (requires **Home Assistant 2026.8.0 or newer**; see [compatibility details](docs/in-process-server.md#requirements)). On **Home Assistant 2026.8–2026.10**, open HACS, search for **HA-MCP**, then **Download**.
+   On **Home Assistant 2026.11 or newer**, open **Settings → Marketplace**, accept its first-run warning, and search for **HA-MCP**, then **Install**. HA-MCP is in the default catalog, so installing it and receiving its updates do not require connecting GitHub or adding a custom repository. The badge above also opens its catalog page.
+   Already installed from the earlier `homeassistant-ai/ha-mcp-integration` repository? It keeps receiving the same releases. On the Marketplace, keep GitHub connected for its background checks on that custom repository.
+   Older installed releases may still appear as **HA-MCP Custom Component**; searching for **HA-MCP** matches both names.
 2. **Restart Home Assistant.**
 3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → **Security** → **Long-lived access tokens** → **Create token**; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under **Settings → People → Add person** with **Allow login**, **Local access only** and **Administrator** on. Never use your own login for the second option.
-4. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP Custom Component** and choose **HA-MCP Server**. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — **Remote access through Home Assistant** (start with **Secret URL**, the simplest; **Home Assistant sign-in** adds a login) and/or **Network access: Local network** — then click **Submit**. Both start disabled, so a client on another device needs one of them.
-5. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure**). A notification confirms the server started and points you there.
+4. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP** and choose **HA-MCP Server**. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — **Remote access through Home Assistant** (start with **Secret URL**, the simplest; **Home Assistant sign-in** adds a login) and/or **Network access: Local network** — then click **Submit**. Both start disabled, so a client on another device needs one of them.
+5. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → “HA-MCP — Manage Home Assistant with AI” → HA-MCP Server → Configure**). A notification confirms the server started and points you there.
 6. Paste that URL into your AI client — done.
 **Connect URL.** The Configure screen gives you a Home Assistant webhook URL for remote clients — `https://<your-ha-domain>/api/webhook/<webhook-id>` through Nabu Casa or any reverse proxy already pointed at Home Assistant (locally, `http://<ha-host>:8123/api/webhook/<webhook-id>`). For clients on the same network, the server is also reachable directly at `http://<ha-ip>:9584/private_<random>`.
@@ -354,7 +354,7 @@ ha-mcp is a standalone server built for **configuring, building, and debugging**
 ## 🔌 Custom Component (ha_mcp_tools) — File & YAML Services
-The **HA-MCP Custom Component** also powers a set of privileged tools that standard Home Assistant APIs can't provide: file system access and YAML config editing. (The same component runs the full server in-process — that's the recommended install in the **Get Started** section at the top.) Its **File & YAML services entry** (**HA-MCP File & YAML Tools**) enables the tools below.
+The **HA-MCP integration** also powers a set of privileged tools that standard Home Assistant APIs can't provide: file system access and YAML config editing. (The same component runs the full server in-process — that's the recommended install in the **Get Started** section at the top.) Its **File & YAML services entry** (**HA-MCP File & YAML Tools**) enables the tools below.
 **Tools that require the component:**
@@ -372,13 +372,13 @@ These tools also require beta feature flags. See **[Beta Features](docs/beta.md)
 ### Install
-Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP Custom Component**:
+Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP integration**:
 [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
-To add manually on Home Assistant 2026.10 or older: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**. On 2026.11 or newer: in **Marketplace**, accept the first-run warning and **Connect GitHub**, then **Add from link** > `https://github.com/homeassistant-ai/ha-mcp` as an **Integration** > **Install**. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
+Requires **Home Assistant 2026.8.0 or newer** through HACS or the Marketplace; see [compatibility details](docs/in-process-server.md#requirements) for manual installs. On Home Assistant 2026.8–2026.10: open **HACS**, search for **HA-MCP**, and **Download**. On 2026.11 or newer: open **Marketplace**, accept the first-run warning, search for **HA-MCP**, and **Install**. The main repository is in the default catalog for both. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
-After installing, restart Home Assistant, then open **Settings** > **Devices & Services** > **Add Integration**, search for **HA-MCP Custom Component**, and add the **HA-MCP File & YAML Tools** entry.
+After installing, restart Home Assistant, then open **Settings** > **Devices & Services** > **Add Integration**, search for **HA-MCP**, and add the **HA-MCP File & YAML Tools** entry.
 To run the full ha-mcp server in-process through this same component, see the **Get Started** section at the top and the [full in-process server documentation →](docs/in-process-server.md).
@@ -442,7 +442,7 @@ A `ha_manage_*` tool combines several operations, so it is reachable from more t
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
-> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; disconnect and reconnect a Claude Desktop custom connector; refresh the tools list of a claude.ai connector; or quit and reopen Claude Desktop for a server in `claude_desktop_config.json`), then start a new conversation. If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
 For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-app settings UI for fine-grained tool enable/disable/pin.

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/README.md RENAMED Viewed

@@ -3,7 +3,7 @@
 <div align="center">
   <img src="https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/docs/img/ha-mcp-logo.png" alt="Home Assistant MCP Server Logo" width="300"/>
-  # The Unofficial and Awesome Home Assistant MCP Server
+  # HA-MCP — Manage Home Assistant with AI
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
@@ -21,8 +21,7 @@
   </p>
   <p align="center">
-    <em>A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with Home Assistant.<br>
-    Using natural language, control smart home devices, query states, execute services and manage your automations.</em>
+    <em>Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants.</em>
   </p>
 </div>
@@ -34,7 +33,7 @@
 ## 🚀 Get Started
-The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
+The recommended way to run ha-mcp is the **HA-MCP integration**. It installs into Home Assistant through HACS (the built-in Marketplace on Home Assistant 2026.11+), runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
 **Add it to Home Assistant via HACS or, on Home Assistant 2026.11+, the Marketplace (the preferred install):**
@@ -44,13 +43,14 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 > The setup below is for version 9.0.0 (October 28, 2026) and later; earlier versions show a shorter setup form without the administrator account step.
-1. Install the **HA-MCP Custom Component**. On **Home Assistant 2026.10 or older**, from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp` (category: **Integration**), then **Download**.
-   On **Home Assistant 2026.11 or newer**, HACS is built in as the **Marketplace**: open **Settings → Marketplace** and accept its first-run warning, then **Connect GitHub** (a device sign-in). Adding a custom repository needs it, and until HA-MCP is in the Marketplace catalog it is also what makes the Marketplace check HA-MCP for updates in the background; without it, **Refresh information** on HA-MCP's Marketplace page checks by hand. Then click the badge above, or open the **Add from link** tab and add `https://github.com/homeassistant-ai/ha-mcp` as an **Integration**, and **Install**.
-   Already installed from the earlier `homeassistant-ai/ha-mcp-integration` repository? It keeps receiving the same releases; nothing to change.
+1. Install the **HA-MCP integration** (requires **Home Assistant 2026.8.0 or newer**; see [compatibility details](docs/in-process-server.md#requirements)). On **Home Assistant 2026.8–2026.10**, open HACS, search for **HA-MCP**, then **Download**.
+   On **Home Assistant 2026.11 or newer**, open **Settings → Marketplace**, accept its first-run warning, and search for **HA-MCP**, then **Install**. HA-MCP is in the default catalog, so installing it and receiving its updates do not require connecting GitHub or adding a custom repository. The badge above also opens its catalog page.
+   Already installed from the earlier `homeassistant-ai/ha-mcp-integration` repository? It keeps receiving the same releases. On the Marketplace, keep GitHub connected for its background checks on that custom repository.
+   Older installed releases may still appear as **HA-MCP Custom Component**; searching for **HA-MCP** matches both names.
 2. **Restart Home Assistant.**
 3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → **Security** → **Long-lived access tokens** → **Create token**; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under **Settings → People → Add person** with **Allow login**, **Local access only** and **Administrator** on. Never use your own login for the second option.
-4. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP Custom Component** and choose **HA-MCP Server**. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — **Remote access through Home Assistant** (start with **Secret URL**, the simplest; **Home Assistant sign-in** adds a login) and/or **Network access: Local network** — then click **Submit**. Both start disabled, so a client on another device needs one of them.
-5. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure**). A notification confirms the server started and points you there.
+4. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP** and choose **HA-MCP Server**. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — **Remote access through Home Assistant** (start with **Secret URL**, the simplest; **Home Assistant sign-in** adds a login) and/or **Network access: Local network** — then click **Submit**. Both start disabled, so a client on another device needs one of them.
+5. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → “HA-MCP — Manage Home Assistant with AI” → HA-MCP Server → Configure**). A notification confirms the server started and points you there.
 6. Paste that URL into your AI client — done.
 **Connect URL.** The Configure screen gives you a Home Assistant webhook URL for remote clients — `https://<your-ha-domain>/api/webhook/<webhook-id>` through Nabu Casa or any reverse proxy already pointed at Home Assistant (locally, `http://<ha-host>:8123/api/webhook/<webhook-id>`). For clients on the same network, the server is also reachable directly at `http://<ha-ip>:9584/private_<random>`.
@@ -293,7 +293,7 @@ ha-mcp is a standalone server built for **configuring, building, and debugging**
 ## 🔌 Custom Component (ha_mcp_tools) — File & YAML Services
-The **HA-MCP Custom Component** also powers a set of privileged tools that standard Home Assistant APIs can't provide: file system access and YAML config editing. (The same component runs the full server in-process — that's the recommended install in the **Get Started** section at the top.) Its **File & YAML services entry** (**HA-MCP File & YAML Tools**) enables the tools below.
+The **HA-MCP integration** also powers a set of privileged tools that standard Home Assistant APIs can't provide: file system access and YAML config editing. (The same component runs the full server in-process — that's the recommended install in the **Get Started** section at the top.) Its **File & YAML services entry** (**HA-MCP File & YAML Tools**) enables the tools below.
 **Tools that require the component:**
@@ -311,13 +311,13 @@ These tools also require beta feature flags. See **[Beta Features](docs/beta.md)
 ### Install
-Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP Custom Component**:
+Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP integration**:
 [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
-To add manually on Home Assistant 2026.10 or older: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**. On 2026.11 or newer: in **Marketplace**, accept the first-run warning and **Connect GitHub**, then **Add from link** > `https://github.com/homeassistant-ai/ha-mcp` as an **Integration** > **Install**. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
+Requires **Home Assistant 2026.8.0 or newer** through HACS or the Marketplace; see [compatibility details](docs/in-process-server.md#requirements) for manual installs. On Home Assistant 2026.8–2026.10: open **HACS**, search for **HA-MCP**, and **Download**. On 2026.11 or newer: open **Marketplace**, accept the first-run warning, search for **HA-MCP**, and **Install**. The main repository is in the default catalog for both. Or copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory.
-After installing, restart Home Assistant, then open **Settings** > **Devices & Services** > **Add Integration**, search for **HA-MCP Custom Component**, and add the **HA-MCP File & YAML Tools** entry.
+After installing, restart Home Assistant, then open **Settings** > **Devices & Services** > **Add Integration**, search for **HA-MCP**, and add the **HA-MCP File & YAML Tools** entry.
 To run the full ha-mcp server in-process through this same component, see the **Get Started** section at the top and the [full in-process server documentation →](docs/in-process-server.md).
@@ -381,7 +381,7 @@ A `ha_manage_*` tool combines several operations, so it is reachable from more t
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
-> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; disconnect and reconnect a Claude Desktop custom connector; refresh the tools list of a claude.ai connector; or quit and reopen Claude Desktop for a server in `claude_desktop_config.json`), then start a new conversation. If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
 For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-app settings UI for fine-grained tool enable/disable/pin.

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/pyproject.toml RENAMED Viewed

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 [project]
 name = "ha-mcp-dev"
-version = "9.1.1.dev3380"
-description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
+version = "9.1.1.dev3386"
+description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
 license = "MIT"

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/pyproject.toml.orig RENAMED Viewed

@@ -4,8 +4,8 @@ build-backend = "uv_build"
 [project]
 name = "ha-mcp-dev"
-version = "9.1.1.dev3380"
-description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
+version = "9.1.1.dev3386"
+description = "Configure and automate Home Assistant with Claude, ChatGPT, and other AI assistants."
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's
 # interpreter when run in-process by the ha_mcp_tools component (HA

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/hacs_auto_refresh.py RENAMED Viewed

@@ -1,12 +1,11 @@
 """Ask HACS to surface the paired component update after a server update (opt-in).
-HACS refreshes a *custom* repository's release data from GitHub only about
-every 48 hours, and the Marketplace that replaces it in Home Assistant 2026.11
-only when a GitHub account is connected. The ha_mcp_tools component ships in
-lockstep with each server release, so a component update can go unnoticed for
-days, or for good. This module closes that gap for every install, the embedded
-server included. It goes away once ha-mcp is in the default catalog, which the
-Marketplace refreshes every 6 hours.
+The main repository is already in the HACS and Marketplace default catalog.
+An external server can update before the store's next scheduled metadata
+refresh, leaving its paired integration update undiscovered. This optional
+startup nudge asks for fresh repository information sooner, for installed
+main-repository entries and existing legacy-mirror entries alike. It is not
+required for catalog installation and never installs an update itself.
 On startup, when the server version changed since the last recorded nudge (the
 just-updated case) or a newer release is pending, it sends the store's "Update

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/renamed_tools.py RENAMED Viewed

@@ -18,11 +18,16 @@ readers pick the more restrictive one (``rename_retired_keys``'s ``prefer``).
 And a call on a retired name carries the old signature, which the merged tool
 cannot dispatch without the ``action`` it never had —
 ``adapt_retired_arguments`` fills that in.
+A parameter can move the same way a tool does. ``RENAMED_PARAMETERS`` keeps
+the old parameter name callable for a client that has not re-listed, and
+``CLIENT_TOOL_LIST_REFRESH_STEPS`` is what such a client's user has to do.
 """
 from __future__ import annotations
-from collections.abc import Callable, Mapping
+import json
+from collections.abc import Callable, Mapping, Sequence
 from typing import Any
 # Retired tool name -> the name that serves it today.
@@ -37,6 +42,24 @@ RENAMED_TOOLS: dict[str, str] = {
     "ha_import_blueprint": "ha_manage_blueprints",
 }
+# Current tool name -> retired parameter name -> the name that serves it today.
+# Only a pure rename belongs here: the value keeps its meaning and its format.
+RENAMED_PARAMETERS: dict[str, dict[str, str]] = {
+    "ha_config_get_automation": {"identifier": "entity_id"},
+    "ha_config_set_automation": {"identifier": "entity_id"},
+    "ha_config_remove_automation": {"identifier": "entity_id"},
+}
+# How each client re-fetches the tool list, for every text that tells an agent
+# its list is stale. Steps are separated by ";" and carry none inside.
+CLIENT_TOOL_LIST_REFRESH_STEPS = (
+    "Claude Desktop custom connector: disconnect and reconnect it; "
+    "server in claude_desktop_config.json: quit and reopen Claude Desktop; "
+    "claude.ai: refresh the connector's tools list; Claude Code: /mcp, "
+    "reconnect; ChatGPT: open Settings, then the plugin settings, select the "
+    "connector and click Refresh tools"
+)
 def current_tool_name(name: str) -> str:
     """The name a tool answers to today, given any name it has had."""
@@ -101,3 +124,56 @@ def adapt_retired_arguments(
     if adapter is None:
         return dict(arguments) if arguments is not None else None
     return adapter(dict(arguments or {}))
+def retired_parameters_used(
+    name: str, arguments: Mapping[str, Any] | None
+) -> dict[str, str]:
+    """The retired parameter names a call on ``name`` carries, with their current names.
+    A retired name sent together with its current name is left out: that
+    caller knows the current signature, so the stray argument is rejected like
+    any other unknown one instead of replacing the value sent under the
+    current name.
+    """
+    renames = RENAMED_PARAMETERS.get(name)
+    if not renames or not arguments:
+        return {}
+    return {
+        old: new
+        for old, new in renames.items()
+        if old in arguments and new not in arguments
+    }
+def add_stale_list_warning(result: Any, renames: Sequence[tuple[str, str]]) -> None:
+    """Tell the caller of a call served through an old name that its list is stale.
+    ``renames`` holds each old name with its current one. The warning joins the
+    result's top-level ``warnings`` in both representations: the structured
+    content and the JSON text a client without it reads.
+    """
+    listed = ", ".join(f"`{old}` is now `{new}`" for old, new in renames)
+    warning = (
+        f"This call used a name from before an ha-mcp update ({listed}). It "
+        "was served, but your tool list is a stale copy. Ask the user to "
+        f"refresh it ({CLIENT_TOOL_LIST_REFRESH_STEPS}), then start a new "
+        "conversation."
+    )
+    structured = getattr(result, "structured_content", None)
+    if isinstance(structured, dict):
+        result.structured_content = {
+            **structured,
+            "warnings": [*(structured.get("warnings") or []), warning],
+        }
+    for block in getattr(result, "content", None) or []:
+        text = getattr(block, "text", None)
+        if not isinstance(text, str):
+            continue
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            parsed["warnings"] = [*(parsed.get("warnings") or []), warning]
+            block.text = json.dumps(parsed)

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/server_tool_text.py RENAMED Viewed

@@ -480,10 +480,11 @@ LITE_DOCSTRINGS: dict[str, str] = {
         "The response carries the full workflow in its `instructions` "
         "field (duplicate check, the mandatory anonymisation step, and "
         "how to file the issue), plus "
-        '`missing_tool_hint` for the "a tool I expected is missing" '
-        "case, which is usually a stale client tool list rather than a "
-        "bug. Read `instructions` before presenting anything to the "
-        "user; ha_get_skill_guide does not cover issue reporting."
+        '`missing_tool_hint` for the "a tool I expected is missing" or '
+        '"a tool rejects as unknown a parameter my tool list shows" case, '
+        "which is usually a stale client tool list rather than a bug. Read "
+        "`instructions` before presenting anything to the user; "
+        "ha_get_skill_guide does not cover issue reporting."
     ),
 }

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/settings_ui/locales/en.json RENAMED Viewed

@@ -27,7 +27,7 @@
     "tabs.policies": "Tool Security Policies",
     "tabs.visibility": "Entity Visibility",
     "tabs.accessibility": "Accessibility",
-    "notice.restart_required": "⚠ Changes saved. Restart HA-MCP for them to take effect. On next startup, HA-MCP fully removes disabled tools from the MCP tool list. Then reconnect or refresh the MCP server in your AI client (e.g. refresh tool list on claude.ai, re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop) so it reloads the tool list. Restarting the app (add-on) or Home Assistant does NOT refresh your client's cached tool list. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
+    "notice.restart_required": "⚠ Changes saved. Restart HA-MCP for them to take effect. On next startup, HA-MCP fully removes disabled tools from the MCP tool list. Then reconnect or refresh the MCP server in your AI client (e.g. refresh tool list on claude.ai; in ChatGPT open Settings, then the plugin settings, select the connector and click Refresh tools; disconnect and reconnect a Claude Desktop custom connector; or quit and reopen Claude Desktop for a server in claude_desktop_config.json) so it reloads the tool list, then start a new conversation. Restarting the app (add-on) or Home Assistant does NOT refresh your client's cached tool list. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
     "notice.shared_settings": "Server-wide features (Tool Search, YAML config editing, filesystem tools, etc.) appear in both the <strong>Server Settings</strong> tab and the app (add-on) Configuration page; they're the same settings either way. Either surface stays in sync with the other after the app (add-on) restarts. Changes require HA-MCP to be restarted.",
     "notice.env_pins": "Tools listed in the <code>DISABLED_TOOLS</code> or <code>PINNED_TOOLS</code> env vars are locked read-only; unset the env var to edit them here. Pin toggles only take effect when Tool Search is enabled (Server Settings tab or app (add-on) Configuration page).",
     "actions.restart_addon": "Restart app (add-on)",
@@ -39,7 +39,7 @@
     "tools.read_only.help": "Turns off all write tools and blocks every tool from making write or destructive calls. Mixed read/write tools (backups, Apps (add-ons), energy preferences, voice pipelines, and code mode when enabled) stay available with their write operations blocked.",
     "tools.read_only.unknown": "Could not read server settings. Read Only Mode status unknown; this view may not reflect what the server enforces.",
     "tools.search": "Search tools...",
-    "server.auto_save_notice": "Settings on this tab save automatically. Changes take effect only after you restart HA-MCP (applies them server-side) and reconnect or refresh the MCP server in your AI client (reloads the tool list), e.g. refresh tool list on claude.ai, re-add or refresh the connector in ChatGPT, or close and reopen Claude Desktop. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
+    "server.auto_save_notice": "Settings on this tab save automatically. Changes take effect only after you restart HA-MCP (applies them server-side) and reconnect or refresh the MCP server in your AI client (reloads the tool list), e.g. refresh tool list on claude.ai; in ChatGPT open Settings, then the plugin settings, select the connector and click Refresh tools; disconnect and reconnect a Claude Desktop custom connector; or quit and reopen Claude Desktop for a server in claude_desktop_config.json; then start a new conversation. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
     "server.sections.search": "Search & matching",
     "server.sections.operations": "Operations",
     "server.sections.tool_surface": "Tool surface",
@@ -221,10 +221,10 @@
     "common.range_or_value": "Range {min}–{max}, or {value}.",
     "common.restart_required": "Restart required.",
     "common.none": "(none)",
-    "notice.restart.addon": "⚠ Changes saved. Click \"Restart app (add-on)\" for them to take effect. Disabled tools will be removed from the MCP tool list on next startup. Then refresh the tool list in your AI client; restarting the App alone does not refresh the client's cached list.",
-    "notice.restart.embedded": "⚠ Changes saved. Click \"Restart HA-MCP Server\" to reload the in-process integration. Then refresh the MCP tool list in your AI client.",
-    "notice.restart.sidecar": "⚠ Changes saved. Fully quit and reopen your MCP client for them to take effect. Disabled tools will be removed from the MCP tool list on next startup.",
-    "notice.restart.standalone": "⚠ Changes saved. Restart the ha-mcp process, then refresh the MCP tool list in your AI client.",
+    "notice.restart.addon": "⚠ Changes saved. Click \"Restart app (add-on)\" for them to take effect. Disabled tools will be removed from the MCP tool list on next startup. Then refresh the tool list in your AI client (for a Claude Desktop custom connector, disconnect and reconnect it; for a server in claude_desktop_config.json, quit and reopen Claude Desktop) and start a new conversation; restarting the App alone does not refresh the client's cached list.",
+    "notice.restart.embedded": "⚠ Changes saved. Click \"Restart HA-MCP Server\" to reload the in-process integration. Then refresh the MCP tool list in your AI client (for a Claude Desktop custom connector, disconnect and reconnect it; for a server in claude_desktop_config.json, quit and reopen Claude Desktop) and start a new conversation.",
+    "notice.restart.sidecar": "⚠ Changes saved. Fully quit and reopen your MCP client for them to take effect. Disabled tools will be removed from the MCP tool list on next startup. Then start a new conversation.",
+    "notice.restart.standalone": "⚠ Changes saved. Restart the ha-mcp process, then refresh the MCP tool list in your AI client (for a Claude Desktop custom connector, disconnect and reconnect it; for a server in claude_desktop_config.json, quit and reopen Claude Desktop) and start a new conversation.",
     "server.sidecar.confirm_disable": "⚠ PERMANENTLY disable the settings server?\n\nThis stops the server and writes a marker that prevents it from starting again. To restore access, delete ~/.ha-mcp/settings_ui_disabled and unset HA_MCP_DISABLE_SETTINGS_UI. Continue?",
     "tools.empty": "No tools found. The sidecar reads ~/.ha-mcp/tool_metadata.json. If it is missing or empty, restart your MCP client. See ~/.ha-mcp/sidecar.log for details.",
     "tools.group_count": "{enabled}/{total} enabled",
@@ -324,7 +324,7 @@
     "backup.bulk.in_use": "{count} backup(s) are in use. Retry after the active capture or restore finishes.",
     "backup.bulk.unknown": "The deletion result could not be confirmed. Check the backup list before retrying.",
     "filesystem.custom.title": "Custom filesystem paths (advanced)",
-    "filesystem.custom.help": "Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, and <code>/ssl</code> (read-only on HAOS and Supervised) are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.",
+    "filesystem.custom.help": "Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, and <code>/ssl</code> (read-only on HAOS and Supervised) are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → “HA-MCP — Manage Home Assistant with AI” (“HA-MCP Custom Component” on older installs) → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.",
     "filesystem.custom.blocked": "Always blocked: {paths}, path traversal (<code>..</code>), and absolute paths outside allowed HAOS volumes.",
     "filesystem.custom.enable_first": "Enable beta features and filesystem tools above to edit.",
     "filesystem.custom.unavailable": "Custom paths are currently unavailable.",
@@ -476,7 +476,7 @@
     "advanced.enable_history_query_guardrails.label": "History query guardrails",
     "advanced.enable_history_query_guardrails.help": "Reject recorder queries that exceed conservative entity and time-range budgets. Disabled by default.",
     "advanced.hacs_refresh_after_update.label": "Refresh the component in HACS after an update",
-    "advanced.hacs_refresh_after_update.help": "At startup after a server update, ask HACS (the Marketplace on Home Assistant 2026.11+) to re-check the HA-MCP Custom Component repository, so its matching update shows right away instead of at the next 48-hour check. Off by default; installs that already did this keep it on.",
+    "advanced.hacs_refresh_after_update.help": "At startup after a server update, ask HACS (the Marketplace on Home Assistant 2026.11+) to re-check the HA-MCP repository, so its matching update shows right away instead of waiting for the next background check. Off by default; installs that already did this keep it on.",
     "advanced.ha_tool_concurrency.label": "Home Assistant tool concurrency",
     "advanced.ha_tool_concurrency.help": "Optional limit on outer Home Assistant tool calls across all sessions. Internal REST, WebSocket, and per-tool fan-out concurrency is unchanged. 0 keeps unlimited behavior. A call waiting for capacity fails after 60 seconds.",
     "advanced.dashboard_screenshot_engine_url.label": "Dashboard screenshot engine URL",

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/settings_ui/settings.html RENAMED Viewed

@@ -173,10 +173,13 @@
     ⚠ Changes saved. Restart HA-MCP for them to take effect. On next
     startup, HA-MCP fully removes disabled tools from the MCP tool list.
     Then reconnect or refresh the MCP server in your AI client (e.g.
-    refresh tool list on claude.ai, re-add/refresh the connector in
-    ChatGPT, or close and reopen Claude Desktop) so it reloads the tool
-    list. Restarting the App (add-on) or Home Assistant does NOT refresh your
-    client's cached tool list.
+    refresh tool list on claude.ai; in ChatGPT open Settings, then the
+    plugin settings, select the connector and click Refresh tools;
+    disconnect and reconnect a Claude Desktop custom connector; or quit
+    and reopen Claude Desktop for a server in claude_desktop_config.json)
+    so it reloads the tool list, then start a new conversation. Restarting
+    the App (add-on) or Home Assistant does NOT refresh your client's
+    cached tool list.
   </span>
   <button class="restart-btn" id="restartBtn" style="display:none" data-i18n="actions.restart_addon">Restart App (add-on)</button>
 </div>
@@ -232,8 +235,11 @@
       Settings on this tab save automatically. Changes take effect only after
       you restart the App (add-on) (applies them server-side) and reconnect or
       refresh the MCP server in your AI client (reloads the tool list), e.g.
-      refresh tool list on claude.ai, re-add or refresh the connector in
-      ChatGPT, or close and reopen Claude Desktop.
+      refresh tool list on claude.ai; in ChatGPT open Settings, then the
+      plugin settings, select the connector and click Refresh tools;
+      disconnect and reconnect a Claude Desktop custom connector; or quit
+      and reopen Claude Desktop for a server in claude_desktop_config.json;
+      then start a new conversation.
     </div>
   </div>

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/settings_ui/settings_js/04_backups.js RENAMED Viewed

@@ -197,7 +197,7 @@ function renderFsCustomPathsSubForm(parentEl, masterOn, fsOn) {
       : '.storage, secrets.yaml';
   info.innerHTML =
     `<div class="feature-name">${escapeHtml(t('filesystem.custom.title', {}, 'Custom filesystem paths (advanced)'))}</div>` +
-    `<div class="feature-help">${tHtml('filesystem.custom.help', {}, 'Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, and <code>/ssl</code> (read-only on HAOS and Supervised) are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → HA-MCP Custom Component → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.')}</div>` +
+    `<div class="feature-help">${tHtml('filesystem.custom.help', {}, 'Extra paths (one per line) that file tools may <strong>read and write</strong>. Config-relative paths, including exact filenames such as <code>sensor.yaml</code>, and paths under <code>/share</code>, <code>/media</code>, and <code>/ssl</code> (read-only on HAOS and Supervised) are supported. Each entry allows that path and anything below it. Entries are matched literally; wildcards such as <code>*</code> are not supported. You can also manage these paths in Home Assistant under Settings → Devices & Services → “HA-MCP — Manage Home Assistant with AI” (“HA-MCP Custom Component” on older installs) → HA-MCP File & YAML Tools → Configure; both locations edit the same setting and apply changes immediately.')}</div>` +
     `<div class="feature-help">${tHtml('filesystem.custom.blocked', {paths: `<code>${escapeHtml(denyList)}</code>`}, 'Always blocked: {paths}, path traversal (<code>..</code>), and absolute paths outside allowed HAOS volumes.')}</div>`;
   const control = document.createElement('div');

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/tools/config_entry_flow.py RENAMED Viewed

@@ -738,8 +738,9 @@ COMPONENT_DOMAIN = "ha_mcp_tools"
 COMPONENT_ENTRY_SUGGESTIONS: tuple[str, ...] = (
     "Manage it in the Home Assistant UI: Settings > Devices & services > "
-    + "HA-MCP Custom Component (Configure for options; the entry's menu for "
-    + "enable/disable, delete and debug logging).",
+    + "“HA-MCP — Manage Home Assistant with AI” (listed as “HA-MCP Custom Component” "
+    + "on older installs). Choose Configure for options; use the entry's menu for "
+    + "enable/disable, delete and debug logging.",
     "Server settings and updates: with developer mode on, "
     + "ha_dev_manage_settings / ha_dev_manage_server.",
 )

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/tools/dashboard_card_describe.py RENAMED Viewed

@@ -121,7 +121,7 @@ async def describe_card_response(client: Any, card_type: str | None) -> dict[str
                 "with dashboard card support.",
                 suggestions=[
                     (
-                        "Install or update the HA-MCP Custom Component through "
+                        "Install or update the HA-MCP integration through "
                         "HACS (the Marketplace on Home Assistant 2026.11+)"
                     ),
                     "Restart Home Assistant after the update completes",

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3386}/src/ha_mcp/tools/log_sources_fault.py RENAMED Viewed

@@ -97,7 +97,7 @@ def _raise_read_failure(error: str) -> NoReturn:
                 f"{MIN_COMPONENT_VERSION_FAULT_LOG}).",
                 details=error,
                 suggestions=[
-                    "Settings → System → Updates → HA-MCP Custom Component → Update (HACS, or the Marketplace on Home Assistant 2026.11+)",
+                    "Settings → System → Updates → HA-MCP → Update (HACS, or the Marketplace on Home Assistant 2026.11+)",
                     "Restart Home Assistant after the update completes",
                 ],
                 context={"source": "fault_log"},

ha-mcp-dev 9.1.1.dev3380__tar.gz → 9.1.1.dev3386__tar.gz

ha-mcp-dev 9.1.1.dev3380tar.gz → 9.1.1.dev3386tar.gz