feat: rename ha_delete_helpers_integrations → ha_remove_helpers_integrations + commit to idempotent contract

Closes #1412.

Rename joins the `_remove_*` naming family (12 existing tools) and the
tool now ships `idempotentHint: True` per the MCP spec. The behavioral
contract is unified across all four routing paths: a confirmed-absent
target returns `success=True` with `fallback_used="already_deleted"`;
transient connectivity failures and call-shape conflicts still raise.

Per-path idempotency:

- SIMPLE (Path 1): existing state-machine + entity-registry double-empty
  short-circuit (now positively asserted by
  test_helper_delete_nonexistent).
- FLOW (Path 2): not_in_registry → idempotent success;
  bare_id_not_supported / lookup_failed / no_config_entry still raise
  with their distinct error codes (call-shape, transient, YAML-vs-
  storage conflict respectively). Step-3 delete now catches
  HomeAssistantAPIError(status_code=404) for the TOCTOU window between
  registry resolution and the actual delete.
- Direct config entry (Path 3, helper_type=None): catches
  HomeAssistantAPIError(status_code=404) from the REST DELETE and
  returns idempotent success. Non-404 API errors still surface via
  exception_to_structured_error.
- Config subentry (Path 4): inspects the WebSocket error code/message
  for "not_found" / "not found" and returns idempotent success.
  Other failure modes still raise SERVICE_CALL_FAILED.

YAML-configured FLOW helpers (Path 2 no_config_entry) keep raising
RESOURCE_NOT_FOUND deliberately — that's a call-shape conflict, not a
missing target: the entity exists in HA but cannot be removed via the
config-entry delete path. Silently succeeding would mislead callers
into thinking the YAML helper was removed.

Per-call sites updated:
- src/ha_mcp/tools/tools_integrations.py: rename + annotation + four
  per-path idempotent branches + docstring with full contract.
- src/ha_mcp/tools/tools_groups.py: 3 cross-reference docstrings.
- ~95 occurrences across 21 test files + cleanup utility mechanically
  renamed.
- 3 unit tests updated to assert the new idempotent contract:
  test_direct_path_entry_not_found,
  test_flow_path_entity_not_in_registry,
  test_flow_path_entry_not_found_at_delete.
- 1 new unit test pinning Path 4 idempotency:
  test_delete_helpers_integrations_subentry_not_found_is_idempotent.
- 1 E2E test hardened from soft-coverage if/else to positive assertion
  on idempotent shape: test_helper_delete_nonexistent.
- 1 E2E test flipped to assert idempotent success:
  test_delete_config_entry_nonexistent_confirmed.
- site/src/data/tools.json + README.md + homeassistant-addon/DOCS.md
  regenerated via scripts/extract_tools.py.

CHANGELOG entries referencing the old name (the original #1007
introduction notes) are intentionally untouched — history stays.

Verified locally:
- ruff check src/ tests/ → All checks passed!
- ruff format on changed files
- mypy src/ha_mcp/tools/tools_integrations.py → no issues
- 3257 unit tests passed, 1 skipped (numpy), 6 deselected (slow)

