fix: survive read-only filesystems at startup (#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:

**Shared resolver** (`utils/data_paths.py`, new): single source of truth
for "where does ha-mcp write its persistent files". Priority:
1. `HA_MCP_CONFIG_DIR` env var — explicit override for hardened Docker
   setups bind-mounting a writable volume.
2. `/data` — Home Assistant add-on supervisor data dir.
3. `~/.ha-mcp` — standard.
4. `<tempdir>/ha-mcp` — last-resort fallback.

The result is memoized so the fallback warning emits once at startup
instead of on every save/load HTTP request. Replaces the previous
inconsistent ad-hoc resolution in two places (`settings_ui` and
`usage_logger`).

**`settings_ui`**: `_get_config_path` becomes a thin
`get_data_dir() / "tool_config.json"` wrapper. `load_tool_config`
replaces the `path.exists()` + `read_text()` two-step with a single
`try: read_text() except OSError:` — `Path.exists()` only swallows
ENOENT/ENOTDIR/EBADF/ELOOP, so EACCES (e.g. `HA_MCP_CONFIG_DIR` pointing
at an existing 0700 dir owned by another UID) would re-introduce the
same class of crash. `save_tool_config` returns `bool` so the
`_save_tools` HTTP route can return 500 when the write fails — the JS
already handles `!resp.ok` with "Save failed!", but it was never given
the chance.

**`usage_logger`**: switch the default log path from
`Path.home() / ".ha-mcp" / "logs"` to `get_data_dir() / "logs"`. Logs
now follow the same precedence as the settings-UI tool config — honors
`HA_MCP_CONFIG_DIR` so users with a bind-mount don't lose their logs,
lands in `/data/logs/` in add-on mode (the supervisor's persistent
location, was previously going to ephemeral `~/.ha-mcp/logs`).

**Dockerfile**: set `ENV HOME=/home/mcpuser` so `Path.home()` resolves
correctly under the default user. `chmod 0755 /home/mcpuser` because
the base image's `/etc/login.defs` sets `HOME_MODE=0700`; that's fine
when the container runs as mcpuser, but un-traversable when users
override `--user UID:GID` (the issue reporter does so) — anything that
stats a path under HOME then raises PermissionError. Mode 0755 keeps
write access restricted to mcpuser.

Tests: 9 new in `test_data_paths.py` and `test_settings_ui.py` covering
priority order, both fallback chains, memoization, the `load_tool_config`
EACCES regression guard, the `save_tool_config` bool contract, and the
500-on-save-failure HTTP path. Plus a `usage_logger` test verifying it
uses the shared resolver.

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

@@ -21,6 +21,7 @@
 
 from .errors import ErrorCode, create_error_response
 from .transforms import DEFAULT_PINNED_TOOLS
+from .utils.data_paths import get_data_dir
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -112,23 +113,36 @@ def _is_addon() -> bool:
 
 
 def _get_config_path() -> Path:
-    """Return the path to the tool config JSON file."""
-    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"
+    """Return the path to the tool config JSON file.
+
+    Delegates directory resolution to :func:`utils.data_paths.get_data_dir`,
+    which handles ``HA_MCP_CONFIG_DIR`` override, add-on ``/data``,
+    home-dir, and tmpdir fallback (memoized).
+    """
+    return get_data_dir() / "tool_config.json"
 
 
 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 {}
@@ -156,14 +170,23 @@ def load_tool_config(settings: Settings | None = None) -> dict[str, Any]:
     return {}
 
 
-def save_tool_config(config: dict[str, Any]) -> None:
-    """Persist tool config to disk."""
+def save_tool_config(config: dict[str, Any]) -> bool:
+    """Persist tool config to disk.
+
+    Returns True on success, False on failure (read-only filesystem,
+    permission denied, etc.). Caller is responsible for surfacing the
+    failure to the user — the HTTP route at ``_save_tools`` returns 500
+    so the UI's ``saveConfig`` shows "Save failed!" instead of the
+    misleading "Saved — restart required".
+    """
     path = _get_config_path()
     try:
         path.write_text(json.dumps(config, indent=2))
         logger.info("Saved tool config to %s", path)
+        return True
     except OSError:
         logger.exception("Failed to save tool config to %s", path)
+        return False
 
 
 async def _get_tool_metadata(server: HomeAssistantSmartMCPServer) -> list[dict[str, Any]]:
@@ -760,7 +783,19 @@ async def _save_tools(request: Request) -> JSONResponse:
 
         config = load_tool_config()
         config["tools"] = states
-        save_tool_config(config)
+        if not save_tool_config(config):
+            return JSONResponse(
+                create_error_response(
+                    ErrorCode.INTERNAL_ERROR,
+                    "Failed to persist tool config to disk",
+                    suggestions=[
+                        "Set HA_MCP_CONFIG_DIR to a writable path "
+                        "(common with read_only Docker setups)",
+                        "Check the server logs for the underlying OSError",
+                    ],
+                ),
+                status_code=500,
+            )
 
         disabled_count = sum(1 for s in states.values() if s == "disabled")
         pinned_count = sum(1 for s in states.values() if s == "pinned")

src/ha_mcp/utils/data_paths.py

@@ -0,0 +1,108 @@
+"""Resolve a writable directory for ha-mcp persistent data.
+
+Single source of truth for "where does ha-mcp write its files?" — used by
+both ``settings_ui`` (tool config) and ``usage_logger`` (rolling JSONL).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Cached resolved data directory. Populated on first ``get_data_dir()``
+# call so any warnings about unwritable dirs / fallback usage emit once
+# at startup rather than on every save/load HTTP request.
+_DATA_DIR_CACHE: Path | None = None
+
+
+def _is_addon() -> bool:
+    """Return True when running inside the Home Assistant add-on container.
+
+    Mirrors the convention in ``settings_ui.py`` of treating
+    ``SUPERVISOR_TOKEN`` as the add-on detector — more reliable than
+    checking for ``/data`` because some Docker setups have a ``/data``
+    directory that isn't the supervisor data dir.
+    """
+    return bool(os.environ.get("SUPERVISOR_TOKEN"))
+
+
+def get_data_dir() -> Path:
+    """Return a writable directory for ha-mcp persistent data (memoized).
+
+    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`` — Home Assistant add-on (writable supervisor data dir).
+    3. ``~/.ha-mcp`` — standard.
+    4. ``<tempdir>/ha-mcp`` — last-resort fallback when (1) and (3) fail
+       (read-only filesystem, or ``HOME`` unset so ``Path.home()`` resolves
+       to ``/``). Loses persistence across restarts but lets the server
+       start; users wanting persistence should set ``HA_MCP_CONFIG_DIR``.
+    """
+    global _DATA_DIR_CACHE
+    if _DATA_DIR_CACHE is None:
+        _DATA_DIR_CACHE = _resolve_data_dir()
+    return _DATA_DIR_CACHE
+
+
+def _resolve_data_dir() -> Path:
+    """Resolve the data directory; falls back if writes are blocked."""
+    config_dir_env = os.environ.get("HA_MCP_CONFIG_DIR")
+    preferred: Path | None = None
+    if config_dir_env:
+        custom_dir = Path(config_dir_env)
+        try:
+            custom_dir.mkdir(parents=True, exist_ok=True)
+            return custom_dir
+        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
+
+    if _is_addon():
+        return Path("/data")
+
+    if preferred is None:
+        home_dir = Path.home() / ".ha-mcp"
+        try:
+            home_dir.mkdir(parents=True, exist_ok=True)
+            return home_dir
+        except OSError:
+            preferred = home_dir
+
+    fallback = Path(tempfile.gettempdir()) / "ha-mcp"
+    try:
+        fallback.mkdir(parents=True, exist_ok=True)
+        logger.warning(
+            "Cannot write ha-mcp data to %s (read-only filesystem or HOME unset). "
+            "Falling back to %s — data 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; usage_logger disables itself) can degrade
+        # gracefully.
+        logger.warning(
+            "Cannot write ha-mcp data to %s or fallback %s (%s: %s); "
+            "persistence is disabled. "
+            "Set HA_MCP_CONFIG_DIR to a writable path for persistence.",
+            preferred,
+            fallback,
+            type(e).__name__,
+            e,
+        )
+    return fallback

src/ha_mcp/utils/usage_logger.py

@@ -13,6 +13,8 @@
 from queue import Queue
 from typing import Any
 
+from .data_paths import get_data_dir
+
 # Default ring buffer size - keeps last N entries in memory
 DEFAULT_RING_BUFFER_SIZE = 200
 
@@ -46,13 +48,15 @@ def emit(self, record: logging.LogRecord) -> None:
             return
 
         with self._lock:
-            self._logs.append({
-                "timestamp": datetime.now(UTC).isoformat(),
-                "level": record.levelname,
-                "logger": record.name,
-                "message": record.getMessage(),
-                "elapsed_seconds": round(elapsed, 2),
-            })
+            self._logs.append(
+                {
+                    "timestamp": datetime.now(UTC).isoformat(),
+                    "level": record.levelname,
+                    "logger": record.name,
+                    "message": record.getMessage(),
+                    "elapsed_seconds": round(elapsed, 2),
+                }
+            )
 
     def get_logs(self) -> list[dict[str, Any]]:
         """Get collected startup logs."""
@@ -115,9 +119,12 @@ def __init__(
         if log_file_path:
             self.log_file_path = Path(log_file_path)
         else:
-            # Use user's home directory by default to avoid read-only filesystem errors
-            # when running via uvx/npx which might have read-only CWD
-            self.log_file_path = Path.home() / ".ha-mcp" / "logs" / "mcp_usage.jsonl"
+            # Defer to the shared resolver so logs follow the same precedence
+            # as the settings-UI tool config (HA_MCP_CONFIG_DIR > /data >
+            # ~/.ha-mcp > tempdir). Avoids polluting the filesystem root when
+            # HOME is unset and avoids surprising users who bind-mount a
+            # writable volume via HA_MCP_CONFIG_DIR but find logs missing.
+            self.log_file_path = get_data_dir() / "logs" / "mcp_usage.jsonl"
 
         try:
             self.log_file_path.parent.mkdir(parents=True, exist_ok=True)