fix: tolerate read-only filesystem when locating tool config (#1125)

`:latest` crashed at startup under hardened Docker setups (`read_only: true`,
`user: 1000:1000`) because `_get_config_path()` did an unconditional
`mkdir(parents=True, exist_ok=True)` on `Path.home() / ".ha-mcp"`. Two
contributing factors:

1. The Dockerfile didn't set `ENV HOME`, so under `USER mcpuser` Docker
   left `HOME=/`. `Path.home()` resolved to `/`, ha-mcp tried to mkdir
   `/.ha-mcp`, and `read_only: true` made that fatal (issue #1125).
2. Even on writable filesystems this silently polluted the container's
   filesystem root with a `/.ha-mcp/` directory.

Three coordinated changes:

- `settings_ui.py`: honor `HA_MCP_CONFIG_DIR` env var, and wrap the
  home-dir mkdir in `try/except OSError` so we fall back to a tmpdir
  path instead of crashing. Mirrors the existing pattern in
  `utils/usage_logger.py:120-127`.
- `Dockerfile`: set `ENV HOME=/home/mcpuser` so `Path.home()` resolves
  correctly when running as the default user (default-user setups now
  persist settings to `~/.ha-mcp` instead of `/.ha-mcp`).
- `Dockerfile`: chmod `/home/mcpuser` to 0755 so users that override
  `--user UID:GID` can still stat the directory; otherwise FastMCP's
  startup version-check raises `PermissionError` on
  `~/.local/share/fastmcp/version_cache.json`.

Verified locally with three Docker scenarios: bondskin's hardened compose
(`--read-only --user 1000:1000 --tmpfs /tmp`), default user, and
`HA_MCP_CONFIG_DIR=/data/ha-mcp` bind-mount. Server starts cleanly in all
three; original stack trace from #1125 no longer reproduces.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: amccats3409

Dockerfile

@@ -31,8 +31,13 @@ LABEL org.opencontainers.image.title="Home Assistant MCP Server" \
       org.opencontainers.image.licenses="MIT" \
       io.modelcontextprotocol.server.name="io.github.homeassistant-ai/ha-mcp"
 
-# Create non-root user for security
-RUN groupadd -r mcpuser && useradd -r -g mcpuser -m mcpuser
+# Create non-root user for security. /home/mcpuser is mode 0755 (instead of
+# the useradd default 0700) so users that override `--user UID:GID` can still
+# stat the home dir — otherwise FastMCP's startup version-check raises
+# PermissionError on Path.home()/.local/share/fastmcp/version_cache.json.
+RUN groupadd -r mcpuser \
+    && useradd -r -g mcpuser -m mcpuser \
+    && chmod 0755 /home/mcpuser
 
 WORKDIR /app
 
@@ -43,6 +48,12 @@ COPY --chown=mcpuser:mcpuser fastmcp.json fastmcp-http.json ./
 
 USER mcpuser
 
+# Set HOME explicitly. Docker doesn't auto-derive HOME from /etc/passwd when
+# a USER directive is set (moby/moby#2968), leaving HOME=/ at runtime. That
+# made Path.home() resolve to "/" and ha-mcp tried to mkdir "/.ha-mcp" on
+# every start — fatal under `read_only: true` (issue #1125).
+ENV HOME=/home/mcpuser
+
 # Activate virtual environment via PATH
 ENV PATH="/app/.venv/bin:$PATH"
 

src/ha_mcp/settings_ui.py

@@ -12,6 +12,7 @@
 import json
 import logging
 import os
+import tempfile
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -112,12 +113,62 @@ def _is_addon() -> bool:
 
 
 def _get_config_path() -> Path:
-    """Return the path to the tool config JSON file."""
+    """Return the path to the tool config JSON file.
+
+    Priority:
+    1. ``HA_MCP_CONFIG_DIR`` env var — explicit override, e.g. for hardened
+       Docker setups bind-mounting a writable volume into a ``read_only: true``
+       container.
+    2. ``/data/tool_config.json`` — Home Assistant add-on (writable supervisor
+       data dir).
+    3. ``~/.ha-mcp/tool_config.json`` — standard. Falls back to
+       ``<tempdir>/ha-mcp/tool_config.json`` when the home dir can't be
+       created (read-only filesystem, or ``HOME`` unset so ``Path.home()``
+       resolves to ``/``). The fallback loses persistence across restarts
+       but lets the server start; users wanting persistence should set
+       ``HA_MCP_CONFIG_DIR``.
+    """
+    config_dir_env = os.environ.get("HA_MCP_CONFIG_DIR")
+    if config_dir_env:
+        custom_dir = Path(config_dir_env)
+        try:
+            custom_dir.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            logger.warning(
+                "HA_MCP_CONFIG_DIR=%s is not writable; tool config will not persist.",
+                custom_dir,
+            )
+        return custom_dir / "tool_config.json"
+
     if _is_addon():
         return Path("/data") / "tool_config.json"
+
     home_dir = Path.home() / ".ha-mcp"
-    home_dir.mkdir(parents=True, exist_ok=True)
-    return home_dir / "tool_config.json"
+    try:
+        home_dir.mkdir(parents=True, exist_ok=True)
+        return home_dir / "tool_config.json"
+    except OSError:
+        # Home is unwritable — typically a Docker container with
+        # `read_only: true` (issue #1125) or one where USER is set without
+        # ENV HOME so Path.home() resolves to "/". Fall back to a tmpdir
+        # path so the server still starts.
+        fallback = Path(tempfile.gettempdir()) / "ha-mcp"
+        try:
+            fallback.mkdir(parents=True, exist_ok=True)
+        except OSError:
+            logger.warning(
+                "Tool config fallback dir %s is also not writable; "
+                "settings persistence is disabled.",
+                fallback,
+            )
+        logger.warning(
+            "Cannot write tool config to %s (read-only filesystem or HOME unset). "
+            "Falling back to %s — settings will NOT persist across restarts. "
+            "Set HA_MCP_CONFIG_DIR to a writable path for persistence.",
+            home_dir,
+            fallback,
+        )
+        return fallback / "tool_config.json"
 
 
 def load_tool_config(settings: Settings | None = None) -> dict[str, Any]:
@@ -166,7 +217,9 @@ def save_tool_config(config: dict[str, Any]) -> None:
         logger.exception("Failed to save tool config to %s", path)
 
 
-async def _get_tool_metadata(server: HomeAssistantSmartMCPServer) -> list[dict[str, Any]]:
+async def _get_tool_metadata(
+    server: HomeAssistantSmartMCPServer,
+) -> list[dict[str, Any]]:
     """Extract metadata for all registered tools from the server.
 
     Uses FastMCP's internal ``local_provider._list_tools()`` because the
@@ -196,14 +249,16 @@ async def _get_tool_metadata(server: HomeAssistantSmartMCPServer) -> list[dict[s
         title = getattr(tool, "title", None) or tool.name
         if tool.annotations and getattr(tool.annotations, "title", None):
             title = tool.annotations.title
-        tools.append({
-            "name": tool.name,
-            "title": title,
-            "description": (tool.description or "")[:200],
-            "tags": tags,
-            "primary_tag": primary,
-            "annotations": annotations,
-        })
+        tools.append(
+            {
+                "name": tool.name,
+                "title": title,
+                "description": (tool.description or "")[:200],
+                "tags": tags,
+                "primary_tag": primary,
+                "annotations": annotations,
+            }
+        )
 
     # Inject stub entries for feature-gated tools that aren't registered
     registered_names = {t["name"] for t in tools}
@@ -215,15 +270,17 @@ async def _get_tool_metadata(server: HomeAssistantSmartMCPServer) -> list[dict[s
             stub_annotations["readOnlyHint"] = True
         if meta.get("destructiveHint") == "true":
             stub_annotations["destructiveHint"] = True
-        tools.append({
-            "name": name,
-            "title": meta["title"],
-            "description": meta["description"],
-            "tags": [meta["primary_tag"]],
-            "primary_tag": meta["primary_tag"],
-            "annotations": stub_annotations,
-            "disabled_by": meta["disabled_by"],
-        })
+        tools.append(
+            {
+                "name": name,
+                "title": meta["title"],
+                "description": meta["description"],
+                "tags": [meta["primary_tag"]],
+                "primary_tag": meta["primary_tag"],
+                "annotations": stub_annotations,
+                "disabled_by": meta["disabled_by"],
+            }
+        )
 
     tools.sort(key=lambda t: (t["primary_tag"], t["name"]))
     return tools
@@ -271,7 +328,8 @@ def apply_tool_visibility(
     return pinned_names
 
 
-_SETTINGS_HTML = """\
+_SETTINGS_HTML = (
+    """\
 <!DOCTYPE html>
 <html lang="en">
 <head>
@@ -434,8 +492,12 @@ def apply_tool_visibility(
   }
 }
 
-const DEFAULT_PINNED = """ + json.dumps(list(DEFAULT_PINNED_TOOLS)) + """;
-const MANDATORY = """ + json.dumps(list(MANDATORY_TOOLS)) + """;
+const DEFAULT_PINNED = """
+    + json.dumps(list(DEFAULT_PINNED_TOOLS))
+    + """;
+const MANDATORY = """
+    + json.dumps(list(MANDATORY_TOOLS))
+    + """;
 
 function getState(name) {
   if (toolStates[name]) return toolStates[name];
@@ -672,6 +734,7 @@ def apply_tool_visibility(
 </body>
 </html>
 """
+)
 
 
 def register_settings_routes(
@@ -766,15 +829,18 @@ async def _save_tools(request: Request) -> JSONResponse:
         pinned_count = sum(1 for s in states.values() if s == "pinned")
         logger.info(
             "Saved tool config (restart required to apply): %d disabled, %d pinned",
-            disabled_count, pinned_count,
+            disabled_count,
+            pinned_count,
         )
 
-        return JSONResponse({
-            "success": True,
-            "disabled": disabled_count,
-            "pinned": pinned_count,
-            "restart_required": True,
-        })
+        return JSONResponse(
+            {
+                "success": True,
+                "disabled": disabled_count,
+                "pinned": pinned_count,
+                "restart_required": True,
+            }
+        )
 
     async def _restart_addon(_: Request) -> JSONResponse:
         token = os.environ.get("SUPERVISOR_TOKEN")
@@ -822,9 +888,11 @@ async def _restart_addon(_: Request) -> JSONResponse:
         return JSONResponse({"success": True, "message": "Restart initiated"})
 
     async def _settings_info(_: Request) -> JSONResponse:
-        return JSONResponse({
-            "is_addon": _is_addon(),
-        })
+        return JSONResponse(
+            {
+                "is_addon": _is_addon(),
+            }
+        )
 
     secret_prefix = secret_path.rstrip("/") if secret_path else ""
     is_addon = _is_addon()
@@ -856,7 +924,15 @@ async def _settings_info(_: Request) -> JSONResponse:
         # endpoint. The frontend uses relative fetches (./api/settings/...)
         # so the JS works at either prefix unchanged.
         mcp.custom_route(f"{secret_prefix}/settings", methods=["GET"])(_settings_page)
-        mcp.custom_route(f"{secret_prefix}/api/settings/tools", methods=["GET"])(_get_tools)
-        mcp.custom_route(f"{secret_prefix}/api/settings/tools", methods=["POST"])(_save_tools)
-        mcp.custom_route(f"{secret_prefix}/api/settings/restart", methods=["POST"])(_restart_addon)
-        mcp.custom_route(f"{secret_prefix}/api/settings/info", methods=["GET"])(_settings_info)
+        mcp.custom_route(f"{secret_prefix}/api/settings/tools", methods=["GET"])(
+            _get_tools
+        )
+        mcp.custom_route(f"{secret_prefix}/api/settings/tools", methods=["POST"])(
+            _save_tools
+        )
+        mcp.custom_route(f"{secret_prefix}/api/settings/restart", methods=["POST"])(
+            _restart_addon
+        )
+        mcp.custom_route(f"{secret_prefix}/api/settings/info", methods=["GET"])(
+            _settings_info
+        )

tests/src/unit/test_settings_ui.py

@@ -142,15 +142,88 @@ class TestConfigPath:
 
     def test_addon_path_when_supervisor_token_set(self, monkeypatch):
         monkeypatch.setenv("SUPERVISOR_TOKEN", "fake")
+        monkeypatch.delenv("HA_MCP_CONFIG_DIR", raising=False)
         assert _get_config_path() == Path("/data/tool_config.json")
 
     def test_home_path_when_no_supervisor_token(self, monkeypatch, tmp_path):
         monkeypatch.delenv("SUPERVISOR_TOKEN", raising=False)
+        monkeypatch.delenv("HA_MCP_CONFIG_DIR", raising=False)
         monkeypatch.setattr(Path, "home", lambda: tmp_path)
         result = _get_config_path()
         assert result == tmp_path / ".ha-mcp" / "tool_config.json"
         assert (tmp_path / ".ha-mcp").is_dir()
 
+    def test_honors_ha_mcp_config_dir_env_var(self, monkeypatch, tmp_path):
+        """HA_MCP_CONFIG_DIR overrides the default location.
+
+        Lets users on read-only Docker setups bind-mount a writable directory
+        without relying on $HOME being set correctly. Takes precedence over
+        SUPERVISOR_TOKEN so add-on users can override too.
+        """
+        custom_dir = tmp_path / "custom"
+        monkeypatch.setenv("HA_MCP_CONFIG_DIR", str(custom_dir))
+        monkeypatch.setenv("SUPERVISOR_TOKEN", "fake")  # should be ignored
+        result = _get_config_path()
+        assert result == custom_dir / "tool_config.json"
+        assert custom_dir.is_dir()
+
+    def test_falls_back_to_tmpdir_when_home_unwritable(self, monkeypatch, tmp_path):
+        """When Path.home()/.ha-mcp can't be created (read-only fs / HOME=/),
+        fall back to a tmp dir instead of crashing."""
+        monkeypatch.delenv("SUPERVISOR_TOKEN", raising=False)
+        monkeypatch.delenv("HA_MCP_CONFIG_DIR", raising=False)
+        # Simulate Path.home() returning a path under a read-only filesystem.
+        readonly_home = tmp_path / "readonly-home"
+        readonly_home.mkdir()
+        monkeypatch.setattr(Path, "home", lambda: readonly_home)
+        # Force mkdir on the .ha-mcp dir to fail with a read-only OSError.
+        original_mkdir = Path.mkdir
+
+        def fake_mkdir(self: Path, *args, **kwargs):
+            if self == readonly_home / ".ha-mcp":
+                raise OSError(30, "Read-only file system")
+            return original_mkdir(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "mkdir", fake_mkdir)
+        # Direct the tmpdir fallback into tmp_path so we can assert location.
+        fallback_root = tmp_path / "fallback-tmp"
+        fallback_root.mkdir()
+        monkeypatch.setattr(
+            "ha_mcp.settings_ui.tempfile.gettempdir", lambda: str(fallback_root)
+        )
+
+        result = _get_config_path()
+
+        assert result == fallback_root / "ha-mcp" / "tool_config.json"
+        assert (fallback_root / "ha-mcp").is_dir()
+
+    def test_load_tool_config_does_not_crash_when_home_unwritable(
+        self, monkeypatch, tmp_path
+    ):
+        """Regression for #1125: server startup must not raise when the
+        home directory is read-only (e.g. Docker with read_only: true)."""
+        monkeypatch.delenv("SUPERVISOR_TOKEN", raising=False)
+        monkeypatch.delenv("HA_MCP_CONFIG_DIR", raising=False)
+        readonly_home = tmp_path / "readonly-home"
+        readonly_home.mkdir()
+        monkeypatch.setattr(Path, "home", lambda: readonly_home)
+        original_mkdir = Path.mkdir
+
+        def fake_mkdir(self: Path, *args, **kwargs):
+            if self == readonly_home / ".ha-mcp":
+                raise OSError(30, "Read-only file system")
+            return original_mkdir(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "mkdir", fake_mkdir)
+        fallback_root = tmp_path / "fallback-tmp"
+        fallback_root.mkdir()
+        monkeypatch.setattr(
+            "ha_mcp.settings_ui.tempfile.gettempdir", lambda: str(fallback_root)
+        )
+
+        # Must not raise, must return a usable dict.
+        assert load_tool_config() == {}
+
 
 class TestFeatureGatedTools:
     """Test the FEATURE_GATED_TOOLS dict aligns with the beta tag system."""
@@ -168,7 +241,12 @@ def test_filesystem_tools_use_addon_option_name(self):
         # disabled_by should reference the dev addon option name (matches
         # how the JS renders "set <code>{disabled_by}</code> in the dev
         # add-on config or the matching env var (see docs/beta.md)").
-        for name in ("ha_list_files", "ha_read_file", "ha_write_file", "ha_delete_file"):
+        for name in (
+            "ha_list_files",
+            "ha_read_file",
+            "ha_write_file",
+            "ha_delete_file",
+        ):
             assert FEATURE_GATED_TOOLS[name]["disabled_by"] == "enable_filesystem_tools"
 
 
@@ -230,6 +308,7 @@ def decorator(fn):
                 if path == "/api/settings/tools" and "POST" in methods:
                     captured["save"] = fn
                 return fn
+
             return decorator
 
         mcp = MagicMock()
@@ -276,13 +355,17 @@ async def test_drops_garbage_state_values(self, monkeypatch, tmp_path):
         config_path = tmp_path / "tool_config.json"
         monkeypatch.setattr("ha_mcp.settings_ui._get_config_path", lambda: config_path)
         save = self._capture_handler(monkeypatch)
-        resp = await save(self._make_request({
-            "states": {
-                "ha_good_tool": "disabled",
-                "ha_bad_value": "not_a_real_state",
-                42: "disabled",  # non-string key
-            },
-        }))
+        resp = await save(
+            self._make_request(
+                {
+                    "states": {
+                        "ha_good_tool": "disabled",
+                        "ha_bad_value": "not_a_real_state",
+                        42: "disabled",  # non-string key
+                    },
+                }
+            )
+        )
         assert resp.status_code == 200
         saved = json.loads(config_path.read_text())
         assert saved["tools"] == {"ha_good_tool": "disabled"}