The rename is NOT a breaking change per .gemini/styleguide.md
("Tool consolidation / refactor / rename / param change are NOT
breaking.").

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Patch76

README.md

@@ -169,7 +169,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Files** | `ha_delete_file` *(beta)*, `ha_list_files` *(beta)*, `ha_read_file` *(beta)*, `ha_write_file` *(beta)* |
 | **Groups** | `ha_config_list_groups`, `ha_config_remove_group`, `ha_config_set_group` |
 | **HACS** | `ha_hacs_add_repository`, `ha_hacs_download`, `ha_hacs_repository_info`, `ha_hacs_search` |
-| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_delete_helpers_integrations` |
+| **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_remove_helpers_integrations` |
 | **History & Statistics** | `ha_get_automation_traces`, `ha_get_history`, `ha_get_logs` |
 | **Integrations** | `ha_get_integration`, `ha_get_system_health`, `ha_set_integration_enabled` |
 | **Labels & Categories** | `ha_config_get_category`, `ha_config_get_label`, `ha_config_remove_category`, `ha_config_remove_label`, `ha_config_set_category`, `ha_config_set_label` |

homeassistant-addon/DOCS.md

@@ -445,7 +445,7 @@ The add-on provides 88+ MCP tools for controlling Home Assistant:
 ### Helper Entities
 - `ha_config_list_helpers` — List all Home Assistant helpers of a specific type with their configurations.
 - `ha_config_set_helper` — Create or update Home Assistant helper entities and config subentries
-- `ha_delete_helpers_integrations` — Delete a Home Assistant helper or integration config entry.
+- `ha_remove_helpers_integrations` — Remove a Home Assistant helper or integration config entry.
 
 ### History & Statistics
 - `ha_get_automation_traces` — Retrieve execution traces for automations and scripts to debug issues.

site/src/data/tools.json

@@ -1276,7 +1276,7 @@
   {
     "name": "ha_config_remove_group",
     "title": "Remove Group",
-    "description": "Remove a service-based Home Assistant entity group via the group.remove service.\n\n**When NOT to use:** for groups created through `ha_config_set_helper(helper_type=\"group\", ...)`,\nuse `ha_delete_helpers_integrations`. Those config-entry-backed groups are not reachable via the\ngroup.remove service.\n\n**When to use:** removing groups created with `ha_config_set_group` or defined in YAML\nvia `group:` configuration. Config-entry-backed deletion tools cannot find these.\n\nEXAMPLES:\n- Remove group: ha_config_remove_group(\"living_room_lights\")\n\nUse ha_config_list_groups() to find existing groups.\n\n**WARNING:**\n- Removing a group used in automations may cause those automations to fail.\n- Groups defined in YAML can be removed at runtime but will reappear after restart.\n- This only removes old-style groups, not platform-specific groups.",
+    "description": "Remove a service-based Home Assistant entity group via the group.remove service.\n\n**When NOT to use:** for groups created through `ha_config_set_helper(helper_type=\"group\", ...)`,\nuse `ha_remove_helpers_integrations`. Those config-entry-backed groups are not reachable via the\ngroup.remove service.\n\n**When to use:** removing groups created with `ha_config_set_group` or defined in YAML\nvia `group:` configuration. Config-entry-backed deletion tools cannot find these.\n\nEXAMPLES:\n- Remove group: ha_config_remove_group(\"living_room_lights\")\n\nUse ha_config_list_groups() to find existing groups.\n\n**WARNING:**\n- Removing a group used in automations may cause those automations to fail.\n- Groups defined in YAML can be removed at runtime but will reappear after restart.\n- This only removes old-style groups, not platform-specific groups.",
     "inputSchema": {
       "properties": {
         "object_id": {
@@ -1303,7 +1303,7 @@
   {
     "name": "ha_config_set_group",
     "title": "Create or Update Group",
-    "description": "Create or update a service-based Home Assistant entity group via the group.set service.\n\n**When NOT to use:** for typical \"combine these entities into one controllable group\"\nrequests, prefer `ha_config_set_helper(helper_type=\"group\", ...)`. Config-entry-backed\ngroups are registered in the entity registry, so `ha_set_entity` can assign them to\nareas and they are deletable via `ha_delete_helpers_integrations`.\n\n**When to use:** compatibility with existing groups already configured via group.set\nor YAML, or the rare case where entity-registry membership is explicitly unwanted.\nGroups created here are only removable via `ha_config_remove_group` —\n`ha_delete_helpers_integrations` will not find them.\n\n**For NEW groups:** Provide object_id and entities (required).\n**For EXISTING groups:** Provide object_id and any fields to update.\n\nEXAMPLES:\n- Create group: ha_config_set_group(\"bedroom_lights\", entities=[\"light.lamp\", \"light.ceiling\"])\n- Create with name: ha_config_set_group(\"sensors\", entities=[\"sensor.temp\"], name=\"All Sensors\")\n- Update name: ha_config_set_group(\"lights\", name=\"Living Room Lights\")\n- Add entities: ha_config_set_group(\"lights\", add_entities=[\"light.extra\"])\n- Remove entities: ha_config_set_group(\"lights\", remove_entities=[\"light.old\"])\n- Replace all entities: ha_config_set_group(\"lights\", entities=[\"light.new1\", \"light.new2\"])\n\n**NOTE:** entities, add_entities, and remove_entities are mutually exclusive.",
+    "description": "Create or update a service-based Home Assistant entity group via the group.set service.\n\n**When NOT to use:** for typical \"combine these entities into one controllable group\"\nrequests, prefer `ha_config_set_helper(helper_type=\"group\", ...)`. Config-entry-backed\ngroups are registered in the entity registry, so `ha_set_entity` can assign them to\nareas and they are deletable via `ha_remove_helpers_integrations`.\n\n**When to use:** compatibility with existing groups already configured via group.set\nor YAML, or the rare case where entity-registry membership is explicitly unwanted.\nGroups created here are only removable via `ha_config_remove_group` —\n`ha_remove_helpers_integrations` will not find them.\n\n**For NEW groups:** Provide object_id and entities (required).\n**For EXISTING groups:** Provide object_id and any fields to update.\n\nEXAMPLES:\n- Create group: ha_config_set_group(\"bedroom_lights\", entities=[\"light.lamp\", \"light.ceiling\"])\n- Create with name: ha_config_set_group(\"sensors\", entities=[\"sensor.temp\"], name=\"All Sensors\")\n- Update name: ha_config_set_group(\"lights\", name=\"Living Room Lights\")\n- Add entities: ha_config_set_group(\"lights\", add_entities=[\"light.extra\"])\n- Remove entities: ha_config_set_group(\"lights\", remove_entities=[\"light.old\"])\n- Replace all entities: ha_config_set_group(\"lights\", entities=[\"light.new1\", \"light.new2\"])\n\n**NOTE:** entities, add_entities, and remove_entities are mutually exclusive.",
     "inputSchema": {
       "properties": {
         "object_id": {
@@ -1668,9 +1668,9 @@
     "source_file": "tools_config_helpers.py"
   },
   {
-    "name": "ha_delete_helpers_integrations",
-    "title": "Delete Helper or Integration",
-    "description": "Delete a Home Assistant helper or integration config entry.\n\nCombines simple-helper websocket deletion, config-entry deletion, and\nconfig-subentry deletion under one entry point with four routing paths\ndriven by helper_type.\n\nWHEN NOT TO USE:\n- Removing only an entity (without deleting its underlying helper or\n  config entry) — use `ha_remove_entity` instead.\n- YAML-configured helpers — they have no storage backend. Edit the\n  YAML file and reload the relevant integration.\n\nSUPPORTED HELPER TYPES:\n- SIMPLE (12, websocket-delete): input_button, input_boolean,\n  input_select, input_number, input_text, input_datetime, counter,\n  timer, schedule, zone, person, tag.\n- FLOW (15, config-entry-delete via entity lookup): template, group,\n  utility_meter, derivative, min_max, threshold, integration,\n  statistics, trend, random, filter, tod, generic_thermostat,\n  switch_as_x, generic_hygrostat.\n\nROUTING:\n- SIMPLE helper_type + bare helper_id or entity_id → websocket delete.\n- FLOW helper_type + entity_id → resolve entity_id to config_entry_id\n  via entity_registry, then delete the config entry. All sub-entities\n  (e.g. utility_meter tariffs) are removed together.\n- helper_type=None + entry_id → direct config entry delete (any\n  integration).\n- helper_type=\"config_subentry\" + parent entry_id + subentry_id →\n  delete one config subentry.\n\nEXAMPLES:\n- Delete SIMPLE button:\n  ha_delete_helpers_integrations(\n      target=\"my_button\", helper_type=\"input_button\", confirm=True\n  )\n- Delete FLOW utility_meter (any sub-entity works):\n  ha_delete_helpers_integrations(\n      target=\"sensor.energy_peak\",\n      helper_type=\"utility_meter\",\n      confirm=True,\n  )\n- Delete any integration by entry_id:\n  ha_delete_helpers_integrations(\n      target=\"01HXYZ...\", confirm=True\n  )\n- Delete a config subentry:\n  ha_delete_helpers_integrations(\n      target=\"01HXYZ...\", helper_type=\"config_subentry\",\n      subentry_id=\"subentry-123\", confirm=True\n  )\n\n**WARNING:** Deleting a helper or integration that is referenced by\nautomations, scripts, or other integrations may cause those to fail.\nUse ha_search_entities() / ha_get_integration() to verify before\ndeletion. Cannot be undone.",
+    "name": "ha_remove_helpers_integrations",
+    "title": "Remove Helper or Integration",
+    "description": "Remove a Home Assistant helper or integration config entry.\n\nCombines simple-helper websocket deletion, config-entry deletion, and\nconfig-subentry deletion under one entry point with four routing paths\ndriven by helper_type.\n\nWHEN NOT TO USE:\n- Removing only an entity (without deleting its underlying helper or\n  config entry) — use `ha_remove_entity` instead.\n- YAML-configured helpers — they have no storage backend. Edit the\n  YAML file and reload the relevant integration.\n\nSUPPORTED HELPER TYPES:\n- SIMPLE (12, websocket-delete): input_button, input_boolean,\n  input_select, input_number, input_text, input_datetime, counter,\n  timer, schedule, zone, person, tag.\n- FLOW (15, config-entry-delete via entity lookup): template, group,\n  utility_meter, derivative, min_max, threshold, integration,\n  statistics, trend, random, filter, tod, generic_thermostat,\n  switch_as_x, generic_hygrostat.\n\nROUTING:\n- SIMPLE helper_type + bare helper_id or entity_id → websocket delete.\n- FLOW helper_type + entity_id → resolve entity_id to config_entry_id\n  via entity_registry, then delete the config entry. All sub-entities\n  (e.g. utility_meter tariffs) are removed together.\n- helper_type=None + entry_id → direct config entry delete (any\n  integration).\n- helper_type=\"config_subentry\" + parent entry_id + subentry_id →\n  delete one config subentry.\n\nIDEMPOTENT-SUCCESS CONTRACT:\nA target that is *confirmed absent* returns ``success=True`` with\n``fallback_used=\"already_deleted\"``. This applies per-path:\n- SIMPLE: state-machine empty AND entity registry empty.\n- FLOW: entity_id not in registry (target was never there or\n  already removed). YAML-configured helpers (no config entry\n  backing) still raise ``RESOURCE_NOT_FOUND`` — that's a\n  call-shape conflict, not a missing target.\n- Direct config entry (helper_type=None): backend returns HTTP 404.\n- Config subentry: backend returns a \"not_found\" error.\n\nTransient connectivity failures (WebSocket disconnected, network\ntimeouts) still raise so callers can retry. Idempotency applies\nonly when the target is *known* not to exist.\n\nEXAMPLES:\n- Delete SIMPLE button:\n  ha_remove_helpers_integrations(\n      target=\"my_button\", helper_type=\"input_button\", confirm=True\n  )\n- Delete FLOW utility_meter (any sub-entity works):\n  ha_remove_helpers_integrations(\n      target=\"sensor.energy_peak\",\n      helper_type=\"utility_meter\",\n      confirm=True,\n  )\n- Delete any integration by entry_id:\n  ha_remove_helpers_integrations(\n      target=\"01HXYZ...\", confirm=True\n  )\n- Delete a config subentry:\n  ha_remove_helpers_integrations(\n      target=\"01HXYZ...\", helper_type=\"config_subentry\",\n      subentry_id=\"subentry-123\", confirm=True\n  )\n\n**WARNING:** Deleting a helper or integration that is referenced by\nautomations, scripts, or other integrations may cause those to fail.\nUse ha_search_entities() / ha_get_integration() to verify before\ndeletion. Cannot be undone.",
     "inputSchema": {
       "properties": {
         "target": {
@@ -1698,7 +1698,8 @@
       ]
     },
     "annotations": {
-      "destructiveHint": true
+      "destructiveHint": true,
+      "idempotentHint": true
     },
     "tags": [
       "Helper Entities",

src/ha_mcp/tools/tools_groups.py

@@ -277,12 +277,12 @@ async def ha_config_set_group(
         **When NOT to use:** for typical "combine these entities into one controllable group"
         requests, prefer `ha_config_set_helper(helper_type="group", ...)`. Config-entry-backed
         groups are registered in the entity registry, so `ha_set_entity` can assign them to
-        areas and they are deletable via `ha_delete_helpers_integrations`.
+        areas and they are deletable via `ha_remove_helpers_integrations`.
 
         **When to use:** compatibility with existing groups already configured via group.set
         or YAML, or the rare case where entity-registry membership is explicitly unwanted.
         Groups created here are only removable via `ha_config_remove_group` —
-        `ha_delete_helpers_integrations` will not find them.
+        `ha_remove_helpers_integrations` will not find them.
 
         **For NEW groups:** Provide object_id and entities (required).
         **For EXISTING groups:** Provide object_id and any fields to update.
@@ -414,7 +414,7 @@ async def ha_config_remove_group(
         Remove a service-based Home Assistant entity group via the group.remove service.
 
         **When NOT to use:** for groups created through `ha_config_set_helper(helper_type="group", ...)`,
-        use `ha_delete_helpers_integrations`. Those config-entry-backed groups are not reachable via the
+        use `ha_remove_helpers_integrations`. Those config-entry-backed groups are not reachable via the
         group.remove service.
 
         **When to use:** removing groups created with `ha_config_set_group` or defined in YAML