ha-mcp-dev 8.4.3.dev2642__tar.gz → 8.4.3.dev2645__tar.gz

{ha_mcp_dev-8.4.3.dev2642/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2645}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2642
+Version: 8.4.3.dev2645
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -408,6 +408,30 @@ For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`]
 
 ---
 
+### Read-only HTTP connections
+
+Append `/readonly` to the server's HTTP MCP endpoint to restrict that connection
+to the existing Read Only Mode while other clients keep normal access:
+
+```text
+Normal:     https://example.com/private_your_secret
+Read-only:  https://example.com/private_your_secret/readonly
+```
+
+OAuth and OIDC connections use the same login/provider: for example,
+`https://example.com/mcp/readonly`. No additional secret or server is required.
+Read-only connections hide write tools and block write calls, including calls
+through cached tools or search proxies. The global Read Only Mode setting still
+restricts both endpoints when enabled. Reconnect the client after changing its URL
+so it refreshes its tool list.
+
+This is a connection mode for automated agents, not a separate permission on the
+credential: the same credentials still work at the normal endpoint. Home Assistant
+webhook URLs also accept the suffix:
+`https://your-ha.example/api/webhook/<webhook-id>/readonly`. This requires the
+updated embedded integration or Webhook Proxy dev app (add-on), together with
+the updated MCP server.
+
 ## 🧪 Dev Channel
 
 Want early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/README.md

@@ -376,6 +376,30 @@ For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`]
 
 ---
 
+### Read-only HTTP connections
+
+Append `/readonly` to the server's HTTP MCP endpoint to restrict that connection
+to the existing Read Only Mode while other clients keep normal access:
+
+```text
+Normal:     https://example.com/private_your_secret
+Read-only:  https://example.com/private_your_secret/readonly
+```
+
+OAuth and OIDC connections use the same login/provider: for example,
+`https://example.com/mcp/readonly`. No additional secret or server is required.
+Read-only connections hide write tools and block write calls, including calls
+through cached tools or search proxies. The global Read Only Mode setting still
+restricts both endpoints when enabled. Reconnect the client after changing its URL
+so it refreshes its tool list.
+
+This is a connection mode for automated agents, not a separate permission on the
+credential: the same credentials still work at the normal endpoint. Home Assistant
+webhook URLs also accept the suffix:
+`https://your-ha.example/api/webhook/<webhook-id>/readonly`. This requires the
+updated embedded integration or Webhook Proxy dev app (add-on), together with
+the updated MCP server.
+
 ## 🧪 Dev Channel
 
 Want early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2642"
+version = "8.4.3.dev2645"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/src/ha_mcp/dashboard_screenshot/theme_guard.py

@@ -80,9 +80,9 @@ def _read_only_mode() -> bool:
     must know about it.
     """
     try:
-        from ..config import get_global_settings
+        from ..read_only import is_read_only
 
-        return bool(get_global_settings().read_only_mode)
+        return is_read_only()
     except Exception:  # pragma: no cover - settings must never break a read
         return False
 
@@ -423,12 +423,14 @@ class ThemeGuard:
                 "> General in the Home Assistant UI."
             )
         elif _read_only_mode():
+            from ..read_only import read_only_remedy_hint
+
             remedy = (
                 "Server Read Only Mode is on, so ha-mcp will not restore "
                 "it: captures keep running there, but every theme write is "
                 "blocked at call time. Restore it from that account's own "
-                "session, Profile > General in the Home Assistant UI, or "
-                "turn Read Only Mode off first."
+                "session, Profile > General in the Home Assistant UI. "
+                f"{read_only_remedy_hint()}"
             )
         else:
             remedy = (

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/src/ha_mcp/http_transport.py

@@ -1,4 +1,4 @@
-"""Default-off HTTP diagnostics and JSON responses for HA-MCP launchers."""
+"""Shared HTTP endpoint modes and transport options for HA-MCP launchers."""
 
 from __future__ import annotations
 
@@ -22,6 +22,28 @@ from .config import get_global_settings
 logger = logging.getLogger(__name__)
 
 
+def _get_route_path(scope: Scope) -> str:
+    """Local copy of ``starlette._utils.get_route_path`` (private API).
+
+    Strips a mount's ``root_path`` prefix from ``scope["path"]``, the same
+    prefix Starlette's own routers use to resolve a sub-app's route. Vendored
+    because the source module is private and a minor Starlette bump could
+    move or change it without notice; keep this in sync with upstream if
+    scope's routing fields ever change.
+    """
+    path: str = scope["path"]
+    root_path = scope.get("root_path", "")
+    if not root_path:
+        return path
+    if not path.startswith(root_path):
+        return path
+    if path == root_path:
+        return ""
+    if path[len(root_path)] == "/":
+        return path[len(root_path) :]
+    return path
+
+
 @dataclass
 class _DiagnosticLogLevel:
     """Shared ownership while HTTP app lifespans overlap during a restart."""
@@ -67,7 +89,7 @@ class HttpTransportFastMCP(FastMCP):
     """
 
     def http_app(self, *args: Any, **kwargs: Any) -> StarletteWithLifespan:
