Tool consolidation to address issue #424 (#453)

* feat: consolidate list/get tool pairs to reduce tool count

Consolidate 5 pairs of ha_list_*/ha_get_* tools into single tools with optional
parameters, following the pattern established in issue #420 for ha_get_blueprint.

Tool consolidations:
- ha_list_updates + ha_get_release_notes → ha_get_updates(entity_id=None)
- ha_list_zones → ha_get_zone(zone_id=None)
- ha_list_devices + ha_get_device → ha_get_device(device_id=None, manufacturer=None)
- ha_list_exposed_entities + ha_get_entity_exposure → ha_get_entity_exposure(entity_id=None)
- ha_list_integrations + ha_get_config_entry → ha_get_integration(entry_id=None)

Net reduction: 4 tools (from 105 to 101)

The consolidated tools now support both modes:
- Without identifier: Lists all items (with optional filters)
- With identifier: Returns detailed info for specific item

Closes #424

* chore: update uv.lock

* feat: consolidate additional list tools (round 2) - reduce to 97 tools

Consolidate 4 more tool pairs to further reduce tool count:

- ha_config_list_dashboards → ha_config_get_dashboard(list_only=True)
- ha_config_list_labels → ha_config_get_label(label_id=None)
- ha_list_addons + ha_list_available_addons → ha_get_addon(source=None)
- ha_list_todo_lists + ha_get_todo_items → ha_get_todo(entity_id=None)

Tool count: 101 → 97 (saved 4 tools)
Combined with first round: 105 → 97 (saved 8 tools total)

All consolidated tools follow the established pattern:
- When optional ID/filter param is None → list mode
- When param provided → get specific item mode

Updated tests and documentation accordingly.

Closes #424

* fix: update voice assistant tests to match consolidated tool API

The ha_get_entity_exposure tool returns different response structures:
- When entity_id is provided: returns exposed_to, is_exposed_anywhere, etc.
- When listing all: returns exposed_entities, count, assistant_filter

Updated tests to match the actual implementation:
- Use assistant_filter instead of filters_applied.assistant
- Use entity-specific response keys when entity_id is provided

* fix: remove `or True` expressions that ignored user-provided False values

The `or True` pattern used to satisfy the type checker was causing
`coerce_bool_param(..., default=True) or True` to always return True,
even when the user explicitly passed False for preserve_voice_exposure,
parallel, or report_errors parameters.

Fixed by replacing `or True` with an assert for type narrowing, which
correctly preserves user input while satisfying the type checker.

Affected tools:
- ha_rename_entity(): preserve_voice_exposure parameter
- ha_rename_entity_and_device(): preserve_voice_exposure parameter
- ha_bulk_control(): parallel parameter
- ha_render_template(): report_errors parameter

Fixes bug identified by Gemini Code Assist review.

* chore: update uv.lock

* fix: validate credentials in standard mode entry points

The config now has OAuth-mode placeholder defaults for homeassistant_url
and homeassistant_token. In standard mode (main, main_web, main_sse),
validate that real credentials are provided - not the OAuth placeholders.

Also updates test mocks to match current function signatures:
- mock_run_async now accepts show_banner kwarg
- mock_run_http now accepts default_port kwarg
- HTTP entry point tests now provide mock credentials

This restores the expected behavior where missing credentials show a
friendly error message and exit with non-zero status.

* fix: update e2e tests to use consolidated tool names

The tool consolidation PR renamed/consolidated these tools:
- ha_config_list_dashboards -> ha_config_get_dashboard(list_only=True)
- ha_get_config_entry -> ha_get_integration

Update e2e tests to use the new consolidated tool names.

* fix: update voice assistant tests to match consolidated tool API

Change ha_get_entity_exposure response to use filters_applied dict
instead of assistant_filter to match the expected e2e test API.

- Rename assistant_filter -> filters_applied["assistant"]
- Update unit test to match new response structure

* fix: add pre-flight HACS availability check for install tests

Add pre-flight HACS availability check using ha_hacs_info before
attempting HACS install operations. This prevents flaky test failures
when HACS is rate-limited or temporarily unavailable.

Affects:
- test_install_mcp_tools_basic
- test_install_mcp_tools_idempotent
- test_check_mcp_tools_in_hacs

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: kingpanther13

README.md

@@ -120,23 +120,23 @@ Spend less time configuring, more time enjoying your smart home.
 | **Automations** | `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation` |
 | **Scripts** | `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script` |
 | **Helper Entities** | `ha_config_list_helpers`, `ha_config_set_helper`, `ha_config_remove_helper` |
