ha-mcp-dev 7.6.0.dev658__tar.gz → 7.6.0.dev660__tar.gz

{ha_mcp_dev-7.6.0.dev658/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev660}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev658
+Version: 7.6.0.dev660
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -245,6 +245,26 @@ Spend less time configuring, more time enjoying your smart home.
 
 ---
 
+## 🆚 ha-mcp vs. Home Assistant's built-in MCP Server
+
+Home Assistant ships its own [MCP Server integration](https://www.home-assistant.io/integrations/mcp_server/). It is built on the **Assist** pipeline, so a connected MCP client can read and control the entities you have exposed to Assist and run the intents Assist understands — handy for voice-style control of already-exposed devices.
+
+ha-mcp is a standalone server built for **configuring, building, and debugging** your smart home, not just controlling it. On top of device control, it adds capabilities the built-in integration does not have:
+
+| Capability | Built-in MCP Server | ha-mcp |
+|------------|:-------------------:|:------:|
+| Control exposed devices, query states | Yes | Yes |
+| Entity scope | Only entities exposed to Assist | Everything in Home Assistant |
+| Create / edit automations, scripts, scenes | No | Yes |
+| Build & edit dashboards | No | Yes |
+| Debug automations from traces, read history & logs | No | Yes |
+| Manage helpers, areas, zones, labels, groups | No | Yes |
+| Backups, add-ons, HACS, device & entity registry | No | Yes |
+
+**Rule of thumb:** Use the built-in integration for voice-style control of devices you have already exposed; use ha-mcp when you want an AI assistant that can also build and maintain your Home Assistant setup.
+
+---
+
 ## 🔌 Custom Component (ha_mcp_tools) *(beta)*
 
 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.

{ha_mcp_dev-7.6.0.dev658 → ha_mcp_dev-7.6.0.dev660}/README.md

@@ -215,6 +215,26 @@ Spend less time configuring, more time enjoying your smart home.
 
 ---
 
+## 🆚 ha-mcp vs. Home Assistant's built-in MCP Server
+
+Home Assistant ships its own [MCP Server integration](https://www.home-assistant.io/integrations/mcp_server/). It is built on the **Assist** pipeline, so a connected MCP client can read and control the entities you have exposed to Assist and run the intents Assist understands — handy for voice-style control of already-exposed devices.
+
+ha-mcp is a standalone server built for **configuring, building, and debugging** your smart home, not just controlling it. On top of device control, it adds capabilities the built-in integration does not have:
+
+| Capability | Built-in MCP Server | ha-mcp |
+|------------|:-------------------:|:------:|
+| Control exposed devices, query states | Yes | Yes |
+| Entity scope | Only entities exposed to Assist | Everything in Home Assistant |
+| Create / edit automations, scripts, scenes | No | Yes |
+| Build & edit dashboards | No | Yes |
+| Debug automations from traces, read history & logs | No | Yes |
+| Manage helpers, areas, zones, labels, groups | No | Yes |
+| Backups, add-ons, HACS, device & entity registry | No | Yes |
+
+**Rule of thumb:** Use the built-in integration for voice-style control of devices you have already exposed; use ha-mcp when you want an AI assistant that can also build and maintain your Home Assistant setup.
+
+---
+
 ## 🔌 Custom Component (ha_mcp_tools) *(beta)*
 
 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.

{ha_mcp_dev-7.6.0.dev658 → ha_mcp_dev-7.6.0.dev660}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev658"
+version = "7.6.0.dev660"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.6.0.dev658 → ha_mcp_dev-7.6.0.dev660}/src/ha_mcp/errors.py

@@ -134,7 +134,7 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
         "Create a new token with required permissions",
     ],
     ErrorCode.ENTITY_NOT_FOUND: [
-        "Use ha_search_entities() to find correct entity ID",
+        "Use ha_search() to find correct entity ID",
         "Verify the entity exists in Home Assistant",
         "Check for typos in the entity ID",
     ],
@@ -145,7 +145,7 @@ DEFAULT_SUGGESTIONS: dict[ErrorCode, list[str]] = {
     ],
     ErrorCode.ENTITY_INVALID_ID: [
         "Entity ID must be in format: domain.name",
-        "Use ha_search_entities() to find valid entity IDs",
+        "Use ha_search() to find valid entity IDs",
     ],
     ErrorCode.ENTITY_DOMAIN_MISMATCH: [
         "Cannot change entity to a different domain",
@@ -241,7 +241,7 @@ def create_error_response(
                 "code": "ENTITY_NOT_FOUND",
                 "message": "Entity light.nonexistent not found",
                 "details": "No entity with this ID exists in Home Assistant",
-                "suggestion": "Use ha_search_entities() to find correct entity ID"
+                "suggestion": "Use ha_search() to find correct entity ID"
             },
             "entity_id": "light.nonexistent"
         }

{ha_mcp_dev-7.6.0.dev658 → ha_mcp_dev-7.6.0.dev660}/src/ha_mcp/server.py

