ha-mcp-dev 7.12.3.dev1937__tar.gz → 7.12.3.dev1942__tar.gz

{ha_mcp_dev-7.12.3.dev1937/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.12.3.dev1942}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1937
+Version: 7.12.3.dev1942
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -83,12 +83,13 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 
 **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>`.
 
+- **Replaces other install methods:** the in-process server is a complete, standalone ha-mcp install — it takes the place of the add-on, Docker, and uvx/PyPI (stdio) methods. Run only one; do not run the in-process server alongside another install.
 - **Local only?** Turn off **Remote access via webhook** in the entry options — no webhook is registered at all, while the direct port and sidebar panel keep working.
 - **Settings panel:** while the server runs, an admin-only **HA-MCP** panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
 - **Optional authentication:** set **Webhook authentication** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
 - **Manual install (no HACS):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
 
-The component's second entry type, **HA MCP Tools**, is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time.
+The component's second entry type, the **File & YAML services entry** (**HA-MCP File & YAML Tools**), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, add-on, Docker, or stdio).
 
 [Full in-process server documentation →](docs/in-process-server.md) · [Setup Wizard for client-specific config →](https://homeassistant-ai.github.io/ha-mcp/setup/)
 
@@ -275,9 +276,9 @@ Spend less time configuring, more time enjoying your smart home.
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_get_overview`, `ha_get_state`, `ha_search` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_config_get_yaml` *(beta)*, `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
-| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
+| **Utilities** | `ha_eval_template`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
 
 <!-- TOOLS_TABLE_END -->
@@ -307,7 +308,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 **HA MCP Tools** services entry enables the tools below.
+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.
 
 **Tools that require the component:**
 
@@ -325,13 +326,13 @@ These tools also require beta feature flags. See **[Beta Features](docs/beta.md)
 
 ### Install
 
