feat: web-based settings UI for per-tool enable/disable/pin

[kingpanther13]

What does this PR do?

Adds a self-contained web settings page for configuring per-tool enable/disable/pin states. Served directly by the FastMCP HTTP server, works across all installation methods (add-on, Docker, standalone).

Context: Discussed with @julienld in #857 — he suggested using the built-in FastMCP HTTP server to expose a configuration UI that works across all installation methods rather than relying on HAOS add-on config.yaml schema. This PR implements that approach.

UI features

• Grouped by category — tools organized by their primary tag (Device Registry, HACS, System, etc.) with collapsible groups
• Two toggles per tool — separate enabled and pinned switches. Pinned is grayed out when a tool is disabled.
• Per-group master toggle — enable/disable all non-mandatory tools in a group with one click
• Search/filter — live search across tool names and titles
• Badges — mandatory, read-only, destructive labels per tool
• Feature-gated tool stubs — beta tools (ha_config_set_yaml, the four filesystem tools, ha_install_mcp_tools) appear in the list with a stub note pointing at docs/beta.md whether or not they are currently registered. Their toggles are locked because they require the underlying feature flag.
• Mandatory tool protection — ha_search_entities, ha_get_overview, ha_get_state, ha_report_issue shown with mandatory badge and locked toggles
• Pinning note — banner explaining that pinning only applies when tool search is enabled
• Dark theme matching HA aesthetic
• Open state persistence — expanded groups stay open across re-renders after toggle changes
• Built-in restart button — when running as an add-on, a "Restart Add-on" button appears in the save notice that calls the Supervisor API (POST /addons/self/restart) to apply changes with one click

Endpoints and where they mount

The settings UI uses FastMCP custom routes, which bypass FastMCP's auth middleware. To match the auth-by-obscurity model the rest of the server uses for HTTP modes, routes are mounted under the MCP secret path (/<secret_path>/...) so HTTP clients need the same secret to reach the UI as they do to reach the MCP endpoint itself. In add-on mode the routes are also mounted at root so HA ingress (which proxies localhost:9583/) can serve the "Open Web UI" button.

Path	Add-on	Docker / standalone	stdio
/ and /settings	✅ (HA ingress)	❌	not registered
/<secret_path>/settings	✅ (direct port access)	✅	not registered
/api/settings/tools (GET / POST)	✅	❌	not registered
/<secret_path>/api/settings/tools (GET / POST)	✅	✅	not registered
/api/settings/restart (POST)	✅ (only succeeds with SUPERVISOR_TOKEN)	n/a	not registered
/api/settings/info (GET)	✅	n/a	not registered

If neither SUPERVISOR_TOKEN nor a secret path is available, register_settings_routes logs a warning and registers nothing rather than expose the routes publicly.

Persistence and apply model

• Changes save to /data/tool_config.json (add-on) or ~/.ha-mcp/tool_config.json (standalone) on every toggle. The path is selected by SUPERVISOR_TOKEN presence, not by /data directory existence (matches the rest of the file).
• Changes require restart to apply — runtime mcp.disable() calls accumulate transforms unreliably; startup-time apply via _apply_settings_visibility() is the clean path. Disabled tools are fully removed from the MCP tool list on next startup.
• Seeds from DISABLED_TOOLS/PINNED_TOOLS env vars on first run (backwards-compatible with existing env var config).
• Safety toggles (enable_yaml_config_editing, enable_tool_search, enable_skills, etc.) remain in the dev add-on config page as source of truth. AND-semantics: a beta-gated tool is enabled only when the safety toggle is on and the UI hasn't disabled it.

