feat: add OAuth 2.1 authentication with DCR and consent form

Implements OAuth 2.1 authentication for ha-mcp using FastMCP's OAuthProvider pattern
with Dynamic Client Registration (DCR). This enables secure, zero-config authentication
for MCP clients like Claude.ai.

Features:
- HomeAssistantOAuthProvider subclass with full OAuth 2.1 support
- Consent form for collecting Home Assistant URL and Long-Lived Access Token
- LLAT validation against HA API before issuing auth codes
- Token management with refresh token support
- New `ha-mcp-oauth` entry point for OAuth-enabled server mode

The OAuth flow:
1. Claude.ai registers dynamically via DCR
2. User is redirected to consent form
3. User enters HA URL and LLAT
4. Credentials are validated against HA
5. Auth code is issued and exchanged for tokens

Closes #245

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: julienld

pyproject.toml

@@ -46,6 +46,7 @@ ha-mcp-smoke-test = "ha_mcp.smoke_test:main"
 hamcp-test-env = "tests.test_env_manager:main"
 ha-mcp-web = "ha_mcp.__main__:main_web"
 ha-mcp-sse = "ha_mcp.__main__:main_sse"
+ha-mcp-oauth = "ha_mcp.__main__:main_oauth"
 
 [tool.setuptools]
 package-dir = {"" = "src", "tests" = "tests"}

src/ha_mcp/__init__.py

@@ -9,6 +9,7 @@
 __author__ = "Julien"
 __license__ = "MIT"
 