-Install the **HA MCP Tools** services entry from the same **HA-MCP Custom Component**:
+Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP Custom Component**:
 
 [![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-integration&category=integration)
 
 To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp-integration` (category: Integration) > **Download**. 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 Tools** services entry.
+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.
 
 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).
 
@@ -477,7 +478,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@TomasDJo](https://github.com/TomasDJo)** — Category support for automations, scripts, and scenes.
 - **[@bzelch](https://github.com/bzelch)** — `python_transform` support for automations and scripts.
 - **[@gcormier](https://github.com/gcormier)** — Windows installer improvements: removed unused variable and fixed terminal closing after install.
-- **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
+- **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and the (since removed) `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
 - **[@w3z315](https://github.com/w3z315)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
 - **[@griffinmartin](https://github.com/griffinmartin)** — Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.
 - **[@hhopke](https://github.com/hhopke)** — Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing `ha_manage_addon` proxy mode on addon installs.

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/README.md

@@ -50,12 +50,13 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 
 **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>`.
 
+- **Replaces other install methods:** the in-process server is a complete, standalone ha-mcp install — it takes the place of the add-on, Docker, and uvx/PyPI (stdio) methods. Run only one; do not run the in-process server alongside another install.
 - **Local only?** Turn off **Remote access via webhook** in the entry options — no webhook is registered at all, while the direct port and sidebar panel keep working.
 - **Settings panel:** while the server runs, an admin-only **HA-MCP** panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
 - **Optional authentication:** set **Webhook authentication** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
 - **Manual install (no HACS):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
 
-The component's second entry type, **HA MCP Tools**, is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time.
+The component's second entry type, the **File & YAML services entry** (**HA-MCP File & YAML Tools**), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, add-on, Docker, or stdio).
 
 [Full in-process server documentation →](docs/in-process-server.md) · [Setup Wizard for client-specific config →](https://homeassistant-ai.github.io/ha-mcp/setup/)
 
@@ -242,9 +243,9 @@ Spend less time configuring, more time enjoying your smart home.
 | **Scripts** | `ha_config_get_script`, `ha_config_remove_script`, `ha_config_set_script` |
 | **Search & Discovery** | `ha_get_overview`, `ha_get_state`, `ha_search` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_config_get_yaml` *(beta)*, `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
-| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
+| **Utilities** | `ha_eval_template`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
 
 <!-- TOOLS_TABLE_END -->
@@ -274,7 +275,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 **HA MCP Tools** services entry enables the tools below.
+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.
 
 **Tools that require the component:**
 
@@ -292,13 +293,13 @@ These tools also require beta feature flags. See **[Beta Features](docs/beta.md)
 
 ### Install
 
-Install the **HA MCP Tools** services entry from the same **HA-MCP Custom Component**:
+Install the **HA-MCP File & YAML Tools** entry from the same **HA-MCP Custom Component**:
 
 [![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-integration&category=integration)
 
 To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp-integration` (category: Integration) > **Download**. 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 Tools** services entry.
+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.
 
 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).
 
@@ -444,7 +445,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@TomasDJo](https://github.com/TomasDJo)** — Category support for automations, scripts, and scenes.
 - **[@bzelch](https://github.com/bzelch)** — `python_transform` support for automations and scripts.
 - **[@gcormier](https://github.com/gcormier)** — Windows installer improvements: removed unused variable and fixed terminal closing after install.
-- **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
+- **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and the (since removed) `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
 - **[@w3z315](https://github.com/w3z315)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
 - **[@griffinmartin](https://github.com/griffinmartin)** — Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.
 - **[@hhopke](https://github.com/hhopke)** — Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing `ha_manage_addon` proxy mode on addon installs.

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.12.3.dev1937"
+version = "7.12.3.dev1942"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/config.py

@@ -257,14 +257,6 @@ class Settings(BaseSettings):
     # other gated capability.
     enable_filesystem_tools: bool = Field(False, alias="HAMCP_ENABLE_FILESYSTEM_TOOLS")
 
-    # Custom-component installer (``ha_install_mcp_tools``) — pulls the
-    # ``ha_mcp_tools`` integration into HACS. Same env-var-direct
-    # background as ``enable_filesystem_tools``; promoted for the same
-    # reason.
-    enable_custom_component_integration: bool = Field(
-        False, alias="HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"
-    )
-
     # Dashboard screenshot mode — the ``ha_get_dashboard_screenshot`` tool
     # plus the ``include_screenshot`` / ``return_screenshot`` params on the
     # dashboard get/set tools. Renders responsive Lovelace images via a
@@ -356,15 +348,15 @@ class Settings(BaseSettings):
     )
 
     # Mirror the legacy ``os.getenv("FLAG", "").lower() in ("true", ...)``
-    # semantics for the two ex-direct-getenv flags: an empty env var
-    # value MUST be treated as False rather than raising
+    # semantics for the ex-direct-getenv ``enable_filesystem_tools`` flag (and
+    # its sibling toggles listed above): an empty env var value MUST be treated
+    # as False rather than raising
     # ``ValidationError``. Pydantic v2's bool parser raises on ``""``
     # which broke ``test_tools_filesystem.py::TestFeatureFlag::
     # test_disabled_with_empty_string`` after the migration; this
     # validator restores the contract callers rely on.
     @field_validator(
         "enable_filesystem_tools",
-        "enable_custom_component_integration",
         "enable_dashboard_screenshot",
         mode="before",
     )
@@ -693,11 +685,6 @@ FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = (
     FeatureFlagField("enable_yaml_packages_scene", "ENABLE_YAML_PACKAGES_SCENE", bool),
     FeatureFlagField("enable_lite_docstrings", "ENABLE_LITE_DOCSTRINGS", bool),
     FeatureFlagField("enable_filesystem_tools", "HAMCP_ENABLE_FILESYSTEM_TOOLS", bool),
-    FeatureFlagField(
-        "enable_custom_component_integration",
-        "HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION",
-        bool,
-    ),
     # ``enable_code_mode`` lives in this tuple so the override file (and
     # the web UI Server Settings tab) can write the flag. Without this
     # entry, the UI save logic would have nowhere to land the value.
@@ -744,7 +731,6 @@ BETA_FEATURE_FIELDS: tuple[str, ...] = (
     "enable_yaml_packages_script",
     "enable_yaml_packages_scene",
     "enable_filesystem_tools",
-    "enable_custom_component_integration",
     "enable_code_mode",
     "enable_lite_docstrings",
     "enable_dashboard_screenshot",

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/server.py

@@ -632,9 +632,8 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "Create or update a Home Assistant script.\n\n"
             "Supports two modes: full `config` replacement, or surgical "
             "`python_transform` on an existing script (requires "
-            "`identifier` and `config_hash` from "
-            "ha_config_get_script). Omit `identifier` to create a new "
-            "script.\n\n"
+            "`config_hash` from ha_config_get_script). `script_id` names "
+            "the script in both modes.\n\n"
             "For schema details and examples, see "
             "ha_get_skill_guide."
         ),
@@ -650,19 +649,20 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "Create or update a Home Assistant scene.\n\n"
             "Supports two modes: full `config` replacement, or surgical "
             "`python_transform` on an existing scene (requires "
-            "`identifier` and `config_hash`).\n\n"
+            "`config_hash`). `scene_id` names the scene in both modes.\n\n"
             "For schema details and examples, see "
             "ha_get_skill_guide."
         ),
         "ha_config_list_helpers": (
-            "List Home Assistant helpers of a given simple type. "
-            "Accepts the 12 storage-backed helper types only: "
-            "input_button, input_boolean, input_select, input_number, "
+            "List Home Assistant helpers of a given type, one page per "
+            "call (`limit`/`offset`; `total_count` and `has_more` "
+            "describe the full set). The 12 storage-backed types "
+            "(input_button, input_boolean, input_select, input_number, "
             "input_text, input_datetime, counter, timer, schedule, "
-            "zone, person, tag. Flow-based helpers (template, group, "
-            "utility_meter, derivative, statistics, trend, threshold, "
-            "filter, switch_as_x, etc.) cannot be listed through this "
-            "tool — use ha_search.\n\n"
+            "zone, person, tag) are listed on every install. Flow-based "
+            "types (template, group, utility_meter, derivative, and the "
+            "rest) and `helper_type='all'` are served only through the "
+            "ha_mcp_tools custom component.\n\n"
             "For per-type schemas and decision guidance, see "
             "ha_get_skill_guide."
         ),

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/settings_ui/_tools_meta.py

@@ -90,8 +90,7 @@ TRANSFORM_GENERATED_TOOLS: dict[str, ToolStub] = {}
 # into the settings UI so users discover the tool exists and how to enable
 # it. Keep this dict in sync with the ``"beta"`` tag added to each tool's
 # source file (tools_yaml_config.py, tools_yaml_read.py, tools_filesystem.py,
-# tools_mcp_component.py, tools_code.py) — a future rename or removal needs to
-# land in both places.
+# tools_code.py) — a future rename or removal needs to land in both places.
 FEATURE_GATED_TOOLS: dict[str, ToolStub] = {
     "ha_config_set_yaml": {
         "title": "Set YAML Config",
@@ -142,13 +141,6 @@ FEATURE_GATED_TOOLS: dict[str, ToolStub] = {
         "disabled_by": "enable_filesystem_tools",
         "destructiveHint": True,
     },
-    "ha_install_mcp_tools": {
-        "title": "Install MCP Tools Component",
-        "primary_tag": "Utilities",
-        "description": "Install the ha_mcp_tools custom component via HACS.",
-        "disabled_by": "enable_custom_component_integration",
-        "destructiveHint": True,
-    },
 }
 
 

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/settings_ui/settings.js

@@ -1616,10 +1616,6 @@ const FEATURE_META = {
     label: "Enable filesystem tools (beta)",
     help: "Sets HAMCP_ENABLE_FILESYSTEM_TOOLS=true. Enables direct file read/write access to your Home Assistant filesystem. WARNING: This gives the MCP server sensitive direct file access to your system. Only enable if you trust the AI assistant with file operations. Requires restart to take effect.",
   },
-  enable_custom_component_integration: {
-    label: "Enable custom component integration (beta)",
-    help: "Sets HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true. Enables the ha_install_mcp_tools installer tool, which can help install the ha_mcp_tools custom component. This setting does not control whether the MCP server loads or interacts with the custom component, and it is not 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.",
-  },
   enable_code_mode: {
     label: "Enable code-mode sandbox (beta)",
     help: "Beta feature, disabled by default. Enables ha_manage_custom_tool, a sandboxed Python interpreter (pydantic-monty) that lets AI assistants write/run/save/delete custom tools when no built-in tool covers the request. Sandbox cannot touch the filesystem or arbitrary network, but CAN call any registered MCP tool, hit the HA REST API, or send HA WebSocket commands, effectively 'do whatever existing tools allow you to do, in any combination'. Saved tools persist and are visible to any client that can connect to ha-mcp. See docs/beta.md for known limitations. Requires restart to take effect.",

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_bug_report.py

@@ -211,10 +211,9 @@ def _detect_platform() -> dict[str, str]:
 # ``enable_beta_features`` leads the list because it is the master gate: when
 # off it force-disables every beta sub-flag (filesystem tools, code mode, YAML
 # editing, ...) regardless of the sub-flag's own value, so a "missing tool"
-# report is meaningless without it. ``enable_filesystem_tools`` and
-# ``enable_custom_component_integration`` are the exact beta-gated tool families
-# from issue #1804 — surfacing them lets triage see at a glance whether the tool
-# the user couldn't find was even enabled server-side.
+# report is meaningless without it. ``enable_filesystem_tools`` is a beta-gated
+# tool family from issue #1804 — surfacing it lets triage see at a glance whether
+# the tool the user couldn't find was even enabled server-side.
 _CONFIG_TOGGLE_FIELDS: tuple[str, ...] = (
     "enable_beta_features",
     "enable_websocket",
@@ -223,7 +222,6 @@ _CONFIG_TOGGLE_FIELDS: tuple[str, ...] = (
     "tool_search_max_results",
     "enable_yaml_config_editing",
     "enable_filesystem_tools",
-    "enable_custom_component_integration",
     "enable_code_mode",
     "enabled_tool_modules",
 )

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_config_helpers.py

@@ -53,6 +53,7 @@ from .util_helpers import (
     attach_skill_content,
     augment_error_dict_with_skill_content,
     augment_tool_error_with_skill_content,
+    build_pagination_metadata,
     parse_json_param,
     parse_string_list_param,
     wait_for_entity_registered,
@@ -1356,21 +1357,36 @@ def _flatten_helper_list_result(result: Any) -> list[Any]:
     """Flatten a {type}/list WS response into a flat list of helper dicts.
 
     Handles the person/list shape ({"storage": [...], "config": [...]}) and
-    the standard list shape ([...]).
+    the standard list shape ([...]). An unrecognised shape yields an empty
+    list, which downstream is indistinguishable from a helper type that has no
+    entries, so it is logged rather than dropped in silence.
     """
     if isinstance(result, dict):
         inner = result.get("result", [])
         if isinstance(inner, dict):
             items: list[Any] = []
+            matched = False
             for key in ("storage", "config"):
                 sub = inner.get(key)
                 if isinstance(sub, list):
+                    matched = True
                     items.extend(sub)
+            if not matched:
+                logger.warning(
+                    "Helper listing has neither a 'storage' nor a 'config' list "
+                    "(keys: %s); treating it as empty",
+                    sorted(inner),
+                )
             return items
         if isinstance(inner, list):
             return inner
     if isinstance(result, list):
         return result
+    logger.warning(
+        "Cannot flatten a helper listing: expected a list or a storage/config "
+        "split, got %s; treating it as empty",
+        type(result).__name__,
+    )
     return []
 
 
@@ -3508,6 +3524,53 @@ def _shape_flow_helper_record(rec: dict[str, Any]) -> dict[str, Any]:
     return out
 
 
+def _paginate_helpers_response(
+    response: dict[str, Any], offset: int, limit: int
+) -> dict[str, Any]:
+    """Slice a helper listing envelope down to one page.
+
+    The single normalization point for every ``ha_config_list_helpers`` route
+    (all-types, component, legacy): each builds the same
+    ``success``/``helper_type``/``count``/``helpers``/``message`` envelope, so
+    the slice is applied once here instead of in each builder. ``count`` becomes
+    the page size and ``total_count`` carries the full size, matching
+    ``ha_list_services``.
+    """
+    helpers = response.get("helpers")
+    if not isinstance(helpers, list):
+        # Every builder owes this function a flat list; anything else is a bug in
+        # the caller (a {type}/list shape that escaped _flatten_helper_list_result).
+        # The records are still usable, so return them unpaginated rather than
+        # raising -- but say so in warnings[], not just the log: the caller is an
+        # agent that never sees server logs, and absent metadata otherwise reads
+        # as "the collection fits on one page".
+        shape = type(helpers).__name__
+        logger.warning(
+            "Cannot paginate %r listing: expected a list of helpers, got %s; "
+            "returning the envelope unpaginated",
+            response.get("helper_type"),
+            shape,
+        )
+        warning = (
+            f"Listing could not be paginated (expected a list of helpers, got "
+            f"{shape}); returned in full, without pagination metadata."
+        )
+        existing = response.get("warnings")
+        return {
+            **response,
+            "warnings": [*existing, warning]
+            if isinstance(existing, list)
+            else [warning],
+        }
+    total_count = len(helpers)
+    page = helpers[offset : offset + limit]
+    return {
+        **response,
+        "helpers": page,
+        **build_pagination_metadata(total_count, offset, limit, len(page)),
+    }
+
+
 def _shape_component_helpers_response(
     helper_type: str, result: dict[str, Any]
 ) -> dict[str, Any]:
@@ -3643,11 +3706,30 @@ class HelperConfigTools:
                 )
             ),
         ],
+        limit: Annotated[
+            int,
+            Field(
+                default=100,
+                ge=1,
+                le=500,
+                description="Max helpers to return per page (default: 100)",
+            ),
+        ] = 100,
+        offset: Annotated[
+            int,
+            Field(
+                default=0,
+                ge=0,
+                description="Number of helpers to skip for pagination (default: 0)",
+            ),
+        ] = 0,
     ) -> dict[str, Any]:
         """
-        List all Home Assistant helpers of a specific type with their configurations.
+        List Home Assistant helpers of a specific type with their configurations.
 
-        Returns complete configuration for all helpers of the specified type including:
+        Returns one page of helpers; `total_count` and `has_more` report the full
+        set. Each record carries the complete configuration for its helper,
+        including:
         - id (immutable storage key), entity_id (current — address the helper by
           this, where available), name (current display name), original_name
           (creation-time name), icon
@@ -3682,8 +3764,12 @@ class HelperConfigTools:
         - List all persons: ha_config_list_helpers("person")
         - List all tags: ha_config_list_helpers("tag")
         - List every helper type at once: ha_config_list_helpers("all")
+        - Next page: ha_config_list_helpers("input_boolean", offset=100)
 
-        **NOTE:** This only returns storage-based helpers (created via UI/API), not YAML-defined helpers.
+        **NOTE:** Storage types list what HA's ``{type}/list`` command returns:
+        the storage-backed helpers (created via UI/API), not the YAML-defined
+        ones. ``person`` is the exception — HA lists its YAML-configured persons
+        alongside the storage ones, so both appear here.
 
         Flow-based types (template / group / utility_meter / derivative / etc.)
         require the ha_mcp_tools custom component (>= 1.1.0) and are served only
@@ -3702,7 +3788,9 @@ class HelperConfigTools:
         # No legacy equivalent exists (no single WS command enumerates all
         # types), so it is component-only — see ``_list_all_helpers``.
         if helper_type == "all":
-            return await self._list_all_helpers()
+            return _paginate_helpers_response(
+                await self._list_all_helpers(), offset, limit
+            )
 
         # Flow-based helper types have no ``{type}/list`` command, so only the
         # component's ``helpers_list`` can enumerate them: they are served
@@ -3723,7 +3811,7 @@ class HelperConfigTools:
                 helper_type, is_flow=is_flow
             )
             if component_response is not None:
-                return component_response
+                return _paginate_helpers_response(component_response, offset, limit)
         if is_flow:
             # No usable component path and the legacy body cannot serve flow
             # helpers: hard error rather than an empty or misleading list.
@@ -3751,7 +3839,7 @@ class HelperConfigTools:
                 }
                 if warnings:
                     response["warnings"] = warnings
-                return response
+                return _paginate_helpers_response(response, offset, limit)
             raise_tool_error(
                 create_error_response(
                     ErrorCode.SERVICE_CALL_FAILED,
@@ -3880,7 +3968,11 @@ class HelperConfigTools:
                     context={"helper_type": helper_type},
                 )
             )
-        items = result.get("result", [])
+        # Flatten like the inline body: person/list returns {"storage": [...],
+        # "config": [...]} rather than a flat list, so a raw result["result"]
+        # would be a dict here — breaking count, the pagination slice and the
+        # all-types merge, which all expect a list of records.
+        items = _flatten_helper_list_result(result)
         return {
             "success": True,
             "helper_type": helper_type,
@@ -4005,11 +4097,23 @@ class HelperConfigTools:
             )
         for helper_type in sorted(SIMPLE_HELPER_TYPES - covered_set):
             legacy = await self._legacy_helper_list(helper_type)
+            skipped = 0
             for item in legacy.get("helpers", []):
                 if isinstance(item, dict):
                     row = dict(item)
                     row.setdefault("helper_type", helper_type)
                     helpers.append(row)
+                else:
+                    skipped += 1
+            if skipped:
+                # This is how the unflattened person/list dict used to vanish:
+                # iterating it yielded its keys, and each failed the check here.
+                logger.warning(
+                    "Dropped %d unrecognised item(s) from the %s listing while "
+                    "merging all types; the merged listing is incomplete",
+                    skipped,
+                    helper_type,
+                )
 
         return {
             "success": True,

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_dev.py

@@ -126,7 +126,8 @@ async def find_server_config_entry(
 
     Probes each ``ha_mcp_tools`` entry's options flow: the server entry's
     flow is a form whose schema carries the ``pip_spec`` field; the tools
-    (services) entry's flow aborts immediately. Returns
+    (services) entry's flow is an informational form with no ``pip_spec``
+    field, so it never matches. Returns
     ``(entry_id, open_flow, current_options)`` with the options flow left
     OPEN (callers must submit or abort it), or ``None`` when no server
     entry exists. ``current_options`` maps schema field names to their current

{ha_mcp_dev-7.12.3.dev1937 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_filesystem.py

@@ -7,8 +7,10 @@ configuration directory, enabling AI assistants to:
 - List files in allowed directories
 - Write/delete files in restricted directories (www/, themes/, custom_templates/)
 
-**Dependency:** Requires the ha_mcp_tools custom component to be installed.
-The tools will gracefully fail with installation instructions if the component is not available.
+**Dependency:** Requires the ha_mcp_tools custom component, added in HA via its
+"HA-MCP File & YAML Tools" config entry (NOT the "HA-MCP Server" entry, which
+starts a redundant in-process server). The tools will gracefully fail with
+installation instructions if the component is not available.
 
 Feature Flag: Set HAMCP_ENABLE_FILESYSTEM_TOOLS=true to enable these tools.
 """
@@ -141,7 +143,7 @@ def _raise_component_too_old(detail: str) -> NoReturn:
             f"This ha-mcp release requires >= {MIN_COMPONENT_VERSION}. "
             "Update via HACS and restart Home Assistant.",
             suggestions=[
-                "HACS → Integrations → HA MCP Tools → Update",
+                "HACS → Integrations → HA-MCP Custom Component → Update",
                 "Restart Home Assistant after update completes",
                 "Then retry the operation",
             ],
@@ -362,8 +364,17 @@ async def _assert_mcp_tools_available(client: Any) -> None:
         raise_tool_error(
             create_error_response(
                 ErrorCode.COMPONENT_NOT_INSTALLED,
-                f"The {MCP_TOOLS_DOMAIN} custom component is not installed. "
-                "Use ha_install_mcp_tools() to install it via HACS, then restart Home Assistant.",
+                f"The {MCP_TOOLS_DOMAIN} custom component is not installed.",
+                suggestions=[
+                    'Add the repository to HACS: ha_manage_hacs(action="add_repository",'
+                    + ' repository="homeassistant-ai/ha-mcp-integration", category="integration")',
+                    'Download the component: ha_manage_hacs(action="download",'
+                    + ' repository_id="homeassistant-ai/ha-mcp-integration")',
+                    "Restart Home Assistant (ha_restart) so the integration loads",
+                    'In HA, add the "HA-MCP Custom Component" integration and choose the'
+                    + ' "HA-MCP File & YAML Tools" entry — NOT "HA-MCP Server", which starts'
+                    + " a second in-process server this ha-mcp server does not need",
+                ],
             )
         )