fix: upgrade to FastMCP v3.0.0 (#657)

Fixes #654

Upgrade from FastMCP v2 to v3.0.0 to resolve silent server crashes on
connection. FastMCP v3 properly supports the 2025-11-25 protocol version
that modern MCP clients (Claude Desktop 1.1+) negotiate.

Breaking API changes addressed:
- get_tools() removed → list_tools() (returns list, not dict)
- _tool_manager internal removed → use public list_tools() in smoke test
- FASTMCP_SHOW_CLI_BANNER renamed → FASTMCP_SHOW_SERVER_BANNER
- transport="streamable-http" deprecated → transport="http"
- log_level= kwarg removed from run() → use logging.basicConfig()
- TYPE_CHECKING import mcp.server.fastmcp → fastmcp

Also improves addon crash diagnostics: catches BaseException (including
SystemExit) and logs full traceback + chained cause to stderr, so
FastMCP crashes are never silent.

Author: sergeykad

fastmcp-http.json

@@ -5,7 +5,7 @@
     "entrypoint": "mcp"
   },
   "deployment": {
-    "transport": "streamable-http",
+    "transport": "http",
     "host": "0.0.0.0",
     "port": 8086,
     "path": "/mcp",

fastmcp-webclient.json

@@ -5,7 +5,7 @@
     "entrypoint": "mcp"
   },
   "deployment": {
-    "transport": "streamable-http",
+    "transport": "http",
     "host": "0.0.0.0",
     "port": 8086,
     "path": "/mcp",

homeassistant-addon/start.py

@@ -132,28 +132,42 @@ def main() -> int:
     log_info("=" * 80)
     log_info("")
 
+    # Configure logging before server start (v3 removed log_level from run())
+    import logging
+    logging.basicConfig(level=logging.INFO)
+
     # Import and run MCP server directly
     try:
         log_info("Importing ha_mcp module...")
         from ha_mcp.__main__ import _get_timestamped_uvicorn_log_config, mcp
 
         log_info("Starting MCP server...")
         mcp.run(
-            transport="streamable-http",
+            transport="http",
             host="0.0.0.0",
             port=port,
             path=secret_path,
-            log_level="info",
             stateless_http=True,
             uvicorn_config={"log_config": _get_timestamped_uvicorn_log_config()},
         )
-    except Exception as e:
-        log_error(f"Failed to start MCP server: {e}")
+    except KeyboardInterrupt:
+        log_info("Interrupted, exiting")
+        return 0
+    except BaseException as e:
         import traceback
 
-        traceback.print_exc()
+        log_error(f"MCP server crashed: {e}")
+        traceback.print_exc(file=sys.stderr)
+        # Log the root cause if this exception was chained
+        cause = e.__cause__ or e.__context__
+        if cause:
+            log_error(f"Caused by: {cause}")
+            traceback.print_exception(type(cause), cause, cause.__traceback__, file=sys.stderr)
+        if isinstance(e, SystemExit):
+            return int(e.code) if isinstance(e.code, int) else 1
         return 1
 
+    log_info("MCP server stopped")
     return 0
 
 

pyproject.toml

@@ -24,7 +24,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "fastmcp>=2.11.0,<3.0.0",  # Pin: v3.0.0 has breaking changes (see #644, #645, #648)
+    "fastmcp>=3.0.0,<4.0.0",
     "mcp>=1.24.0",  # Required for protocol version 2025-11-25 support (see #651)
     "httpx[socks]>=0.27.0,<1.0",
     'jq>=1.8.0; sys_platform != "win32"',

site/src/content/clients/antigravity.md

@@ -32,14 +32,14 @@ Google Antigravity supports MCP servers via the built-in MCP Store and custom co
       "env": {
         "HOMEASSISTANT_URL": "{{HOMEASSISTANT_URL}}",
         "HOMEASSISTANT_TOKEN": "{{HOMEASSISTANT_TOKEN}}",
-        "FASTMCP_SHOW_CLI_BANNER": "false"
+        "FASTMCP_SHOW_SERVER_BANNER": "false"
       }
     }
   }
 }
 ```
 
-> **Note:** `FASTMCP_SHOW_CLI_BANNER=false` disables the startup banner, which prevents "Unexpected server output" errors in Antigravity.
+> **Note:** `FASTMCP_SHOW_SERVER_BANNER=false` disables the startup banner, which prevents "Unexpected server output" errors in Antigravity.
 
 **Important:** Use absolute paths if specifying a local command. Restart the Agent session after saving.
 
@@ -59,7 +59,7 @@ Google Antigravity supports MCP servers via the built-in MCP Store and custom co
 
 ## Troubleshooting
 
-- **"Unexpected server output" error:** Add `"FASTMCP_SHOW_CLI_BANNER": "false"` to your env config (see example above)
+- **"Unexpected server output" error:** Add `"FASTMCP_SHOW_SERVER_BANNER": "false"` to your env config (see example above)
 - **Tools load but fail when called:** Try stdio mode instead of HTTP
 - **"EOF" errors:** Ensure command paths are absolute, not relative
 - **First run timeout:** Run `uvx ha-mcp@latest --version` in terminal first to cache the package

src/ha_mcp/__main__.py

@@ -236,10 +236,10 @@ def _validate_standard_credentials(settings) -> None:
 
 
 def _get_show_banner() -> bool:
-    """Check if CLI banner should be shown (respects FASTMCP_SHOW_CLI_BANNER env var)."""
+    """Check if server banner should be shown (respects FASTMCP_SHOW_SERVER_BANNER env var)."""
     import fastmcp
 
-    return fastmcp.settings.show_cli_banner
+    return fastmcp.settings.show_server_banner
 
 
 def _setup_standard_mode() -> None:
@@ -563,7 +563,7 @@ 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).
+        transport: Transport type (http or sse).
         default_port: Default port to use if MCP_PORT env var is not set.
     """
     port, path = _get_http_runtime(default_port)
@@ -584,7 +584,7 @@ def main_web() -> None:
     - MCP_SECRET_PATH (optional, default: "/mcp")
     """
     _setup_standard_mode()
-    _run_http_server("streamable-http", default_port=8086)
+    _run_http_server("http", default_port=8086)
 
 
 def main_sse() -> None:
@@ -665,13 +665,13 @@ async def _run_oauth_server(base_url: str, port: int, path: str) -> None:
 
     logger.info("Server created with OAuthProxyClient")
 
-    tools = await mcp.get_tools()
+    tools = await mcp.list_tools()
     logger.info(
         f"Starting OAuth-enabled MCP server with {len(tools)} tools on {base_url}{path}"
     )
 
     await _run_with_shutdown(
-        mcp.run_async(**_http_run_kwargs("streamable-http", port, path))
+        mcp.run_async(**_http_run_kwargs("http", port, path))
     )
 
 

src/ha_mcp/smoke_test.py

@@ -74,16 +74,18 @@ def main() -> int:
     # Test 4: Tool discovery
     print("\n[4/4] Testing tool discovery...")
     try:
-        # Access the tools from the MCP instance
-        tool_count = len(mcp._tool_manager._tools)
+        import asyncio
+
+        tools = asyncio.run(mcp.list_tools())
+        tool_count = len(tools)
         print(f"  ✓ Discovered {tool_count} tools")
 
         if tool_count < 50:
             errors.append(f"Too few tools discovered: {tool_count} (expected 50+)")
             print("  ✗ Tool count too low (expected 50+)")
         else:
             # List a few tool names as examples
-            tool_names = list(mcp._tool_manager._tools.keys())[:5]
+            tool_names = [t.name for t in tools[:5]]
             print(f"  ✓ Sample tools: {', '.join(tool_names)}...")
     except Exception as e:
         errors.append(f"Failed to discover tools: {e}")

src/ha_mcp/tools/backup.py

@@ -16,7 +16,7 @@
 from .helpers import get_connected_ws_client, log_tool_usage
 
 if TYPE_CHECKING:
-    from mcp.server.fastmcp import FastMCP
+    from fastmcp import FastMCP
 
 logger = logging.getLogger(__name__)
 

tests/src/e2e/conftest.py

@@ -326,7 +326,7 @@ async def mcp_server(
 
     # Create server with the client
     server = HomeAssistantSmartMCPServer(client=client)
-    tools = await server.mcp.get_tools()
+    tools = await server.mcp.list_tools()
     logger.info(
         f"✅ MCP server initialized with {len(tools)} tools connected to {base_url}"
     )

tests/src/unit/test_graceful_shutdown.py

@@ -385,8 +385,8 @@ def mock_setup():
 class TestHTTPEntryPoints:
     """Tests for HTTP entry points (main_web, main_sse)."""
 
-    def test_main_web_uses_streamable_http_transport(self):
-        """main_web should use streamable-http transport."""
+    def test_main_web_uses_http_transport(self):
+        """main_web should use http transport."""
         import ha_mcp.__main__ as main_module
 
         transport_used = None
@@ -407,7 +407,7 @@ def mock_run_http(transport, default_port=8086):
         }), patch.object(main_module, "_run_http_server", side_effect=mock_run_http), pytest.raises(SystemExit):
             main_module.main_web()
 
-        assert transport_used == "streamable-http"
+        assert transport_used == "http"
 
     def test_main_sse_uses_sse_transport(self):
         """main_sse should use sse transport."""