Filesystem tools (ha_read_file/ha_write_file/ha_list_files/ha_delete_file) not registered despite HAMCP_ENABLE_FILESYSTEM_TOOLS active and ha_mcp_tools component installed[BUG]

[xrichx]

💬 What Happened?

markdown## 🚨 Auto-Generated by ha_report_issue Tool

This template was auto-generated by the ha_report_issue tool.
All environment info and logs below were collected automatically.

---

📋 Bug Description

The filesystem tools (ha_read_file, ha_write_file, ha_list_files, ha_delete_file) never appear in the MCP tool list, even though the startup log confirms the feature flag fired and the required ha_mcp_tools custom component is installed and reporting a version.

🔄 Steps to Reproduce

1. Run ha-mcp as the Home Assistant add-on (v7.12.1) with HAMCP_ENABLE_FILESYSTEM_TOOLS=true set.
2. Confirm the ha_mcp_tools custom component is installed in HA (diagnostic_info reports component_version: 1.0.2).
3. Restart the add-on.
4. Connect an MCP client (Claude, via HTTP transport) and search/list available tools (including deferred tool-search).
5. Look for ha_read_file / ha_write_file / ha_list_files / ha_delete_file.

✅ Expected vs ❌ Actual Behavior

Expected:
Since the startup log explicitly states ha_mcp.tools.tools_filesystem: Filesystem tools enabled via feature flag, and the custom component is installed and active, the four filesystem tools should be discoverable/callable.

Actual:
None of the four filesystem tools are ever returned by tool discovery (tried multiple keyword variations: "filesystem", "read_file", "write_file", "list_directory", exact tool names). Every other tool module loaded in the same startup batch (yaml_config, mcp_component, etc.) is discoverable normally.

---

💬 Triggering Prompt & Tool Call

User prompt: "bearbeite die yaml datei über HAMCP_ENABLE_FILESYSTEM_TOOLS" (asked the agent to edit a blueprint YAML file directly using the filesystem tools, believing the feature flag was enabled)

Tool call(s):
tool_search(query="filesystem file read write edit config directory")
→ Loaded 5 tools — none were filesystem tools
tool_search(query="read_file write_file list_directory config path")
→ Loaded 15 tools — none were filesystem tools
tool_search(query="ha_read_file ha_write_file ha_list_files ha_delete_file")
→ Loaded 5 tools — none matched the literal names
ha_get_logs(source="error_log", search="filesystem", hours_back=2)
→ 0 matching lines
ha_report_issue(tool_call_count=16)
→ startup_logs contains:
"ha_mcp.tools.tools_filesystem: Filesystem tools enabled via feature flag"
diagnostic_info.component_version = "1.0.2" (custom component present)

---

🔧 Environment

• ha-mcp Version: 7.12.1
• Custom Component: 1.0.2
• Installation Method: addon
• MCP Transport: http
• MCP Client: Claude (Anthropic) — Claude Sonnet 5
• AI Model: Claude Sonnet 5 (Anthropic)
• Operating System: Linux 6.18.34-haos-raspi (aarch64)
• Python Version: 3.13.12
• Home Assistant Version: 2026.7.1
• Connection Status: Connected
• Entity Count: 272

---

⚙️ ha-mcp Configuration

• enable_websocket: True
• enable_dashboard_partial_tools: True
• enable_tool_search: False
• tool_search_max_results: 5
• enable_yaml_config_editing: True
• enable_code_mode: False
• enabled_tool_modules: all
• disabled_tools_count: 0
• pinned_tools_count: 0

---

🚀 Startup Logs (relevant excerpt)

+00.80s | INFO | ha_mcp.tools.tools_filesystem: Filesystem tools enabled via feature flag
+00.95s | INFO | ha_mcp.tools.tools_mcp_component: MCP tools installer enabled via feature flag
+01.26s | INFO | ha_mcp.tools.tools_yaml_config: YAML config editing tools enabled
+01.32s | INFO | ha_mcp.tools.registry: Auto-discovery registered tools from 40 modules

Note: enable_yaml_config_editing tools (a sibling beta feature) load and are discoverable fine — only the filesystem module's log line fires without producing discoverable tools.

💡 Additional Context

• No error is thrown anywhere — the log line implies success, but zero tools are registered from tools_filesystem.py.
• HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION also appears active (its installer-tool log line fired too), but ha_install_mcp_tools itself was also not discoverable via tool_search — possibly related/same root cause across both beta modules gated through tools_mcp_component.py.
• Suspect this may be specific to the enable_tool_search: False + Claude's own deferred tool_search combination — possibly the filesystem tools are registered against ha-mcp's internal search index (which is disabled) rather than exposed as directly discoverable MCP tools, in a way that differs from other beta modules.