@@ -453,7 +453,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         "Once you know a tool name, call it directly \u2014 no need to search "
         "again.\n\n"
         "If using proxies, call with TWO top-level params:\n"
-        '   ha_call_read_tool(name="ha_search_entities", arguments={"query": "..."})\n'
+        '   ha_call_read_tool(name="ha_search", arguments={"query": "..."})\n'
         "   Do NOT nest name/arguments inside the arguments param.\n"
         "   Call proxy tools SEQUENTIALLY, not in parallel.\n\n"
         "ALWAYS search before assuming a capability is unavailable. "
@@ -467,11 +467,12 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
     # (no semantic matching). Original tool docstrings stay unchanged;
     # these keywords are appended by the transform at list-tools time.
     _SEARCH_KEYWORDS: ClassVar[dict[str, str]] = {
-        # s02: "find entities" → ha_search_entities should outrank ha_deep_search
-        "ha_search_entities": (
-            "find entities lookup discover search lights sensors switches "
+        # s02: "find entities or configs" → ha_search outranks more specific tools
+        "ha_search": (
+            "find entities configs lookup discover search lights sensors switches "
             "covers climate fans media_player binary_sensor device_tracker "
-            "person weather automation script helper input_boolean input_number"
+            "person weather automation script helper input_boolean input_number "
+            "automations scripts scenes helpers dashboards"
         ),
         # s07: "get/read automation" → ha_config_get_automation should outrank set
         "ha_config_get_automation": (
@@ -488,7 +489,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "integration statistics trend random filter tod "
             "generic_thermostat switch_as_x generic_hygrostat"
         ),
-        # Boost tools that compete with ha_deep_search for common queries
+        # Boost tools that compete with ha_search for common queries
         "ha_config_get_script": (
             "read inspect fetch view existing script config sequence "
             "actions get show detail"
@@ -607,7 +608,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "zone, person, tag. Flow-based helpers (template, group, "
             "utility_meter, derivative, statistics, trend, threshold, "
             "filter, switch_as_x, etc.) cannot be listed through this "
-            "tool — use ha_search_entities or ha_deep_search.\n\n"
+            "tool — use ha_search.\n\n"
             "For per-type schemas and decision guidance, see "
             "ha_get_skill_guide."
         ),
@@ -655,7 +656,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "Execute a Home Assistant service to control entities or "
             "trigger automations. Calls `<domain>.<service>` "
             "(e.g., light.turn_on, climate.set_temperature). Use "
-            "ha_search_entities to find entity IDs and ha_get_state "
+            "ha_search to find entity IDs and ha_get_state "
             "to read current values before changing them.\n\n"
             "For service-parameter details and per-domain guidance, "
             "see ha_get_skill_guide."
@@ -685,15 +686,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
     # enable_tool_search=True, because they are tuned specifically for the
     # categorized search transform and replacing the base description would
     # unnecessarily trim context for other clients.
-    _SEARCH_DESCRIPTION_OVERRIDES: ClassVar[dict[str, str]] = {
-        "ha_deep_search": (
-            "Search INSIDE automation, script, and helper YAML configurations. "
-            "Use ONLY when you need to find where a specific service call, "
-            "entity reference, or config field appears within existing "
-            "automation/script/helper definitions. "
-            "NOT for finding entities or discovering tools."
-        ),
-    }
+    _SEARCH_DESCRIPTION_OVERRIDES: ClassVar[dict[str, str]] = {}
 
     def _apply_lite_docstrings(self) -> None:
         """Swap heavy tool descriptions for shorter variants if enabled.
@@ -1212,7 +1205,11 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         self.mcp.tool(
             name=SKILL_TOOL_NAME,
             description=tool_description,
-            annotations={"readOnlyHint": True, "idempotentHint": True},
+            annotations={
+                "readOnlyHint": True,
+                "idempotentHint": True,
+                "title": "Get Home Assistant Best Practices Skill Guide",
+            },
             tags={"System"},
         )(ha_get_skill_guide)
         logger.info(

{ha_mcp_dev-7.6.0.dev658 → ha_mcp_dev-7.6.0.dev660}/src/ha_mcp/settings_ui.py

@@ -83,12 +83,12 @@ logger = logging.getLogger(__name__)
 # Tools that are always enabled regardless of saved config — the server
 # strips them out of any disable list before applying. Three of these
 # overlap with DEFAULT_PINNED_TOOLS in transforms/categorized_search.py
-# (ha_search_entities, ha_get_overview, ha_report_issue); ha_get_state
+# (ha_search, ha_get_overview, ha_report_issue); ha_get_state
 # is mandatory but not pinned-by-default because it is reachable via the
 # ha_call_read_tool proxy when tool search is on. Keep these lists in
 # sync where it matters and divergent where it matters — don't merge them.
 MANDATORY_TOOLS: set[str] = {
-    "ha_search_entities",
+    "ha_search",
     "ha_get_overview",
     "ha_get_state",
     "ha_report_issue",