[FEATURE] Advanced settings panel in web UI + beta-features opt-in

[kingpanther13]

What would you like to see?

Extend the web settings UI from #960 with two new sections.

Advanced settings

Render every Settings field that's plausibly user-tweakable on a running server. Verified field list from src/ha_mcp/config.py (23 env-aliased fields total):

Connection (display only — source of truth is env / addon options):

• HOMEASSISTANT_URL, HOMEASSISTANT_TOKEN, HA_TIMEOUT, HA_MAX_RETRIES, HA_VERIFY_SSL

Search & matching:

• FUZZY_THRESHOLD (0-100, validator-enforced), ENTITY_SEARCH_LIMIT, ENABLE_TOOL_SEARCH, TOOL_SEARCH_MAX_RESULTS (2-10, Pydantic-enforced)

Tool surface:

• ENABLED_TOOL_MODULES, ENABLE_SKILLS, ENABLE_SKILLS_AS_TOOLS, DISABLED_TOOLS, PINNED_TOOLS (last two already covered by existing UI section — link, don't duplicate)

Operations:

• BACKUP_HINT (strong/normal/weak/auto, validator-enforced), ENABLE_WEBSOCKET

Identity / diagnostics:

• MCP_SERVER_NAME, MCP_SERVER_VERSION, ENVIRONMENT, LOG_LEVEL, DEBUG

Fields not listed: ENABLE_DASHBOARD_PARTIAL_TOOLS (defined but not read anywhere in src/ha_mcp/ — separate cleanup), ENABLE_YAML_CONFIG_EDITING (covered in beta panel below).

Each field renders with current value, default, and validation bounds where Pydantic enforces them. Apply-mode (live vs. requires restart) needs an audit during implementation — LOG_LEVEL is set once via _setup_logging at startup so it needs restart; tool-registration flags (ENABLE_TOOL_SEARCH, ENABLE_SKILLS*) also gate startup paths; the others haven't been traced.

Beta features

Two compatible entry points:

1. Web UI panel — checkboxes that flip the underlying gate flags, replacing #960's locked-stub note with an actual opt-in. Each entry links to the relevant section of docs/beta.md. Initial set, matching the 6 stub tools #960 already renders:

• ENABLE_YAML_CONFIG_EDITING (on Settings) → unlocks ha_config_set_yaml
• HAMCP_ENABLE_FILESYSTEM_TOOLS (read via os.getenv in tools_filesystem.py) → unlocks ha_list_files, ha_read_file, ha_write_file, ha_delete_file
• HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION (read via os.getenv in tools_mcp_component.py) → unlocks ha_install_mcp_tools

Architectural note: the two HAMCP_ENABLE_* flags are not on the Settings class. To present them in the UI alongside Settings-backed fields, either migrate them onto Settings first, or give the UI a separate read/write path for raw env-gated flags. Worth deciding before implementation.

2. Stable addon config.yaml text field — beta_features: "" option (parsed by homeassistant-addon/start.py into the corresponding env vars before the server starts), comma-separated feature names matching docs/beta.md keys. For users who don't use the web UI.

Both write to the same persistence file so the surfaces stay coherent.

Why do you need this?

Three threads collapse into one surface:

• [FEATURE] Use MCP Apps to expose server settings via in-client UI #863 — runtime tunables editable without env-var/addon-schema gymnastics. Original MCP App approach is uncertain on client support (open question Patch76 raised in [FEATURE] Use MCP Apps to expose server settings via in-client UI #863); feat: web-based settings UI for per-tool enable/disable/pin #960 gives us a working web surface to extend instead.
• [FEATURE] Generic beta-features opt-in mechanism for the stable addon #986 — operators on the stable addon need a way to opt into individual beta features. HA Supervisor only honors options listed in the addon's schema:, so arbitrary env vars aren't available. Switching to the dev channel addon to get one beta feature pulls in every other dev change.
• The non-addon (pip / Docker direct / uv) env var path already works; the gap is the addon path.

Additional context

#942 (docs/beta.md, removes enable_yaml_config_editing from stable addon UI) merged 2026-04-15. #960 (settings UI) merged 2026-05-02. This issue extends an already-merged surface — no upstream blockers.

Persistence: tool_config.json (at get_data_dir() / "tool_config.json") is keyed for per-tool state. Runtime settings + beta flags need their own channel — sibling JSON file or new top-level blocks in the existing one. Don't mutate the in-memory pydantic singleton without persisting (gotcha Patch76 flagged on #863 — edits would be lost on restart).

Apply model: match #960's "save now, restart to apply" pattern (per #960's description: runtime mcp.disable() accumulates transforms unreliably; startup-time apply is the clean path). Mark each field's apply-mode in the UI once audited.

Connection settings stay read-only. Editing HOMEASSISTANT_URL / _TOKEN from a web UI served by the running server is a chicken-and-egg footgun.

More context: as part of this we need to make sure that the web UI is always synced with the addon settings (in other words, changing settings will always require addon restart) and making sure the toggles in addon settings sync both directions between web UI. We may need to find a way to include the current pinned and/or disabled tools in the text boxes in the addon side. Similarly, we need to make sure the web UI syncs up with env vars in the non addon versions; I'm thinking if someone has set something up in the environment vars, it should be displayed in the web UI as read only, stating that the setting either needs to be modified in the env vars OR the setting can be removed from the env vars and then the web UI can take over. The beginning framework for this is being introduced in PR #1403 (if it doesn't already exist with the pinned tools and whatnot, then 1403 def adds it )