-        """Build the normal app, adding only explicitly enabled experiments."""
+        """Build the app with a readonly alias and optional transport experiments."""
         settings = get_global_settings()
         if settings.http_json_response:
             # FastMCP accepts json_response as its third positional argument.
@@ -89,7 +111,41 @@ class HttpTransportFastMCP(FastMCP):
                 args = (args[0], middleware, *args[2:])
             else:
                 kwargs["middleware"] = middleware
-        return super().http_app(*args, **kwargs)
+        app = super().http_app(*args, **kwargs)
+        if app.state.transport_type == "streamable-http":
+            app.add_middleware(ReadOnlyEndpoint, path=app.state.path)
+        return app
+
+
+class ReadOnlyEndpoint:
+    """Route the exact /readonly alias through the same authenticated MCP app.
+
+    This selects read-only behavior for a configured client connection; the
+    credential still works at the normal endpoint. Settings and other HTTP
+    routes are not aliased.
+    """
+
+    def __init__(self, app: ASGIApp, path: str) -> None:
+        self.app = app
+        self.path = path
+        self.readonly_path = f"{path.rstrip('/')}/readonly"
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if (
+            scope["type"] != "http"
+            or _get_route_path(scope).rstrip("/") != self.readonly_path
+        ):
+            await self.app(scope, receive, send)
+            return
+
+        from .read_only import read_only_request
+
+        route_path = _get_route_path(scope)
+        prefix = scope["path"][: -len(route_path)]
+        path = prefix + self.path
+        scope = {**scope, "path": path, "raw_path": path.encode("utf-8")}
+        with read_only_request():
+            await self.app(scope, receive, send)
 
 
 @dataclass

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/src/ha_mcp/read_only.py

