docs: add custom component documentation and HACS install badge - #877
Conversation
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 improves user onboarding and discoverability by providing clear documentation for the ha_mcp_tools custom component. By integrating installation guides and feature flag requirements directly into the project's primary documentation and FAQ, it ensures users can easily set up the necessary components for advanced Home Assistant tool functionality. 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
|
![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 documentation for the ha_mcp_tools custom component in the README and FAQ page, detailing installation steps and the specific tools that require it. The review feedback correctly identifies the omission of the HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION feature flag, which is necessary for the automated installation tool mentioned in system error messages.
kingpanther13
left a comment
kingpanther13
left a comment
There was a problem hiding this comment.
Review: docs: add custom component documentation and HACS install badge
Good docs-only PR that accurately addresses issue #864. All tool names, feature flags, and tool-to-flag mappings verified correct against the source code. Two items to address:
Important
1. ha_install_mcp_tools still points to the wrong repository — this tool IS the intended install path
src/ha_mcp/tools/tools_mcp_component.py:36
ha_install_mcp_tools exists specifically to automate custom component installation so users don't have to manually navigate HACS. When the filesystem tools detect the component is missing, their error messages explicitly direct users to it: "Use ha_install_mcp_tools() to install it via HACS, then restart Home Assistant." (tools_filesystem.py:85). It's the primary, frictionless install mechanism — the HACS badge and manual steps are fallbacks.
Right now, tools_mcp_component.py:36 has:
MCP_TOOLS_REPO = "julienld/ha-mcp-test-custom-component"with a TODO: "Switch to homeassistant-ai/ha-mcp after hacs.json is on default branch."
Meanwhile these docs tell users to manually add homeassistant-ai/ha-mcp via HACS. So the automated tool installs from a test repo while the manual instructions point to the real repo — users following different paths get different components.
hacs.json appears to already be on the default branch (custom_components/ha_mcp_tools/hacs.json exists in master). If that's the case, the TODO is stale and MCP_TOOLS_REPO should be updated to homeassistant-ai/ha-mcp before or alongside this docs PR.
This matters because the tool is the recommended path — making it work properly with the correct repo is more valuable than documenting manual workarounds around it. The focus should be on ensuring ha_install_mcp_tools works end-to-end with the real repo, then documenting it as the primary install method.
2. ha_read_file description is incomplete
README.md and faq.astro
The docs describe ha_read_file as "Read configuration and log files." Per the actual implementation and custom_components/ha_mcp_tools/__init__.py, it also reads files from www/, themes/, custom_templates/, and custom_components/**/*.py. The current description undersells the tool and could mislead users.
Suggested fix:
ha_read_file | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/)
Suggestions (non-blocking)
3. ha_config_set_yaml — consider mentioning "whitelisted" keys
The description says "top-level YAML keys" which could imply all keys work. Only specific whitelisted keys are allowed (template, sensor, binary_sensor, command_line, rest, mqtt, shell_command, switch, light, fan, cover, climate, notify, group, utility_meter). Users might try homeassistant: or automation: and be confused.
4. Stale docstring in tools_mcp_component.py:8
Says HAMCP_ENABLE_MCP_TOOLS_INSTALLER but the actual flag at line 25 is HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION. Pre-existing, not introduced by this PR, but worth a follow-up.
Strengths
- All five custom-component-dependent tools correctly identified and documented
- Feature flag names and tool-to-flag mappings verified accurate against source
- Dual documentation (README + FAQ site) ensures discoverability
- FAQ section well-structured with progressive disclosure (what/why → install → flags)
- Style consistent with existing README and FAQ patterns
- Second commit correctly addressed Gemini's feedback about the missing flag
- Update MCP_TOOLS_REPO from test repo to real repo (hacs.json is on default branch) - Fix stale docstring referencing wrong feature flag name - Improve ha_read_file description to list all allowed paths
|
Addressed all review feedback: Important items:
Also fixed:
Re: suggestion #3 (whitelisted keys): Intentionally omitted the key list from the docs — it would go stale as keys are added. The tool returns a clear error with the allowed keys if a user tries an unsupported one. |
kingpanther13
left a comment
kingpanther13
left a comment
There was a problem hiding this comment.
All review feedback addressed in 8f9a2d9. Verified:
- ✅
MCP_TOOLS_REPOupdated tohomeassistant-ai/ha-mcp— tool now installs from the correct repo, consistent with HACS badge and manual instructions - ✅
ha_read_filedescription updated to include all allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) - ✅ Stale docstring in
tools_mcp_component.py:8fixed — now saysHAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION
All CI checks passing. LGTM.
🧪 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. |
2 participants
What does this PR do?
Adds documentation for the
ha_mcp_toolscustom component to the README and docs site FAQ. Users currently have no way to discover what the component does, why they need it, or how to install it.Changes:
Closes #864
Type of change
Testing
uv run pytest)uv run ruff check)Checklist