ha-mcp-dev 7.1.0.dev308__tar.gz → 7.1.0.dev310__tar.gz

{ha_mcp_dev-7.1.0.dev308/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.1.0.dev310}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev308
+Version: 7.1.0.dev310
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.14,>=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastmcp==3.1.1
+Requires-Dist: fastmcp==3.2.0
 Requires-Dist: httpx[socks]==0.28.1
 Requires-Dist: pydantic==2.12.5
 Requires-Dist: python-dotenv==1.2.2
@@ -37,7 +37,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-93-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-94-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -160,7 +160,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (93 tools)</b></summary>
+<summary><b>Complete Tool List (94 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -183,7 +183,7 @@ 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_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_get_states`, `ha_search_entities` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_service`, `ha_get_bulk_status`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_config_set_yaml`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_add_todo_item`, `ha_get_todo`, `ha_remove_todo_item`, `ha_update_todo_item` |
 | **Utilities** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/README.md

@@ -8,7 +8,7 @@
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-93-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-94-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -131,7 +131,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (93 tools)</b></summary>
+<summary><b>Complete Tool List (94 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -154,7 +154,7 @@ 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_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_get_states`, `ha_search_entities` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_service`, `ha_get_bulk_status`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_config_set_yaml`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_add_todo_item`, `ha_get_todo`, `ha_remove_todo_item`, `ha_update_todo_item` |
 | **Utilities** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.1.0.dev308"
+version = "7.1.0.dev310"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -24,7 +24,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "fastmcp==3.1.1",
+    "fastmcp==3.2.0",
     "httpx[socks]==0.28.1",
     "pydantic==2.12.5",
     "python-dotenv==1.2.2",

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp/config.py

@@ -48,7 +48,9 @@ class Settings(BaseSettings):
     # Home Assistant connection
     # In OAuth mode, these are optional and provided per-request
     homeassistant_url: str = Field(default=OAUTH_MODE_URL, alias="HOMEASSISTANT_URL")
-    homeassistant_token: str = Field(default=OAUTH_MODE_TOKEN, alias="HOMEASSISTANT_TOKEN")
+    homeassistant_token: str = Field(
+        default=OAUTH_MODE_TOKEN, alias="HOMEASSISTANT_TOKEN"
+    )
 
     # Server configuration
     timeout: int = Field(30, alias="HA_TIMEOUT")
@@ -70,7 +72,9 @@ class Settings(BaseSettings):
 
     # MCP Server configuration
     mcp_server_name: str = Field("ha-mcp", alias="MCP_SERVER_NAME")
-    mcp_server_version: str = Field(default=_PACKAGE_VERSION, alias="MCP_SERVER_VERSION")
+    mcp_server_version: str = Field(
+        default=_PACKAGE_VERSION, alias="MCP_SERVER_VERSION"
+    )
 
     # Environment configuration
     environment: str = Field("development", alias="ENVIRONMENT")
@@ -83,7 +87,9 @@ class Settings(BaseSettings):
     # Dashboard partial update tools (python_transform, find_card)
     # These are token-efficient alternatives to full config replacement.
     # Disable when using clients with programmatic tool use (future).
-    enable_dashboard_partial_tools: bool = Field(True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS")
+    enable_dashboard_partial_tools: bool = Field(
+        True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS"
+    )
 
     # Skills configuration
     # Serve bundled HA best-practice skills as MCP resources (skill:// URIs).
@@ -101,6 +107,11 @@ class Settings(BaseSettings):
     # Dramatically reduces idle context token usage for LLMs.
     enable_tool_search: bool = Field(False, alias="ENABLE_TOOL_SEARCH")
 
+    # Managed YAML config editing — allows ha_config_set_yaml to add,
+    # replace, or remove top-level keys in configuration.yaml and package
+    # files. Disabled by default; only for YAML-only features with no UI/API path.
+    enable_yaml_config_editing: bool = Field(False, alias="ENABLE_YAML_CONFIG_EDITING")
+
     @model_validator(mode="after")
     def _skills_dependency(self) -> "Settings":
         """Auto-enable skills (resources) when skills-as-tools is on.

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp/server.py

@@ -380,6 +380,11 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "create update modify edit script sequence actions "
             "new script write save"
         ),
+        "ha_config_set_yaml": (
+            "edit yaml configuration.yaml packages template sensor "
+            "binary_sensor command_line rest mqtt platform yaml-only "
+            "config file modify add remove replace"
+        ),
     }
 
     # Description overrides that REPLACE the original description for BM25.

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp/tools/tools_traces.py

@@ -5,6 +5,7 @@ This module provides tools for retrieving execution traces from Home Assistant
 to help debug automation and script issues.
 """
 
+import json
 import logging
 from typing import Annotated, Any
 
@@ -51,6 +52,31 @@ def register_trace_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 le=50,
             ),
         ] = 10,
+        deduplicate: Annotated[
+            bool,
+            Field(
+                description="Deduplicate variables across action steps (default: True). Set to False to include full variables at every step.",
+                default=True,
+            ),
+        ] = True,
+        detailed: Annotated[
+            bool,
+            Field(
+                description="Include extra diagnostic data: logbook entries and context metadata (default: False). Use when standard trace lacks detail for debugging.",
+                default=False,
+            ),
+        ] = False,
+        sections: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Comma-separated list of trace sections to return. "
+                    "Valid values: trigger, conditions, actions, config, error, logbook, context. "
+                    "Omit to return all sections. Example: 'actions' or 'trigger,conditions'."
+                ),
+                default=None,
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         """
         Retrieve execution traces for automations and scripts to debug issues.
@@ -73,6 +99,17 @@ def register_trace_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
            Returns full execution details including trigger info, condition results,
            action trace with timing, and context variables.
 
+        3. Get detailed trace with logbook (provide run_id and detailed=True):
+           ha_get_automation_traces("automation.motion_light", run_id="1705312800.123456", detailed=True)
+           Returns the formatted trace plus logbook entries and context metadata.
+           Useful when the standard trace summary doesn't reveal enough for debugging.
+           Note: script-style action paths (sequence/, numeric) are always matched
+           regardless of this flag.
+
+        4. Get full variables without deduplication (provide run_id and deduplicate=False):
+           ha_get_automation_traces("automation.motion_light", run_id="1705312800.123456", deduplicate=False)
+           Returns the formatted trace with full variables at every action step.
+
         DEBUGGING EXAMPLES:
 
         Automation not triggering:
@@ -152,7 +189,11 @@ def register_trace_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                         ))
 
                     trace_data = result.get("result", {})
-                    return _format_detailed_trace(automation_id, run_id, trace_data)
+                    return _format_detailed_trace(
+                        automation_id, run_id, trace_data,
+                        deduplicate=deduplicate, detailed=detailed,
+                        sections=sections,
+                    )
                 else:
                     # List recent traces
                     result = await ws_client.send_command(
@@ -412,9 +453,12 @@ def _format_trace_list(
 
 
 def _format_detailed_trace(
-    automation_id: str, run_id: str, trace: dict[str, Any]
+    automation_id: str, run_id: str, trace: dict[str, Any],
+    *, deduplicate: bool = True, detailed: bool = False,
+    sections: str | None = None,
 ) -> dict[str, Any]:
     """Format detailed trace for AI consumption."""
+    domain = "automation" if automation_id.startswith("automation.") else "script"
     result: dict[str, Any] = {
         "success": True,
         "automation_id": automation_id,
@@ -445,7 +489,11 @@ def _format_detailed_trace(
                 triggers.append(step_info)
             elif path == "condition" or path.startswith("condition/"):
                 conditions.append(step_info)
-            elif path == "action" or path.startswith("action/"):
+            elif (
+                path == "action" or path.startswith("action/")
+                or path.startswith("sequence/")
+                or (domain == "script" and (path.split("/")[0].isdigit()))
+            ):
                 actions.append(step_info)
 
     # Sort by timestamp (if available) or path to maintain execution order
@@ -494,9 +542,15 @@ def _format_detailed_trace(
             condition_results.append(cond_result)
         result["condition_results"] = condition_results
 
-    # Extract action trace
+    # Extract action trace with optional variable deduplication.
+    # Home Assistant includes the full variable context at every trace step,
+    # but variables rarely change between steps. For complex automations with
+    # hundreds of steps (e.g., blueprint choose actions), this can produce
+    # 100KB+ of duplicated data. When deduplicate=True (default), we only
+    # include variables at steps where they actually changed.
     if actions:
         action_results = []
+        last_vars_fingerprint: str | None = None
         for action in actions:
             action_info: dict[str, Any] = {
                 "path": action.get("path"),
@@ -515,14 +569,24 @@ def _format_detailed_trace(
             if "error" in action:
                 action_info["error"] = action["error"]
 
-            # Extract variables if they contain useful debugging info
+            # Extract variables, optionally deduplicating across steps.
             # Check both 'variables' and 'changed_variables'
             variables = action.get("variables") or action.get("changed_variables", {})
             if variables and "trigger" not in variables:  # Skip trigger vars (already shown)
-                # Only include non-empty variable sets
                 useful_vars = {k: v for k, v in variables.items() if v is not None}
                 if useful_vars:
-                    action_info["variables"] = useful_vars
+                    if deduplicate:
+                        # Compare with previous step using JSON fingerprint
+                        try:
+                            fingerprint = json.dumps(useful_vars, sort_keys=True, default=str)
+                        except (TypeError, ValueError):
+                            fingerprint = str(useful_vars)
+
+                        if fingerprint != last_vars_fingerprint:
+                            action_info["variables"] = useful_vars
+                            last_vars_fingerprint = fingerprint
+                    else:
+                        action_info["variables"] = useful_vars
 
             # Add child execution info (for nested scripts/automations)
             if "child_id" in action:
@@ -549,4 +613,30 @@ def _format_detailed_trace(
     if trace.get("script_execution"):
         result["script_execution"] = trace["script_execution"]
 
+    # In detailed mode, include logbook entries and context metadata
+    # that are essential for debugging but omitted by default to save context.
+    if detailed:
+        if "logbook_entries" in trace:
+            result["logbook_entries"] = trace["logbook_entries"]
+        if trace.get("context"):
+            result["context"] = trace["context"]
+
+    # Filter to requested sections if specified.
+    # Maps user-facing section names to result dict keys.
+    if sections:
+        section_key_map = {
+            "trigger": "trigger",
+            "conditions": "condition_results",
+            "actions": "action_trace",
+            "config": "config_summary",
+            "error": "error",
+            "logbook": "logbook_entries",
+            "context": "context",
+        }
+        requested = {s.strip().lower() for s in sections.split(",")}
+        keep_keys = {section_key_map[s] for s in requested if s in section_key_map}
+        # Always keep metadata keys
+        keep_keys |= {"success", "automation_id", "run_id", "timestamp", "state", "script_execution"}
+        result = {k: v for k, v in result.items() if k in keep_keys}
+
     return result

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp/tools/tools_utility.py

@@ -17,6 +17,23 @@ from .util_helpers import add_timezone_metadata, coerce_bool_param, coerce_int_p
 
 logger = logging.getLogger(__name__)
 
+# Fields to keep in compact logbook mode (strips attribute dictionaries
+# and other bulky fields that can cause context exhaustion — see #683)
+COMPACT_LOGBOOK_FIELDS = {"when", "entity_id", "state", "name", "message", "domain", "context_id", "source"}
+
+
+def _compact_logbook_entries(entries: list[Any]) -> list[dict[str, Any]]:
+    """Strip logbook entries to essential fields only.
+
+    Returns entries with only the fields in COMPACT_LOGBOOK_FIELDS,
+    filtering out any non-dict entries.
+    """
+    return [
+        {k: v for k, v in entry.items() if k in COMPACT_LOGBOOK_FIELDS}
+        for entry in entries
+        if isinstance(entry, dict)
+    ]
+
 
 def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     """Register Home Assistant utility tools."""
@@ -40,6 +57,7 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         end_time: str | None = None,
         limit: int | str | None = None,
         offset: int | str = 0,
+        compact: bool | str = True,
     ) -> dict[str, Any]:
         """
         Get Home Assistant logbook entries for the specified time period.
@@ -52,6 +70,9 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         - end_time: Optional end time in ISO format (defaults to now)
         - limit: Maximum number of entries to return (default: 50, max: 500)
         - offset: Number of entries to skip for pagination (default: 0)
+        - compact: Return only essential fields per entry (default: True).
+          When True, each entry contains only: when, entity_id, state, name, message, domain, context_id.
+          Set to False to include full attribute dictionaries and all fields.
 
         **Pagination:**
         When the logbook has more entries than the limit, use offset to get
@@ -68,9 +89,12 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         **Example:**
         - First page: ha_get_logbook(hours_back=24, limit=50, offset=0)
         - Second page: ha_get_logbook(hours_back=24, limit=50, offset=50)
+        - Full details: ha_get_logbook(hours_back=1, compact=False)
         """
 
         # Coerce parameters with string handling for AI tools
+        compact_bool = coerce_bool_param(compact, "compact", default=True)
+
         try:
             hours_back_int = coerce_int_param(
                 hours_back,
@@ -145,6 +169,12 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 paginated_entries = response
                 has_more = False
 
+            # In compact mode, strip entries to essential fields only.
+            # This prevents full attribute dictionaries from exhausting
+            # the LLM context window during debugging workflows.
+            if compact_bool and isinstance(paginated_entries, list):
+                paginated_entries = _compact_logbook_entries(paginated_entries)
+
             logbook_data = {
                 "success": True,
                 "entries": paginated_entries,
@@ -174,6 +204,8 @@ def register_utility_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     param_parts.append(f"entity_id={entity_id}")
                 if end_time:
                     param_parts.append(f"end_time={end_time}")
+                if not compact_bool:
+                    param_parts.append("compact=False")
 
                 param_str = ", ".join(param_parts)
                 logbook_data["pagination_hint"] = (

ha_mcp_dev-7.1.0.dev310/src/ha_mcp/tools/tools_yaml_config.py

@@ -0,0 +1,205 @@
+"""
+Managed YAML configuration editing tools for Home Assistant MCP Server.
+
+Provides a structured, validated tool for editing YAML configuration files
+(configuration.yaml and package files) for Home Assistant features that exist
+only in YAML and have no REST/WebSocket API equivalent.
+
+**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.
+
+Feature Flag: Set ENABLE_YAML_CONFIG_EDITING=true to enable.
+"""
+
+import logging
+from typing import Annotated, Any
+
+from fastmcp.exceptions import ToolError
+from pydantic import Field
+
+from ..config import get_global_settings
+from ..errors import ErrorCode, create_error_response
+from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
+from .tools_filesystem import (
+    MCP_TOOLS_DOMAIN,
+    _assert_mcp_tools_available,
+)
+from .util_helpers import add_timezone_metadata, coerce_bool_param
+
+logger = logging.getLogger(__name__)
+
+
+def register_yaml_config_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
+    """Register YAML config editing tools with the MCP server.
+
+    Requires ENABLE_YAML_CONFIG_EDITING=true.
+    """
+    settings = get_global_settings()
+    if not settings.enable_yaml_config_editing:
+        logger.debug(
+            "YAML config tools disabled (set ENABLE_YAML_CONFIG_EDITING=true to enable)"
+        )
+        return
+
+    logger.info("YAML config editing tools enabled")
+
+    @mcp.tool(
+        tags={"System"},
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": False,
+            "title": "Set YAML Config",
+        },
+    )
+    @log_tool_usage
+    async def ha_config_set_yaml(
+        yaml_path: Annotated[
+            str,
+            Field(
+                description=(
+                    "Top-level YAML key to modify (e.g., 'template', 'sensor', "
+                    "'input_boolean'). Only whitelisted keys are allowed."
+                ),
+            ),
+        ],
+        action: Annotated[
+            str,
+            Field(
+                description=(
+                    "Action to perform: 'add' (insert/merge content under key), "
+                    "'replace' (overwrite key with new content), or "
+                    "'remove' (delete the key entirely)."
+                ),
+            ),
+        ],
+        content: Annotated[
+            str | None,
+            Field(
+                default=None,
+                description=(
+                    "YAML content for the value under yaml_path. Required for "
+                    "'add' and 'replace' actions. Must be valid YAML."
+                ),
+            ),
+        ] = None,
+        file: Annotated[
+            str,
+            Field(
+                default="configuration.yaml",
+                description=(
+                    "Relative path to the YAML config file. Defaults to "
+                    "'configuration.yaml'. Also supports 'packages/*.yaml'."
+                ),
+            ),
+        ] = "configuration.yaml",
+        backup: Annotated[
+            bool | str,
+            Field(
+                default=True,
+                description=(
+                    "Create a backup before editing. Defaults to True. "
+                    "Backups are saved to www/yaml_backups/."
+                ),
+            ),
+        ] = True,
+    ) -> dict[str, Any]:
+        """Add, replace, or remove a top-level key in configuration.yaml or package files.
+
+        IMPORTANT: Only use when NO UI or API alternative exists. Prefer:
+        - Template sensors -> ha_config_set_helper (Template Helper)
+        - Automations -> ha_config_set_automation
+        - Scripts -> ha_config_set_script
+        - Input helpers -> ha_config_set_helper
+        - Scenes -> ha_config_set_scene
+
+        This tool is for YAML-only features with no UI/API path (e.g.,
+        command_line sensors, platform-based MQTT sensors in YAML, rest
+        sensors defined in packages).
+
+        Safeguards: file backup, YAML validation, top-level key whitelist,
+        path traversal blocking, post-edit config check.
+
+        IMPORTANT: Check 'post_action' in the response. Most keys require
+        a full HA restart ('restart_required'). Only template, mqtt, and
+        group support reload ('reload_available' with 'reload_service').
+
+        Note: YAML comments are not preserved after editing. The backup
+        retains the original file with comments intact.
+        """
+        try:
+            # Validate action
+            valid_actions = ("add", "replace", "remove")
+            if action not in valid_actions:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"Invalid action '{action}'. Must be one of: {', '.join(valid_actions)}",
+                        suggestions=[
+                            "Use action='add' to insert content under a key",
+                            "Use action='replace' to overwrite a key's content",
+                            "Use action='remove' to delete a key entirely",
+                        ],
+                    )
+                )
+
+            # Validate content is provided for add/replace
+            if action in ("add", "replace") and not content:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        f"'content' is required for action '{action}'.",
+                        suggestions=[
+                            "Provide valid YAML content to insert or replace."
+                        ],
+                    )
+                )
+
+            # Coerce boolean parameter
+            backup_bool = coerce_bool_param(backup, "backup", default=True)
+
+            # Check if custom component is available
+            await _assert_mcp_tools_available(client)
+
+            # Build service data
+            service_data: dict[str, Any] = {
+                "file": file,
+                "action": action,
+                "yaml_path": yaml_path,
+                "backup": backup_bool,
+            }
+            if content is not None:
+                service_data["content"] = content
+
+            # Call the custom component service
+            result = await client.call_service(
+                MCP_TOOLS_DOMAIN,
+                "edit_yaml_config",
+                service_data,
+                return_response=True,
+            )
+
+            if isinstance(result, dict):
+                if not result.get("success", True):
+                    raise_tool_error(result)
+                return await add_timezone_metadata(client, result)
+
+            raise_tool_error(
+                create_error_response(
+                    ErrorCode.SERVICE_CALL_FAILED,
+                    "Unexpected response format from YAML config service",
+                    context={"file": file},
+                )
+            )
+
+        except ToolError:
+            raise
+        except Exception as e:
+            exception_to_structured_error(
+                e,
+                context={
+                    "tool": "ha_config_set_yaml",
+                    "file": file,
+                    "action": action,
+                    "yaml_path": yaml_path,
+                },
+            )

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp/transforms/categorized_search.py

@@ -46,6 +46,7 @@ DEFAULT_PINNED_TOOLS: tuple[str, ...] = (
     "ha_search_entities",
     "ha_config_get_automation",
     "ha_config_set_automation",
+    "ha_config_set_yaml",
 )
 
 # Tool name patterns that indicate delete/remove operations

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev308
+Version: 7.1.0.dev310
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -18,7 +18,7 @@ Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <3.14,>=3.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: fastmcp==3.1.1
+Requires-Dist: fastmcp==3.2.0
 Requires-Dist: httpx[socks]==0.28.1
 Requires-Dist: pydantic==2.12.5
 Requires-Dist: python-dotenv==1.2.2
@@ -37,7 +37,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-93-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-94-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -160,7 +160,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (93 tools)</b></summary>
+<summary><b>Complete Tool List (94 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -183,7 +183,7 @@ 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_deep_search`, `ha_get_overview`, `ha_get_state`, `ha_get_states`, `ha_search_entities` |
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_service`, `ha_get_bulk_status`, `ha_get_operation_status`, `ha_list_services` |
-| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
+| **System** | `ha_backup_create`, `ha_backup_restore`, `ha_check_config`, `ha_config_set_yaml`, `ha_get_system_health`, `ha_get_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_add_todo_item`, `ha_get_todo`, `ha_remove_todo_item`, `ha_update_todo_item` |
 | **Utilities** | `ha_eval_template`, `ha_install_mcp_tools`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -76,6 +76,7 @@ src/ha_mcp/tools/tools_traces.py
 src/ha_mcp/tools/tools_updates.py
 src/ha_mcp/tools/tools_utility.py
 src/ha_mcp/tools/tools_voice_assistant.py
+src/ha_mcp/tools/tools_yaml_config.py
 src/ha_mcp/tools/tools_zones.py
 src/ha_mcp/tools/util_helpers.py
 src/ha_mcp/transforms/__init__.py

{ha_mcp_dev-7.1.0.dev308 → ha_mcp_dev-7.1.0.dev310}/src/ha_mcp_dev.egg-info/requires.txt

@@ -1,4 +1,4 @@
-fastmcp==3.1.1
+fastmcp==3.2.0
 httpx[socks]==0.28.1
 pydantic==2.12.5
 python-dotenv==1.2.2