📋 Copy-Paste from Conversation

bearbeite die yaml datei über HAMCP_ENABLE_FILESYSTEM_TOOLS
Klärte Unterschied zwischen Umgebungsvariable und aktivierbarem Tool

Das ist leider keine Option, die ich von hier aus umschalten kann: HAMCP_ENABLE_FILESYSTEM_TOOLS ist eine Server-seitige Umgebungsvariable für den HAC-MCP-Server selbst (also auf dem Rechner/Container, auf dem er läuft) – kein Tool, das ich in dieser Unterhaltung aufrufen kann.

Ich habe gerade nochmal in meiner Tool-Liste nachgesehen (tool_search nach Dateisystem-Funktionen) – aktuell sind mir keine Dateisystem-Tools (lesen/schreiben von Dateien auf deinem HA-Server) freigeschaltet, egal ob die Variable bei dir gesetzt ist oder nicht. Damit ich sie nutzen könnte, müsstest du:

    Auf dem Rechner, der den HAC-MCP-Server hostet, die Umgebungsvariable HAMCP_ENABLE_FILESYSTEM_TOOLS=true (oder wie auch immer sie bei dir heißt) setzen
    Den HAC-MCP-Server neu starten
    Danach die Verbindung hier in Claude neu verbinden/reconnecten, damit die neuen Tools in meiner Liste auftauchen

Falls du das gemacht hast und ich die Tools trotzdem nicht sehe, sag Bescheid – dann probiere ich tool_search erneut, falls sich meine Tool-Liste zwischenzeitlich aktualisiert hat.

Bis dahin bleibt der Weg über die HA-UI (Blueprint → „In YAML bearbeiten" → den input:-Block aus der Datei von eben einfügen) die zuverlässigste Lösung. Soll ich dir alternativ die komplette Blueprint-Datei (inkl. triggers:/actions:) zusammenstellen, damit du einfach alles auf einmal ersetzen kannst, statt nur den input:-Teil?

probiere tool_search erneut
Evaluierte theoretische Möglichkeiten, bestätigte aber fehlende direkte Lösung

Auch nach dem erneuten tool_search taucht kein Dateisystem-Tool auf – die verfügbaren HAC-MCP-Tools decken weiterhin nur Entities, Automationen, Scripts, Szenen, Helper, Dashboards, Add-ons, Backups, Updates etc. ab, aber keinen direkten Datei-Editor für /config/blueprints/....

Zwei ehrliche Optionen von hier aus:

    Add-on-Umweg: Falls du in Home Assistant ein Add-on wie „Studio Code Server" (VS Code im Browser) oder „File editor" installiert hast, könnte ich versuchen, dessen HTTP-API über ha_manage_addon (Proxy-Modus) anzusprechen, um die Datei zu lesen/schreiben. Das ist aber fragil und hängt davon ab, ob so ein Add-on bei dir läuft und welche API es genau bietet – sag mir, ob du eins installiert hast, dann probiere ich es.
    Der zuverlässige Weg bleibt die HA-UI mit der Datei, die ich dir vorhin erstellt habe (bewaesserung_blueprint_input_block.yaml) – copy-paste in „Blueprint → In YAML bearbeiten", 2 Minuten Aufwand.

Hast du eins der genannten Add-ons (Studio Code Server / File editor / Samba) am Laufen? Dann versuche ich Option 1.

check die logs, Filesystem tools enabled via feature flag sollte aktiviert sein
Thinking about checking logs and verifying filesystem tools feature flag activation

Es gibt ha_get_logs, damit kann ich in die MCP-Server-eigenen Logs schauen (über ha_report_issue, das recent_logs/startup_logs liefert) bzw. die HA-Logs durchsuchen. Ich prüfe beides:
Entwirren der Konfigurationstoggles und Filesystem-Tool-Aktivierung

Interessanter Fund in den Startup-Logs – dort steht tatsächlich:

ha_mcp.tools.tools_filesystem: Filesystem tools enabled via feature flag

Das Modul wird also serverseitig geladen. Lass mich gezielter danach suchen, wie die Tools heißen könnten:
Diagnosed Filesystem-Tool-Aktivierungsproblem trotz aktiviertem Flag

Guter Fund – die Logs bestätigen tatsächlich:

ha_mcp.tools.tools_filesystem: Filesystem tools enabled via feature flag

Das Modul wird beim Start geladen (ha-mcp v7.12.1, Add-on-Installation). Trotzdem taucht in meiner Tool-Liste über mehrfaches tool_search (auch mit sehr gezielten Begriffen wie "read_file", "write_file", "filesystem") kein einziges Filesystem-Tool auf. Der Config-Dump zeigt außerdem "disabled_tools_count": 0" und "enabled_tool_modules": "all" – serverseitig ist also nichts explizit deaktiviert.

Das ist eine echte Diskrepanz, die ich nicht auflösen kann: das Modul lädt laut Log, aber es registriert bei mir keine aufrufbaren Tools. Mögliche Ursachen, die nur du/dein Setup klären kann:

    Das Filesystem-Modul in ha-mcp 7.12.1 könnte nur einen Platzhalter/experimentellen Zustand haben (Log-Zeile ohne tatsächliche Tool-Registrierung — evtl. ein Bug in dieser Version)
    Es könnte eine zusätzliche Berechtigung/einen zusätzlichen Scope brauchen, der separat vom generellen Feature-Flag gesetzt wird
    Ein Neustart des ha-mcp-Add-ons nach dem Setzen des Flags könnte nötig sein, falls das noch nicht geschah

Ich würde vorschlagen, das direkt bei den ha-mcp-Machern zu prüfen: https://github.com/homeassistant-ai/ha-mcp/issues — das passt zu dem, was ha_report_issue mir als Vorlage angeboten hat. Falls du magst, kann ich dir daraus einen fertigen, anonymisierten Bug-Report zusammenstellen.

Ansonsten bleibt der YAML-Copy-Paste-Weg über die HA-UI weiterhin die zuverlässige Lösung für die Blueprint-Umstrukturierung.

erstelle einenen bug report
Investigated Komponenten-Abhängigkeiten und Konfigurationsanforderungen vor Fehlerbericht

Ich habe die Dokumentation gefunden – das erklärt vermutlich schon einiges. Laut den ha-mcp-Docs registrieren sich die Filesystem-Tools (ha_read_file, ha_write_file, ha_list_files, ha_delete_file) nur, wenn zusätzlich zum Feature-Flag auch die Custom Component "HA MCP Tools" Services-Entry in Home Assistant installiert und der ENABLE_BETA_FEATURES-Master-Flag aktiv ist. Lass mich gezielt nach den exakten Toolnamen suchen, bevor ich den Bug Report schreibe:
Analysierte Komponenten-Integration und identifizierte potenzielle Lösungsstrategie

Ich glaube, ich habe den eigentlichen Fehlerpunkt gefunden – aber das ist evtl. kein Bug, sondern fehlende Voraussetzung. Die Doku sagt: Die Filesystem-Tools brauchen zusätzlich die Custom Component ha_mcp_tools in Home Assistant selbst (nicht nur das Server-Flag). Und dein Log zeigte auch: „MCP tools installer enabled via feature flag" – das klingt nach dem Installer-Tool ha_install_mcp_tools. Lass mich das direkt suchen, bevor ich einen Bug Report schreibe – vielleicht lässt sich das Problem einfach lösen:
Verifizierte Komponente und orchestrierte strukturierten Bug-Report-Prozess

Wichtiger Fund: component_version: "1.0.2" in den Diagnosedaten zeigt, dass die Custom Component ha_mcp_tools bei dir bereits installiert und aktiv ist – die im Netz beschriebene Voraussetzung ("Component fehlt") trifft also nicht zu. Das Modul lädt, das Flag ist an, die Component ist da — trotzdem keine Tools. Das sieht nach einem echten Bug aus. Ich erstelle jetzt den Report.

[github-actions]

✅ Thanks for the report — this issue has enough information and has been added to the backlog.

🤖 Automated triage by Issue Bot

[kingpanther13]

The filesystem tools have absolutely nothing to do with our built in toolsearch. Did you enable the beta toggle in the web UI? If you can use the yaml tool then I'm assuming so.

What exact client are you using? Claude Desktop, claude.ai, Claude Code, etc? Did you refresh your MCP connector when you enabled the tools? You have to do that any time you make any changes to your tool list or Claude won't be able t see it. If you're using Claude desktop orClaude.ai there is an option to refresh the tool list in the connector settings or you can just simply disconnect and reconnect it, if it's claude code do /mcp and reconnect the mcp server.

[kingpanther13]

@xrichx please confirm if you refreshed your tool list or not on your AI client after you enabled these tools, that's the most likely problem here. It has nothing to do with ha-mcp toolsearch being disabled, that's just Claude making wild guesses.

[xrichx]

Hi @kingpanther13
I'm using claude.ai.
Yes the refresh of the MCP connectors did the trick, just had to add the blueprints path additionally to the Custom filesystem directories, now it works, thanks a lot!
sorry, i did follow a video that explains the steps, but this was not part of that video!

[kingpanther13]

No worries! It appears that the report issue tool really mislead Claude, so I think I might just add a simple hint to the report issue tool to remind users to refresh their tool list if they can't find a tool.