-| **Dashboards** | `ha_config_list_dashboards`, `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_update_dashboard_metadata`, `ha_config_delete_dashboard`, `ha_get_dashboard_guide`, `ha_get_card_types`, `ha_get_card_documentation` |
+| **Dashboards** | `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_update_dashboard_metadata`, `ha_config_delete_dashboard`, `ha_get_dashboard_guide`, `ha_get_card_types`, `ha_get_card_documentation` |
 | **Areas & Floors** | `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor` |
-| **Labels** | `ha_config_list_labels`, `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
-| **Zones** | `ha_list_zones`, `ha_create_zone`, `ha_update_zone`, `ha_delete_zone` |
+| **Labels** | `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels` |
+| **Zones** | `ha_get_zone`, `ha_create_zone`, `ha_update_zone`, `ha_delete_zone` |
 | **Groups** | `ha_config_list_groups`, `ha_config_set_group`, `ha_config_remove_group` |
-| **Todo Lists** | `ha_list_todo_lists`, `ha_get_todo_items`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item` |
+| **Todo Lists** | `ha_get_todo`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item` |
 | **Calendar** | `ha_config_get_calendar_events`, `ha_config_set_calendar_event`, `ha_config_remove_calendar_event` |
 | **Blueprints** | `ha_list_blueprints`, `ha_get_blueprint`, `ha_import_blueprint` |
-| **Device Registry** | `ha_list_devices`, `ha_get_device`, `ha_update_device`, `ha_remove_device`, `ha_rename_entity` |
+| **Device Registry** | `ha_get_device`, `ha_update_device`, `ha_remove_device`, `ha_rename_entity` |
 | **ZHA & Integrations** | `ha_get_zha_devices`, `ha_get_entity_integration_source` |
-| **Add-ons** | `ha_list_addons`, `ha_list_available_addons` |
+| **Add-ons** | `ha_get_addon` |
 | **Camera** | `ha_get_camera_image` |
 | **History & Statistics** | `ha_get_history`, `ha_get_statistics` |
 | **Automation Traces** | `ha_get_automation_traces` |
-| **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_list_updates`, `ha_get_release_notes`, `ha_get_system_version` |
+| **System & Updates** | `ha_check_config`, `ha_restart`, `ha_reload_core`, `ha_get_system_info`, `ha_get_system_health`, `ha_get_updates` |
 | **Backup & Restore** | `ha_backup_create`, `ha_backup_restore` |
-| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_domain_docs`, `ha_list_integrations` |
+| **Utility** | `ha_get_logbook`, `ha_eval_template`, `ha_get_domain_docs`, `ha_get_integration` |
 
 </details>
 

homeassistant-addon/DOCS.md

@@ -291,19 +291,19 @@ The add-on provides 80+ MCP tools for controlling Home Assistant:
 - **Scripts**: `ha_config_get_script`, `ha_config_set_script`, `ha_config_remove_script`
 - **Automations**: `ha_config_get_automation`, `ha_config_set_automation`, `ha_config_remove_automation`
 - **Groups**: `ha_config_list_groups`, `ha_config_set_group`, `ha_config_remove_group`
-- **Dashboards**: `ha_config_list_dashboards`, `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard`
+- **Dashboards**: `ha_config_get_dashboard`, `ha_config_set_dashboard`, `ha_config_delete_dashboard`
 - **Areas & Floors**: `ha_config_list_areas`, `ha_config_set_area`, `ha_config_remove_area`, `ha_config_list_floors`, `ha_config_set_floor`, `ha_config_remove_floor`
-- **Labels**: `ha_config_list_labels`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels`
-- **Zones**: `ha_list_zones`, `ha_create_zone`, `ha_update_zone`, `ha_delete_zone`
+- **Labels**: `ha_config_get_label`, `ha_config_set_label`, `ha_config_remove_label`, `ha_manage_entity_labels`
+- **Zones**: `ha_get_zone`, `ha_create_zone`, `ha_update_zone`, `ha_delete_zone`
 
 ### Todo & Calendar
