ha-mcp-dev 7.10.0.dev777__tar.gz → 7.10.0.dev779__tar.gz

{ha_mcp_dev-7.10.0.dev777/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.10.0.dev779}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.10.0.dev777
+Version: 7.10.0.dev779
 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.10.0.dev777 → ha_mcp_dev-7.10.0.dev779}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.10.0.dev777"
+version = "7.10.0.dev779"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-7.10.0.dev777 → ha_mcp_dev-7.10.0.dev779}/src/ha_mcp/__main__.py

@@ -34,8 +34,10 @@ from typing import TYPE_CHECKING, Any  # noqa: E402
 
 from fastmcp.exceptions import ToolError  # noqa: E402
 from pydantic import ValidationError as PydanticValidationError  # noqa: E402
-from starlette.requests import Request  # noqa: E402
-from starlette.responses import PlainTextResponse  # noqa: E402
+
+from ha_mcp.browser_landing import (  # noqa: E402
+    register_browser_landing as _register_landing_route,
+)
 
 if TYPE_CHECKING:
     from fastmcp import FastMCP
@@ -962,21 +964,20 @@ async def _run_http_with_graceful_shutdown(
     )
 
 
-_registered_landing_paths: set[str] = set()
-
-
 def register_browser_landing(
     mcp_instance: "FastMCP | _DeferredMCP",
     path: str,
     *,
     quiet_probe_log: bool = True,
 ) -> None:
-    """Register a GET handler that returns 405 with a helpful message.
+    """Register the friendly browser landing page and tidy the uvicorn access log.
 
-    Browsers and misconfigured clients that send GET instead of POST will see
-    a human-readable explanation instead of a bare "Method Not Allowed" error.
-    The 405 status and Allow header are set explicitly by this handler so
-    automated clients still get the correct HTTP semantics.
+    Delegates the GET landing route to the reusable core in
+    :mod:`ha_mcp.browser_landing` (also used by the in-process ``ha_mcp_tools``
+    server) and, when the route is newly registered, attaches
+    :class:`ProbeAccessLogFilter` to the uvicorn access logger. Browsers and
+    misconfigured clients that send GET instead of POST see a human-readable
+    explanation instead of a bare "Method Not Allowed" error.
 
     Args:
         mcp_instance: The FastMCP server to register the route on.