@@ -1,7 +1,8 @@
 """Read-only mode — catalog filtering and call-time write blocking (#1569).
 
 When ``Settings.read_only_mode`` is on (Tools-tab toggle in the web UI,
-``read_only_mode`` addon option, or ``READ_ONLY_MODE`` env var):
+``read_only_mode`` addon option, or ``READ_ONLY_MODE`` env var), or the
+HTTP connection uses the ``/readonly`` endpoint:
 
 - ``ReadOnlyToolsTransform`` hides write-capable tools from the MCP
   catalog at list time, except the exempt mixed read/write tools in
@@ -14,6 +15,8 @@ When ``Settings.read_only_mode`` is on (Tools-tab toggle in the web UI,
 Both consult the live settings singleton per request, so flipping the
 toggle in standalone HTTP mode takes effect without a restart (addon
 and stdio modes pick it up on restart, like every other feature flag).
+The HTTP endpoint additionally restricts its own request context without
+changing the shared settings.
 
 A tool counts as write-capable when its ``readOnlyHint`` annotation is
 not ``True`` — the same fail-closed default the policy handlers and the
@@ -30,7 +33,9 @@ from __future__ import annotations
 
 import json
 import logging
-from collections.abc import Awaitable, Callable, Sequence
+from collections.abc import Awaitable, Callable, Iterator, Sequence
+from contextlib import contextmanager
+from contextvars import ContextVar
 from typing import TYPE_CHECKING, Any, NamedTuple, NoReturn
 
 from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
@@ -49,6 +54,41 @@ if TYPE_CHECKING:
 
 logger = logging.getLogger(__name__)
 
+_request_read_only: ContextVar[bool] = ContextVar(
+    "ha_mcp_request_read_only", default=False
+)
+
+
+def is_read_only() -> bool:
+    """Apply the global setting or the current HTTP endpoint's restriction."""
+    return get_global_settings().read_only_mode or _request_read_only.get()
+
+
+@contextmanager
+def read_only_request() -> Iterator[None]:
+    """Restrict this request and its nested tool calls without affecting others."""
+    token = _request_read_only.set(True)
+    try:
+        yield
+    finally:
+        _request_read_only.reset(token)
+
+
+def read_only_remedy_hint() -> str:
+    """User-facing guidance for lifting Read Only Mode.
+
+    Deliberately never names the ``/readonly`` endpoint suffix: #2433 wants
+    this restriction to hold even for an untrusted model that could talk a
+    user into dropping it. The global setting has no such escape-hatch risk,
+    so it stays nameable when it is the (or an) active source.
+    """
+    if get_global_settings().read_only_mode:
+        return (
+            "To allow changes, the user must turn off Read Only Mode in the "
+            "ha-mcp settings UI (Tools tab) or the add-on configuration."
+        )
+    return "This connection is read-only. If changes are needed, ask the user."
+
 
 class ReadOnlyExemption(NamedTuple):
     """One mixed read/write tool that stays enabled in read-only mode.
@@ -322,9 +362,7 @@ def _raise_read_only_error(
             suggestions=[
                 "Continue with read-only tools — searching, getting, and "
                 + "listing data all remain available.",
-                "If the user wants to allow changes, they must turn off "
-                + "Read Only Mode in the ha-mcp settings UI (Tools tab) or "
-                + "the add-on configuration.",
+                read_only_remedy_hint(),
             ],
             context=context,
         )
@@ -333,7 +371,7 @@ def _raise_read_only_error(
 
 def require_write_access(tool_name: str) -> None:
     """Reject direct tool execution while Read Only Mode is enabled."""
-    if get_global_settings().read_only_mode:
+    if is_read_only():
         _raise_read_only_error(tool_name)
 
 
@@ -346,7 +384,7 @@ class ReadOnlyToolsTransform(Transform):
     """
 
     async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
-        if not get_global_settings().read_only_mode:
+        if not is_read_only():
             return tools
         return [t for t in tools if read_only_visible(t)]
 
@@ -354,7 +392,7 @@ class ReadOnlyToolsTransform(Transform):
         self, name: str, call_next: GetToolNext, *, version: VersionSpec | None = None
     ) -> Tool | None:
         tool = await call_next(name, version=version)
-        if tool is None or not get_global_settings().read_only_mode:
+        if tool is None or not is_read_only():
             return tool
         return tool if read_only_visible(tool) else None
 
@@ -495,7 +533,7 @@ class ReadOnlyMiddleware(Middleware):
     async def on_call_tool(
         self, context: MiddlewareContext, call_next: CallNext
     ) -> Any:
-        if not get_global_settings().read_only_mode:
+        if not is_read_only():
             return await call_next(context)
 
         # RenamedToolAliasMiddleware runs ahead of this one and normally

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/src/ha_mcp/settings_ui/locales/zh-Hans.json

@@ -467,7 +467,7 @@
     "advanced.code_mode_saved_tools_path.label": "已保存工具路径",
     "advanced.code_mode_saved_tools_path.help": "用于在重启间持久化自定义工具的 JSON 文件。需重启。",
     "advanced.extra_yaml_write_keys.label": "额外的 YAML 可写键",
-    "advanced.extra_yaml_write_keys.help": "以逗号分隔的顶层键：除内置键外，ha_config_set_yaml 还可写入这些键，适用于本安装中以 YAML 为主的集成（例如 alert2）。重新定义 Home Assistant 自身信任边界的键始终无法添加，会被忽略。需要自定义组件 1.2.4 或更高版本。",
+    "advanced.extra_yaml_write_keys.help": "此安装中面向 YAML 优先的集成（例如 alert2）除内置键外，ha_config_set_yaml 还可写入的额外顶级键。每行输入一个键或用逗号分隔键。重新定义 Home Assistant 自身信任边界的键永远无法添加且将被忽略。需要自定义组件 1.2.4 或更新版本。",
     "advanced.sidecar_pin_port.label": "设置界面旁路服务端口",
     "advanced.sidecar_pin_port.help": "0 会在首次启动时选择一个空闲端口，并在后续重启中保留该端口；1024–65535 会固定一个首选端口（如果被占用，则回退到空闲端口）。需要重启。",
     "advanced.enable_dev_mode.label": "开发者模式",

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/src/ha_mcp/tools/tools_search.py

@@ -4265,15 +4265,15 @@ class SearchTools:
 
         # Surface Read Only Mode after projection so the flag survives any
         # fields= filter.
-        if get_global_settings().read_only_mode:
+        from ..read_only import is_read_only, read_only_remedy_hint
+
+        if is_read_only():
             projected["read_only_mode"] = True
             projected["read_only_mode_hint"] = (
                 "Read Only Mode is ON: write-capable tools are disabled and "
                 "all write or destructive operations are blocked "
-                "server-side. You can search, read, and analyze freely. To "
-                "allow changes, the user must turn off Read Only Mode in "
-                "the ha-mcp settings UI (Tools tab) or the add-on "
-                "configuration."
+                "server-side. You can search, read, and analyze freely. "
+                f"{read_only_remedy_hint()}"
             )
 
         # Surface the MCP server's own update status after projection.

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645}/src/ha_mcp/transforms/categorized_search.py

@@ -276,9 +276,9 @@ def _execute_via(proxy: str, tool_name: str) -> str:
 
 def _read_only_mode() -> bool:
     """Whether Read Only Mode is on — consulted per request, like its filter."""
-    from ..config import get_global_settings
+    from ..read_only import is_read_only
 
-    return bool(get_global_settings().read_only_mode)
+    return is_read_only()
 
 
 def _advertised_routes(name: str, category: Capability) -> list[Capability]:

{ha_mcp_dev-8.4.3.dev2642 → ha_mcp_dev-8.4.3.dev2645/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2642
+Version: 8.4.3.dev2645
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -408,6 +408,30 @@ For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`]
 
 ---
 
+### Read-only HTTP connections
+
+Append `/readonly` to the server's HTTP MCP endpoint to restrict that connection
+to the existing Read Only Mode while other clients keep normal access:
+
+```text
+Normal:     https://example.com/private_your_secret
+Read-only:  https://example.com/private_your_secret/readonly
+```
+
+OAuth and OIDC connections use the same login/provider: for example,
+`https://example.com/mcp/readonly`. No additional secret or server is required.
+Read-only connections hide write tools and block write calls, including calls
+through cached tools or search proxies. The global Read Only Mode setting still
+restricts both endpoints when enabled. Reconnect the client after changing its URL
+so it refreshes its tool list.
+
+This is a connection mode for automated agents, not a separate permission on the
+credential: the same credentials still work at the normal endpoint. Home Assistant
+webhook URLs also accept the suffix:
+`https://your-ha.example/api/webhook/<webhook-id>/readonly`. This requires the
+updated embedded integration or Webhook Proxy dev app (add-on), together with
+the updated MCP server.
+
 ## 🧪 Dev Channel
 
 Want early access to new features and fixes? Dev releases (`.devN`) are published on every push to master.