fix: resolve Docker environment variable validation error (#354) (#356)

* fix: resolve Docker environment variable validation error (#354)

- Revert fastmcp config files to use hardcoded port/path values
  - fastmcp-http.json: port 8086, path "/mcp"
  - fastmcp-sse.json: port 8087, path "/mcp"
  - fastmcp-webclient.json: port 8086, path "/mcp"
- Update Docker docs to use ha-mcp-web command instead of fastmcp run
- Add documentation for customizing port/path via environment variables

Root cause: FastMCP doesn't expand ${VAR:-default} syntax in JSON before
Pydantic validates. The ha-mcp-web command reads MCP_PORT and MCP_SECRET_PATH
environment variables directly in Python code (__main__.py:304-305).

Fixes #354

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

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

* fix: use correct default port for ha-mcp-sse (8087)

- Update _get_http_runtime to accept default_port parameter
- Set ha-mcp-sse to use port 8087 (was incorrectly using 8086)
- Add documentation note about Docker port mapping

Addresses code review feedback from Gemini Code Assist:
- Prevents port conflict between ha-mcp-web (8086) and ha-mcp-sse (8087)
- Clarifies that both -p and MCP_PORT must match for custom ports

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

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

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: julienld

fastmcp-http.json

@@ -7,8 +7,8 @@
   "deployment": {
     "transport": "streamable-http",
     "host": "0.0.0.0",
-    "port": "${MCP_PORT:-8086}",
-    "path": "${MCP_SECRET_PATH:-/mcp}",
+    "port": 8086,
+    "path": "/mcp",
     "env": {
       "HOMEASSISTANT_URL": "${HOMEASSISTANT_URL}",
       "HOMEASSISTANT_TOKEN": "${HOMEASSISTANT_TOKEN}"

fastmcp-sse.json

@@ -7,8 +7,8 @@
   "deployment": {
     "transport": "sse",
     "host": "0.0.0.0",
-    "port": "${MCP_PORT:-8087}",
-    "path": "${MCP_SECRET_PATH:-/mcp}",
+    "port": 8087,
+    "path": "/mcp",
     "env": {
       "HOMEASSISTANT_URL": "${HOMEASSISTANT_URL}",
       "HOMEASSISTANT_TOKEN": "${HOMEASSISTANT_TOKEN}"

fastmcp-webclient.json

@@ -7,8 +7,8 @@
   "deployment": {
     "transport": "streamable-http",
     "host": "0.0.0.0",
-    "port": "${MCP_PORT:-8086}",
-    "path": "${MCP_SECRET_PATH:-/mcp}",
+    "port": 8086,
+    "path": "/mcp",
     "env": {
       "HOMEASSISTANT_URL": "${HOMEASSISTANT_URL}",
       "HOMEASSISTANT_TOKEN": "${HOMEASSISTANT_TOKEN}"

site/src/content/deployment/docker.md

@@ -38,11 +38,28 @@ docker run -d --name ha-mcp \
   -e HOMEASSISTANT_URL=http://homeassistant.local:8123 \
   -e HOMEASSISTANT_TOKEN=your_token \
   ghcr.io/homeassistant-ai/ha-mcp:latest \
-  fastmcp run fastmcp-http.json
+  ha-mcp-web
 ```
 
 Server will be available at: `http://YOUR_IP:8086/mcp`
 
+**Customize port and path:**
+
+```bash
+docker run -d --name ha-mcp \
+  -p 9000:9000 \
+  -e HOMEASSISTANT_URL=http://homeassistant.local:8123 \
+  -e HOMEASSISTANT_TOKEN=your_token \
+  -e MCP_PORT=9000 \
+  -e MCP_SECRET_PATH=/my-secret-path \
+  ghcr.io/homeassistant-ai/ha-mcp:latest \
+  ha-mcp-web
+```
+
+Server URL: `http://YOUR_IP:9000/my-secret-path`
+
+> **Note:** Both the Docker port mapping (`-p 9000:9000`) and the `MCP_PORT` environment variable must match the desired port. The first number in `-p` is the host port, the second is the container port (which matches `MCP_PORT`).
+
 ### Management Commands
 
 ```bash
@@ -80,7 +97,7 @@ docker run -d --name ha-mcp \
   -e SSL_CERT_FILE=/certs/ca-bundle.crt \
   -v /path/to/combined-ca-bundle.crt:/certs/ca-bundle.crt:ro \
   ghcr.io/homeassistant-ai/ha-mcp:latest \
-  fastmcp run fastmcp-http.json
+  ha-mcp-web
 ```
 
 ## Requirements

src/ha_mcp/__main__.py

@@ -298,10 +298,14 @@ def main() -> None:
 
 
 # HTTP entry point for web clients
-def _get_http_runtime() -> tuple[int, str]:
-    """Return runtime configuration shared by HTTP transports."""
+def _get_http_runtime(default_port: int = 8086) -> tuple[int, str]:
+    """Return runtime configuration shared by HTTP transports.
 
-    port = int(os.getenv("MCP_PORT", "8086"))
+    Args:
+        default_port: Default port to use if MCP_PORT env var is not set.
+    """
+
+    port = int(os.getenv("MCP_PORT", str(default_port)))
     path = os.getenv("MCP_SECRET_PATH", "/mcp")
     return port, path
 
@@ -375,9 +379,14 @@ async def _run_http_with_graceful_shutdown(
                     pass
 
 
-def _run_http_server(transport: str) -> None:
-    """Common runner for HTTP-based transports."""
-    port, path = _get_http_runtime()
+def _run_http_server(transport: str, default_port: int = 8086) -> None:
+    """Common runner for HTTP-based transports.
+
+    Args:
+        transport: Transport type (streamable-http or sse).
+        default_port: Default port to use if MCP_PORT env var is not set.
+    """
+    port, path = _get_http_runtime(default_port)
 
     # Set up signal handlers before running
     _setup_signal_handlers()
@@ -420,7 +429,7 @@ def main_web() -> None:
         format='%(asctime)s %(name)s %(levelname)s: %(message)s'
     )
 
-    _run_http_server("streamable-http")
+    _run_http_server("streamable-http", default_port=8086)
 
 
 def main_sse() -> None:
@@ -429,7 +438,7 @@ def main_sse() -> None:
     Environment:
     - HOMEASSISTANT_URL (required)
     - HOMEASSISTANT_TOKEN (required)
-    - MCP_PORT (optional, default: 8086)
+    - MCP_PORT (optional, default: 8087)
     - MCP_SECRET_PATH (optional, default: "/mcp")
     """
     # Configure logging before server creation
@@ -440,7 +449,7 @@ def main_sse() -> None:
         format='%(asctime)s %(name)s %(levelname)s: %(message)s'
     )
 
-    _run_http_server("sse")
+    _run_http_server("sse", default_port=8087)
 
 
 if __name__ == "__main__":