ha-mcp-dev 7.0.0.dev273__tar.gz → 7.0.0.dev274__tar.gz

{ha_mcp_dev-7.0.0.dev273/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.0.0.dev274}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.0.0.dev273
+Version: 7.0.0.dev274
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.0.0.dev273 → ha_mcp_dev-7.0.0.dev274}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.0.0.dev273"
+version = "7.0.0.dev274"
 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.0.0.dev273 → ha_mcp_dev-7.0.0.dev274}/src/ha_mcp/server.py

@@ -67,6 +67,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         self._smart_tools: Any = None
         self._device_tools: Any = None
         self._tools_registry: ToolsRegistry | None = None
+        self._skill_tool_names: list[str] = []
 
         # Get server name/version from settings if no client provided
         if not self._client_provided:
@@ -324,6 +325,96 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                 "Failed to expose skills as tools (resources still available)"
             )
 
+        # Phase 4: Register skill guidance tools for clients that don't read
+        # server instructions (e.g., claude.ai). The tool description contains
+        # the trigger conditions so the AI sees them in the tool listing.
+        # Names stored for pinning in search transforms (always-visible).
+        self._register_skill_guidance_tools(skills_dir)
+
+    def _register_skill_guidance_tools(self, skills_dir: Path) -> None:
+        """Register a lightweight guidance tool per skill.
+
+        Clients like claude.ai don't read the MCP server instructions field,
+        so the bootstrap prompt (trigger conditions, symptoms) is invisible.
+        This registers a tool per skill whose description contains the trigger
+        conditions. The tool itself just lists available reference files —
+        actual content is loaded on demand via read_resource.
+        """
+        try:
+            entries = sorted(skills_dir.iterdir())
+        except OSError:
+            logger.warning("Could not read skills directory: %s", skills_dir)
+            return
+
+        for skill_dir in entries:
+            main_file = skill_dir / "SKILL.md"
+            if not skill_dir.is_dir() or not main_file.exists():
+                continue
+
+            frontmatter = self._parse_skill_frontmatter(main_file)
+            if not frontmatter:
+                continue
+
+            description = frontmatter["description"].strip()
+            skill_name = skill_dir.name
+            tool_name = f"ha_get_skill_{skill_name.replace('-', '_')}"
+            uri = f"skill://{skill_name}/SKILL.md"
+
+            tool_description = (
+                f"CALL THIS FIRST before performing matching actions. "
+                f"{description}\n\n"
+                f"Returns available reference files. Use read_resource with "
+                f"the file URI to load specific guides as needed."
+            )
+
+            # Collect available reference files for the listing.
+            # Filter out symlinks and verify path containment to prevent
+            # traversal via symlinked directories.
+            ref_files = []
+            resolved_root = skill_dir.resolve()
+            try:
+                for f in sorted(skill_dir.rglob("*")):
+                    if not f.is_file() or f.is_symlink():
+                        continue
+                    # Ensure resolved path stays within the skill directory
+                    if not f.resolve().is_relative_to(resolved_root):
+                        continue
+                    rel = f.relative_to(skill_dir)
+                    ref_uri = f"skill://{skill_name}/{rel}"
+                    ref_files.append({"name": str(rel), "uri": ref_uri})
+            except OSError:
+                logger.warning("Error reading skill files in %s", skill_dir)
+
+            # Use factory to capture ref_files in closure
+            def _make_skill_handler(
+                s_name: str, s_uri: str, files: list[dict[str, str]],
+            ):
+                async def handler() -> dict[str, Any]:
+                    return {
+                        "skill": s_name,
+                        "skill_uri": s_uri,
+                        "how_to_use": (
+                            "Use read_resource with a file URI below to load "
+                            "the specific reference you need. Start with "
+                            "SKILL.md for the decision workflow."
+                        ),
+                        "available_files": files,
+                    }
+                return handler
+
+            self.mcp.tool(
+                name=tool_name,
+                description=tool_description,
+                annotations={"readOnlyHint": True},
+            )(_make_skill_handler(skill_name, uri, ref_files))
+
+            self._skill_tool_names.append(tool_name)
+            logger.info(
+                "Registered skill guidance tool %s (%d reference files)",
+                tool_name,
+                len(ref_files),
+            )
+
     # Helper methods required by EnhancedToolsMixin
 
     async def smart_entity_search(

{ha_mcp_dev-7.0.0.dev273 → ha_mcp_dev-7.0.0.dev274/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.0.0.dev273
+Version: 7.0.0.dev274
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT