docs: add custom component documentation and HACS install badge

README.md

@@ -164,6 +164,38 @@ Spend less time configuring, more time enjoying your smart home.
 
 ---
 
+## 🔌 Custom Component (ha_mcp_tools)
+
+Some tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.
+
+**Tools that require the component:**
+
+| Tool | Description |
+|------|-------------|
+| `ha_config_set_yaml` | Safely add, replace, or remove top-level YAML keys in `configuration.yaml` and package files (automatic backup, validation, and config check) |
+| `ha_list_files` | List files in allowed directories (www/, themes/, custom_templates/) |
+| `ha_read_file` | Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/) |
+| `ha_write_file` | Write files to allowed directories |
+| `ha_delete_file` | Delete files from allowed directories |
+
+All other tools work without the component. These five return an error with installation instructions if the component is missing.
+
+These tools also require feature flags: `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (file tools) and `ENABLE_YAML_CONFIG_EDITING=true` (YAML editing). To enable the `ha_install_mcp_tools` installer tool, set `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true`.
+
+### Install using HACS (recommended)
+
+[![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration)
+
+To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**.
+
+After installing, restart Home Assistant. Then open **Settings** > **Devices & Services** > **Add Integration** and search for **HA MCP Tools**.
+
+### Install manually
+
+Copy `custom_components/ha_mcp_tools/` from this repository into your HA `config/custom_components/` directory. Restart Home Assistant, then add the integration as described above.
+
+---
+
 ## 🧠 Better Results with Agent Skills
 
 This server gives your AI agent tools to control Home Assistant. For better configurations, pair it with [Home Assistant Agent Skills](https://github.com/homeassistant-ai/skills) — domain knowledge that teaches the agent Home Assistant best practices.

site/src/pages/faq.astro

@@ -27,6 +27,7 @@ const withBase = (path: string) => {
         <li><a href="#general-questions" class="text-blue-400 hover:underline">General Questions</a></li>
         <li><a href="#demo" class="text-blue-400 hover:underline">Try Without Your Own Home Assistant</a></li>
         <li><a href="#troubleshooting" class="text-blue-400 hover:underline">Troubleshooting</a></li>
+        <li><a href="#custom-component" class="text-blue-400 hover:underline">Custom Component (ha_mcp_tools)</a></li>
         <li><a href="#configuration" class="text-blue-400 hover:underline">Configuration Options</a></li>
         <li><a href="#feedback" class="text-blue-400 hover:underline">Feedback & Help</a></li>
       </ul>
@@ -227,6 +228,69 @@ source ~/.zshrc
       </div>
     </section>
 
+    <!-- Custom Component -->
+    <section class="mb-12" id="custom-component">
+      <h2 class="text-2xl font-semibold text-white mb-6">Custom Component (ha_mcp_tools)</h2>
+
+      <div class="space-y-6">
+        <div class="faq-item">
+          <h3 class="text-lg font-medium text-white mb-2">What is the custom component and why do I need it?</h3>
+          <p class="text-slate-300 mb-3">Some tools require a companion custom component installed in Home Assistant. Standard HA APIs do not expose file system access or YAML config editing. This component provides both.</p>
+          <p class="text-slate-300 mb-2"><strong class="text-white">Tools that require the component:</strong></p>
+          <ul class="list-disc list-inside text-slate-300 space-y-1 ml-2">
+            <li><code class="bg-slate-800 px-1 rounded">ha_config_set_yaml</code> — Safely add, replace, or remove top-level YAML keys in configuration.yaml and package files (automatic backup, validation, and config check)</li>
+            <li><code class="bg-slate-800 px-1 rounded">ha_list_files</code> — List files in allowed directories (www/, themes/, custom_templates/)</li>
+            <li><code class="bg-slate-800 px-1 rounded">ha_read_file</code> — Read files from allowed paths (config YAML, logs, www/, themes/, custom_templates/, custom_components/)</li>
+            <li><code class="bg-slate-800 px-1 rounded">ha_write_file</code> — Write files to allowed directories</li>
+            <li><code class="bg-slate-800 px-1 rounded">ha_delete_file</code> — Delete files from allowed directories</li>
+          </ul>
+          <p class="text-slate-400 text-sm mt-3">All other tools work without the component. These five return an error with installation instructions if the component is missing.</p>
+        </div>
+
+        <div class="faq-item">
+          <h3 class="text-lg font-medium text-white mb-2">How do I install it?</h3>
+          <p class="text-slate-300 mb-3"><strong class="text-white">Using HACS (recommended):</strong></p>
+          <p class="text-slate-300 mb-3">
+            <a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=homeassistant-ai&repository=ha-mcp&category=integration" class="inline-block" target="_blank" rel="noopener">
+              <img src="https://my.home-assistant.io/badges/hacs_repository.svg" alt="Open your Home Assistant instance and open a repository inside the Home Assistant Community Store." />
+            </a>
+          </p>
+          <p class="text-slate-300 mb-3">To add manually: open <strong class="text-white">HACS</strong> &gt; <strong class="text-white">Integrations</strong> &gt; three-dot menu &gt; <strong class="text-white">Custom repositories</strong> &gt; add <code class="bg-slate-800 px-1 rounded">https://github.com/homeassistant-ai/ha-mcp</code> (category: Integration) &gt; <strong class="text-white">Download</strong>.</p>
+          <p class="text-slate-300 mb-3">After installing, restart Home Assistant. Then open <strong class="text-white">Settings</strong> &gt; <strong class="text-white">Devices &amp; Services</strong> &gt; <strong class="text-white">Add Integration</strong> and search for <strong class="text-white">HA MCP Tools</strong>.</p>
+          <p class="text-slate-300"><strong class="text-white">Manual install:</strong> Copy <code class="bg-slate-800 px-1 rounded">custom_components/ha_mcp_tools/</code> from the <a href="https://github.com/homeassistant-ai/ha-mcp" class="text-blue-400 hover:underline" target="_blank">repository</a> into your HA config's <code class="bg-slate-800 px-1 rounded">custom_components/</code> directory. Restart Home Assistant, then add the integration as described above.</p>
+        </div>
+
+        <div class="faq-item">
+          <h3 class="text-lg font-medium text-white mb-2">Do I also need to enable feature flags?</h3>
+          <p class="text-slate-300">Yes. The component is required, but the tools are also gated by feature flags for safety:</p>
+          <div class="overflow-x-auto mt-3">
+            <table class="w-full text-sm">
+              <thead>
+                <tr class="border-b border-slate-700">
+                  <th class="text-left py-2 text-slate-300">Variable</th>
+                  <th class="text-left py-2 text-slate-300">Enables</th>
+                </tr>
+              </thead>
+              <tbody class="text-slate-400">
+                <tr class="border-b border-slate-800">
+                  <td class="py-2"><code class="bg-slate-800 px-1 rounded">HAMCP_ENABLE_FILESYSTEM_TOOLS=true</code></td>
+                  <td class="py-2"><code class="bg-slate-800 px-1 rounded">ha_list_files</code>, <code class="bg-slate-800 px-1 rounded">ha_read_file</code>, <code class="bg-slate-800 px-1 rounded">ha_write_file</code>, <code class="bg-slate-800 px-1 rounded">ha_delete_file</code></td>
+                </tr>
+                <tr class="border-b border-slate-800">
+                  <td class="py-2"><code class="bg-slate-800 px-1 rounded">ENABLE_YAML_CONFIG_EDITING=true</code></td>
+                  <td class="py-2"><code class="bg-slate-800 px-1 rounded">ha_config_set_yaml</code></td>
+                </tr>
+                <tr>
+                  <td class="py-2"><code class="bg-slate-800 px-1 rounded">HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true</code></td>
+                  <td class="py-2"><code class="bg-slate-800 px-1 rounded">ha_install_mcp_tools</code> (automated installer)</td>
+                </tr>
+              </tbody>
+            </table>
+          </div>
+        </div>
+      </div>
+    </section>
+
     <!-- Configuration Options -->
     <section class="mb-12" id="configuration">
       <h2 class="text-2xl font-semibold text-white mb-6">Configuration Options</h2>

src/ha_mcp/tools/tools_mcp_component.py

@@ -5,7 +5,7 @@
 ha_mcp_tools custom component via HACS. This enables additional services
 that are not available through standard Home Assistant APIs.
 
-Feature Flag: Set HAMCP_ENABLE_MCP_TOOLS_INSTALLER=true to enable this tool.
+Feature Flag: Set HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION=true to enable this tool.
 """
 
 import logging
@@ -32,8 +32,7 @@ def is_custom_component_integration_enabled() -> bool:
 
 
 # Constants for ha_mcp_tools custom component
-# TODO: Switch to "homeassistant-ai/ha-mcp" after hacs.json is on default branch
-MCP_TOOLS_REPO = "julienld/ha-mcp-test-custom-component"
+MCP_TOOLS_REPO = "homeassistant-ai/ha-mcp"
 MCP_TOOLS_DOMAIN = "ha_mcp_tools"