---

Addendum (2026-05-22): per-field env-pin pattern verified in PR #1403

PR #1403 (auto-backup web UI editor) implemented the env-var / web-UI sync
contract described in the "More context" paragraph above for the 3 new
auto-backup scalar settings (enable_auto_backup, auto_backup_throttle_minutes,
auto_backup_retain_per_entity). Behavior shipped there:

• Addon mode: web UI POST routes through Supervisor /addons/self/options
  → addon restart; config.yaml stays authoritative; both UIs stay in sync.
• Standalone, env var not set: web UI edits write <data_dir>/backup_settings.json,
  Settings cache invalidates, change takes effect immediately (no restart).
• Standalone, env var set on that specific field: web UI shows the field
  read-only with a banner pointing at the env var; POST returns 409 if a write
  is attempted. Detection is per-field via os.environ.get(env_name) — having a
  .env file present is not enough; the specific key must be present.

Verification of the existing disabled_tools / pinned_tools panel (settings_ui.py:158-204):
those env vars are currently seed-only — load_tool_config reads
tool_config.json if present and falls back to env-var seeding only on first
run. After the file exists, env-var changes are silently ignored and the web
UI POST writes the file without any env-pin check. The addon translation for
both fields documents this as "text fallback ... seeds the initial config when
the web UI hasn't been used yet."

This violates the principle laid out in the "More context" paragraph (env vars
should not be silently overridden). Two options for the eventual #1164 PR:

