Added feature flags for gated features to App config. - #1030
Conversation
…E_CUSTOM_COMPONENT_INTEGRATION to the App configuration.
…tegration addon options
Summary of ChangesHello, I'm Gemini Code Assist1! 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 introduces two new feature flags to the Home Assistant add-on configuration. By exposing these settings in the configuration file, users can now toggle specific filesystem tools and custom component integrations directly through the UI, which previously required manual environment variable configuration. Highlights
Using Gemini Code AssistThe 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
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 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
|
There was a problem hiding this comment.
Pull request overview
Adds support for toggling two gated feature flags via Home Assistant add-on configuration, so the add-on can set the corresponding environment variables at startup.
Changes:
- Add
enable_filesystem_toolsandenable_custom_component_integrationoptions to the add-on and dev add-onconfig.yamlschemas (and defaults). - Read the new options from
/data/options.jsonand exportHAMCP_ENABLE_FILESYSTEM_TOOLS/HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATIONinstart.py. - Document the new configuration options in
homeassistant-addon/DOCS.md.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| homeassistant-addon/start.py | Reads new config booleans and sets the corresponding feature-flag environment variables. |
| homeassistant-addon/config.yaml | Exposes the new options and schema entries for the stable add-on. |
| homeassistant-addon/DOCS.md | Documents the new configuration options. |
| homeassistant-addon-dev/config.yaml | Exposes the same new options for the dev add-on. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces two new configuration options, enable_filesystem_tools and enable_custom_component_integration, across the Home Assistant add-on and its development version. These options are integrated into the configuration schema, documented in DOCS.md, and implemented in start.py to set corresponding environment variables. Feedback was provided to improve the documentation descriptions for these new features, making them less technical and more descriptive of the specific tools and functionality they enable.
|
We have been intentionally keeping these things as advanced settings. I'm ok with adding toggles on the dev/beta version, but we shouldn't let it go to the live version. See PR #942 for a framework on how to keep things as beta status so they won't get merged over to live version. Once you can do that and resolve the Gemini and copilot reviews we can look at getting this merged. |
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Thanks for the comment. I have read #942. But I have a fundamental question: Is the intent to specifically prohibit the HA Apps (standard and dev/beta) from setting these flags altogether while all other installation methods allow it? That's the current state. None of the file operation tools are tagged beta - thus they are already currently shipping in both the stable and dev releases. Based on the current state of these features, an argument could be made that the feature flag should be removed or set to true by default since these are not beta features - although they do require installation of a custom component. The documentation prominently shows the If you drill into the tools, the Any user who installs the MCP server locally on their desktop, in docker, or some other manual way can easily follow these directions and enable the feature flags with a However, as it sits today, it's impossible to set these feature flags via the App or the Dev App in HA. There is no mechanism to define environment variables for an HA App - they have to be set in code after the container launches, thus the code in Thus, there are currently 2 separate things, plus a bug already stopping someone from enabling them using the App:
Without a feature like this it's literally impossible to enable the feature flags at all if you use the HA App as your MCP server. If the concern is that users will mindlessly turn them on and then get into trouble when an agent does a Bad Thing to a file, there are still a lot of hurdles to get there vis-a-vis looking up the All that to say, this just brings the HA App container version up to the same level of capability to modify these feature flags as any other container installation method. Last point: Hopefully a user doesn't have to expose themselves to the wilds of the dev branch to use a feature available to everyone else on the stable branch, albeit feature-flagged. Sorry for the long explanation - I'm new here. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
ekobres
left a comment
ekobres
left a comment
There was a problem hiding this comment.
Made the suggested documentation and string changes.
|
The tools were created long before we had a beta mode, in fact we made the beta mode due to the config set yaml tool causing issues and having a lot of glaring problems and risks. These tools carry the same risks. So yeah, the intent was for them to not be available at all in the addon version initially, but we can follow the pattern of #942 and make them available in the dev server only. There are no plans to make them available in the live version at this time. It isn't hard to switch to the dev version if you really want to use the tools, the idea is that users should be more aware that things are riskier when on the dev version. Also there really isn't any great case to be using those tools anyways, pretty much everything can be done with the existing tools, the only reason to modify files in your HA config is if you are using legacy features. LLMs are extremely prone to hallucinating and trying to modify configuration.yaml, and having any of these tools available greatly increases this risk. With modern HA there are very few instances where directly modifying files/yaml is actually needed. |
So should these also be tagged beta and stripped from the live/stable version? Because as of now they are in there.
Using one experimental feature != taking every push to main. The dev branch comes with a lot more risk than the ability to flip a couple feature flags. But I understand your point.
And this is why they are buried in the add-on configuration and require a whole separate HACS install. My use case is mostly to analyze files for agent context (e.g. source files of custom integrations, zippy quirks, etc.) It would also be nice for the agent to be able to push files to www or other locations - there are a lot of use cases other than the 83 existing tools that can be accomplished with simple file operations. The guidance already does a pretty good job steering the agent away from making direct file changes unless they are specifically asked for. I will drop the non-dev files from the PR if that's what you want - though I think that leaves a fair bit of confusing inconsistency with the features not tagged as beta. |
|
Yes they should be labeled as beta, if you could do that while you're in there please that would be great. There is an issue #986 I have filed to allow access to beta features from the live version in the future to address your exact concern, the other maintainers just been a bit slow to get PRs approved lately so I haven't made a PR yet myself. If you would like to make a PR for that I would review it and approve it for you, so we'd be able to keep those tools as beta and still be able to access them from the live version. Just keep in mind that our release cycle is every 2 weeks, so it'll be a while till you see it on live anyways. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 9 out of 9 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
ekobres
left a comment
ekobres
left a comment
There was a problem hiding this comment.
Requested changes are in.
kingpanther13
left a comment
kingpanther13
left a comment
There was a problem hiding this comment.
Thanks for your patience with all the back-and-forth here — this is my first formal review on this PR (everything before has just been comments), so appreciate you bearing with me while I got the framing right. The core structure of what you've done is great: the "beta" tags on the four file tools, keeping the new flags out of stable config.yaml's options:/schema:, and extending the maintainer comment to name all three dev-only flags all correctly mirror #942's isolation mechanism. Just four things to clean up and I think this is ready to merge.
1. Drop the two hand-added subsections in homeassistant-addon/DOCS.md (lines 247–261).
The ### enable_filesystem_tools (Beta) and ### enable_custom_component_integration (Beta) subsections live in the hand-maintained ## Configuration Options block, well above the <!-- ADDON_TOOLS_START --> marker at line 346, so they're not touched by scripts/extract_tools.py. #942 deliberately kept stable DOCS.md silent about enable_yaml_config_editing — grep enable_yaml_config_editing homeassistant-addon/DOCS.md returns zero hits today. Documenting dev-only toggles as configurable options in stable DOCS.md (with **Default:** false, no less) invites stable users to try to set them. The auto-regenerated tool list will still emit the four file tools with **(beta — dev channel only)** after merge and point users at docs/beta.md, which is exactly the visibility stable users should get.
2. Fix the "require both" wording in docs/beta.md (line 56).
Copilot flagged this in comment 3117670029 and the reply says "Requested changes are in," but the text in commit 4f94316 is unchanged. The code disagrees: register_filesystem_tools() in src/ha_mcp/tools/tools_filesystem.py is gated only by HAMCP_ENABLE_FILESYSTEM_TOOLS. HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION (in src/ha_mcp/tools/tools_mcp_component.py) only gates the ha_install_mcp_tools installer — it does not affect whether the file tools register or work. Copilot's suggested replacement captures this accurately; please apply it.
3. Add the four new file tools to the docs/beta.md "Current beta tools" table.
The table at line 9 still only lists ha_config_set_yaml. Please add rows for ha_list_files, ha_read_file, ha_write_file, and ha_delete_file so it stays the canonical reference for what's beta (and add ha_install_mcp_tools too if you accept #4 below).
4. Tag ha_install_mcp_tools as beta.
src/ha_mcp/tools/tools_mcp_component.py:166 has tags={"Utilities"}. This tool is gated by HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION — the same env var this PR is exposing as a dev-add-on toggle. Without adding "beta" to its tags, the toggle this PR adds turns on a tool that still renders in stable docs as a plain Utilities tool with no beta marker. Tagging it keeps the #942 pattern consistent: flag-gated ⇒ beta tag ⇒ auto-rendered with **(beta — dev channel only)** everywhere the generator runs.
Once those four are in, this should be good to merge. Thanks again for sticking with it.
|
One other thing, if you'd like to do something that addresses issue #986 but not completely closes it such as adding the text field for env vars within the addon itself under the uncommonly used settings thing, so that way addon users on stable can activate these beta tools as well if they know the correct things to type into the env vars box, I'm OK with you adding that to this PR as well. That isn't a blocker for this PR and isn't necessary, but I'm just giving you the option since that's essentially what you were asking for earlier to give parity between app and non-app. |
ekobres
left a comment
ekobres
left a comment
There was a problem hiding this comment.
Requested changes are in.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Thanks for raising #986 — happy to tackle it as a follow-on PR. Quick context on the constraint: the HA Supervisor's config.yaml schema only supports a closed set of typed fields ( Given that, the cleanest minimal approach is probably a single I would probably create something like a beta_features.json to map env vars to beta feature flag names and beta tags so start.py doesn't need to be touched each time. That could become the basis for a more robust beta/feature flag management process later that could automatically wire everything up at build time. Ultimately it would be nice to fully encapsulate the app-specific handling of feature flags into the apps so that beta features are handled automatically with existing tagging. Then, if maintainers later want a more automatic mechanism (e.g. CI-driven schema generation from tool tags), we have a starting place - but that's a separate and larger effort probably worth its own issue. |
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
kingpanther13
left a comment
kingpanther13
left a comment
There was a problem hiding this comment.
All four items from the prior review are addressed, and the (beta) name labels on the two new dev-addon translations are in as well. Stable addon's config.yaml and translations stay clean. Thanks for the back-and-forth on this — nice to have the pattern fully consistent with #942 now.
|
Thanks for thinking through this so carefully — the beta_features.json + single-bool idea is interesting, but it's more structure than I was picturing for #986. What I had in mind is much smaller: a single free-form text field in the stable addon config where users paste env vars verbatim, the same way the FlareSolverr HA addon exposes its config. Coarse on purpose — if you know the env var name you want to set, you can set it; no per-flag schema churn, no opinion about which flags are "beta." The more structured UX (per-tool toggles, beta feature catalog, etc.) is really the territory of the web settings UI #960 is building. Once that lands, it becomes the natural home for discoverable feature flag management rather than wedging it into the Supervisor config schema. #986 can be fully closed once #960 merges and I can add the same functionality to the web interface. Adding the addon text box would just be the first half of #986 — the web interface completes it. |
🧪 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): Quick start# Run dev version
uvx ha-mcp-dev
# Check version
uvx ha-mcp-dev --versionDocker: 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:devFound an issue? Please open a new bug report and mention this PR for context. |
Conflicts:
- homeassistant-addon-dev/{config.yaml,translations/en.yaml,DOCS.md,start.py}:
combined homeassistant-ai#1030 beta flags (filesystem/yaml/custom-component) with this
PR's new dev-only options (tool_search_max_results, disabled_tools,
pinned_tools). New options stay dev-only per homeassistant-ai#942 channel convention.
- src/ha_mcp/server.py: combined homeassistant-ai#955's _apply_search_keyword_enrichment
refactor with this PR's settings-visibility apply step. Order:
tools -> enhanced -> skills -> _apply_settings_visibility ->
_apply_search_keyword_enrichment -> _apply_tool_search.
- homeassistant-addon/start.py: kept homeassistant-ai#806 migrate_skills_as_tools_default
+ relocated supervisor-token validation; added new env var exports.
Patch76 review fixes:
- G1: Mount settings UI under MCP secret_path so Docker/standalone clients
share the same auth-by-obscurity as the MCP endpoint. Add-on continues
to mount at root for HA ingress proxy. Routes don't register at all
when neither path is available (stdio mode, or HTTP without secret).
Moved register_settings_routes out of _initialize_server into the HTTP
entry points (_run_http_server, _run_oauth_server, addon start.py).
- G2: Wire tool_search_max_results through CategorizedSearchTransform;
enforce 2-10 range in Pydantic Field and addon-dev schema int(2,10)?.
- G3: 400 instead of 500 when POST body is JSON but not an object.
- G4: Use SUPERVISOR_TOKEN, not /data existence, to detect add-on mode
in _get_config_path. Matches the rest of the module.
- G5: HTML-escape interpolated tool metadata in the settings JS.
- G6: Comment explaining MANDATORY_TOOLS vs DEFAULT_PINNED_TOOLS overlap.
- G7: Add ha_install_mcp_tools stub to FEATURE_GATED_TOOLS; rewrite stub
copy to point at docs/beta.md (covers both stable and dev paths post-homeassistant-ai#942).
- G9: Keep enable_yaml_config_editing guard with defense-in-depth comment;
drop the discard so AND semantics apply (UI off OR toggle off -> tool off).
- G12: Restore .env.example trailing newline.
Tests cover non-dict body, garbage state values, route mounting under
secret_path, _get_config_path env-driven path, FEATURE_GATED_TOOLS
beta-system alignment, and the G9 AND-semantics regression.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
What does this PR do?
This PR adds the ability to enable the feature flags
HAMCP_ENABLE_FILESYSTEM_TOOLSandHAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATIONto the Dev App configuration since there is no other way to define environment variables to enable them within an HA App.Also tagged these features as (beta) in the source and docs.
Type of change
Testing
uv run pytest)uv run ruff check)Checklist