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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.1.0.dev308
+Version: 7.1.0.dev309
 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.1.0.dev308 → ha_mcp_dev-7.1.0.dev309}/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.dev309"
 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.1.0.dev308 → ha_mcp_dev-7.1.0.dev309}/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.dev309}/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.dev309/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(
+        annotations={
+            "destructiveHint": True,
+            "idempotentHint": False,
+            "tags": ["filesystem", "config", "yaml"],
+            "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.dev309}/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.dev309/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.dev309
 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.1.0.dev308 → ha_mcp_dev-7.1.0.dev309}/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