ha-mcp-dev 8.7.0.dev3080__tar.gz → 9.0.0.dev3096__tar.gz

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.7.0.dev3080
+Version: 9.0.0.dev3096
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -46,8 +46,8 @@ Requires-Dist: uvicorn>=0.35 ; sys_platform != 'emscripten'
 Requires-Dist: watchfiles>=1.0.0
 Requires-Dist: httpx[socks]>=0.28.1,<0.29
 Requires-Dist: pydantic[email]>=2.13.4,<3
-Requires-Dist: python-dotenv==1.2.4
-Requires-Dist: truststore==0.10.4
+Requires-Dist: python-dotenv>=1.2.4,<2
+Requires-Dist: truststore>=0.10.4,<0.11
 Requires-Dist: cryptography>=48.0.0,<51
 Requires-Dist: pydantic-monty==0.0.18
 Requires-Dist: tzdata>=2024.1
@@ -94,7 +94,7 @@ Description-Content-Type: text/markdown
 
 ## 🚀 Get Started
 
-The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS, runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case, with no access token to manage.
+The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS, runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
 
 **Add it to Home Assistant via HACS (the preferred install):**
 
@@ -104,16 +104,17 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 
 1. Install the **HA-MCP Custom Component** from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp-integration` (category: **Integration**), then **Download**.
 2. **Restart Home Assistant.**
-3. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP Custom Component**, choose **HA-MCP Server**, and click **Submit**. Creating the entry starts the server.
-4. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure**) — it is also printed in the Home Assistant log. A notification confirms the server started and points you there.
-5. Paste that URL into your AI client — done.
+3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → **Security** → **Long-lived access tokens** → **Create token**; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under **Settings → People → Add person** with **Allow login**, **Local access only** and **Administrator** on. Never use your own login for the second option.
+4. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP Custom Component** and choose **HA-MCP Server**. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — **Remote access through Home Assistant** (start with **Secret URL**, the simplest; **Home Assistant sign-in** adds a login) and/or **Network access: Local network** — then click **Submit**. Both start disabled, so a client on another device needs one of them.
+5. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure**). A notification confirms the server started and points you there.
+6. Paste that URL into your AI client — done.
 
 **Connect URL.** The Configure screen gives you a Home Assistant webhook URL for remote clients — `https://<your-ha-domain>/api/webhook/<webhook-id>` through Nabu Casa or any reverse proxy already pointed at Home Assistant (locally, `http://<ha-host>:8123/api/webhook/<webhook-id>`). For clients on the same network, the server is also reachable directly at `http://<ha-ip>:9584/private_<random>`.
 
 - **Replaces other install methods:** the in-process server is a complete, standalone ha-mcp install — it takes the place of the app (add-on), Docker, and uvx/PyPI (stdio) methods. Run only one; do not run the in-process server alongside another install.
-- **Local only?** Turn off **Remote access via webhook** in the entry options — no webhook is registered at all, while the direct port and sidebar panel keep working.
+- **Local only?** Leave remote access disabled at setup (or turn off **Remote access via webhook** in the entry options) — no webhook is registered at all, while the direct port and sidebar panel keep working.
 - **Settings panel:** while the server runs, an admin-only **HA-MCP** panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
-- **Optional authentication:** set **Webhook authentication** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
+- **Optional authentication:** set **Authentication mode** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
 - **Manual install (no HACS):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
 
 The component's second entry type, the **File & YAML services entry** (**HA-MCP File & YAML Tools**), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, app, Docker, or stdio).

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/README.md

@@ -34,7 +34,7 @@
 
 ## 🚀 Get Started
 
-The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS, runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case, with no access token to manage.
+The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It installs into Home Assistant through HACS, runs the full server **in-process**, and works on **every** Home Assistant installation type — Home Assistant OS, Supervised, Container, and Core — with full feature parity. It is the easiest setup in every case: setup asks for an administrator access token and how clients may connect.
 
 **Add it to Home Assistant via HACS (the preferred install):**
 