+from .auth import HomeAssistantOAuthProvider
 from .client.rest_client import HomeAssistantClient
 from .config import Settings
 from .errors import (
@@ -32,6 +33,7 @@
     "Settings",
     "HomeAssistantClient",
     "HomeAssistantSmartMCPServer",
+    "HomeAssistantOAuthProvider",
     # Error handling exports
     "ErrorCode",
     "create_error_response",

src/ha_mcp/__main__.py

@@ -65,13 +65,15 @@ def _handle_config_error(error: Exception) -> None:
                     missing_vars.append(f"  - {field_loc[0]}")
 
         if missing_vars:
-            print(_CONFIG_ERROR_MESSAGE.format(
-                missing_vars="\n".join(missing_vars)
-            ), file=sys.stderr)
+            print(
+                _CONFIG_ERROR_MESSAGE.format(missing_vars="\n".join(missing_vars)),
+                file=sys.stderr,
+            )
             sys.exit(1)
 
     # For other validation errors, show the original error with guidance
-    print(f"""
+    print(
+        f"""
 ==============================================================================
                     Home Assistant MCP Server - Configuration Error
 ==============================================================================
@@ -82,18 +84,22 @@ def _handle_config_error(error: Exception) -> None:
   https://github.com/homeassistant-ai/ha-mcp#-installation
 
 ==============================================================================
-""", file=sys.stderr)
+""",
+        file=sys.stderr,
+    )
     sys.exit(1)
 
 
 def _create_server():
     """Create server instance (deferred to avoid import during smoke test)."""
     try:
         from ha_mcp.server import HomeAssistantSmartMCPServer  # type: ignore[import-not-found]
+
         return HomeAssistantSmartMCPServer()
     except Exception as e:
         # Check if this is a pydantic validation error (missing env vars)
         from pydantic import ValidationError
+
         if isinstance(e, ValidationError):
             _handle_config_error(e)
         raise
@@ -123,6 +129,7 @@ def _get_server():
 # This is accessed when the module is imported, so we need deferred creation
 class _DeferredMCP:
     """Wrapper that defers MCP creation until actually accessed."""
+
     def __getattr__(self, name: str) -> Any:
         return getattr(_get_mcp(), name)
 
@@ -142,6 +149,7 @@ async def _cleanup_resources() -> None:
     # Close WebSocket listener service if running
     try:
         from ha_mcp.client.websocket_listener import stop_websocket_listener
+
         await stop_websocket_listener()
         logger.debug("WebSocket listener stopped")
     except Exception as e:
@@ -150,6 +158,7 @@ async def _cleanup_resources() -> None:
     # Close WebSocket manager connections
     try:
         from ha_mcp.client.websocket_client import websocket_manager
+
         await websocket_manager.disconnect()
         logger.debug("WebSocket manager disconnected")
     except Exception as e:
@@ -241,8 +250,7 @@ async def _run_with_graceful_shutdown() -> None:
         # Clean up resources with timeout
         try:
             await asyncio.wait_for(
-                _cleanup_resources(),
-                timeout=SHUTDOWN_TIMEOUT_SECONDS
+                _cleanup_resources(), timeout=SHUTDOWN_TIMEOUT_SECONDS
             )
         except TimeoutError:
             logger.warning("Resource cleanup timed out")
@@ -269,6 +277,7 @@ def main() -> None:
     # Check for smoke test flag
     if "--smoke-test" in sys.argv:
         from ha_mcp.smoke_test import main as smoke_test_main
+
         sys.exit(smoke_test_main())
 
     # Configure logging before server creation
@@ -363,8 +372,7 @@ async def _run_http_with_graceful_shutdown(
         # Clean up resources with timeout
         try:
             await asyncio.wait_for(
-                _cleanup_resources(),
-                timeout=SHUTDOWN_TIMEOUT_SECONDS
+                _cleanup_resources(), timeout=SHUTDOWN_TIMEOUT_SECONDS
             )
         except TimeoutError:
             logger.warning("Resource cleanup timed out")
@@ -452,5 +460,127 @@ def main_sse() -> None:
     _run_http_server("sse", default_port=8087)
 
 
+def main_oauth() -> None:
+    """Run server with OAuth 2.1 authentication over HTTP.
+
+    This mode enables zero-config authentication for MCP clients like Claude.ai.
+    Users authenticate via a consent form where they enter their Home Assistant
+    URL and Long-Lived Access Token.
+
+    Environment:
+    - MCP_PORT (optional, default: 8086)
+    - MCP_SECRET_PATH (optional, default: "/mcp")
+    - MCP_BASE_URL (optional, default: http://localhost:{MCP_PORT})
+
+    Note: HOMEASSISTANT_URL and HOMEASSISTANT_TOKEN are NOT required in this mode.
+    They are collected via the OAuth consent form.
+    """
+    port = int(os.getenv("MCP_PORT", "8086"))
+    path = os.getenv("MCP_SECRET_PATH", "/mcp")
+    base_url = os.getenv("MCP_BASE_URL", f"http://localhost:{port}")
+
+    # Set up signal handlers
+    _setup_signal_handlers()
+
+    try:
+        asyncio.run(_run_oauth_server(base_url, port, path))
+    except KeyboardInterrupt:
+        logger.info("Interrupted, exiting")
+    except SystemExit:
+        raise
+    except Exception as e:
+        logger.error(f"OAuth server error: {e}")
+        sys.exit(1)
+
+    sys.exit(0)
+
+
+async def _run_oauth_server(base_url: str, port: int, path: str) -> None:
+    """Run the OAuth-authenticated MCP server."""
+    global _shutdown_event
+
+    from fastmcp import FastMCP
+    from ha_mcp.auth import HomeAssistantOAuthProvider
+
+    _shutdown_event = asyncio.Event()
+
+    # Create OAuth provider
+    auth_provider = HomeAssistantOAuthProvider(
+        base_url=base_url,
+        service_documentation_url="https://github.com/homeassistant-ai/ha-mcp",
+    )
+
+    # Create a minimal FastMCP server with OAuth
+    # Note: In OAuth mode, we create a simpler server that doesn't require
+    # pre-configured HA credentials. The tools will use credentials from OAuth.
+    mcp = FastMCP(
+        name="ha-mcp",
+        version="4.14.0",
+        auth=auth_provider,
+    )
+
+    # Register a simple tool to verify authentication works
+    @mcp.tool
+    async def get_ha_connection_info() -> dict:
+        """Get information about the authenticated Home Assistant connection."""
+        from fastmcp.server.dependencies import get_access_token
+
+        token = get_access_token()
+        if not token:
+            return {"error": "Not authenticated"}
+
+        # Get HA credentials from the OAuth provider
+        credentials = auth_provider.get_ha_credentials_for_token(token.token)
+        if not credentials:
+            return {"error": "No Home Assistant credentials found for this session"}
+
+        return {
+            "ha_url": credentials.ha_url,
+            "authenticated": True,
+            "validated_at": credentials.validated_at,
+        }
+
+    logger.info(f"Starting OAuth-enabled MCP server on {base_url}{path}")
+
+    # Run server
+    server_task = asyncio.create_task(
+        mcp.run_async(
+            transport="streamable-http",
+            host="0.0.0.0",
+            port=port,
+            path=path,
+        )
+    )
+
+    shutdown_task = asyncio.create_task(_shutdown_event.wait())
+
+    try:
+        done, pending = await asyncio.wait(
+            [server_task, shutdown_task],
+            return_when=asyncio.FIRST_COMPLETED,
+        )
+
+        if shutdown_task in done:
+            logger.info("Shutdown signal received, stopping OAuth server...")
+            server_task.cancel()
+            try:
+                await asyncio.wait_for(server_task, timeout=SHUTDOWN_TIMEOUT_SECONDS)
+            except TimeoutError:
+                logger.warning("OAuth server did not stop within timeout")
+            except asyncio.CancelledError:
+                pass
+
+    except asyncio.CancelledError:
+        logger.info("OAuth server task cancelled")
+    finally:
+        for task in [server_task, shutdown_task]:
+            if not task.done():
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+
+
 if __name__ == "__main__":
     main()

src/ha_mcp/auth/__init__.py

@@ -0,0 +1,10 @@
+"""
+OAuth 2.1 authentication for Home Assistant MCP Server.
+
+This module provides OAuth 2.1 authentication with Dynamic Client Registration (DCR)
+and a consent form for collecting Home Assistant credentials.
+"""
+
+from .provider import HomeAssistantOAuthProvider
+
+__all__ = ["HomeAssistantOAuthProvider"]