[FEATURE] Convert static documentation tools to MCP resources / skill references

[kingpanther13]

What would you like to see?

Building on @sergeykad's proposal, convert 4 documentation-only tools into MCP resources and skill reference files, removing them from tools/list:

Tool to remove	What it does today	Proposed replacement
ha_get_dashboard_guide	Returns static dashboard_guide.md from disk	Skill reference file in home-assistant-best-practices
ha_get_card_documentation	No-arg: returns card types list from static card_types.json. With arg: fetches card docs from GitHub	Skill reference file for the card types list. MCP resource URI template ha://docs/cards/{card_type} for the GitHub fetch
ha_get_domain_docs	Fetches integration docs from GitHub	MCP resource URI template ha://docs/domains/{domain}
ha_config_info	Returns hardcoded guidance text about how ha-mcp configuration access works (remote API vs filesystem, which tool families exist, YAML snippet workflow). Takes a config_type param (general/automation/script/dashboard/integration/yaml) — zero API calls, 100% static strings	Content folded into the best-practices skill

The static content moves into the existing home-assistant-best-practices skill as reference files (companion issue: homeassistant-ai/skills#20).

The GitHub-fetching capabilities become MCP resource URI templates. When resources/read is called with e.g. ha://docs/cards/light, the server fetches from GitHub and returns the content. This works in both config modes:

• Default (ENABLE_SKILLS_AS_TOOLS=false): LLM uses resources/read directly
• Skills-as-tools mode: ResourcesAsTools auto-exposes them as tool operations

Why do you need this?

ha-mcp has 91+ tools. Every tool definition consumes tokens in the tools/list context. These 4 tools return reference data that never modifies HA state — they don't belong in the tool list.

MCP resources are the correct primitive for read-only reference data accessed by URI. This approach:

• Frees 4 tool slots from the context window
• Uses the existing skills infrastructure (SkillsDirectoryProvider, ResourcesAsTools transform) — no new patterns needed
• Ensures all clients can still access the content: resource-capable clients use resources/read, others use the ENABLE_SKILLS_AS_TOOLS=true fallback

Additional context

Companion issue for skill reference files: homeassistant-ai/skills#20

I would plan to add a bit in the relevant tool descriptions to give them a heads up of the existing skills resources as well, so they're more likely to be referenced.

[github-actions]

The ha-mcp project currently includes four tools that serve static or read-only documentation: ha_get_dashboard_guide, ha_get_card_documentation, ha_get_domain_docs, and ha_config_info. These tools consume valuable slots in the LLM's tool context and don't modify the state of Home Assistant, making them ideal candidates for conversion to MCP resources and skill references.

🔍 Analysis

The proposed change involves shifting documentation content from the tool list into more appropriate MCP primitives. By converting these to resources and skill references, we free up context window tokens while maintaining (and improving) accessibility for AI agents.

1. Static Content Transition: High-level guidance like the dashboard guide and configuration info will move to the home-assistant-best-practices skill. This allows agents to "consult" the best practices only when relevant, using the existing skills infrastructure.
2. Resource Templates: Dynamic documentation fetching (from GitHub for integration and card docs) will be implemented as MCP resource URI templates. This aligns with the MCP specification's intent for read-only reference data.
3. Client Compatibility: For clients that do not natively support MCP resources, the ENABLE_SKILLS_AS_TOOLS setting ensures these resources are still exposed as tool operations (via ResourcesAsTools), providing a seamless fallback.

🛠️ Suggested Steps

1. Create a new documentation resources module: Implement the GitHub-fetching logic as MCP resource templates in a new file (e.g., src/ha_mcp/tools/tools_docs.py).
2. Remove the legacy tools: Delete the tool definitions from src/ha_mcp/tools/tools_config_dashboards.py, src/ha_mcp/tools/tools_utility.py, and src/ha_mcp/tools/tools_config_info.py.
3. Update references: Search and replace all mentions of the removed tools in error messages and other tool descriptions (e.g., in src/ha_mcp/errors.py and src/ha_mcp/tools/tools_service.py) to point to the new resource URIs.

📊 Technical Analysis (for maintainers)

Root Cause

The current implementation uses standard tools for read-only documentation access. While functional, this is token-inefficient for the LLM's context window. Converting these to MCP resources allows the server to provide the same information via resources/read without cluttering the tool definitions.

Affected Code

• src/ha_mcp/tools/tools_config_dashboards.py - Contains ha_get_dashboard_guide and ha_get_card_documentation.
• src/ha_mcp/tools/tools_utility.py - Contains ha_get_domain_docs.
• src/ha_mcp/tools/tools_config_info.py - Contains ha_config_info (can be removed entirely).
• src/ha_mcp/errors.py - Contains references to these tools in error suggestions.
• src/ha_mcp/server.py - May need to register the new documentation resources.

Proposed Fix

Create src/ha_mcp/tools/tools_docs.py with resource definitions:

import httpx
from typing import Annotated
from fastmcp import FastMCP

def register_docs_resources(mcp: FastMCP):
    @mcp.resource("ha://docs/domains/{domain}")
    async def ha_docs_domain(domain: str) -> str:
        """Fetch official Home Assistant integration documentation from GitHub."""
        url = f"https://raw.githubusercontent.com/home-assistant/home-assistant.io/refs/heads/current/source/_integrations/{domain.lower()}.markdown"
        async with httpx.AsyncClient(timeout=30.0) as client:
            response = await client.get(url)
            response.raise_for_status()
            return response.text

    @mcp.resource("ha://docs/cards/{card_type}")
    async def ha_docs_card(card_type: str) -> str:
        """Fetch official Home Assistant card documentation from GitHub."""
        url = f"https://raw.githubusercontent.com/home-assistant/home-assistant.io/refs/heads/current/source/_integrations/lovelace-card-{card_type.lower()}.markdown"
        async with httpx.AsyncClient(timeout=30.0) as client:
            response = await client.get(url)
            response.raise_for_status()
            return response.text

And update src/ha_mcp/errors.py to point to the new URIs:

--- a/src/ha_mcp/errors.py
+++ b/src/ha_mcp/errors.py
@@ -140,7 +140,7 @@
-        "Use ha_get_domain_docs() to see available services",
+        "Read ha://docs/domains/{domain} for available services",

Related Issues/PRs

• Add dashboard, card types, and configuration reference files to home-assistant-best-practices skills#20 - Companion issue for skill reference files

---

🤖 Automated analysis by Issue Bot

[kingpanther13]

Once homeassistant-ai/skills#25 has been finalized and merged into the skills, I will create a PR for this. This will remove 4 tools that really aren't necessary, while still preserving the data.