@@ -986,83 +987,13 @@ def register_browser_landing(
             access log (the handler logs an annotated replacement). Pass False
             for SSE, where a GET answers 200 and a 405 is a genuine fault.
     """
-    if path in _registered_landing_paths:
-        logger.warning(
-            "register_browser_landing: %r already registered, skipping", path
-        )
+    if not _register_landing_route(mcp_instance, path):
+        # Already registered for this path — don't double-attach the log filter.
         return
-    _registered_landing_paths.add(path)
-
-    _landing_message = (
-        "HA-MCP server is up and running!\n"
-        "\n"
-        "To connect, paste the full URL (including the /private_... key) into the\n"
-        "connector or MCP settings of your AI/LLM client. No username or password required.\n"
-        "Setup instructions: https://homeassistant-ai.github.io/ha-mcp/\n"
-        "\n"
-        "--- Seeing this page? Your URL is set up correctly ---\n"
-        "\n"
-        "If this page loads in your browser, the MCP server is reachable and the\n"
-        "URL is correct. If your AI client still cannot connect, the problem is\n"
-        "not on HA-MCP's side. Common causes:\n"
-        "\n"
-        "- Geo / country blocking in your reverse proxy / CDN (Cloudflare, NGINX,\n"
-        "  Traefik, Zoraxy, etc.). Most AI/LLM services connect from US-based\n"
-        "  cloud infrastructure, so if you block US IP addresses (or only allow\n"
-        "  your own country), that is why your client cannot connect. Allow your\n"
-        "  provider's IP ranges (or your client's egress IPs). For example,\n"
-        # Anthropic's documented outbound range; re-verify at
-        # https://platform.claude.com/docs/en/api/ip-addresses if it ever changes.
-        "  Claude.ai connects from Anthropic's network, 160.79.104.0/21.\n"
-        "- WAF, bot-blocking, or rate-limiting rules on the proxy that drop or\n"
-        "  challenge the request.\n"
-        "- The AI client's network can sometimes be spotty -- you may just need\n"
-        "  to try connecting again.\n"
-        "- The AI client itself refusing certain domains or proxy providers on\n"
-        "  its end. This is rare and outside your control; try a different\n"
-        "  hostname or proxy if you suspect it.\n"
-        "\n"
-        "Your proxy's access logs will show the blocked attempt -- look for the\n"
-        "request from your AI provider's IP (e.g. an Anthropic 160.79.x.x address).\n"
-        "\n"
-        "--- Cloudflare Users ---\n"
-        "\n"
-        'If your LLM cannot connect, Cloudflare\'s "Block AI training bots"\n'
-        "setting is the most common cause. To disable it:\n"
-        "\n"
-        "1. Log in to Cloudflare (https://dash.cloudflare.com)\n"
-        "2. In the left sidebar, click Domains, then click Overview\n"
-        "3. Click on the domain you use for connecting to Home Assistant\n"
-        '4. On the right side, find "Control AI Crawlers"\n'
-        '5. Under "Block AI training bots", open the dropdown\n'
-        '6. Select "do not block (allow crawlers)"\n'
-        "\n"
-        "Screenshot of the setting:\n"
-        "https://homeassistant-ai.github.io/ha-mcp/images/cloudflare-ai-crawlers-setting.jpg\n"
-    )
-
-    # Safe because FastMCP registers the MCP route with methods=["POST", "DELETE"]
-    # in stateless mode, so Starlette rejects GET requests before the MCP handler runs.
-    # Custom routes are registered at lowest precedence (after the MCP route).
-    @mcp_instance.custom_route(path, methods=["GET"])
-    async def _browser_landing(_: Request) -> PlainTextResponse:
-        # Any GET here is a non-MCP caller (browser, health check, proxy, or a
-        # connector's SSE-style pre-flight) hitting this POST-only Streamable HTTP
-        # endpoint, which answers 405 by design. Log one annotated line so the 405
-        # reads as expected; ProbeAccessLogFilter drops the raw uvicorn access line
-        # so there's no cryptic duplicate.
-        logger.info("GET %s -> 405 (NORMAL for most non-SSE connections)", path)
-        return PlainTextResponse(
-            _landing_message,
-            status_code=405,
-            # DELETE is included per the MCP Streamable HTTP spec (used for
-            # session termination), even though this deployment uses stateless mode.
-            headers={"Allow": "POST, DELETE"},
-        )
 
     # Tidy uvicorn's access log: always drop browser favicon 404s, and drop the
-    # raw by-design GET/HEAD-405 probe line on the MCP path (the handler above logs
-    # an annotated replacement). The 405 drop is skipped for SSE
+    # raw by-design GET/HEAD-405 probe line on the MCP path (the landing handler
+    # logs an annotated replacement). The 405 drop is skipped for SSE
     # (quiet_probe_log=False), where a GET answers 200 and a 405 is a real fault.
     # Attach to uvicorn.access directly — it has propagate=False, so a root-logger
     # filter would miss it.

ha_mcp_dev-7.10.0.dev779/src/ha_mcp/browser_landing.py

@@ -0,0 +1,138 @@
+"""Friendly browser landing page for the MCP endpoint (issue #777).
+
+A browser (or any GET client) that hits the POST-only Streamable HTTP MCP
+endpoint would otherwise see a bare "Method Not Allowed". This module registers
+a GET handler that answers ``405`` with a human-readable explanation plus the
+correct ``Allow`` header, so automated clients still get the right HTTP
+semantics.
+
+Extracted from :mod:`ha_mcp.__main__` so the in-process server (the
+``ha_mcp_tools`` custom-component worker thread) can register the same landing
+page. Importing ``ha_mcp.__main__`` runs process-global side effects at module
+load (``truststore.inject_into_ssl()``) that must never happen in-process, so
+the reusable core lives here — free of those side effects. ``__main__`` keeps a
+thin wrapper that additionally tidies the uvicorn access log.
+"""
+
+from __future__ import annotations
+
+import logging
+import weakref
+from typing import Any, Protocol
+
+from starlette.requests import Request
+from starlette.responses import PlainTextResponse
+
+logger = logging.getLogger(__name__)
+
+
+class CustomRouteServer(Protocol):
+    """Structural type for servers exposing FastMCP's ``custom_route`` decorator.
+
+    Matches the real FastMCP server and ``__main__``'s deferred proxy. Only the
+    ``(path, methods)`` call shape used here is pinned; the decorator's return
+    type is left to the implementation (fastmcp also takes optional ``name`` /
+    ``include_in_schema`` parameters this module never passes).
+    """
+
+    def custom_route(self, path: str, methods: list[str]) -> Any:
+        """Return a decorator that registers a handler for ``methods`` at ``path``."""
+
+
+# The landing body. Plain text so no browser ever interprets it as markup, and
+# so it survives the ha_mcp_tools webhook proxy (which forwards text/plain but
+# coerces text/html to JSON as an XSS guard).
+LANDING_MESSAGE = (
+    "HA-MCP server is up and running!\n"
+    "\n"
+    "To connect, paste the full URL (including the /private_... key) into the\n"
+    "connector or MCP settings of your AI/LLM client. No username or password required.\n"
+    "Setup instructions: https://homeassistant-ai.github.io/ha-mcp/\n"
+    "\n"
+    "--- Seeing this page? Your URL is set up correctly ---\n"
+    "\n"
+    "If this page loads in your browser, the MCP server is reachable and the\n"
+    "URL is correct. If your AI client still cannot connect, the problem is\n"
+    "not on HA-MCP's side. Common causes:\n"
+    "\n"
+    "- Geo / country blocking in your reverse proxy / CDN (Cloudflare, NGINX,\n"
+    "  Traefik, Zoraxy, etc.). Most AI/LLM services connect from US-based\n"
+    "  cloud infrastructure, so if you block US IP addresses (or only allow\n"
+    "  your own country), that is why your client cannot connect. Allow your\n"
+    "  provider's IP ranges (or your client's egress IPs). For example,\n"
+    # Anthropic's documented outbound range; re-verify at
+    # https://platform.claude.com/docs/en/api/ip-addresses if it ever changes.
+    "  Claude.ai connects from Anthropic's network, 160.79.104.0/21.\n"
+    "- WAF, bot-blocking, or rate-limiting rules on the proxy that drop or\n"
+    "  challenge the request.\n"
+    "- The AI client's network can sometimes be spotty -- you may just need\n"
+    "  to try connecting again.\n"
+    "- The AI client itself refusing certain domains or proxy providers on\n"
+    "  its end. This is rare and outside your control; try a different\n"
+    "  hostname or proxy if you suspect it.\n"
+    "\n"
+    "Your proxy's access logs will show the blocked attempt -- look for the\n"
+    "request from your AI provider's IP (e.g. an Anthropic 160.79.x.x address).\n"
+    "\n"
+    "--- Cloudflare Users ---\n"
+    "\n"
+    'If your LLM cannot connect, Cloudflare\'s "Block AI training bots"\n'
+    "setting is the most common cause. To disable it:\n"
+    "\n"
+    "1. Log in to Cloudflare (https://dash.cloudflare.com)\n"
+    "2. In the left sidebar, click Domains, then click Overview\n"
+    "3. Click on the domain you use for connecting to Home Assistant\n"
+    '4. On the right side, find "Control AI Crawlers"\n'
+    '5. Under "Block AI training bots", open the dropdown\n'
+    '6. Select "do not block (allow crawlers)"\n'
+    "\n"
+    "Screenshot of the setting:\n"
+    "https://homeassistant-ai.github.io/ha-mcp/images/cloudflare-ai-crawlers-setting.jpg\n"
+)
+
+# Landing routes already registered, keyed PER MCP INSTANCE (weakly, so a
+# discarded server never leaks). The key must not be the path alone: the
+# in-process server builds a NEW FastMCP on every config-entry reload in the
+# SAME Python process while keeping the same secret path — a process-global
+# path set would skip the re-registration and silently drop the landing page
+# after the first reload. The CLI/add-on never sees this (their process exits).
+_registered_landing_paths: weakref.WeakKeyDictionary[CustomRouteServer, set[str]] = (
+    weakref.WeakKeyDictionary()
+)
+
+
+def register_browser_landing(mcp_instance: CustomRouteServer, path: str) -> bool:
+    """Register a GET handler that returns 405 with the friendly landing message.
+
+    ``mcp_instance`` is a FastMCP-like object exposing ``custom_route`` (the real
+    server or ``__main__``'s deferred proxy). Returns True if the route was newly
+    registered, False if this instance already had one for ``path`` (idempotent
+    per instance + path).
+    """
+    paths = _registered_landing_paths.setdefault(mcp_instance, set())
+    if path in paths:
+        logger.warning(
+            "register_browser_landing: %r already registered, skipping", path
+        )
+        return False
+    paths.add(path)
+
+    # Safe because FastMCP registers the MCP route with methods=["POST", "DELETE"]
+    # in stateless mode, so Starlette rejects GET requests before the MCP handler
+    # runs. Custom routes are registered at lowest precedence (after the MCP route).
+    @mcp_instance.custom_route(path, methods=["GET"])
+    async def _browser_landing(_: Request) -> PlainTextResponse:
+        # Any GET here is a non-MCP caller (browser, health check, proxy, or a
+        # connector's SSE-style pre-flight) hitting this POST-only Streamable HTTP
+        # endpoint, which answers 405 by design. Log one annotated line so the 405
+        # reads as expected.
+        logger.info("GET %s -> 405 (NORMAL for most non-SSE connections)", path)
+        return PlainTextResponse(
+            LANDING_MESSAGE,
+            status_code=405,
+            # DELETE is included per the MCP Streamable HTTP spec (used for
+            # session termination), even though this deployment uses stateless mode.
+            headers={"Allow": "POST, DELETE"},
+        )
+
+    return True

{ha_mcp_dev-7.10.0.dev777 → ha_mcp_dev-7.10.0.dev779/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.10.0.dev777
+Version: 7.10.0.dev779
 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.10.0.dev777 → ha_mcp_dev-7.10.0.dev779}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ src/ha_mcp/__main__.py
 src/ha_mcp/_pypi_marker
 src/ha_mcp/_version.py
 src/ha_mcp/backup_manager.py
+src/ha_mcp/browser_landing.py
 src/ha_mcp/config.py
 src/ha_mcp/errors.py
 src/ha_mcp/py.typed