-- **Todo Lists**: `ha_list_todo_lists`, `ha_get_todo_items`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item`
+- **Todo Lists**: `ha_get_todo`, `ha_add_todo_item`, `ha_update_todo_item`, `ha_remove_todo_item`
 - **Calendar**: `ha_config_get_calendar_events`, `ha_config_set_calendar_event`, `ha_config_remove_calendar_event`
 
 ### Device Control
 - `ha_bulk_control` - Multi-device control with verification
 - `ha_get_operation_status` - Check operation status
-- `ha_list_devices`, `ha_get_device`, `ha_update_device`, `ha_remove_device`
+- `ha_get_device`, `ha_update_device`, `ha_remove_device`
 - `ha_rename_entity` - Rename entity ID
 
 ### History & Monitoring
@@ -317,13 +317,12 @@ The add-on provides 80+ MCP tools for controlling Home Assistant:
 - `ha_get_entity_integration_source` - Get integration source for any entity
 
 ### Add-ons (Supervisor only)
-- `ha_list_addons` - List installed add-ons
-- `ha_list_available_addons` - List available add-ons from repositories
+- `ha_get_addon` - List installed or available add-ons (source="installed" or "available")
 
 ### System & Updates
 - `ha_check_config`, `ha_restart`, `ha_reload_core`
 - `ha_get_system_info`, `ha_get_system_health`
-- `ha_list_updates`, `ha_get_release_notes`, `ha_get_system_version`
+- `ha_get_updates` - List updates or get details for a specific update entity
 
 ### Blueprints
 - `ha_list_blueprints`, `ha_get_blueprint`, `ha_import_blueprint`
@@ -336,7 +335,7 @@ The add-on provides 80+ MCP tools for controlling Home Assistant:
 - `ha_get_logbook` - Historical events
 - `ha_eval_template` - Evaluate Jinja2 templates
 - `ha_get_domain_docs` - Domain documentation
-- `ha_list_integrations` - List installed integrations
+- `ha_get_integration` - List or get integration info
 
 See the [main repository](https://github.com/homeassistant-ai/ha-mcp) for detailed tool documentation and examples.
 

src/ha_mcp/__main__.py

@@ -334,6 +334,22 @@ def main() -> None:
     # Configure logging before server creation
     from ha_mcp.config import get_settings
     settings = get_settings()
+
+    # In standard mode (not OAuth), validate that real credentials are provided
+    # The config has defaults for OAuth mode, but standard mode requires real values
+    missing_vars = []
+    if settings.homeassistant_url == "http://oauth-mode":
+        missing_vars.append("  - HOMEASSISTANT_URL")
+    if settings.homeassistant_token == "oauth-mode-token":
+        missing_vars.append("  - HOMEASSISTANT_TOKEN")
+
+    if missing_vars:
+        print(
+            _CONFIG_ERROR_MESSAGE.format(missing_vars="\n".join(missing_vars)),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     logging.basicConfig(
         level=getattr(logging, settings.log_level),
         format='%(asctime)s %(name)s %(levelname)s: %(message)s'
@@ -483,6 +499,21 @@ def main_web() -> None:
     # Configure logging before server creation
     from ha_mcp.config import get_settings
     settings = get_settings()
+
+    # Validate credentials (required in non-OAuth HTTP mode)
+    missing_vars = []
+    if settings.homeassistant_url == "http://oauth-mode":
+        missing_vars.append("  - HOMEASSISTANT_URL")
+    if settings.homeassistant_token == "oauth-mode-token":
+        missing_vars.append("  - HOMEASSISTANT_TOKEN")
+
+    if missing_vars:
+        print(
+            _CONFIG_ERROR_MESSAGE.format(missing_vars="\n".join(missing_vars)),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     logging.basicConfig(
         level=getattr(logging, settings.log_level),
         format='%(asctime)s %(name)s %(levelname)s: %(message)s'
@@ -503,6 +534,21 @@ def main_sse() -> None:
     # Configure logging before server creation
     from ha_mcp.config import get_settings
     settings = get_settings()
+
+    # Validate credentials (required in non-OAuth SSE mode)
+    missing_vars = []
+    if settings.homeassistant_url == "http://oauth-mode":
+        missing_vars.append("  - HOMEASSISTANT_URL")
+    if settings.homeassistant_token == "oauth-mode-token":
+        missing_vars.append("  - HOMEASSISTANT_TOKEN")
+
+    if missing_vars:
+        print(
+            _CONFIG_ERROR_MESSAGE.format(missing_vars="\n".join(missing_vars)),
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     logging.basicConfig(
         level=getattr(logging, settings.log_level),
         format='%(asctime)s %(name)s %(levelname)s: %(message)s'

src/ha_mcp/tools/tools_addons.py

@@ -263,86 +263,81 @@ def register_addon_tools(mcp: Any, client: HomeAssistantClient, **kwargs) -> Non
         **kwargs: Additional arguments (ignored, for auto-discovery compatibility)
     """
 
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["addon"], "title": "List Installed Add-ons"})
+    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["addon"], "title": "Get Add-ons"})
     @log_tool_usage
-    async def ha_list_addons(
+    async def ha_get_addon(
+        source: Annotated[
+            str | None,
+            Field(
+                description="Add-on source: 'installed' (default) for currently installed add-ons, "
+                "'available' for add-ons in the store that can be installed.",
+                default=None,
+            ),
+        ] = None,
         include_stats: Annotated[
             bool,
             Field(
-                description="Include CPU/memory usage statistics for each add-on",
+                description="Include CPU/memory usage statistics (only for source='installed')",
                 default=False,
             ),
         ] = False,
-    ) -> dict[str, Any]:
-        """
-        List installed Home Assistant add-ons.
-
-        Returns add-ons with version, state (started/stopped), and update availability.
-        Optionally includes CPU/memory usage statistics.
-
-        **Note:** This tool only works with Home Assistant OS or Supervised installations.
-
-        **Response includes:**
-        - Add-on name, slug, description
-        - Current version and state
-        - Whether an update is available
-        - Repository the add-on came from
-        - Optional: CPU/memory usage stats
-
-        **Example Usage:**
-        - List all add-ons: ha_list_addons()
-        - List with resource usage: ha_list_addons(include_stats=True)
-
-        **Use Cases:**
-        - Check which add-ons are installed and running
-        - Monitor add-on health and resource usage
-        - Find add-ons with available updates
-        """
-        return await list_addons(client, include_stats)
-
-    @mcp.tool(annotations={"idempotentHint": True, "readOnlyHint": True, "tags": ["addon"], "title": "List Available Add-ons"})
-    @log_tool_usage
-    async def ha_list_available_addons(
         repository: Annotated[
             str | None,
             Field(
-                description="Filter by repository slug (e.g., 'core', 'community')",
+                description="Filter by repository slug, e.g., 'core', 'community' (only for source='available')",
                 default=None,
             ),
         ] = None,
         query: Annotated[
             str | None,
             Field(
-                description="Search filter for add-on names/descriptions",
+                description="Search filter for add-on names/descriptions (only for source='available')",
                 default=None,
             ),
         ] = None,
     ) -> dict[str, Any]:
         """
-        List add-ons available in the Home Assistant add-on store.
+        Get Home Assistant add-ons - list installed or available from store.
 
-        Returns add-ons from official and custom repositories that can be installed.
+        This tool retrieves add-on information based on the source parameter:
+        - source='installed' (default): Lists currently installed add-ons
+        - source='available': Lists add-ons available in the add-on store
 
         **Note:** This tool only works with Home Assistant OS or Supervised installations.
 
-        **Response includes:**
-        - List of configured repositories
-        - Available add-ons with name, slug, description, version
-        - Installation status for each add-on
-        - Summary statistics
+        **INSTALLED ADD-ONS (source='installed'):**
+        Returns add-ons with version, state (started/stopped), and update availability.
+        - include_stats: Optionally include CPU/memory usage statistics
 
-        **Parameters:**
-        - repository: Filter results to a specific repository
+        **AVAILABLE ADD-ONS (source='available'):**
+        Returns add-ons from official and custom repositories that can be installed.
+        - repository: Filter by repository slug (e.g., 'core', 'community')
         - query: Search by name or description (case-insensitive)
 
         **Example Usage:**
-        - List all available add-ons: ha_list_available_addons()
-        - Search for MQTT: ha_list_available_addons(query="mqtt")
-        - List official add-ons: ha_list_available_addons(repository="core")
+        - List installed add-ons: ha_get_addon()
+        - List with resource usage: ha_get_addon(include_stats=True)
+        - List available add-ons: ha_get_addon(source="available")
+        - Search for MQTT: ha_get_addon(source="available", query="mqtt")
+        - List official add-ons: ha_get_addon(source="available", repository="core")
 
         **Use Cases:**
+        - Check which add-ons are installed and running
+        - Monitor add-on health and resource usage
+        - Find add-ons with available updates
         - Find add-ons to recommend for user's needs
         - Check if a specific add-on is available
-        - Explore add-on store contents
         """
-        return await list_available_addons(client, repository, query)
+        # Default to installed if not specified
+        effective_source = (source or "installed").lower()
+
+        if effective_source == "available":
+            return await list_available_addons(client, repository, query)
+        elif effective_source == "installed":
+            return await list_addons(client, include_stats)
+        else:
+            return {
+                "success": False,
+                "error": f"Invalid source: {source}. Must be 'installed' or 'available'.",
+                "valid_sources": ["installed", "available"],
+            }