Option A (leaning) — per-tool env-pinning (mirrors PR #1403 for scalars):
DISABLED_TOOLS=ha_hacs_search,ha_hacs_download locks the ha_hacs_search
and ha_hacs_download rows read-only in the web UI; other tools remain
freely toggleable. Same for PINNED_TOOLS. Most semantically correct match
for the existing pattern. Documented "text fallback" behavior needs updating
in homeassistant-addon-dev/translations/en.yaml.

Option B — blanket env-pinning: if either env var is set at all, the
entire Tools tab is read-only. Simpler implementation but crude — blocks
managing tools the env var didn't mention.

Same treatment likely applies to every other env-mediated setting that the
advanced-settings panel from this issue eventually surfaces. The PR that
closes this issue should bundle the tools-panel fix with the new advanced-
settings panel so the env-pin contract is implemented in one consistent pass.

[github-actions]

🔍 Analysis

The issue #1164 is a feature request to expand the web-based settings UI (introduced in #960) with an Advanced Settings panel and a Beta Features opt-in section. This aims to bridge the gap between the simplified add-on configuration and the full set of environment variables available to advanced users (Docker/pip).

Currently, the settings UI only manages tool visibility (enable/disable/pin) by persisting to tool_config.json. The proposed changes involve:

1. Advanced Settings: Exposing ~23 fields from the Settings class (defined in src/ha_mcp/config.py) that are currently only editable via environment variables or add-on options.
2. Beta Features: Providing a unified interface to enable experimental features like YAML config editing, filesystem tools, and custom component integration.
3. Persistence: Moving beyond per-tool visibility to persisting global server settings, likely to a new settings_config.json sibling file, and ensuring these are applied on startup.
4. Add-on Compatibility: Adding a beta_features string field to the stable add-on configuration to allow opt-in without exposing every experimental toggle in the Supervisor UI.

The investigation confirmed that the feature flags for filesystem tools and custom component integration currently reside in their respective tool modules as raw os.getenv calls, which should be migrated to the central Settings class for consistent management.

🛠️ Suggested Steps

1. Update src/ha_mcp/config.py:
   • Add enable_filesystem_tools and enable_custom_component_integration to the Settings class.
   • Update the tool modules (src/ha_mcp/tools/tools_filesystem.py and src/ha_mcp/tools/tools_mcp_component.py) to use these settings instead of os.getenv.
2. Enhance src/ha_mcp/settings_ui.py:
   • Expand _SETTINGS_HTML to include sections for "Advanced Settings" and "Beta Features".
   • Implement new API endpoints (e.g., GET/POST /api/settings/advanced) to handle these fields.
   • Implement a persistence layer that saves these settings to settings_config.json in the data directory.
3. Update src/ha_mcp/server.py:
   • Modify _apply_settings_visibility (or add a new method) to load settings_config.json on startup and override the global Settings singleton before tools are initialized.
4. Update homeassistant-addon/start.py:
   • Add logic to parse a new beta_features comma-separated option and set the corresponding environment variables.

📊 Technical Analysis (for maintainers)

Root Cause

The current configuration model is split between tool_config.json (runtime UI) and environment variables/add-on options (startup-time). Users on the stable add-on channel lack a surface to enable beta features or tweak advanced performance settings without switching to the dev channel or manually editing files.

Affected Code

• src/ha_mcp/config.py: Needs new fields and a mechanism to load overrides from a JSON file.
• src/ha_mcp/settings_ui.py: The _SETTINGS_HTML blob needs a significant update to include the new UI sections and JS logic for saving/loading advanced settings.
• src/ha_mcp/server.py: Startup logic must be updated to apply persisted settings.
• src/ha_mcp/tools/tools_filesystem.py: Change is_filesystem_tools_enabled to check Settings.
• src/ha_mcp/tools/tools_mcp_component.py: Change is_custom_component_integration_enabled to check Settings.
• homeassistant-addon/start.py: Needs to handle the beta_features option.

Proposed Fix

--- a/src/ha_mcp/config.py
+++ b/src/ha_mcp/config.py
@@ -107,6 +107,14 @@
     # files. Disabled by default; only for YAML-only features with no UI/API path.
     enable_yaml_config_editing: bool = Field(False, alias="ENABLE_YAML_CONFIG_EDITING")
 
+    # Filesystem tools — allows reading/writing files in the HA config directory.
+    # Requires the ha_mcp_tools custom component.
+    enable_filesystem_tools: bool = Field(False, alias="HAMCP_ENABLE_FILESYSTEM_TOOLS")
+
+    # Custom component integration — allows installing the ha_mcp_tools component via HACS.
+    enable_custom_component_integration: bool = Field(
+        False, alias="HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION"
+    )
+
     # Seed values for tool visibility (comma-separated tool names).
     # Used as initial config when no tool_config.json exists.

--- a/homeassistant-addon/start.py
+++ b/homeassistant-addon/start.py
@@ -232,6 +232,15 @@
             advanced_debug_logging = resolve_bool_option(config, "advanced_debug_logging", False)
+            beta_features = config.get("beta_features", "")
+            if isinstance(beta_features, str) and beta_features:
+                features = [f.strip() for f in beta_features.split(",")]
+                if "yaml_config_editing" in features:
+                    enable_yaml_config_editing = True
+                if "filesystem_tools" in features:
+                    enable_filesystem_tools = True
+                if "custom_component_integration" in features:
+                    enable_custom_component_integration = True
         except Exception as e:

Related Issues/PRs

• [FEATURE] Use MCP Apps to expose server settings via in-client UI #863 - Initial discussion on runtime tunables.
• feat: web-based settings UI for per-tool enable/disable/pin #960 - Implementation of the base settings UI.
• [FEATURE] Generic beta-features opt-in mechanism for the stable addon #986 - Request for beta feature opt-in for stable addon.
• [FEATURE] Remove ENABLE_SKILLS / ENABLE_SKILLS_AS_TOOLS toggles, surface skill tools in web settings UI #1133 - Removal of enable_skills_as_tools toggle (relevant for cleanup).

---

🤖 Automated analysis by Issue Bot

[Patch76]

Good spec — the field enumeration and the cross-references to #863/#986/#960 made this analysis quick. Most of what's below is undercount in the enumeration and one architectural angle that didn't make the original write-up.

Field list is undercounted by 6 (and 2 are gone)

The body lists 23 env-aliased Settings fields; HEAD config.py has 28. Concretely:

• Added before filing (same day, ~4h earlier): enable_code_mode + bound-validated quartet code_mode_max_duration / code_mode_max_memory / code_mode_max_recursion / code_mode_max_invocations + code_mode_saved_tools_path — commit 15b48bb from PR feat: add ha_manage_custom_tool — sandboxed code execution escape hatch #854 landed 2026-05-07 16:53 UTC, this issue filed 20:34 UTC. Easy miss.
• Added after filing: enable_lite_docstrings — commit c9966c6 from PR feat: add ENABLE_LITE_DOCSTRINGS beta toggle #1259 on 2026-05-12.
• Removed the day before filing: ENABLE_SKILLS and ENABLE_SKILLS_AS_TOOLS — commit 2e52516 from PR refactor: always-on skills; rename list/read resource tools with ha_ prefix #1136 (closes [FEATURE] Remove ENABLE_SKILLS / ENABLE_SKILLS_AS_TOOLS toggles, surface skill tools in web settings UI #1133) on 2026-05-06. Stale references remain in src/ha_mcp.egg-info/PKG-INFO only.

The Code Mode quartet has non-trivial UI affordances — sliders/spinners with bounds (1–300s wall-clock, 1MB–256MB memory, 1–10k recursion/invocations) — and the rationale for those ceilings probably wants to land in the help text since users tweaking them without context will pick numbers that defeat the safety margin.

enable_code_mode reads more like a beta-panel candidate

The body's beta-panel list is the 3 stub-tool flags. enable_code_mode is security-sensitive ("disabled by default due to the inherent risk of LLM-generated code") and gates a multi-tool sandbox surface — same shape as the other beta toggles, just heavier consequences. In Advanced it ends up next to log levels, which probably understates it.

Small correction on ENABLE_DASHBOARD_PARTIAL_TOOLS

Body has it as "defined but not read anywhere in src/ha_mcp/ — separate cleanup". It's actually picked up by tools/tools_bug_report.py:120 as a member of _CONFIG_TOGGLE_FIELDS (bug-report diagnostic context). No runtime gate branches on it though, so the panel-eligibility question is real — just the cleanup framing isn't quite right.

Addon start.py env-var bridge is already complete

homeassistant-addon/start.py:235-243 parses all 5 flags from the addon config dict (enable_yaml_config_editing, enable_filesystem_tools, enable_custom_component_integration, enable_code_mode, enable_lite_docstrings), and L280-284 translates each into the corresponding env var (ENABLE_YAML_CONFIG_EDITING, HAMCP_ENABLE_FILESYSTEM_TOOLS, HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION, ENABLE_CODE_MODE, ENABLE_LITE_DOCSTRINGS). CODE_MODE_SAVED_TOOLS_PATH is also wired at L295 via setdefault. So the addon-side work reduces to the schema-shape decision in the body: keep the per-flag booleans the addon schema already has, or collapse into a beta_features comma-separated string. The actual env-var plumbing isn't blocking either path.

Three decision points not in the issue body

• Source-of-truth precedence: env > persisted JSON > default is the natural pattern (env is immutable startup-time anyway), but it means a user editing a value in the UI that's also set in env sees no apparent effect. Either the UI silently no-ops, shows "overridden by env" inline, or refuses to save. Worth picking before the UI work starts.
• HAMCP_ENABLE_* migration alias shape: if the two HAMCP_* flags move onto Settings, the back-compat question is whether to keep HAMCP_ENABLE_FILESYSTEM_TOOLS as the alias (consistent with current env-var users) or normalize to ENABLE_FILESYSTEM_TOOLS with HAMCP_* as a secondary alias. Naming-convention drift is already visible — ENABLE_YAML_CONFIG_EDITING has no HAMCP_* prefix; the filesystem/component flags do.
• Apply-mode audit: needs a pre-implementation pass with a per-field column in the UI. LOG_LEVEL (set once in _setup_logging), tool-registration gates (enable_tool_search, enable_yaml_config_editing etc.), and HA client construction (HA_TIMEOUT, HA_VERIFY_SSL — passed to httpx at client init) are all restart-only. Read-on-every-call fields like FUZZY_THRESHOLD are live. Mixed-class behavior in one panel without per-field annotation is a UX hazard.

Closed issue to fold into the PR

Closes #986 — that issue was closed 2026-05-07 with "Superseded by #1164 — beta-features opt-in folded into the broader advanced-settings panel work". The eventual PR should pick it up alongside #1164.

The shape calls (beta-panel scope, alias convention, persistence file layout) are yours as the proposer — these are just surfaced so the choices are explicit before the UI work starts.

[kingpanther13]

Right when I get to this one I will reevaluate the current truth of the code when I make the PR, a lot of stuff here is stale.