Beta tool integration (post-#942)

After #942 and #1030 formalized the beta-channel system, beta-tagged tools (ha_config_set_yaml, ha_list_files, ha_read_file, ha_write_file, ha_delete_file, ha_install_mcp_tools) only register when their feature flag is set. The settings UI injects stub entries for the unregistered ones so users can see the tool exists and how to enable it; the stub points at docs/beta.md which covers both the dev-channel toggle and the env-var path.

Add-on integration

• ingress: true + ingress_port: 9583 + ingress_stream: true on homeassistant-addon-dev/config.yaml — shows the "Open Web UI" button on the add-on info page
• Dev add-on config page gains disabled_tools and pinned_tools text fields (seed/fallback for users who don't want the web UI) plus tool_search_max_results (range-validated 2-10 in both Pydantic and the addon schema)
• homeassistant-addon/ (stable channel) config.yaml is intentionally untouched — these are dev-only options for now, matching the existing convention for beta features. homeassistant-addon/start.py is modified because the dev add-on shares it via COPY in homeassistant-addon-dev/Dockerfile; it reads the new options with safe defaults so the stable add-on keeps working unchanged.

Tool search max results wired through

tool_search_max_results (2-10, default 5) now actually flows into CategorizedSearchTransform(max_results=...) instead of the previous hardcoded 5. Pydantic enforces the range; the dev addon schema uses int(2,10)? so the supervisor UI rejects out-of-range values before they reach env vars.

Closes #798

Type of change

• 🐛 Bug fix
• ✨ New feature
• 📚 Documentation
• 🔧 Maintenance/refactor
• 💥 Breaking change

Testing

• I have tested these changes with a LLM agent
• All automated tests pass (uv run pytest)
• Code follows style guidelines (uv run ruff check)

Checklist

• I have updated documentation if needed

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the Home Assistant MCP server by adding a self-contained web-based settings interface. This allows users to dynamically manage tool visibility and pinning directly through their browser, improving usability across various deployment environments like Docker and Home Assistant Add-ons. The changes ensure that tool configurations are persisted and applied immediately, while maintaining safety constraints for critical system tools.

Highlights

• Web-based Settings UI: Introduced a new /settings endpoint that provides a graphical interface for managing MCP tool states (enabled, disabled, or pinned) without requiring a server restart.
• Persistence and Configuration: Added support for persisting tool visibility settings to a tool_config.json file, with backward compatibility for existing DISABLED_TOOLS and PINNED_TOOLS environment variables.
• Safety and Mandatory Tools: Implemented safety mechanisms to prevent the disabling of mandatory tools and integrated existing configuration toggles into the new UI flow.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a web-based settings UI at /settings to manage MCP tool visibility (enabling, disabling, and pinning tools) without requiring a server restart. It includes new configuration fields in Settings, logic for persisting these choices to a tool_config.json file, and unit tests for the persistence and visibility logic. Several improvements are needed regarding adherence to repository standards: error responses must use the structured format from errors.py, imports should be consolidated to avoid duplication of constants like DEFAULT_PINNED_TOOLS, and exception handling should be narrowed from broad Exception blocks to specific types like OSError or json.JSONDecodeError. Additionally, a brittle file path used for metadata lookup should be addressed to ensure reliability across different installation environments.

[kingpanther13]

✅ All Gemini comments addressed in 0089c27:

• Structured error responses: POST endpoint now returns {"success": false, "error": {"code": "...", "message": "..."}} format
• Import DEFAULT_PINNED_TOOLS: Now imported from ha_mcp.transforms instead of duplicating
• Specific exceptions: Changed except Exception to except (OSError, json.JSONDecodeError) and except OSError throughout
• Brittle tools.json path: Added _find_tools_json() that checks multiple candidate paths, with runtime fallback to FastMCP tool manager if file not found

[kingpanther13]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a web-based settings UI at /settings to manage MCP tool visibility (enabling, disabling, and pinning tools) across different installation methods. It includes updates to the Home Assistant add-on configuration, documentation, and startup scripts to support these new visibility settings and a tool search result limit. Feedback focuses on adhering to the project's structured error response format, improving type hinting for settings, avoiding brittle private method access in FastMCP, and validating user-provided configuration before persistence.

[kingpanther13]

✅ All Gemini review feedback addressed in 9c6e8de:

• Structured errors: REST endpoints (/api/settings/tools, /api/settings/restart) now use create_error_response / ErrorCode from errors.py
• States validation: client-supplied tool states are validated (string keys, allowed state values) before persisting
• Settings type hint: settings parameter typed as Settings via TYPE_CHECKING import
• _user_pinned_tools: now initialized in __init__, accessed directly instead of getattr
• _list_tools() private API: added clearer docstring explaining why the unfiltered list is needed (public list_tools() filters disabled tools, settings UI needs to show them so users can re-enable)

[Patch76]

Hey @kingpanther13 — ran my Claude over this PR with my current review filters as a sanity-check pass; these are my 2 cents on top of what's already in the thread. Solid feature overall, the apply-on-restart model is the right call and the Gemini round was thoroughly addressed. I have two items I'd want resolved before merge plus a handful of smaller ones; happy to be talked out of any of them.

Verdict

Two HIGH items (one auth-surface question, one orphaned setting), one MEDIUM bug (POST handler crashes on non-dict body), plus a small batch of MEDIUM/LOW items and a couple of Boy-Scout opportunities. Nothing architectural.

---

Blockers

G1 — /api/settings/* routes have no auth in non-ingress deployments (HIGH)

File: src/ha_mcp/settings_ui.py:628-752, mounting via mcp.custom_route(...)

In add-on installs (the primary path) this is fine — HA's ingress proxy authenticates before forwarding. The concern is the other deployment paths:

• mcp.custom_route(...) registers Starlette routes on _additional_http_routes, stitched into the Starlette app outside the auth middleware. RequireAuthMiddleware (in FastMCP's server/http.py) only wraps the streamable-http path, not custom routes.
• In ha-mcp-web Docker / standalone HTTP / OAuth-tunnel mode, anyone who can reach the listening port can POST /api/settings/tools and disable any non-mandatory tool, or POST /api/settings/restart and bounce the add-on (this one only succeeds when SUPERVISOR_TOKEN is set, but the surface is still there).

Two reasonable resolutions:

• Refuse to register the routes when SUPERVISOR_TOKEN is unset (settings UI = add-on-only feature, matches the existing assumption that the restart endpoint already only works in add-on mode).
• Or gate the routes behind the same auth the MCP endpoint uses (mount under the secret path, or check Authorization).

If you want to keep the routes unconditional, please add a clear note in DOCS.md / .env.example so a Docker user understands what they're standing up.

G2 — tool_search_max_results setting is wired through everything except the actual transform (HIGH)

Files: src/ha_mcp/config.py:122, src/ha_mcp/server.py:484, homeassistant-addon-dev/{config.yaml,translations/en.yaml,DOCS.md}, .env.example:39-40, plus homeassistant-addon/start.py:113-152

Three problems here:

1. The setting is added everywhere except where it would have effect — _apply_tool_search() in server.py:484 still calls CategorizedSearchTransform(max_results=5, ...) with the literal 5. The new knob is dead code as shipped.
2. No range validation in Pydantic (config.py:122) despite the docstring claiming Range: 2-10 — the Field has no ge/le. Add-on schema (homeassistant-addon-dev/config.yaml:27) is also bare int?.
3. The setting is missing entirely from homeassistant-addon/config.yaml (stable channel) — even after this PR is fixed, stable users won't be able to configure it from their add-on UI.

Cleanest options: either pass max_results=self.settings.tool_search_max_results (with a Field(5, ge=2, le=10) and matching int(2,10)? schema in both add-on configs), or pull this setting out of the PR — it's somewhat tangential to the settings UI itself and feels like it sneaked in.

---

Findings

G3 — POST /api/settings/tools 500s on a non-dict JSON body (MEDIUM)

File: src/ha_mcp/settings_ui.py:666

body = await request.json()
...
raw_states = body.get("states", {})

A valid-JSON-but-non-object payload (null, [], "string", 42) raises AttributeError on body.get → 500 from Starlette. The validation block a few lines below catches a non-dict raw_states, but not a non-dict body. Add if not isinstance(body, dict) immediately after the parse, returning the same VALIDATION_INVALID_PARAMETER shape.

G4 — _get_config_path heuristic conflates "/data exists" with "running as add-on" (MEDIUM)

File: src/ha_mcp/settings_ui.py:85-92

data_dir = Path("/data")
if data_dir.exists():
    return data_dir / "tool_config.json"

The rest of the same module uses os.environ.get("SUPERVISOR_TOKEN") for add-on detection (lines 704, 751). This heuristic disagrees: any host with a /data directory (some Linux Docker setups, some macOS dev configs) writes the config there instead of ~/.ha-mcp/. Worse, if /data exists but is unwritable, save_tool_config silently logs and the user sees Save failed! with no obvious cause. Suggest using SUPERVISOR_TOKEN here too for consistency.

G5 — Tool metadata interpolated into HTML without escaping (MEDIUM)

File: src/ha_mcp/settings_ui.py:518-541

title, t.name, desc, disabledBy, and tag flow straight into innerHTML via JS template literals. Source is server-controlled today (tool docstrings + FEATURE_GATED_TOOLS), so this is not a live exploit — but the moment someone lands a docstring with < or &, the page breaks or executes attacker-supplied markup (e.g., a contributor copy-pasting an example with <entity_id> would render as a broken/ignored tag). Two cheap fixes: a small escapeHtml(s) helper applied to every interpolated value, or render via textContent/createElement instead of innerHTML.

G6 — Mandatory-tools list overlap is non-obvious (LOW)

File: src/ha_mcp/settings_ui.py:35-40 and src/ha_mcp/transforms/categorized_search.py:39-50

MANDATORY_TOOLS overlaps DEFAULT_PINNED_TOOLS by 3 of 4 entries (ha_search_entities, ha_get_overview, ha_report_issue). The fourth, ha_get_state, is mandatory but not pinned by default — intentional (it's reachable via ha_call_read_tool proxy when search is enabled), but worth a one-line comment so the next person editing either constant doesn't merge them or drift them.

G7 — FEATURE_GATED_TOOLS is incomplete (LOW)

File: src/ha_mcp/settings_ui.py:46-82

tools_mcp_component.py registers ha_install_mcp_tools behind HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION. With that flag off, the tool isn't in _list_tools() and isn't a stub here — users won't know it exists. Either add it to FEATURE_GATED_TOOLS, or document the truth-source as "we only stub the headline gated tools".

Also worth a # Keep in sync with tools_filesystem.py / tools_yaml_config.py / tools_mcp_component.py comment — gate strings and tool names live in two files now and a future rename will silently desync.

G8 — Per-restart enable transform layering (LOW / informational)

File: src/ha_mcp/settings_ui.py:237, src/ha_mcp/server.py:150

apply_tool_visibility calls mcp.enable(names=MANDATORY_TOOLS) unconditionally on every server boot. Each call appends a Visibility transform (FastMCP providers/base.py:518-565). In-memory only, so restart resets — harmless in practice, but if the apply ever moves to a hot-reload path (which the PR explicitly avoids and explains), it becomes a slow leak. A one-line "restart-only by design" comment guards the assumption.

G9 — if not enable_yaml_config_editing add is redundant (LOW)

File: src/ha_mcp/settings_ui.py:226-229

if not settings.enable_yaml_config_editing:
    disabled_names.add("ha_config_set_yaml")
else:
    disabled_names.discard("ha_config_set_yaml")

When enable_yaml_config_editing=False, tools_yaml_config.py:38-42 early-returns and the tool is never registered, so mcp.disable(names={"ha_config_set_yaml"}) is a no-op (FastMCP's disable doesn't validate names). The if not branch (line 227-228) is therefore redundant — drop it, or keep it as defense-in-depth and add a comment.

To be clear: the else: discard on line 229 is load-bearing — when the safety toggle is on and the user has saved "disabled" in tool_config.json, the discard strips it back out, force-enabling the tool. Don't drop the whole if/else.

(One question while we're here: is the safety-toggle-overrides-UI-toggle semantics intentional? A user might enable YAML editing in add-on config because they want it available, then disable the tool in the UI to keep it out of tool-search results — and the next restart re-enables it. If that's the intended hierarchy, fine; if not, worth a follow-up issue.)

G10 — _apply_settings_ui registers HTTP routes even in stdio mode (LOW)

File: src/ha_mcp/server.py:315-330, called unconditionally from _initialize_server at :150

In stdio transport, the custom routes are appended to _additional_http_routes but never reachable. Cost is trivial (a few Starlette Route objects), and apply_tool_visibility needs to run regardless of transport. I lean toward leaving it; a one-line comment that "routes are inert in stdio mode" closes the clarity nit if you want it.

---

Boy-Scout opportunities

G11 — PR body says homeassistant-addon/ is untouched, but the change is required

PR body line 56: "homeassistant-addon/ (stable channel) is intentionally untouched — it's updated automatically by the release pipeline". But homeassistant-addon/start.py is modified (lines 110-152) — and it has to be, because homeassistant-addon-dev/Dockerfile:31 does COPY homeassistant-addon/start.py /, so the dev add-on shares stable's start.py. The modification is functionally required for the new config keys to wire through in the dev channel.

Code is correct as-is; suggest just updating the PR description so future archaeology doesn't get the wrong story. (And per G2 above, the matching homeassistant-addon/config.yaml actually does need touching to expose tool_search_max_results to stable users.)

G12 — .env.example lost its trailing newline

Diff shows \ No newline at end of file. Re-add the final \n.

G13 — GET /api/settings/tools mutates server state in place (NIT)

File: src/ha_mcp/settings_ui.py:646-649

The default-pin loop (for name in DEFAULT_PINNED_TOOLS: if name not in states: states[name] = "pinned") mutates the dict returned by load_tool_config() by reference. Not persisted, not a bug — just slightly off-pattern for a GET handler. Cheap fix: copy the dict before mutating, or build a fresh states dict from scratch.

G14 — POST flow has no lock (NIT)

File: src/ha_mcp/settings_ui.py:684-705

Load → mutate → save without an asyncio.Lock. Practical impact on a single-admin settings page is essentially zero, but two near-simultaneous saves can lose updates. If you're already in the file, an asyncio.Lock around the read-modify-write is two lines.

---

Positives

• Apply-on-restart model is the right call — the docstring at settings_ui.py:1-8 plus the in-UI banner make the deferred-effect contract visible.
• Restart-as-success on dropped connection (settings_ui.py:722-725) — correctly handles the supervisor killing the process mid-request, with a clear comment.
• States validation added in the Gemini round (settings_ui.py:677-682) is the right shape: parse, validate per-key, drop garbage rather than 400.
• Mandatory-tool defense in depth — UI locks them client-side, apply_tool_visibility strips them server-side, and the unconditional enable re-arms them. A forged POST can't disable ha_search_entities.
• local_provider._list_tools() docstring explains the public-API gap clearly. Good response to the Gemini comment.

---

Test coverage gaps

The [ ] All automated tests pass checkbox is blank in the PR body. The existing unit test (tests/src/unit/test_settings_ui.py, 111 lines) covers persistence and apply_tool_visibility cleanly but the following scenarios have no coverage:

1. POST /api/settings/tools with bad payloads (G3 would have been caught).
2. JSON parse errors / non-dict bodies (the validation block at :666-674 is not exercised).
3. Restart endpoint — missing-SUPERVISOR_TOKEN branch and connection-drop-as-success branch.
4. Feature-gated stub injection in _get_tool_metadata.
5. HTML escaping (once G5 is addressed).
6. is_addon flag in /api/settings/info.
7. load_tool_config → apply_tool_visibility end-to-end.

For ~970 lines of new code with state-mutating HTTP endpoints, current coverage is light. At minimum, adding async tests against the route handlers via Starlette's TestClient covering items 1-3 would catch the G3 class of bugs going forward.

---

Note on a separable concern

Re your worry about silent setting-loss on tool rename — that's a real issue but separable. A schema_version field in tool_config.json plus a migration map ({"old_name": "new_name"}) on the next major rename would handle it. Worth a follow-up issue, no need to block this PR.

Findings citable as G1-G14 for the implementation summary. Let me know which you'd push back on — happy to pair on the auth question (G1) in particular, since the right answer depends on how strongly you want to commit to "settings UI is add-on-only".

[kingpanther13]

@Patch76 — addressed in 72cd3ca (merge + bulk fixes) and 3477a39 (mypy followup). Quick rundown:

What was implemented

#	Status	Notes
G1	✅ done — option (b) variant	Settings routes now mount under the MCP secret path so Docker / standalone clients share the same auth-by-obscurity as the MCP endpoint. Add-on still mounts at root for HA ingress. If neither SUPERVISOR_TOKEN nor a secret path is available, register_settings_routes registers nothing and logs a warning rather than expose them publicly. Moving registration out of _initialize_server into the HTTP entry points (_run_http_server, _run_oauth_server, addon start.py) was a side benefit — closes G10 too.
G2 part 1	✅	tool_search_max_results now actually flows into CategorizedSearchTransform(max_results=...).
G2 part 2	✅	Field(5, ge=2, le=10, ...) in Pydantic, int(2,10)? in dev addon schema. Out-of-range values rejected at the supervisor UI before they reach env vars.
G2 part 3	📝 declined	Stable homeassistant-addon/config.yaml is intentionally untouched — release pipeline syncs at the next biweekly cut. Same convention as enable_yaml_config_editing / enable_filesystem_tools / enable_custom_component_integration post-#942.
G3	✅	if not isinstance(body, dict) guard added before body.get. Returns the same 400 / VALIDATION_INVALID_PARAMETER shape.
G4	✅	_get_config_path now keys off SUPERVISOR_TOKEN, matches the rest of the module. Factored into a _is_addon() helper so the GET /api/settings/info endpoint and _get_config_path can't drift.
G5	✅	escapeHtml(s) helper applied to every ${...} interpolation including data-attribute values.
G6	✅	Comment added explaining the MANDATORY_TOOLS / DEFAULT_PINNED_TOOLS overlap (and the deliberate divergence on ha_get_state).
G7	✅ + extra	ha_install_mcp_tools added to FEATURE_GATED_TOOLS. Took the chance to rewrite the stub copy: instead of "Requires <flag> in add-on config" (which is misleading on stable where the flag isn't exposed at all post-#942), it now points at docs/beta.md — covers both the dev-channel toggle path and the env-var path uniformly.
G8	📝 acknowledged, no code change	The unconditional mcp.enable(names=MANDATORY_TOOLS) is restart-only by design, your read is correct. Adding a comment felt like noise; happy to add one if you want.
G9 part 1 (redundancy)	✅ kept the if not with a defense-in-depth comment	Agree the mcp.disable() call is a no-op today thanks to the early-return in tools_yaml_config.py. Kept the guard because if the registration site ever moves the visibility apply still does the right thing.
G9 part 2 (semantics)	✅ AND semantics	Dropped the else: discard("ha_config_set_yaml") line. UI off or safety toggle off → tool off. New regression test in TestApplyToolVisibility::test_yaml_editing_on_but_ui_disabled_keeps_tool_disabled.
G10	✅	Resolved as a side effect of the G1 entry-point relocation — routes only register in HTTP modes now.
G11	✅	PR description rewritten to drop the "stable channel intentionally untouched" claim that contradicted the homeassistant-addon/start.py edit. New body explains the dev/stable split honestly.
G12	✅	Trailing newline restored.
G13	📝 declined	load_tool_config() reads from disk on every call so the dict isn't shared state. Worth revisiting if that ever caches; not today.
G14	📝 declined	Single-admin contention is genuinely zero. Happy to add an asyncio.Lock if it bothers you, but it's a save-on-toggle UI so even two browser windows would just produce a last-write-wins which is what users expect.

Tests added in tests/src/unit/test_settings_ui.py

• TestConfigPath — _get_config_path honors SUPERVISOR_TOKEN, falls back to ~/.ha-mcp/ otherwise.
• TestFeatureGatedTools — ha_install_mcp_tools is registered as a stub; filesystem tools point at the dev addon option name (alignment check with the beta tag system).
• TestRouteRegistration — root mount only happens in addon mode, secret-path mount always happens (when provided), no mounts at all if neither.
• TestSaveToolsValidation — POST handler rejects non-dict body (null, [], 42), rejects non-dict states, drops garbage values silently rather than 400ing the whole batch.
• AND-semantics regression for ha_config_set_yaml (G9.2).

Merge context

Picked up the #1030 beta flags, #806 migrate_skills_as_tools_default migration, and #955's _apply_search_keyword_enrichment extraction along the way. New PR options stayed dev-only per #942 channel convention. The FEATURE_GATED_TOOLS stub now treats ha_config_set_yaml / filesystem tools / ha_install_mcp_tools consistently as beta-channel tools rather than referencing addon-config keys that don't exist on stable.

Re tool-rename setting-loss — agreed it's separable, will track as a follow-up issue.

[Patch76]

Re-review on top of 72cd3ca + 3477a39 — all 14 findings addressed cleanly.

Spot-checked load-bearing fixes:

• G1 (auth): register_settings_routes refuses to mount when neither SUPERVISOR_TOKEN nor secret_path is available; secret-path mount in non-add-on mode matches the MCP-endpoint auth-by-obscurity model. Relocating registration out of _initialize_server into the HTTP entry points closes G10 as a side effect — clean.
• G2: max_results wired at server.py:543, Field(5, ge=2, le=10) plus int(2,10)? in the dev addon schema. Stable-channel deferral to the release pipeline is consistent with the post-#942 convention.
• G3 / G5 / G9.2: isinstance(body, dict) guard, escapeHtml on every interpolation, and AND-semantics regression test all in place.

Declined items (G2.3 / G8 / G13 / G14): reasoning holds, nothing I'd push back on.

One non-blocking note: the restart endpoint's missing-SUPERVISOR_TOKEN branch (settings_ui.py:780) and the drop-connection-as-success branch (settings_ui.py:798) still don't have tests — the rest of my coverage list is now covered. Two short cases would close the loop; happy to follow up post-merge instead.

Approving.

[github-actions]

🧪 Your changes are now in the dev channel!

Your PR has been merged to master and is available for testing in the dev channel.

Test your changes before the next stable release (biweekly Wednesday):
📖 Dev Channel Documentation

Quick start

# Run dev version
uvx ha-mcp-dev

# Check version
uvx ha-mcp-dev --version

Docker:

docker pull ghcr.io/homeassistant-ai/ha-mcp:dev
docker run --rm -i \
  -e HOMEASSISTANT_URL=http://your-ha:8123 \
  -e HOMEASSISTANT_TOKEN=your_token \
  ghcr.io/homeassistant-ai/ha-mcp:dev

---

Found an issue? Please open a new bug report and mention this PR for context.

[kingpanther13]

Hey I actually had auto-merge disabled on purpose for this one, I wanted to verify how it looked in my browser/the HA UI again before merging it, were you able to look at that yourself? If not no worries I will check on the dev server when I get a chance

[kingpanther13]

That should have been posted in our private maintainer chat, but thanks for the heads up. Surprised it made it this far, I'll find the token it's using and kill it.