@@ -44,16 +44,17 @@ The recommended way to run ha-mcp is the **HA-MCP Custom Component**. It install
 
 1. Install the **HA-MCP Custom Component** from HACS — click the badge above, or in HACS open **Integrations → ⋮ → Custom repositories**, add `https://github.com/homeassistant-ai/ha-mcp-integration` (category: **Integration**), then **Download**.
 2. **Restart Home Assistant.**
-3. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP Custom Component**, choose **HA-MCP Server**, and click **Submit**. Creating the entry starts the server.
-4. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure**) — it is also printed in the Home Assistant log. A notification confirms the server started and points you there.
-5. Paste that URL into your AI client — done.
+3. Decide which administrator account the server acts as. Either create a long-lived access token on your own account (your profile → **Security** → **Long-lived access tokens** → **Create token**; it works from anywhere if it leaks, and the server's changes show under your name), or, safer, create an account just for HA-MCP under **Settings → People → Add person** with **Allow login**, **Local access only** and **Administrator** on. Never use your own login for the second option.
+4. Go to **Settings → Devices & Services → Add Integration**, search for **HA-MCP Custom Component** and choose **HA-MCP Server**. Paste your token, or enter the user name and password of the account you made for HA-MCP (HA-MCP creates its token), pick how clients may connect — **Remote access through Home Assistant** (start with **Secret URL**, the simplest; **Home Assistant sign-in** adds a login) and/or **Network access: Local network** — then click **Submit**. Both start disabled, so a client on another device needs one of them.
+5. Copy the connect URL from the entry's **Configure** screen (**Settings → Devices & Services → HA-MCP Custom Component → HA-MCP Server → Configure**). A notification confirms the server started and points you there.
+6. Paste that URL into your AI client — done.
 
 **Connect URL.** The Configure screen gives you a Home Assistant webhook URL for remote clients — `https://<your-ha-domain>/api/webhook/<webhook-id>` through Nabu Casa or any reverse proxy already pointed at Home Assistant (locally, `http://<ha-host>:8123/api/webhook/<webhook-id>`). For clients on the same network, the server is also reachable directly at `http://<ha-ip>:9584/private_<random>`.
 
 - **Replaces other install methods:** the in-process server is a complete, standalone ha-mcp install — it takes the place of the app (add-on), Docker, and uvx/PyPI (stdio) methods. Run only one; do not run the in-process server alongside another install.
-- **Local only?** Turn off **Remote access via webhook** in the entry options — no webhook is registered at all, while the direct port and sidebar panel keep working.
+- **Local only?** Leave remote access disabled at setup (or turn off **Remote access via webhook** in the entry options) — no webhook is registered at all, while the direct port and sidebar panel keep working.
 - **Settings panel:** while the server runs, an admin-only **HA-MCP** panel appears in the Home Assistant sidebar for managing tools, feature flags, backups, and themes.
-- **Optional authentication:** set **Webhook authentication** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
+- **Optional authentication:** set **Authentication mode** to `ha_auth` to require a Home Assistant account sign-in instead of using the secret URL as the credential.
 - **Manual install (no HACS):** copy `custom_components/ha_mcp_tools/` from this repository into your Home Assistant `config/custom_components/` directory, then restart and add the integration as above.
 
 The component's second entry type, the **File & YAML services entry** (**HA-MCP File & YAML Tools**), is only needed if you enable ha-mcp's opt-in file and YAML editing tools (feature flags, off by default) — skip it otherwise; you can add it later at any time. It works with any server type (in-process, app, Docker, or stdio).

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.12.17,<0.13"]
+requires = ["uv_build>=0.12.17,<0.14"]
 build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3080"
+version = "9.0.0.dev3096"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"
@@ -59,8 +59,8 @@ dependencies = [
     "watchfiles>=1.0.0",
     "httpx[socks]>=0.28.1,<0.29",
     "pydantic[email]>=2.13.4,<3",
-    "python-dotenv==1.2.4",
-    "truststore==0.10.4",
+    "python-dotenv>=1.2.4,<2",
+    "truststore>=0.10.4,<0.11",
     "cryptography>=48.0.0,<51",
     "pydantic-monty==0.0.18",
     "tzdata>=2024.1",
@@ -273,6 +273,11 @@ filterwarnings = [
 
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
+version_variables = [
+    "custom_components/ha_mcp_tools/manifest.json:version",
+    "custom_components/ha_mcp_tools/manifest.json:ha-mcp",
+    "custom_components/ha_mcp_tools/const.py:COMPONENT_VERSION",
+]
 build_command = """
 pip install uv && uv lock
 git add uv.lock
@@ -319,6 +324,6 @@ dev = [
     "ruff>=0.12.12",
     "testcontainers>=4.13.0",
     "ast-grep-cli>=0.42.0",
-    "python-semantic-release==10.6.2",
+    "python-semantic-release==10.7.0",
     "hamcp-test-env",
 ]

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/pyproject.toml.orig

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["uv_build>=0.12.17,<0.13"]
+requires = ["uv_build>=0.12.17,<0.14"]
 build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.7.0.dev3080"
+version = "9.0.0.dev3096"
 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
@@ -67,8 +67,8 @@ dependencies = [
     # before raising these floors; standalone lock updates can move independently.
     "httpx[socks]>=0.28.1,<0.29",
     "pydantic[email]>=2.13.4,<3",
-    "python-dotenv==1.2.4",
-    "truststore==0.10.4",
+    "python-dotenv>=1.2.4,<2",
+    "truststore>=0.10.4,<0.11",
     # websockets is deliberately ABSENT from this list: ha-mcp ships its own
     # private copy (src/ha_mcp/_vendor/websockets, pinned in the vendor
     # requirements.txt and synced by scripts/vendor_websockets.py) and never
@@ -420,7 +420,7 @@ dev = [
     # Renders templates/CHANGELOG.md.j2 in test_changelog_template.py. Keep the
     # version equal to the action pinned in .github/workflows/semver-release.yml,
     # so the test renders with the release that writes the real notes.
-    "python-semantic-release==10.6.2",
+    "python-semantic-release==10.7.0",
     # Provides `uv run hamcp-test-env` without shipping it in the ha-mcp wheel.
     "hamcp-test-env",
 ]
@@ -431,6 +431,14 @@ hamcp-test-env = { path = "tests/test-env", editable = true }
 # Semantic versioning configuration
 [tool.semantic_release]
 version_toml = ["pyproject.toml:project.version"]
+# The HACS component shares the server's version and pins the server build it
+# ships with, so each release commit stamps all three below as well as
+# project.version (#2427).
+version_variables = [
+    "custom_components/ha_mcp_tools/manifest.json:version",
+    "custom_components/ha_mcp_tools/manifest.json:ha-mcp",
+    "custom_components/ha_mcp_tools/const.py:COMPONENT_VERSION",
+]
 build_command = """
 pip install uv && uv lock
 git add uv.lock

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/browser_landing.py

@@ -125,8 +125,8 @@ def register_browser_landing(mcp_instance: CustomRouteServer, path: str) -> bool
         # Any GET here is a non-MCP caller (browser, health check, proxy, or a
         # connector's SSE-style pre-flight) hitting this POST-only Streamable HTTP
         # endpoint, which answers 405 by design. Log one annotated line so the 405
-        # reads as expected.
-        logger.info("GET %s -> 405 (NORMAL for most non-SSE connections)", path)
+        # reads as expected. The path is left out: it is the secret path.
+        logger.info("GET -> 405 (NORMAL for most non-SSE connections)")
         return PlainTextResponse(
             LANDING_MESSAGE,
             status_code=405,

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/config.py

@@ -104,7 +104,7 @@ _settings: Settings | None = None
 
 # In-process (embedded) HA connection, set only when ha-mcp runs inside Home
 # Assistant core via the ha_mcp_tools custom component's in-process server entry.
-# The component hands the loopback URL + a provisioned admin token to ha-mcp
+# The component hands the loopback URL + the administrator's token to ha-mcp
 # THROUGH THIS DICT — never
 # via os.environ — so the admin token can't be read from the shared HA process
 # environment. Applied onto the Settings singleton in ``get_global_settings``.

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/errors.py

@@ -347,6 +347,18 @@ def create_connection_error(
     )
 
 
+# The in-process server (HA-MCP integration) runs with an administrator token
+# saved in its config entry (#2427), not a HOMEASSISTANT_TOKEN.
+_EMBEDDED_AUTH_INVALID_SUGGESTIONS: list[str] = [
+    "Home Assistant no longer accepts the administrator access token saved in "
+    + "the HA-MCP Server entry: it was revoked, or its account was deactivated "
+    + "or is no longer an administrator",
+    "Replace it under Settings -> Devices & services -> HA-MCP Server -> "
+    + "Configure -> Replace the administrator access token",
+    "Or reload the HA-MCP Server entry: it then stops the server and files a "
+    + "repair that asks for a new token",
+]
+
 # Authentication-error suggestions for Home Assistant add-on installs. On the
 # add-on the token is managed by the Supervisor, not a user-editable
 # HOMEASSISTANT_TOKEN, so the default "verify your token / create a long-lived
@@ -388,9 +400,11 @@ def create_auth_error(
         # Lazy import keeps this low-level module free of an import-time
         # dependency on ._version; is_running_in_addon reads SUPERVISOR_TOKEN
         # live so it reflects the current environment.
-        from ._version import is_running_in_addon
+        from ._version import is_embedded, is_running_in_addon
 
-        if is_running_in_addon():
+        if is_embedded():
+            suggestions = _EMBEDDED_AUTH_INVALID_SUGGESTIONS
+        elif is_running_in_addon():
             suggestions = _ADDON_AUTH_INVALID_SUGGESTIONS
 
     return create_error_response(

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/hacs_auto_refresh.py

@@ -3,10 +3,9 @@
 HACS refreshes a *custom* repository's release data from GitHub only about
 every 48 hours, and the ha_mcp_tools component ships in lockstep with each
 server release — so a freshly updated server can sit for two days next to a
-component update HACS has not noticed yet. The component's own nudge
-(``custom_components/ha_mcp_tools/hacs_nudge.py``) closes that gap only for the
-embedded server, which is where it runs; add-on, Docker, pip and stdio installs
-had no trigger at all. This module is that trigger, server-side.
+component update HACS has not noticed yet. This module closes that gap for
+add-on, Docker, pip and stdio installs. The embedded server is skipped: the
+component manages its updates.
 
 On startup, when the server version changed since the last recorded nudge (the
 just-updated case) or a newer release is pending, it sends HACS's "Update
@@ -44,9 +43,7 @@ from .utils.data_paths import get_data_dir
 logger = logging.getLogger(__name__)
 
 # The repository full_names HACS may track the ha_mcp_tools component under —
-# the dedicated mirror first, the legacy main-repo path second. Values are
-# duplicated from custom_components/ha_mcp_tools/const.py (HACS_MIRROR_ /
-# HACS_LEGACY_REPO_FULL_NAME): the server package cannot import the component.
+# the dedicated mirror first, the legacy main-repo path second.
 CANDIDATE_REPO_FULL_NAMES = (
     "homeassistant-ai/ha-mcp-integration",
     "homeassistant-ai/ha-mcp",
@@ -205,8 +202,7 @@ async def maybe_refresh_hacs_after_update() -> None:
     """Nudge HACS once per startup when the update picture changed."""
     try:
         if is_embedded():
-            # The component's own hacs_nudge already covers embedded installs;
-            # running both would double HACS's GitHub fetches.
+            # The component manages the embedded server's updates.
             return
         if is_update_check_disabled():
             return

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/policy/events.py

@@ -218,8 +218,8 @@ async def emit_approval_requested(
     approval signal needs the silence explained.
 
     ``POST /api/events/<type>`` works identically for every installation
-    method — the embedded component provisions the server a loopback URL
-    and an admin token, so there is no component-only path here.
+    method — the embedded component hands the server a loopback URL and an
+    administrator's token, so there is no component-only path here.
     """
     try:
         with anyio.move_on_after(EMIT_TIMEOUT_SECONDS) as scope:

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/server_lifespan.py

@@ -18,8 +18,8 @@ logger = logging.getLogger(__name__)
 async def warn_if_non_admin_token() -> None:
     """Ask Home Assistant about the configured token so a non-admin one is logged at startup (#2546)."""
     try:
-        # The embedded server provisions its own admin token; OAuth mode has
-        # no server-level token to ask about.
+        # The embedded component checks its token belongs to an active
+        # administrator on every start; OAuth mode has no server-level token.
         settings = get_global_settings()
         if is_embedded() or settings.homeassistant_token == OAUTH_MODE_TOKEN:
             return

{ha_mcp_dev-8.7.0.dev3080 → ha_mcp_dev-9.0.0.dev3096}/src/ha_mcp/settings_ui/__init__.py

@@ -26,6 +26,7 @@ from ..utils.data_paths import get_data_dir
 from ._handlers_advanced import build_advanced_handlers
 from ._handlers_backups import build_backups_handlers
 from ._handlers_fs import build_fs_handlers
+from ._handlers_oauth_callbacks import build_oauth_callback_handlers
 from ._handlers_server import (
     _PROCESS_INSTANCE_ID,
     _PROCESS_STARTED_AT,
@@ -493,6 +494,7 @@ def build_settings_handlers(
     handlers.update(build_backups_handlers(server))
     handlers.update(build_server_handlers(server, is_sidecar=is_sidecar))
     handlers.update(build_advanced_handlers(server))
+    handlers.update(build_oauth_callback_handlers(server))
 
     return handlers
 
@@ -592,6 +594,62 @@ def is_http_settings_mounted() -> bool:
     return _http_settings_mounted
 
 
+# Every settings route except the add-on-only root mount is defined once in
+# this table. register_settings_routes mounts it under each active prefix: at
+# root in add-on mode (so HA ingress can proxy localhost:9583/), and under the
+# secret path when one is set (Docker / standalone direct access); the stdio
+# sidecar mounts it too. Deriving every mount from one table keeps them from
+# drifting; the frontend uses relative fetches (./api/settings/...) so the
+# handlers work at any prefix.
+SETTINGS_ROUTES: tuple[tuple[str, list[str], str], ...] = (
+    ("/settings", ["GET"], "settings_page"),
+    ("/api/settings/tools", ["GET"], "get_tools"),
+    ("/api/settings/tools", ["POST"], "save_tools"),
+    ("/api/settings/restart", ["POST"], "restart_addon"),
+    ("/api/settings/info", ["GET"], "settings_info"),
+    ("/api/settings/features", ["GET"], "get_feature_flags"),
+    ("/api/settings/features", ["POST"], "save_feature_flags"),
+    # Theme / accessibility prefs (#1574 review) — server-side copy so
+    # they survive a stdio sidecar origin change (stable by default
+    # since #2131, but fresh on first spawn / lost ui.state / pin
+    # change / taken remembered port)
+    ("/api/settings/theme", ["GET"], "get_theme_prefs"),
+    ("/api/settings/theme", ["POST"], "save_theme_prefs"),
+    # Advanced settings endpoints
+    ("/api/settings/advanced", ["GET"], "get_advanced_settings"),
+    ("/api/settings/advanced", ["POST"], "save_advanced_settings"),
+    # Auto-backup endpoints (#1288)
+    ("/api/settings/backups", ["GET"], "list_backups"),
+    ("/api/settings/backups", ["DELETE"], "delete_backups_bulk"),
+    ("/api/settings/backups/{name}", ["GET"], "view_backup"),
+    ("/api/settings/backups/{name}/diff", ["GET"], "diff_backup"),
+    ("/api/settings/backups/{name}/restore", ["POST"], "restore_backup"),
+    ("/api/settings/backups/{name}", ["DELETE"], "delete_backup"),
+    ("/api/settings/backup-config", ["GET"], "get_backup_config"),
+    ("/api/settings/backup-config", ["POST"], "save_backup_config"),
+    # Custom filesystem directories (issue #1567) — component-owned list
+    ("/api/settings/fs-custom-paths", ["GET"], "get_fs_custom_paths"),
+    ("/api/settings/fs-custom-paths", ["POST"], "save_fs_custom_paths"),
+    # None-mode OAuth callback allowlist (#2427) — component-owned list
+    ("/api/settings/oauth-callbacks", ["GET"], "get_oauth_callbacks"),
+    ("/api/settings/oauth-callbacks", ["POST"], "save_oauth_callbacks"),
+    # Tool security policies endpoints
+    ("/api/policy/config", ["GET"], "policy_get_config"),
+    ("/api/policy/config", ["PUT"], "policy_put_config"),
+    ("/api/policy/pending", ["GET"], "policy_get_pending"),
+    ("/api/policy/approve", ["POST"], "policy_post_approve"),
+    ("/api/policy/deny", ["POST"], "policy_post_deny"),
+    ("/api/policy/decision-pin", ["GET"], "policy_get_decision_pin"),
+    ("/api/policy/decision-pin", ["POST"], "policy_post_decision_pin"),
+    ("/api/policy/decision-pin", ["DELETE"], "policy_delete_decision_pin"),
+    ("/api/policy/tool-schema", ["GET"], "policy_get_tool_schema"),
+    ("/api/policy/value-source", ["GET"], "policy_get_value_source"),
+    # Entity visibility filter endpoints (issue #1728)
+    ("/api/visibility/config", ["GET"], "visibility_get_config"),
+    ("/api/visibility/config", ["PUT"], "visibility_put_config"),
+)
+
+
 def register_settings_routes(
     mcp: FastMCP,
     server: HomeAssistantSmartMCPServer,
@@ -668,63 +726,11 @@ def register_settings_routes(
     # sidecar even when the prefix itself is not advertised (advertise_prefix=False).
     _http_settings_mounted = True
 
-    # Every route this function mounts except the add-on-only root mount is defined
-    # once in this table and mounted under each active prefix below: at root
-    # in add-on mode (so HA ingress can proxy localhost:9583/), and under the
-    # secret path when one is set (Docker / standalone direct access). A
-    # deployment hits either, both, or — guarded above — neither. Deriving
-    # the mounts from one table keeps them from drifting; the frontend uses
-    # relative fetches (./api/settings/...) so the handlers work at any prefix.
-    routes: list[tuple[str, list[str], str]] = [
-        ("/settings", ["GET"], "settings_page"),
-        ("/api/settings/tools", ["GET"], "get_tools"),
-        ("/api/settings/tools", ["POST"], "save_tools"),
-        ("/api/settings/restart", ["POST"], "restart_addon"),
-        ("/api/settings/info", ["GET"], "settings_info"),
-        ("/api/settings/features", ["GET"], "get_feature_flags"),
-        ("/api/settings/features", ["POST"], "save_feature_flags"),
-        # Theme / accessibility prefs (#1574 review) — server-side copy so
-        # they survive a stdio sidecar origin change (stable by default
-        # since #2131, but fresh on first spawn / lost ui.state / pin
-        # change / taken remembered port)
-        ("/api/settings/theme", ["GET"], "get_theme_prefs"),
-        ("/api/settings/theme", ["POST"], "save_theme_prefs"),
-        # Advanced settings endpoints
-        ("/api/settings/advanced", ["GET"], "get_advanced_settings"),
-        ("/api/settings/advanced", ["POST"], "save_advanced_settings"),
-        # Auto-backup endpoints (#1288)
-        ("/api/settings/backups", ["GET"], "list_backups"),
-        ("/api/settings/backups", ["DELETE"], "delete_backups_bulk"),
-        ("/api/settings/backups/{name}", ["GET"], "view_backup"),
-        ("/api/settings/backups/{name}/diff", ["GET"], "diff_backup"),
-        ("/api/settings/backups/{name}/restore", ["POST"], "restore_backup"),
-        ("/api/settings/backups/{name}", ["DELETE"], "delete_backup"),
-        ("/api/settings/backup-config", ["GET"], "get_backup_config"),
-        ("/api/settings/backup-config", ["POST"], "save_backup_config"),
-        # Custom filesystem directories (issue #1567) — component-owned list
-        ("/api/settings/fs-custom-paths", ["GET"], "get_fs_custom_paths"),
-        ("/api/settings/fs-custom-paths", ["POST"], "save_fs_custom_paths"),
-        # Tool security policies endpoints
-        ("/api/policy/config", ["GET"], "policy_get_config"),
-        ("/api/policy/config", ["PUT"], "policy_put_config"),
-        ("/api/policy/pending", ["GET"], "policy_get_pending"),
-        ("/api/policy/approve", ["POST"], "policy_post_approve"),
-        ("/api/policy/deny", ["POST"], "policy_post_deny"),
-        ("/api/policy/decision-pin", ["GET"], "policy_get_decision_pin"),
-        ("/api/policy/decision-pin", ["POST"], "policy_post_decision_pin"),
-        ("/api/policy/decision-pin", ["DELETE"], "policy_delete_decision_pin"),
-        ("/api/policy/tool-schema", ["GET"], "policy_get_tool_schema"),
-        ("/api/policy/value-source", ["GET"], "policy_get_value_source"),
-        # Entity visibility filter endpoints (issue #1728)
-        ("/api/visibility/config", ["GET"], "visibility_get_config"),
-        ("/api/visibility/config", ["PUT"], "visibility_put_config"),
-    ]
-
     def _mount(prefix: str, *, guard: bool = False) -> None:
         # guard=True wraps each handler in _ingress_only so the route only
         # answers HA ingress (the Supervisor) — used for the add-on root
         # mount, whose port 9583 is reachable without the MCP secret.
-        for path, methods, handler_key in routes:
+        for path, methods, handler_key in SETTINGS_ROUTES:
             handler = handlers[handler_key]
             if guard:
                 handler = _ingress_only(handler)

ha_mcp_dev-9.0.0.dev3096/src/ha_mcp/settings_ui/_handlers_oauth_callbacks.py

@@ -0,0 +1,198 @@
+"""OAuth callback allowlist route handlers for the settings UI (#2427).
+
+The in-process server's none-mode ``/authorize`` redirects only to callbacks
+on an allowlist the ha_mcp_tools component stores on its server entry. These
+handlers read and replace that list through the component's
+``ha_mcp_tools/oauth_callbacks`` commands, so the panel and the entry's
+Configure screen edit the same setting. Only the embedded server has the list;
+every other deployment reports it unavailable and the page hides the section.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse
+
+from .._version import is_embedded
+from ..client.rest_client import HomeAssistantCommandError, HomeAssistantError
+from ..errors import ErrorCode, create_error_response
+
+if TYPE_CHECKING:
+    from ..server import HomeAssistantSmartMCPServer
+
+logger = logging.getLogger(__name__)
+
+WS_OAUTH_CALLBACKS = "ha_mcp_tools/oauth_callbacks"
+WS_OAUTH_CALLBACKS_UPDATE = "ha_mcp_tools/oauth_callbacks_update"
+CAPABILITY = "oauth_callbacks"
+# Transport failures reaching the component; a command it ran and refused is
+# a HomeAssistantCommandError, answered separately.
+_REACH_ERRORS = (HomeAssistantError, OSError, TimeoutError)
+
+
+class _Unavailable(Exception):
+    """The list cannot be edited here; the message says why."""
+
+
+async def _component_command(
+    server: HomeAssistantSmartMCPServer, command: str, **fields: Any
+) -> dict[str, Any]:
+    """Run one allowlist command on the component and return its result.
+
+    The capability probe is strict: one that failed because Home Assistant was
+    unreachable surfaces as a reachability error to retry, not as a component
+    that lacks the commands.
+    """
+    from ..client.websocket_client import get_websocket_client
+    from ..tools.component_api import (
+        ComponentDiscoveryError,
+        component_supports,
+        get_component_caps,
+    )
+
+    client = server.client
+    try:
+        caps = await get_component_caps(client, strict=True)
+    except ComponentDiscoveryError as exc:
+        raise HomeAssistantError(str(exc)) from exc
+    if not component_supports(caps, CAPABILITY):
+        raise _Unavailable(
+            "This HA-MCP component cannot edit the callback list. Update the "
+            "HA-MCP integration in HACS."
+        )
+    ws = await get_websocket_client(
+        url=client.base_url,
+        token=client.token,
+        verify_ssl=getattr(client, "verify_ssl", None),
+    )
+    raw = await ws.send_command(command, **fields)
+    result = raw.get("result") if isinstance(raw, dict) else None
+    if not isinstance(result, dict):
+        raise _Unavailable("HA-MCP component returned an unexpected response.")
+    return result
+
+
+def _unavailable(reason: str | None) -> JSONResponse:
+    return JSONResponse({"success": True, "available": False, "reason": reason})
+
+
+async def _get_oauth_callbacks(
+    server: HomeAssistantSmartMCPServer | None, _: Request
+) -> JSONResponse:
+    """The allowlist in force; always 200, with ``available`` False when absent."""
+    if server is None or not is_embedded():
+        return _unavailable(None)
+    try:
+        result = await _component_command(server, WS_OAUTH_CALLBACKS)
+    except _Unavailable as exc:
+        return _unavailable(str(exc))
+    except HomeAssistantCommandError as exc:
+        return _unavailable(f"The HA-MCP component refused the request: {exc}")
+    except _REACH_ERRORS as exc:
+        logger.warning(
+            "oauth-callbacks GET could not reach ha_mcp_tools", exc_info=True
+        )
+        return _unavailable(f"Could not reach the HA-MCP component: {exc}")
+    return JSONResponse({"success": True, "available": True, **result})
+
+
+def _parse_change(body: Any) -> dict[str, Any] | None:
+    if not isinstance(body, dict):
+        return None
+    if "reset" in body and "allowlist" in body:
+        # The component's schema makes these exclusive; a body carrying both
+        # must not silently let reset win over the list it also sent.
+        return None
+    if body.get("reset") is True:
+        return {"reset": True}
+    allowlist = body.get("allowlist")
+    # Counted and length-checked by the component after normalizing, the same
+    # order Configure uses, so both writers accept the same lists.
+    if isinstance(allowlist, list) and all(isinstance(i, str) for i in allowlist):
+        return {"allowlist": allowlist}
+    return None
+
+
+async def _save_oauth_callbacks(
+    server: HomeAssistantSmartMCPServer | None, request: Request
+) -> JSONResponse:
+    """Replace the allowlist (``{"allowlist": [...]}``) or restore the default
+    (``{"reset": true}``). The change applies to the next sign-in."""
+    if server is None or not is_embedded():
+        return JSONResponse(
+            create_error_response(
+                ErrorCode.CONFIG_VALIDATION_FAILED,
+                "The OAuth callback list belongs to the server built into the "
+                "HA-MCP integration.",
+            ),
+            status_code=409,
+        )
+    try:
+        change = _parse_change(await request.json())
+    except (ValueError, TypeError):
+        change = None
+    if change is None:
+        return JSONResponse(
+            create_error_response(
+                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                "Send 'allowlist' as a list of URLs, or 'reset': true.",
+            ),
+            status_code=400,
+        )
+    try:
+        result = await _component_command(server, WS_OAUTH_CALLBACKS_UPDATE, **change)
+    except _Unavailable as exc:
+        return JSONResponse(
+            create_error_response(ErrorCode.SERVICE_CALL_FAILED, str(exc)),
+            status_code=409,
+        )
+    except HomeAssistantCommandError as exc:
+        return JSONResponse(
+            create_error_response(ErrorCode.VALIDATION_INVALID_PARAMETER, str(exc)),
+            status_code=400,
+        )
+    except _REACH_ERRORS as exc:
+        logger.warning(
+            "oauth-callbacks POST could not reach ha_mcp_tools", exc_info=True
+        )
+        return JSONResponse(
+            create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Could not reach the HA-MCP component: {exc}",
+            ),
+            status_code=502,
+        )
+    if not result.get("saved"):
+        return JSONResponse(
+            {
+                **create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "Nothing was saved. Each callback must be an https:// URL, "
+                    "or an http:// URL on 127.0.0.1, [::1] or localhost, without "
+                    "a user name, password or #fragment.",
+                ),
+                "invalid": result.get("invalid", []),
+            },
+            status_code=400,
+        )
+    return JSONResponse({"success": True, **result})
+
+
+def build_oauth_callback_handlers(
+    server: HomeAssistantSmartMCPServer | None,
+) -> dict[str, Any]:
+    """Construct the OAuth callback allowlist route handlers."""
+
+    async def get_oauth_callbacks(request: Request) -> JSONResponse:
+        return await _get_oauth_callbacks(server, request)
+
+    async def save_oauth_callbacks(request: Request) -> JSONResponse:
+        return await _save_oauth_callbacks(server, request)
+
+    return {
+        "get_oauth_callbacks": get_oauth_callbacks,
+        "save_oauth_callbacks": save_oauth_callbacks,
+    }