Added feature flags for gated features to App config. (#1030)

* Added feature flags for HAMCP_ENABLE_FILESYSTEM_TOOLS and HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION to the App configuration.

* docs: document enable_filesystem_tools and enable_custom_component_integration addon options

* Update homeassistant-addon/DOCS.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Update homeassistant-addon/DOCS.md

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* Moved feature flags to "unused" section for safety.

* Added descriptions for feature flag options.

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Moved file tools to beta status.

* Added beta tag to ha_config_set_yaml in docs.

* Tagged ha_install_mcp_tools as beta and updated docs.

* Update homeassistant-addon-dev/translations/en.yaml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Update homeassistant-addon-dev/translations/en.yaml

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

README.md

@@ -164,7 +164,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Dashboards** | `ha_config_delete_dashboard_resource`, `ha_config_delete_dashboard`, `ha_config_get_dashboard`, `ha_config_list_dashboard_resources`, `ha_config_set_dashboard_resource`, `ha_config_set_dashboard` |
 | **Device Registry** | `ha_get_device`, `ha_remove_device`, `ha_update_device` |
 | **Entity Registry** | `ha_get_entity_exposure`, `ha_get_entity`, `ha_remove_entity`, `ha_set_entity` |
-| **Files** | `ha_delete_file`, `ha_list_files`, `ha_read_file`, `ha_write_file` |
+| **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_remove_helper`, `ha_config_set_helper`, `ha_get_helper_schema` |
@@ -184,19 +184,19 @@ Spend less time configuring, more time enjoying your smart home.
 
 ---
 
-## 🔌 Custom Component (ha_mcp_tools)
+## 🔌 Custom Component (ha_mcp_tools) *(beta)*
 
 Some tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.
 
 **Tools that require the component:**
 
 | Tool | Description |
 |------|-------------|
-| `ha_config_set_yaml` | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
-| `ha_list_files` | List files in allowed directories (www/, themes/, custom_templates/) |
-| `ha_read_file` | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
-| `ha_write_file` | Write files to allowed directories |
-| `ha_delete_file` | Delete files from allowed directories |
+| `ha_config_set_yaml` *(beta)* | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
+| `ha_list_files` *(beta)* | List files in allowed directories (www/, themes/, custom_templates/) |
+| `ha_read_file` *(beta)* | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_write_file` *(beta)* | Write files to allowed directories |
+| `ha_delete_file` *(beta)* | Delete files from allowed directories |
 
 All other tools work without the component. These five return an error with installation instructions if the component is missing.
 

docs/beta.md

@@ -7,17 +7,23 @@ Some ha-mcp tools are gated behind feature flags and available only in the **dev
 | Tool | Toggle / env var | Description |
 |---|---|---|
 | `ha_config_set_yaml` | `enable_yaml_config_editing` (dev add-on) / `ENABLE_YAML_CONFIG_EDITING=true` (env var) | Raw YAML editing of `configuration.yaml` and packages/*.yaml for YAML-only integrations. |
+| `ha_list_files` | `enable_filesystem_tools` (dev add-on) / `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (env var) | List files in allowed directories (www/, themes/, custom_templates/). Requires `ha_mcp_tools` custom component. |
+| `ha_read_file` | `enable_filesystem_tools` (dev add-on) / `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (env var) | Read files from allowed paths. Requires `ha_mcp_tools` custom component. |
+| `ha_write_file` | `enable_filesystem_tools` (dev add-on) / `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (env var) | Write files to allowed directories. Requires `ha_mcp_tools` custom component. |
+| `ha_delete_file` | `enable_filesystem_tools` (dev add-on) / `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (env var) | Delete files from allowed directories. Requires `ha_mcp_tools` custom component. |
+| `ha_install_mcp_tools` | `enable_custom_component_integration` (dev add-on) / `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true` (env var) | Installs the `ha_mcp_tools` custom component via HACS. |
 
 ## How to enable
 
 ### Option 1: Dev channel add-on (Home Assistant users)
 
 1. Install the **Home Assistant MCP Server (Dev)** add-on. See [docs/dev-channel.md](dev-channel.md) for details.
 2. Open the add-on's **Configuration** tab.
-3. Enable the toggle (e.g., `enable_yaml_config_editing`).
-4. Restart the add-on.
+3. Enable "Show unused optional configuration options" to reveal beta toggles.
+4. Enable the desired toggle (e.g., `enable_yaml_config_editing`, `enable_filesystem_tools`).
+5. Restart the add-on.
 
-The stable add-on does not expose beta toggles.
+`enable_yaml_config_editing`, `enable_filesystem_tools`, and `enable_custom_component_integration` are only available in the dev channel add-on. The stable add-on does not expose these beta toggles.
 
 ### Option 2: Environment variable (non-add-on installs)
 
@@ -49,3 +55,15 @@ This tool edits `configuration.yaml` and package files directly, bypassing Home
 **Recommended prerequisites:**
 - Comfort with editing `configuration.yaml` via SSH or File Editor when things go wrong
 - Understanding that dedicated tools (`ha_config_set_helper`, `ha_config_set_automation`, `ha_config_set_script`, `ha_config_set_scene`, etc.) should be preferred for anything they support
+
+### `ha_list_files`, `ha_read_file`, `ha_write_file`, `ha_delete_file`
+
+These tools provide direct file access to your Home Assistant filesystem and require `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` and the `ha_mcp_tools` custom component installed and active.
+
+`HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true` is only needed if you want to allow the `ha_install_mcp_tools` installer tool; it is not required for the filesystem tools themselves.
+
+**Access is restricted but sensitive.** Only `www/`, `themes/`, and `custom_templates/` are writable. `ha_read_file` additionally allows reading config YAML files, logs, and `custom_components/`. An AI assistant with these tools enabled has meaningful read access to your HA configuration.
+
+**No undo.** `ha_delete_file` and `ha_write_file` (with `overwrite=True`) are irreversible. There is no recycle bin or automatic backup for file operations.
+
+**Requires the custom component.** If `ha_mcp_tools` is not installed and active, all file tools will return an error with installation instructions.

homeassistant-addon-dev/DOCS.md

@@ -14,6 +14,11 @@ The dev add-on uses the same configuration as the stable version. See the main a
 |--------|-------------|---------|
 | `backup_hint` | Backup strength preference | `normal` |
 | `secret_path` | Custom secret path (optional) | auto-generated |
+| `enable_yaml_config_editing` *(beta)* | Enables `ha_config_set_yaml` for editing `configuration.yaml` directly. Requires `ha_mcp_tools` custom component. | `false` |
+| `enable_filesystem_tools` *(beta)* | Enables file read/write tools (`ha_list_files`, `ha_read_file`, `ha_write_file`, `ha_delete_file`). Requires `ha_mcp_tools` custom component. | `false` |
+| `enable_custom_component_integration` *(beta)* | Enables `ha_install_mcp_tools` installer tool for the `ha_mcp_tools` custom component. | `false` |
+
+Beta options are hidden under "Show unused optional configuration options" in the add-on Configuration tab. See [beta.md](https://github.com/homeassistant-ai/ha-mcp/blob/master/docs/beta.md) for details.
 
 ## Updates
 

homeassistant-addon-dev/config.yaml

@@ -28,5 +28,7 @@ schema:
   enable_skills_as_tools: bool?
   enable_tool_search: bool?
   enable_yaml_config_editing: bool?
+  enable_filesystem_tools: bool?
+  enable_custom_component_integration: bool?
 ports:
   9583/tcp: 9583

homeassistant-addon-dev/translations/en.yaml

@@ -38,3 +38,21 @@ configuration:
       require a full HA restart to take effect. See docs/beta.md for known
       limitations. Dedicated tools (automations, scripts, scenes, helpers,
       template sensors) should be preferred when available.
+  enable_filesystem_tools:
+    name: Enable filesystem tools (beta)
+    description: >-
+      Sets HAMCP_ENABLE_FILESYSTEM_TOOLS=true. Enables direct file read/write
+      access to your Home Assistant filesystem. WARNING: This gives the MCP
+      server sensitive direct file access to your system. Only enable if you
+      trust the AI assistant with file operations. Requires restart to take
+      effect.
+  enable_custom_component_integration:
+    name: Enable custom component integration (beta)
+    description: >-
+      Sets HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true. Enables the
+      ha_install_mcp_tools installer tool, which can help install the
+      ha_mcp_tools custom component. This setting does not control whether the
+      MCP server loads or interacts with the custom component, and it is not
+      required for filesystem tools to function. Only enable if you want to
+      allow the AI assistant to use the installer tool. Requires restart to
+      take effect.

homeassistant-addon/DOCS.md

@@ -383,10 +383,10 @@ The add-on provides 86+ MCP tools for controlling Home Assistant:
 - `ha_set_entity` — Update entity properties in the entity registry.
 
 ### Files
-- `ha_delete_file` — Delete a file from allowed directories in the Home Assistant config.
-- `ha_list_files` — List files in a directory within the Home Assistant config directory.
-- `ha_read_file` — Read a file from the Home Assistant config directory.
-- `ha_write_file` — Write a file to allowed directories in the Home Assistant config.
+- `ha_delete_file` **(beta)** — Delete a file from allowed directories in the Home Assistant config.
+- `ha_list_files` **(beta)** — List files in a directory within the Home Assistant config directory.
+- `ha_read_file` **(beta)** — Read a file from the Home Assistant config directory.
+- `ha_write_file` **(beta)** — Write a file to allowed directories in the Home Assistant config.
 
 ### Groups
 - `ha_config_list_groups` — List all Home Assistant entity groups with their member entities.

homeassistant-addon/config.yaml

@@ -21,8 +21,9 @@ host_network: true
 # Use pre-built Docker images
 image: "ghcr.io/homeassistant-ai/ha-mcp-addon-{arch}"
 # Options for user configuration
-# NOTE: enable_yaml_config_editing is intentionally NOT exposed here.
-# It is a dev-channel-only beta feature — see docs/beta.md. Do not re-mirror
+# NOTE: enable_yaml_config_editing, enable_filesystem_tools, and
+# enable_custom_component_integration are intentionally NOT exposed here.
+# They are dev-channel-only beta features — see docs/beta.md. Do not re-mirror
 # from homeassistant-addon-dev/config.yaml without reading that doc first.
 options:
   backup_hint: "normal"

homeassistant-addon/start.py

@@ -190,6 +190,8 @@ def main() -> int:
     enable_skills_as_tools = True  # default
     enable_tool_search = False  # default
     enable_yaml_config_editing = False  # default
+    enable_filesystem_tools = False  # default
+    enable_custom_component_integration = False  # default
     config_read_ok = True
 
     if config_file.exists():
@@ -206,6 +208,10 @@ def main() -> int:
             enable_tool_search = raw_tool_search if isinstance(raw_tool_search, bool) else False
             raw_yaml_config = config.get("enable_yaml_config_editing", False)
             enable_yaml_config_editing = raw_yaml_config if isinstance(raw_yaml_config, bool) else False
+            raw_filesystem_tools = config.get("enable_filesystem_tools", False)
+            enable_filesystem_tools = raw_filesystem_tools if isinstance(raw_filesystem_tools, bool) else False
+            raw_custom_component = config.get("enable_custom_component_integration", False)
+            enable_custom_component_integration = raw_custom_component if isinstance(raw_custom_component, bool) else False
         except Exception as e:
             log_error(f"Failed to read config: {e}, using defaults")
             config_read_ok = False
@@ -231,6 +237,8 @@ def main() -> int:
     os.environ["ENABLE_SKILLS_AS_TOOLS"] = str(enable_skills_as_tools).lower()
     os.environ["ENABLE_TOOL_SEARCH"] = str(enable_tool_search).lower()
     os.environ["ENABLE_YAML_CONFIG_EDITING"] = str(enable_yaml_config_editing).lower()
+    os.environ["HAMCP_ENABLE_FILESYSTEM_TOOLS"] = str(enable_filesystem_tools).lower()
+    os.environ["HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"] = str(enable_custom_component_integration).lower()
 
     # Validate Supervisor token
     supervisor_token = os.environ.get("SUPERVISOR_TOKEN")

src/ha_mcp/tools/tools_filesystem.py

@@ -101,7 +101,7 @@ def __init__(self, client: Any) -> None:
 
     @tool(
         name="ha_list_files",
-        tags={"Files"},
+        tags={"Files", "beta"},
         annotations={
             "readOnlyHint": True,
             "title": "List Files",
@@ -195,7 +195,7 @@ async def ha_list_files(
 
     @tool(
         name="ha_read_file",
-        tags={"Files"},
+        tags={"Files", "beta"},
         annotations={
             "readOnlyHint": True,
             "title": "Read File",
@@ -308,7 +308,7 @@ async def ha_read_file(
 
     @tool(
         name="ha_write_file",
-        tags={"Files"},
+        tags={"Files", "beta"},
         annotations={
             "destructiveHint": True,
             "title": "Write File",
@@ -439,7 +439,7 @@ async def ha_write_file(
 
     @tool(
         name="ha_delete_file",
-        tags={"Files"},
+        tags={"Files", "beta"},
         annotations={
             "destructiveHint": True,
             "title": "Delete File",

src/ha_mcp/tools/tools_mcp_component.py

@@ -163,7 +163,7 @@ def _handle_restart(result: dict[str, Any], restart_error: Exception) -> None:
 
     @tool(
         name="ha_install_mcp_tools",
-        tags={"Utilities"},
+        tags={"Utilities", "beta"},
         annotations={
             "destructiveHint": True,
             "title": "Install MCP Tools Component"