ha-mcp-dev 7.5.0.dev540__tar.gz → 7.5.0.dev541__tar.gz

{ha_mcp_dev-7.5.0.dev540/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev541}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev540
+Version: 7.5.0.dev541
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.5.0.dev540 → ha_mcp_dev-7.5.0.dev541}/pyproject.toml

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

{ha_mcp_dev-7.5.0.dev540 → ha_mcp_dev-7.5.0.dev541}/src/ha_mcp/tools/tools_integrations.py

@@ -35,7 +35,9 @@ from .util_helpers import (
     build_pagination_metadata,
     coerce_bool_param,
     coerce_int_param,
+    fetch_integration_diagnostics,
     get_logger_levels,
+    parse_diagnostics_fields,
     wait_for_entity_removed,
 )
 
@@ -219,6 +221,114 @@ class IntegrationTools:
                 description="Number of entries to skip for pagination (default: 0)",
             ),
         ] = 0,
+        include_diagnostics: Annotated[
+            bool | str,
+            Field(
+                description=(
+                    "When entry_id is set, also fetch the integration's diagnostics "
+                    "dump — integration-defined JSON (commonly includes redacted "
+                    "config, device list, state snapshots; exact top-level keys "
+                    "vary by integration). The canonical artifact users grab via "
+                    "Settings → Devices & Services → [integration] → ⋯ → Download "
+                    "diagnostics. Use when triaging integration bugs or filing "
+                    "ha_report_issue for a specific integration. Payloads can be "
+                    "large (Hue ~290 KB, ZHA/MQTT/ESPHome several MB) — pair with "
+                    "diagnostics_fields or diagnostics_truncate_at_bytes to fit "
+                    "the LLM context budget."
+                ),
+                default=False,
+            ),
+        ] = False,
+        device_id: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Optional. When set with include_diagnostics=True, returns the "
+                    "device-scoped diagnostics dump for that specific device under "
+                    "the integration (rather than the full integration dump). Some "
+                    "integrations only expose config-entry-level dumps; others "
+                    "expose both."
+                ),
+                default=None,
+            ),
+        ] = None,
+        diagnostics_fields: Annotated[
+            list[str] | str | None,
+            Field(
+                description=(
+                    "Optional list of top-level keys to keep from the diagnostics "
+                    "data payload (e.g. ['home_assistant', 'issues']). Trims the "
+                    "payload before it hits the LLM context budget. Accepts a JSON "
+                    "list or comma-separated string. Only applies when "
+                    "include_diagnostics=True and the data payload is a dict. "
+                    "Unknown keys are silently dropped and surfaced via the "
+                    "omitted_fields sub-key."
+                ),
+                default=None,
+            ),
+        ] = None,
+        diagnostics_truncate_at_bytes: Annotated[
+            int | str | None,
+            Field(
+                description=(
+                    "Optional byte cap on the serialized diagnostics payload "
+                    "(after diagnostics_fields and diagnostics_data_path have "
+                    "been applied). On hit, drops data and emits truncated=true, "
+                    "bytes_total, byte_cap, plus available_fields (when the "
+                    "capped value is a dict). Recommended starting point: "
+                    "20000 bytes. Only applies when include_diagnostics=True."
+                ),
+                default=None,
+            ),
+        ] = None,
+        diagnostics_data_path: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Optional dotted path into the diagnostics data sub-tree "
+                    "(e.g. '<list-valued path>' for per-device records, "
+                    "'home_assistant.version' for HA core version; the exact "
+                    "key path varies by integration version). Walks into the "
+                    "post-fields payload. Resolution failures replace data "
+                    "with null and surface data_path_error. Use this when the "
+                    "interesting payload lives several levels deep — top-level "
+                    "diagnostics_fields can't address sub-trees on integrations "
+                    "where the bulk lives under one key (ZHA, MQTT, ESPHome). "
+                    "Only applies when include_diagnostics=True."
+                ),
+                default=None,
+            ),
+        ] = None,
+        diagnostics_data_offset: Annotated[
+            int | str | None,
+            Field(
+                description=(
+                    "Pagination start index (default 0) for list-valued "
+                    "diagnostics_data_path results. Ignored when "
+                    "diagnostics_data_path is unset, diagnostics_data_limit is "
+                    "unset, or the resolved value is not a list. Only applies "
+                    "when include_diagnostics=True."
+                ),
+                default=0,
+            ),
+        ] = 0,
+        diagnostics_data_limit: Annotated[
+            int | str | None,
+            Field(
+                description=(
+                    "Pagination window size for list-valued "
+                    "diagnostics_data_path results. When set with a "
+                    "list-resolved path, swaps data for a pagination envelope "
+                    "{path, items, offset, limit, total, has_more}. Default "
+                    "None returns the full resolved value. Workflow: probe "
+                    "with a list-valued diagnostics_data_path and "
+                    "diagnostics_data_limit=10 to walk a large list one page "
+                    "at a time (the exact path varies by integration version). "
+                    "Only applies when include_diagnostics=True."
+                ),
+                default=None,
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         """Get integration (config entry) information with pagination.
 
@@ -231,6 +341,10 @@ class IntegrationTools:
         - Search: ha_get_integration(query="zigbee")
         - Get specific entry: ha_get_integration(entry_id="abc123")
         - Get entry with editable fields: ha_get_integration(entry_id="abc123", include_schema=True)
+        - Get entry with diagnostics dump: ha_get_integration(entry_id="abc123", include_diagnostics=True)
+        - Get device-scoped diagnostics: ha_get_integration(entry_id="abc123", include_diagnostics=True, device_id="dev123")
+        - Walk a sub-tree: ha_get_integration(entry_id="abc123", include_diagnostics=True, diagnostics_data_path="<dotted-path>")
+        - Paginate a large list: ha_get_integration(entry_id="abc123", include_diagnostics=True, diagnostics_data_path="<list-valued path>", diagnostics_data_limit=10, diagnostics_data_offset=20)
         - List template entries: ha_get_integration(domain="template")
 
         STATES: 'loaded', 'setup_error', 'setup_retry', 'not_loaded',
@@ -256,6 +370,9 @@ class IntegrationTools:
             include_schema_bool = coerce_bool_param(
                 include_schema, "include_schema", default=False
             )
+            include_diagnostics_bool = coerce_bool_param(
+                include_diagnostics, "include_diagnostics", default=False
+            )
             exact_match_bool = coerce_bool_param(
                 exact_match, "exact_match", default=True
             )
@@ -263,18 +380,86 @@ class IntegrationTools:
                 limit, "limit", default=50, min_value=1, max_value=200
             )
             offset_int = coerce_int_param(offset, "offset", default=0, min_value=0)
+            fields_list = parse_diagnostics_fields(diagnostics_fields)
+            truncate_bytes = coerce_int_param(
+                diagnostics_truncate_at_bytes,
+                "diagnostics_truncate_at_bytes",
+                default=None,
+                min_value=1,
+            )
+            data_offset_int = coerce_int_param(
+                diagnostics_data_offset,
+                "diagnostics_data_offset",
+                default=0,
+                min_value=0,
+            )
+            data_limit_int = coerce_int_param(
+                diagnostics_data_limit,
+                "diagnostics_data_limit",
+                default=None,
+                min_value=1,
+            )
+            # Type-guard ``diagnostics_data_path`` here so a bad caller (dict /
+            # list) surfaces as ``VALIDATION_INVALID_PARAMETER`` instead of
+            # leaking as ``INTERNAL_ERROR`` from the resolver's ``.strip()``
+            # downstream. Mirrors the coerce_int_param guards above.
+            if diagnostics_data_path is not None and not isinstance(
+                diagnostics_data_path, str
+            ):
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        "diagnostics_data_path must be a string, got "
+                        f"{type(diagnostics_data_path).__name__}",
+                        context={"parameter": "diagnostics_data_path"},
+                    )
+                )
             # Auto-enable options when domain filter is set
             if domain is not None:
                 include_opts = True
 
             # If entry_id provided, get specific config entry
             if entry_id is not None:
-                return await self._get_single_entry(entry_id, include_schema_bool)
+                resp = await self._get_single_entry(entry_id, include_schema_bool)
+                if include_diagnostics_bool:
+                    resp["diagnostics"] = await fetch_integration_diagnostics(
+                        self._client,
+                        entry_id,
+                        device_id,
+                        fields=fields_list,
+                        truncate_at_bytes=truncate_bytes,
+                        data_path=diagnostics_data_path,
+                        data_offset=data_offset_int,
+                        data_limit=data_limit_int,
+                    )
+                elif device_id is not None:
+                    resp.setdefault("warnings", []).append(
+                        "device_id was provided but ignored because "
+                        "include_diagnostics=False"
+                    )
+                return resp
 
             # List mode - get all config entries
-            return await self._list_entries(
+            result = await self._list_entries(
                 domain, query, include_opts, exact_match_bool, limit_int, offset_int
             )
+            if (
+                include_diagnostics_bool
+                or device_id is not None
+                or fields_list is not None
+                or truncate_bytes is not None
+                or diagnostics_data_path is not None
+                or data_limit_int is not None
+                or data_offset_int > 0
+            ):
+                result.setdefault("warnings", []).append(
+                    "include_diagnostics, device_id, diagnostics_fields, "
+                    "diagnostics_truncate_at_bytes, diagnostics_data_path, "
+                    "diagnostics_data_offset, and/or diagnostics_data_limit "
+                    "were provided but ignored because entry_id was not set "
+                    "(list mode)"
+                )
+            return result
 
         except ToolError:
             raise

{ha_mcp_dev-7.5.0.dev540 → ha_mcp_dev-7.5.0.dev541}/src/ha_mcp/tools/tools_system.py

@@ -23,7 +23,13 @@ from .helpers import (
     raise_tool_error,
     register_tool_methods,
 )
-from .util_helpers import coerce_bool_param, filter_active_repairs
+from .util_helpers import (
+    coerce_bool_param,
+    coerce_int_param,
+    fetch_integration_diagnostics,
+    filter_active_repairs,
+    parse_diagnostics_fields,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -334,17 +340,24 @@ class SystemTools:
 
     @tool(
         name="ha_get_system_health",
-        tags={"System", "Zigbee", "Z-Wave"},
-        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get System Health (incl. ZHA/Z-Wave diagnostics)"},
+        tags={"System", "Zigbee", "Z-Wave", "Integrations"},
+        annotations={"idempotentHint": True, "readOnlyHint": True, "title": "Get System Health (incl. ZHA/Z-Wave/integration diagnostics)"},
     )
     @log_tool_usage
     async def ha_get_system_health(
         self,
         include: str | None = None,
         include_dismissed_repairs: bool | str | None = False,
+        config_entry_id: str | None = None,
+        device_id: str | None = None,
+        diagnostics_fields: list[str] | str | None = None,
+        diagnostics_truncate_at_bytes: int | str | None = None,
+        diagnostics_data_path: str | None = None,
+        diagnostics_data_offset: int | str | None = 0,
+        diagnostics_data_limit: int | str | None = None,
     ) -> dict[str, Any]:
         """
-        Get Home Assistant system health, including Zigbee (ZHA) and Z-Wave JS network diagnostics.
+        Get Home Assistant system health, including Zigbee (ZHA), Z-Wave JS, and per-integration diagnostics dumps.
 
         Returns health check results from integrations, system resources, and connectivity.
         Available information varies by installation type and loaded integrations.
@@ -355,8 +368,50 @@ class SystemTools:
           - "zha_network": ZHA Zigbee devices with radio signal summary (name, LQI, RSSI)
           - "zha_network_full": ZHA Zigbee devices with all device details (can be large on 100+ device networks; prefer "zha_network" for summary)
           - "zwave_network": Z-Wave JS network status and node summary (status, security, routing)
+          - "diagnostics": Per-integration diagnostics dump — integration-defined JSON
+            (commonly includes redacted config, device list, state snapshots; exact
+            top-level keys vary by integration). REQUIRES ``config_entry_id``. The
+            canonical artifact users grab via Settings → Devices & Services →
+            [integration] → ⋯ → Download diagnostics. Use this when triaging integration
+            bugs or filing ``ha_report_issue`` for a specific integration. Payloads can
+            be large (Hue ~290 KB, ZHA/MQTT/ESPHome several MB) — pair with
+            ``diagnostics_fields`` or ``diagnostics_truncate_at_bytes`` to fit the LLM
+            context budget.
           - Example: include="repairs,zha_network,zwave_network"
+          - Example: include="diagnostics", config_entry_id="abc123..."
         - include_dismissed_repairs: Include user-dismissed/ignored repairs (default: False). Only meaningful when "repairs" is in `include`.
+        - config_entry_id: Required when ``include`` contains ``diagnostics``. The config
+          entry ID of the integration (find via ``ha_get_integration``).
+        - device_id: Optional. When set with ``include=diagnostics``, returns the
+          device-scoped diagnostics dump for that specific device under the integration
+          (rather than the full integration dump). Some integrations only expose
+          config-entry-level dumps; others expose both.
+        - diagnostics_fields: Optional list of top-level keys to keep from the
+          diagnostics ``data`` payload (e.g. ``["home_assistant", "issues"]``). Accepts
+          a JSON list or comma-separated string. Only applies with ``include=diagnostics``.
+        - diagnostics_truncate_at_bytes: Optional byte cap on the serialized
+          diagnostics payload (post-projection / post-data_path). On hit,
+          drops ``data`` and emits ``truncated=true``, ``bytes_total``,
+          ``byte_cap``, plus ``available_fields`` (when the capped value
+          is a dict). Only applies when ``include`` contains ``diagnostics``.
+          Recommended starting point: 20000 bytes.
+        - diagnostics_data_path: Optional dotted path into the diagnostics
+          ``data`` sub-tree (e.g. ``"data.devices"`` for ZHA per-device records).
+          Walks into the post-fields payload. Resolution failures replace
+          ``data`` with ``null`` and surface ``data_path_error``. Only applies
+          when ``include`` contains ``diagnostics``.
+        - diagnostics_data_offset / diagnostics_data_limit: Pagination on
+          list-valued ``diagnostics_data_path`` results. When ``data_limit``
+          is set and the resolved path is a list, ``data`` becomes
+          ``{"path", "items", "offset", "limit", "total", "has_more"}``. Only
+          applies when ``include`` contains ``diagnostics``.
+
+          Example workflow (walk a list-valued sub-tree one page at a time;
+          the exact ``data_path`` varies by integration version):
+          ``ha_get_system_health(include="diagnostics", config_entry_id="abc",
+          diagnostics_data_path="<list-valued path>", diagnostics_data_limit=10)``
+          → inspect the page envelope's ``total`` / ``has_more`` → repeat
+          with ``diagnostics_data_offset=10`` for the next slice.
         """
         includes = self._parse_includes(include)
         include_dismissed_repairs_bool = bool(
@@ -373,10 +428,18 @@ class SystemTools:
             ws_client, result = await self._fetch_health_info()
 
             # Warn about unrecognized include values
-            VALID_INCLUDES = {"repairs", "zha_network", "zha_network_full", "zwave_network"}
+            VALID_INCLUDES = {
+                "repairs",
+                "zha_network",
+                "zha_network_full",
+                "zwave_network",
+                "diagnostics",
+            }
             unknown = includes - VALID_INCLUDES
             if unknown:
-                result["warning"] = f"Unknown include sections ignored: {', '.join(sorted(unknown))}"
+                result.setdefault("warnings", []).append(
+                    f"Unknown include sections ignored: {', '.join(sorted(unknown))}"
+                )
 
             # Fetch optional sections concurrently. The ws_client serialises
             # outgoing writes via its internal `_send_lock`, but per-message
@@ -462,6 +525,81 @@ class SystemTools:
                     else:
                         result[section_name] = section_result
 
+            # Diagnostics-related coercions live outside the includes branch
+            # so the orphan-args warning at the ``elif`` after the
+            # ``if "diagnostics" in includes`` block (see below) can see
+            # canonicalised values — passing ``diagnostics_data_offset=20``
+            # without ``include=diagnostics`` would otherwise slip past the gate.
+            fields_list = parse_diagnostics_fields(diagnostics_fields)
+            truncate_bytes = coerce_int_param(
+                diagnostics_truncate_at_bytes,
+                "diagnostics_truncate_at_bytes",
+                default=None,
+                min_value=1,
+            )
+            data_offset_int = coerce_int_param(
+                diagnostics_data_offset,
+                "diagnostics_data_offset",
+                default=0,
+                min_value=0,
+            )
+            data_limit_int = coerce_int_param(
+                diagnostics_data_limit,
+                "diagnostics_data_limit",
+                default=None,
+                min_value=1,
+            )
+            # Type-guard ``diagnostics_data_path`` here so a bad caller (dict /
+            # list) surfaces as ``VALIDATION_INVALID_PARAMETER`` instead of
+            # leaking as ``INTERNAL_ERROR`` from the resolver's ``.strip()``
+            # downstream. Mirrors the coerce_int_param guards above.
+            if diagnostics_data_path is not None and not isinstance(
+                diagnostics_data_path, str
+            ):
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        "diagnostics_data_path must be a string, got "
+                        f"{type(diagnostics_data_path).__name__}",
+                        context={"parameter": "diagnostics_data_path"},
+                    )
+                )
+
+            if "diagnostics" in includes:
+                # ``fetch_integration_diagnostics`` carries the empty-id guard
+                # (returns {"config_entry_id": ..., "error": ...}); calling it
+                # unconditionally keeps the missing-id error shape consistent
+                # with the populated path instead of returning a bare
+                # ``{"error": ...}`` sub-dict on the inline branch. Forward
+                # ``config_entry_id`` as-is (None / "") so the helper's echo
+                # field reflects what the caller actually passed.
+                result["diagnostics"] = await fetch_integration_diagnostics(
+                    self._client,
+                    config_entry_id,
+                    device_id,
+                    fields=fields_list,
+                    truncate_at_bytes=truncate_bytes,
+                    data_path=diagnostics_data_path,
+                    data_offset=data_offset_int,
+                    data_limit=data_limit_int,
+                )
+            elif (
+                config_entry_id
+                or device_id
+                or diagnostics_fields is not None
+                or diagnostics_truncate_at_bytes is not None
+                or diagnostics_data_path is not None
+                or diagnostics_data_limit is not None
+                or data_offset_int > 0
+            ):
+                result.setdefault("warnings", []).append(
+                    "config_entry_id, device_id, diagnostics_fields, "
+                    "diagnostics_truncate_at_bytes, diagnostics_data_path, "
+                    "diagnostics_data_offset, and/or diagnostics_data_limit "
+                    "were provided but ignored because 'diagnostics' is not "
+                    "in include"
+                )
+
             return result
 
         except ToolError: