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.

Coordinated changes:

- `settings_ui.py::_resolve_config_path`: honor a new `HA_MCP_CONFIG_DIR`
  env var (explicit override for hardened Docker setups bind-mounting a
  writable volume), and wrap the home-dir mkdir in `try/except OSError` so
  we fall back to a tmpdir path instead of crashing. HA_MCP_CONFIG_DIR
  failure also chains into the tmpdir fallback (mirrors the home-dir
  branch's behavior). Result is memoized at module level via
  `_CONFIG_PATH_CACHE` so the warning emits once at startup, not on every
  save/load HTTP request.

- `settings_ui.py::load_tool_config`: replace the `path.exists()` /
  `read_text()` two-step with a single `try: read_text() except OSError:`.
  `Path.exists()` only swallows ENOENT/ENOTDIR/EBADF/ELOOP — EACCES
  propagates, which would re-introduce the same class of crash if
  `HA_MCP_CONFIG_DIR` pointed at a dir whose parent isn't traversable by
  the runtime UID.

- `Dockerfile`: set `ENV HOME=/home/mcpuser` so `Path.home()` resolves
  correctly under the default user (default-user setups now persist
  settings to `~/.ha-mcp` instead of `/.ha-mcp`).

- `Dockerfile`: `chmod 0755 /home/mcpuser`. The base image's
  `/etc/login.defs` sets `HOME_MODE=0700`; that's fine when the container
  runs as mcpuser, but un-traversable for users that override
  `--user UID:GID` (the issue reporter does so). Anything that stats a
  path under HOME (set above) then raises PermissionError. Making the
  dir mode 0755 keeps it traversable for any uid; write access stays
  restricted to mcpuser.

Tests: 5 unit tests in `TestConfigPath`:
- HA_MCP_CONFIG_DIR overrides SUPERVISOR_TOKEN
- Falls back to tmpdir when home is unwritable (#1125 regression)
- HA_MCP_CONFIG_DIR mkdir failure chains to tmpdir fallback
- load_tool_config doesn't crash when path's parent is unreadable
- Fallback warning emits once via module cache (no log spam)

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,14 @@ 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. The base image's HOME_MODE is 0700 — fine when running
+# as mcpuser, but it makes /home/mcpuser un-traversable when users override
+# `--user UID:GID` (the issue #1125 reporter does so). Any code that stats a
+# path under HOME (set below) then raises PermissionError. chmod 0755 makes
+# the dir traversable for any uid; write access stays restricted to mcpuser.
+RUN groupadd -r mcpuser \
+    && useradd -r -g mcpuser -m mcpuser \
+    && chmod 0755 /home/mcpuser
 
 WORKDIR /app
 
@@ -43,6 +49,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
 
@@ -111,24 +112,114 @@ def _is_addon() -> bool:
     return bool(os.environ.get("SUPERVISOR_TOKEN"))
 
 
-def _get_config_path() -> Path:
-    """Return the path to the tool config JSON file."""
+# Cached resolved config path. Populated on first ``_get_config_path()`` call;
+# any warnings about unwritable dirs / fallback usage emit once at startup
+# rather than on every save/load HTTP request.
+_CONFIG_PATH_CACHE: Path | None = None
+
+
+def _resolve_config_path() -> Path:
+    """Resolve the tool config JSON path, falling back if writes are blocked.
+
+    Priority:
+
+    1. ``HA_MCP_CONFIG_DIR`` env var — explicit override, e.g. for hardened
+       Docker setups that bind-mount 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.
+
+    If neither (1) nor (3) is writable (read-only filesystem, or ``HOME``
+    unset so ``Path.home()`` resolves to ``/``), falls back to
+    ``<tempdir>/ha-mcp/tool_config.json``. 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)
+            return custom_dir / "tool_config.json"
+        except OSError as e:
+            logger.warning(
+                "HA_MCP_CONFIG_DIR=%s could not be prepared (%s: %s); "
+                "falling back to a tmpdir.",
+                custom_dir,
+                type(e).__name__,
+                e,
+            )
+            preferred = custom_dir
+    else:
+        preferred = None
+
     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"
+
+    if preferred is None:
+        home_dir = Path.home() / ".ha-mcp"
+        try:
+            home_dir.mkdir(parents=True, exist_ok=True)
+            return home_dir / "tool_config.json"
+        except OSError:
+            preferred = home_dir
+
+    fallback = Path(tempfile.gettempdir()) / "ha-mcp"
+    try:
+        fallback.mkdir(parents=True, exist_ok=True)
+        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.",
+            preferred,
+            fallback,
+        )
+    except OSError as e:
+        # Even the tmpdir is unwritable. Return the path anyway so the
+        # caller's own try/except (save_tool_config wraps writes in
+        # try/except OSError) can handle it as a degraded-but-running mode.
+        logger.warning(
+            "Cannot write tool config to %s or fallback %s (%s: %s); "
+            "settings persistence is disabled. "
+            "Set HA_MCP_CONFIG_DIR to a writable path for persistence.",
+            preferred,
+            fallback,
+            type(e).__name__,
+            e,
+        )
+    return fallback / "tool_config.json"
+
+
+def _get_config_path() -> Path:
+    """Return the cached tool config JSON path (resolves on first call)."""
+    global _CONFIG_PATH_CACHE
+    if _CONFIG_PATH_CACHE is None:
+        _CONFIG_PATH_CACHE = _resolve_config_path()
+    return _CONFIG_PATH_CACHE
 
 
 def load_tool_config(settings: Settings | None = None) -> dict[str, Any]:
     """Load persisted tool config, seeding from env vars if no file exists."""
     path = _get_config_path()
-    if path.exists():
+    # ``Path.exists()`` only swallows ``ENOENT/ENOTDIR/EBADF/ELOOP``; an
+    # ``EACCES`` (e.g. ``HA_MCP_CONFIG_DIR`` pointing at a dir that exists
+    # but isn't readable by the runtime UID) propagates. Read directly and
+    # treat ``FileNotFoundError`` as "no config yet"; log other ``OSError``s.
+    try:
+        raw = path.read_text()
+    except FileNotFoundError:
+        raw = None
+    except OSError:
+        logger.warning("Cannot read tool config at %s", path)
+        raw = None
+
+    if raw is not None:
         try:
-            result: dict[str, Any] = json.loads(path.read_text())
+            result: dict[str, Any] = json.loads(raw)
             return result
-        except (OSError, json.JSONDecodeError):
-            logger.warning("Failed to read tool config from %s", path)
+        except json.JSONDecodeError:
+            logger.warning("Tool config at %s is not valid JSON; ignoring.", path)
 
     if settings is None:
         return {}

tests/src/unit/test_settings_ui.py

@@ -137,20 +137,192 @@ def test_empty_config_no_disable(self):
         mcp.disable.assert_not_called()
 
 
+@pytest.fixture(autouse=True)
+def _reset_config_path_cache():
+    """Clear the module-level resolved-path cache between tests."""
+    import ha_mcp.settings_ui as su
+
+    su._CONFIG_PATH_CACHE = None
+    yield
+    su._CONFIG_PATH_CACHE = None
+
+
 class TestConfigPath:
-    """Test _get_config_path uses SUPERVISOR_TOKEN, not /data heuristic."""
+    """Tests for _get_config_path priority order and fallbacks.
+
+    Priority: HA_MCP_CONFIG_DIR > SUPERVISOR_TOKEN/data > home > tmpdir.
+    """
 
     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_ha_mcp_config_dir_overrides_supervisor_token(self, monkeypatch, tmp_path):
+        """HA_MCP_CONFIG_DIR takes precedence even when SUPERVISOR_TOKEN is set.
+
+        Lets add-on users override the default ``/data`` location, and lets
+        hardened-Docker users bind-mount a writable volume without depending
+        on ``$HOME``.
+        """
+        custom_dir = tmp_path / "custom"
+        monkeypatch.setenv("HA_MCP_CONFIG_DIR", str(custom_dir))
+        monkeypatch.setenv("SUPERVISOR_TOKEN", "fake")  # would normally route to /data
+        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):
+        """Fall back to a tmpdir path when ``~/.ha-mcp`` can't be created.
+
+        Covers the issue #1125 scenario: ``read_only: true`` Docker, or
+        ``HOME=/`` so ``mkdir(/.ha-mcp)`` fails. The function must return
+        a usable path instead of crashing.
+        """
+        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)
+        )
+
+        result = _get_config_path()
+
+        assert result == fallback_root / "ha-mcp" / "tool_config.json"
+        assert (fallback_root / "ha-mcp").is_dir()
+
+    def test_ha_mcp_config_dir_unwritable_chains_to_tmpdir(
+        self, monkeypatch, tmp_path
+    ):
+        """HA_MCP_CONFIG_DIR mkdir failure chains to the tmpdir fallback.
+
+        Avoids returning a known-broken path and emitting an OSError on
+        every save. Mirrors the home-dir branch's fallback.
+        """
+        monkeypatch.delenv("SUPERVISOR_TOKEN", raising=False)
+        readonly_parent = tmp_path / "readonly-parent"
+        readonly_parent.mkdir()
+        broken_target = readonly_parent / "cannot-create"
+        original_mkdir = Path.mkdir
+
+        def fake_mkdir(self: Path, *args, **kwargs):
+            if self == broken_target:
+                raise OSError(30, "Read-only file system")
+            return original_mkdir(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "mkdir", fake_mkdir)
+        monkeypatch.setenv("HA_MCP_CONFIG_DIR", str(broken_target))
+        monkeypatch.setattr(Path, "home", lambda: tmp_path / "unused-home")
+        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()
+        assert not broken_target.exists()
+
+    def test_load_tool_config_does_not_crash_on_unreadable_config_dir(
+        self, monkeypatch, tmp_path
+    ):
+        """Regression for #1125 + the same-class follow-up bug.
+
+        When the resolved path's parent isn't traversable by the runtime
+        UID (e.g. ``HA_MCP_CONFIG_DIR`` pointing at an existing 0700 dir
+        owned by another user), ``Path.exists()`` would raise
+        ``PermissionError`` because ``EACCES`` is not in
+        ``pathlib._IGNORED_ERRNOS``. ``load_tool_config()`` must treat it
+        as "no config yet" instead of crashing.
+        """
+        monkeypatch.delenv("SUPERVISOR_TOKEN", raising=False)
+        monkeypatch.delenv("HA_MCP_CONFIG_DIR", raising=False)
+        unreadable_dir = tmp_path / "unreadable"
+        unreadable_dir.mkdir()
+        monkeypatch.setattr(Path, "home", lambda: tmp_path / "unused-home")
+        # Stub _get_config_path directly to point at the unreadable dir,
+        # avoiding having to make the real os.chmod call (which is racy
+        # and platform-specific).
+        cfg_path = unreadable_dir / "tool_config.json"
+        monkeypatch.setattr(
+            "ha_mcp.settings_ui._get_config_path", lambda: cfg_path
+        )
+
+        original_read = Path.read_text
+
+        def fake_read_text(self: Path, *args, **kwargs):
+            if self == cfg_path:
+                raise PermissionError(13, "Permission denied")
+            return original_read(self, *args, **kwargs)
+
+        monkeypatch.setattr(Path, "read_text", fake_read_text)
+
+        # Must not raise.
+        assert load_tool_config() == {}
+
+    def test_warning_emitted_only_once_via_module_cache(
+        self, monkeypatch, tmp_path, caplog
+    ):
+        """The fallback warning must emit once, not on every call.
+
+        ``_get_config_path`` is invoked from every save/load HTTP request;
+        without the module-level cache the same warning would spam logs
+        on every UI toggle.
+        """
+        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)
+        )
+
+        import logging
+
+        with caplog.at_level(logging.WARNING, logger="ha_mcp.settings_ui"):
+            for _ in range(5):
+                _get_config_path()
+
+        fallback_warnings = [
+            r for r in caplog.records if "Falling back" in r.getMessage()
+        ]
+        assert len(fallback_warnings) == 1, (
+            f"expected single fallback warning, got {len(fallback_warnings)}"
+        )
+
 
 class TestFeatureGatedTools:
     """Test the FEATURE_GATED_TOOLS dict aligns with the beta tag system."""