[FEATURE] interaction with packages folder

[VPelt]

What would you like to see?

It would be nice if mcp could create templates/scripts/etc in a /package folder

The reason is twofold

1. certain features are just not available through the UI. For example I have a templated device tracker. This is something I cannot create through the UI
2. it would allow for easy version control of changes. My committing the folder in git it's easy to see and/or recert changes made through AI

Why do you need this?

Certain templates are not creatable through UI

Additional context

No response

[github-actions[bot]]

ℹ️ Information Needed

• Installation method - (uvx/pip/docker/addon). This is critical for determining if the MCP server has filesystem access to your Home Assistant configuration directory.
• ha-mcp version - The current version you are running.

---

💡 Please reply to this issue with the requested information.

🤖 Automated triage by Issue Bot

[kingpanther13]

99% of the time you can actually create things thru the UI, your AI is probably misleading you. Every AI I have used with HA has been notorious for suggesting to write things in yaml based on old training, but most things can be achieved thru the UI. Sounds like what you're describing could be a helper made thru the UI, and our config set helper tool could help with that.

We do have a yaml writing tool that can write to packages folder but it's beta/dev server only because it is extremely dangerous, due to the AI hallucinating and thinking that they just write to yaml even though they don't; they often will write broken or old buggy code that can brick your installation. So I recommend not using that, and I recommend pushing back on whatever your AI is and saying "no, this can be made in the UI" and eventually it'll figure it out. Even after all of the optimizations I've made on my own personal AI and ha-mcp setup it still will occasionally recommend writing to yaml or will tell me I have to manually copy and paste something, when in reality it was possible via the UI the whole time... Usually I have to push back 2-3 times and tell it it's wrong and it's possible thru the UI and to think harder, eventually it finds the proper tools.

[VPelt]

I'm pretty wel verder in writing templates myself

And no, specifically a device tracker is something I don't think you can write through the UI

Also getting a to-do list itemized properly requires calling a service/action so my ai actually tries to scriptify this in a ui version but those don't actually work (or at best with so little data it isn't usable)

[github-actions[bot]]

Based on my analysis of the codebase, the user is requesting expanded filesystem and configuration access to support Home Assistant packages.

Currently, ha-mcp (via the ha_mcp_tools custom component) restricts file writing to specific directories (www/, themes/, custom_templates/, dashboards/) and limits structured YAML editing to a specific set of "YAML-only" keys. While packages/*.yaml files are readable, they cannot be created or listed via the filesystem tools, and key domains like automation and script are blocked from the YAML editing tool because specialized API-based tools exist. However, those specialized tools do not support writing to the packages/ directory, which is essential for users who want to organize their configuration for version control (git).

🔍 Analysis

The user wants to interact with the Home Assistant packages/ folder to create templates, scripts, and other configurations (like templated device trackers) that are not manageable through the UI. This allows for better organization and easier versioning via git.

To support this feature, we need to:

1. Enable packages/ directory access: Add packages to the allowed list for directory listing and file writing.
2. Expand YAML editing keys: Add automation, script, and device_tracker to the allowed list for structured YAML editing. This ensures that even though these domains have dedicated tools, they can still be managed via YAML when organized into packages.
3. Provide Reload Services: Ensure that changes to these new keys can be applied without a full Home Assistant restart by mapping them to their respective reload services (e.g., automation.reload).

🛠️ Suggested Steps

1. Update the Custom Component: Modify custom_components/ha_mcp_tools/const.py to allow the packages directory and the new YAML keys (automation, script, device_tracker).
2. Update the Server Tools: Modify src/ha_mcp/tools/tools_filesystem.py to include packages/ in the WRITABLE_DIRS and update the tool documentation so the AI knows it can now use this folder.
3. Verify via Tests: Update tests/src/unit/test_tools_filesystem.py to ensure the new constants are correctly mirrored and protected against regression.

📊 Technical Analysis (for maintainers)

Root Cause

The restriction is hardcoded in both the ha_mcp_tools custom component and the ha-mcp server tools.

• ALLOWED_WRITE_DIRS in the custom component prevents writing to packages/.
• ALLOWED_YAML_KEYS prevents editing automation and script via ha_config_set_yaml.
• WRITABLE_DIRS and docstrings in the server-side FilesystemTools do not mention packages/.

Affected Code

• custom_components/ha_mcp_tools/const.py - Core allowlists for directories and YAML keys.
• src/ha_mcp/tools/tools_filesystem.py - Server-side tool definitions and documentation.

Proposed Fix

--- a/custom_components/ha_mcp_tools/const.py
+++ b/custom_components/ha_mcp_tools/const.py
@@ -6,8 +6,8 @@
 DOMAIN = "ha_mcp_tools"
 
 # Allowed directories for file operations (relative to config dir)
-ALLOWED_READ_DIRS = ["www", "themes", "custom_templates", "dashboards"]
-ALLOWED_WRITE_DIRS = ["www", "themes", "custom_templates", "dashboards"]
+ALLOWED_READ_DIRS = ["www", "themes", "custom_templates", "dashboards", "packages"]
+ALLOWED_WRITE_DIRS = ["www", "themes", "custom_templates", "dashboards", "packages"]
 
 # Files allowed for managed YAML editing
 ALLOWED_YAML_CONFIG_FILES = ["configuration.yaml"]
@@ -32,6 +32,9 @@
         "notify",
         "group",
         "utility_meter",
+        "device_tracker",
+        "automation",
+        "script",
     }
 )
 
@@ -52,6 +55,14 @@
         "post_action": "reload_available",
         "reload_service": "group.reload",
     },
+    "automation": {
+        "post_action": "reload_available",
+        "reload_service": "automation.reload",
+    },
+    "script": {
+        "post_action": "reload_available",
+        "reload_service": "script.reload",
+    },
 }
 # Default for keys not in YAML_KEY_POST_ACTIONS:
 YAML_KEY_DEFAULT_POST_ACTION = {"post_action": "restart_required"}

--- a/src/ha_mcp/tools/tools_filesystem.py
+++ b/src/ha_mcp/tools/tools_filesystem.py
@@ -40,7 +40,7 @@
     "custom_components/**/*.py",
 ]
 
-WRITABLE_DIRS = ["www", "themes", "custom_templates", "dashboards"]
+WRITABLE_DIRS = ["www", "themes", "custom_templates", "dashboards", "packages"]
 
 
 def is_filesystem_tools_enabled() -> bool:
@@ -93,11 +93,11 @@
             Field(
                 description=(
                     "Relative directory path from config directory. "
-                    "Allowed paths: www/, themes/, custom_templates/, dashboards/. "
+                    "Allowed paths: www/, themes/, custom_templates/, dashboards/, packages/. "
                     "Example: 'www/' or 'themes/my_theme'"
                 ),
             ),
         ],
@@ -107,7 +107,7 @@
     ) -> dict[str, Any]:
         """List files in a directory within the Home Assistant config directory.
 
-        Lists files in allowed directories (www/, themes/, custom_templates/, dashboards/) with
+        Lists files in allowed directories (www/, themes/, custom_templates/, dashboards/, packages/) with
         optional glob pattern filtering. Returns file names, sizes, and modification times.
 
         **Allowed Directories:**
@@ -115,6 +115,7 @@
         - `themes/` - Theme files
         - `custom_templates/` - Jinja2 template files
         - `dashboards/` - YAML-mode dashboard files
+        - `packages/` - Package configuration files
 
         **Security:** Only directories in the allowed list can be accessed.

Related Issues/PRs

• [FEATURE] scoped file management for YAML-mode dashboards and configuration.yaml #1034 - Related to YAML-mode dashboard validation which follows a similar pattern.

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

Can you give some specific examples of what you're trying to do with the device tracker may be template only? There are some cases still that require templates and direct yaml but they're few and far between, and often have workarounds. I won't be able to tell you for sure though without a concrete example.

As for the todo stuff, we have tools specific for the todo list that should be working fine. If they aren't working properly then please ask your AI to use the ha report issue tool after you've used the todo tool and it failed to work, then submit the issue here, the. we can see what we can do to Improve the tools.

Also what AI and model are you using? Some behavior can be from poor agent behavior. Our tools are mostly optimized for use with Claude, but we're trying to make them more friendly to other AIs as well.

[kingpanther13]

@VPelt I'm going to go ahead and close this and convert this to a discussion, since the functionality you are asking for exists in our beta/dev server. If I'm wrong or if you are looking for something else then please feel free to reopen an issue.

I'd still like those examples of what you're trying to build too please, that way I can either show you how it's possible using helpers instead of templates, or you can show me that I'm wrong lol one way or the other... If I'm wrong then I'll reconsider doing a very limited version of the yaml writing tool on the stable version to only write to packages folder.

[VPelt]

For todo:
I want a dashboard that displays single todo iteams. I've got sensors like this to get at the data. Otherwise i seem only to be able to get the todo-list as whole todolist
But i want dashboard entries like "display the single last completed item"

template:
  - trigger:
      - trigger: time_pattern
        seconds: "20"
    action:
      - action: todo.get_items
        data:
          status: needs_action
        target:
          entity_id:
            - todo.kanban_backlog
        response_variable: action_response
    sensor:
      - name: Backlog items
        unique_id: backlog_items
        state: "{{ now().isoformat() }}"
        attributes:
          tasks: "{{ action_response['todo.kluslijst']['items'] }}"

for my devicde tracker i got something like this

template:
  - trigger:
      - platform: state
        entity_id: input_select.presence_detection_kid_override

    device_tracker:
      - name: "Kid Presence"
        unique_id: kkid_presence
        state: >
         {% set override = states('input_select.presence_detection_kid_override') %}

          {% if override == 'Home' %}
            home
          {% elif override == 'Away' %}
            away
          {% else %}
            {{ states('device_tracker.some_phone) }}
          {% endif %}

[VPelt]

also i have a shell cleanup function that cleans up old images

shell_command:
  ############################
  # CLEANUP (OLDER THAN 7 DAYS)
  ############################
  # REQUIREMENTS:
  # - Delete doorbell snapshots older than 7 days
  # - Prevent disk usage growth
  # - Only affect doorbell files
  cleanup_doorbell: >
    find /config/www/doorbell -name "doorbell-*.jpg" -mtime +7 -delete

[kingpanther13]

Tested both of your template examples on my live HA — both can be done without templates using UI-configured tools.

Device tracker override (no template needed):
Create an input_select helper with Auto/Home/Away options, then an automation triggered on changes to the input_select or your source device_tracker. Use a choose block to call the device_tracker.see service with the appropriate location_name:

• Home option → device_tracker.see with location_name: home
• Away option → device_tracker.see with location_name: not_home
• Auto → device_tracker.see with location_name: {{ states('device_tracker.your_phone') }} (template inside data.* is fine — that's not the same as a template-entity)

That produces a real device_tracker.kid_presence entity that participates in zones, person entities, etc. The device_tracker.see service does its own state-tracking on the backend (known_devices.yaml is HA-managed, not something you ever touch); nothing for you to maintain.

Todo single-item dashboard (no template needed):
Create an input_text helper per slot you want to display, then an automation triggered on a time pattern (or state change of the todo list) that calls todo.get_items with response_variable: result, then calls input_text.set_value with the item you want extracted from the response. Your dashboard reads the input_text helper directly. Same data flow as your trigger-based template sensor, but no template: block, fully UI-built.

I verified end-to-end on my own HA:

• input_select switched to Home → device_tracker = home
• switched to Away → device_tracker = not_home
• switched to Auto with source tracker home → device_tracker = home
• automation populated input_text with the actual last-completed item from my shopping list

Shell command: you're right that there's no clean UI alternative for shell_command:. That's still YAML-only.

Both helpers are creatable via the UI today (or via ha-mcp's ha_config_set_helper / ha_config_set_automation). I'd push back gently and say the two template cases you showed are solvable without packages-folder access — the shell_command is the one where you have a legitimate point.

[kingpanther13]

And again if you want to stick with yaml that's fine, you can switch to dev/master version to use the yaml editing tool, just keep in mind that it is very dangerous and is likely to cause problems, that's why I push doing it via UI so hard.

[VPelt]

An interesting side note

If I mention yaml in my chatgpt conversation it's smart enough to actually turn on the beta feature of ha-mcp and get yaml access

I believe it might be running any script it wants through advanced ssh & web terminal (an addon I have) which have init commands and if you 'use' that you can run any she'll or python script you want

Of course I pressed yes a few times on Homeassistant access but didn't realize until later that it turned on ha-mcp beta functionality

[kingpanther13]

Claude has done that to me before too with the ssh addon. That's why the filesystem/yaml tools require a totally different custom component to be installed, though with ssh it can still work around it. Tool security policies help with that as well.