feat: add better error messages and hot reload (#183)

Author: arjunkmrm

python/.gitignore

@@ -82,6 +82,9 @@ target/
 profile_default/
 ipython_config.py
 
+# Other
+.spec
+
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "smithery"
-version = "0.1.22"
+version = "0.1.23"
 description = "SDK for using Smithery with Python"
 readme = "README.md"
 requires-python = ">=3.10"

python/src/smithery/cli/dev.py

@@ -4,7 +4,7 @@
 Command-line interface for running Smithery Python MCP servers.
 """
 
-import inspect
+import os
 import sys
 from collections.abc import Callable
 from importlib import import_module
@@ -14,7 +14,61 @@
 
 from ..server.fastmcp_patch import SmitheryFastMCP
 from ..utils.console import console
-from ..utils.project import get_server_ref_from_config
+
+
+def validate_project_setup() -> str:
+    """Project Discovery & Validation
+
+    Returns: server_reference string (e.g., "my_server.server:create_server")
+    Raises: SystemExit with clear error messages for each failure scenario
+    """
+    # 1. Find project root and validate pyproject.toml exists
+    if not os.path.exists("pyproject.toml"):
+        console.error("No pyproject.toml found in current directory")
+        console.nested("Make sure you're in a Python project directory")
+        console.indented("Expected file: [cyan]pyproject.toml[/cyan]")
+        sys.exit(1)
+
+    # 2. Read and parse pyproject.toml
+    try:
+        import tomllib
+        with open("pyproject.toml", "rb") as f:
+            pyproject = tomllib.load(f)
+    except Exception as e:
+        console.error(f"Failed to read pyproject.toml: {e}")
+        console.nested("Ensure pyproject.toml is valid TOML format")
+        sys.exit(1)
+
+    # 3. Extract [tool.smithery] section
+    tool_config = pyproject.get("tool", {})
+    smithery_config = tool_config.get("smithery", {})
+
+    if not smithery_config:
+        console.error("Missing \\[tool.smithery] configuration in pyproject.toml")
+        console.nested("Add to your pyproject.toml:")
+        console.indented("[cyan]\\[tool.smithery][/cyan]")
+        console.indented('[cyan]server = "my_server.server:create_server"[/cyan]')
+        sys.exit(1)
+
+    # 4. Get server reference
+    server_ref = smithery_config.get("server")
+    if not server_ref:
+        console.error("Missing 'server' in \\[tool.smithery] configuration")
+        console.nested("Add to your pyproject.toml:")
+        console.indented("[cyan]\\[tool.smithery][/cyan]")
+        console.indented('[cyan]server = "my_server.server:create_server"[/cyan]')
+        sys.exit(1)
+
+    # 5. Validate server reference format
+    if ":" not in server_ref:
+        console.error(f"Invalid server reference format: '{server_ref}'")
+        console.nested("Expected format: 'module.path:function_name'")
+        console.indented("Example: 'my_server.server:create_server'")
+        sys.exit(1)
+
+    console.info("✓ Project setup validated", muted=True)
+    console.rich_console.print(f"Server reference: [blue]{server_ref}[/blue]")
+    return server_ref
 
 
 class SmitheryModule(TypedDict, total=False):
@@ -24,142 +78,170 @@ class SmitheryModule(TypedDict, total=False):
 
 
 def import_server_module(server_ref: str) -> SmitheryModule:
-    """Import and validate Smithery server module."""
-    try:
-        if ":" not in server_ref:
-            raise ValueError(f"Server reference must include function name: '{server_ref}'. Expected format: 'module.path:function_name'")
+    """Module Resolution & Import
 
-        module_path, function_name = server_ref.split(":", 1)
+    Args: server_ref like "my_server.server:create_server"
+    Returns: SmitheryModule with function and optional config schema
+    Raises: SystemExit with clear error messages for import failures
+    """
+    module_path, function_name = server_ref.split(":", 1)
 
-        console.info(f"Importing module: {module_path}", muted=True)
-        console.info(f"Looking for function: {function_name}", muted=True)
+    console.info(f"Importing module: {module_path}", muted=True)
+    console.info(f"Looking for function: {function_name}", muted=True)
 
+    try:
+        # Import the module (assumes proper Python environment setup)
         module = import_module(module_path)
 
-        # Get the specified server function
+        # Check if function exists
         if not hasattr(module, function_name):
-            raise AttributeError(f"Function '{function_name}' not found in module '{module_path}'")
+            console.error(f"Function '{function_name}' not found in module '{module_path}'")
+            console.nested("Check your server module has the function specified in pyproject.toml")
+            console.indented(f"Expected: def {function_name}() in {module_path}")
+            sys.exit(1)
 
+        # Get the function
         server_function = getattr(module, function_name)
         if not callable(server_function):
-            raise AttributeError(f"'{function_name}' is not callable in module '{module_path}'")
-
-        # Validate function signature and return type
-        try:
-            sig = inspect.signature(server_function)
-            return_annotation = sig.return_annotation
-
-            # Check if return type annotation is present and correct
-            if return_annotation != inspect.Signature.empty:
-                if return_annotation != SmitheryFastMCP:
-                    annotation_name = getattr(return_annotation, '__name__', str(return_annotation))
-                    console.warning(f"Function return type is {annotation_name}, expected SmitheryFastMCP")
-            else:
-                console.warning("No return type annotation found. Expected: -> SmitheryFastMCP")
+            console.error(f"'{function_name}' is not callable in module '{module_path}'")
+            console.nested("The server reference must point to a function")
+            sys.exit(1)
 
-            # Check parameter signature
-            params = list(sig.parameters.values())
-            if len(params) != 1:
-                console.warning(f"Expected exactly 1 parameter (config), found {len(params)}")
-            elif len(params) == 1 and params[0].name not in ('config', 'cfg', 'configuration'):
-                console.warning(f"Parameter name '{params[0].name}' should be 'config' for clarity")
-
-        except Exception as e:
-            console.warning(f"Could not validate function signature: {e}")
-
-        # Get config schema - check decorator metadata first, then module-level variable
+        # Get config schema (optional)
         config_schema = None
-
-        # Priority 1: Check for decorator metadata
         if hasattr(server_function, '_smithery_config_schema'):
             config_schema = server_function._smithery_config_schema
             console.info("Using config schema from @smithery decorator", muted=True)
+        elif hasattr(module, 'config_schema'):
+            config_schema = module.config_schema
+            console.info("Using config schema from module-level variable", muted=True)
 
-        # Priority 2: Fall back to module-level variable (backward compatibility)
-        if not config_schema:
-            config_schema = getattr(module, 'config_schema', None)
-            if config_schema:
-                console.info("Using config schema from module-level variable", muted=True)
-
-        # Validate config schema if present
-        if config_schema and not (inspect.isclass(config_schema) and issubclass(config_schema, BaseModel)):
-            console.warning(f"config_schema should be a Pydantic BaseModel class, got {type(config_schema).__name__}")
-
+        console.info("✓ Module imported successfully", muted=True)
         return {
             'create_server': server_function,
             'config_schema': config_schema,
         }
-    except ModuleNotFoundError as e:
-        console.error(f"Failed to import server module '{server_ref}': {e}")
-        console.nested("Module resolution tips:")
-        console.indented("Make sure your package is built and installed:")
-        console.indented("  uv sync    # Install dependencies")
-        console.indented("  uv build   # Build the package")
-        console.indented("Or run in development mode:")
-        console.indented("  uv run dev # Uses editable install")
+
+    except ImportError as e:
+        console.error(f"Failed to import module '{module_path}': {e}")
+        console.nested("Make sure your project environment is set up correctly")
+        console.indented("Run: uv sync")
+        console.indented("Then: uv run smithery dev")
         sys.exit(1)
     except Exception as e:
-        console.error(f"Failed to import server module '{server_ref}': {e}")
-        console.nested("Expected configuration in pyproject.toml:")
-        console.indented("[tool.smithery]")
-        console.indented('server = "module.path:function_name"')
-        console.nested("Expected module contract:")
-        console.indented("function_name = function(config) -> SmitheryFastMCP")
-        console.indented("config_schema = class(BaseModel)  # Optional")
+        console.error(f"Unexpected error importing module '{module_path}': {e}")
         sys.exit(1)
 
 
-def run_server(server_ref: str, transport: str = "shttp", port: int = 8081, host: str = "127.0.0.1") -> None:
-    """Run Smithery MCP server."""
-    console.rich_console.print(f"Starting [cyan]Python MCP server[/cyan] with [yellow]{transport}[/yellow] transport...")
-    console.rich_console.print(f"Server reference: [green]{server_ref}[/green]")
+def create_and_run_server(
+    server_module: SmitheryModule,
+    transport: str = "shttp",
+    port: int = 8081,
+    host: str = "127.0.0.1",
+    reload: bool = False,
+    server_ref: str | None = None,
+) -> None:
+    """Server Creation & Execution
 
-    try:
-        # Import and validate server module
-        server_module = import_server_module(server_ref)
-        create_server = server_module['create_server']
-        config_schema = server_module.get('config_schema')
+    Args: server_module from Stage 2, transport settings
+    Raises: SystemExit with clear error messages for server creation/startup failures
+    """
+    create_server = server_module['create_server']
+    config_schema = server_module.get('config_schema')
 
+    console.info("Creating server instance...", muted=True)
+
+    try:
         # Create config instance
-        config: Any = {}
         if config_schema:
             try:
-                config = config_schema()
-                console.rich_console.print(f"Using config schema: [blue]{config_schema.__name__}[/blue]")
+                config_schema()
+                console.info(f"Using config schema: {config_schema.__name__}", muted=True)
             except Exception as e:
                 console.warning(f"Failed to instantiate config schema: {e}")
                 console.warning("Proceeding with empty config")
 
-        # Create server instance
-        console.info("Creating server instance...")
-        server = create_server(config)
+        # Call user's server creation function (no config parameter needed)
+        server = create_server()
+
+        # Validate server instance
+        if not hasattr(server, 'run'):
+            console.error("Server function must return a FastMCP server instance")
+            console.nested("Expected: return FastMCP(...)")
+            sys.exit(1)
 
+        console.rich_console.print("[green]✓ Server created successfully[/green]")
+
+        # Configure and start server
         if transport == "shttp":
-            # Set server configuration for HTTP transport
-            server.settings.port = port
-            server.settings.host = host
+            if reload:
+                try:
+                    import uvicorn  # type: ignore
+                except Exception:
+                    console.error("Reload requested but 'uvicorn' is not installed")
+                    console.nested("Install it in your project environment:")
+                    console.indented("uv add uvicorn  # or: pip install uvicorn")
+                    sys.exit(1)
+
+                # Pass server ref for reloader to reconstruct the app in a fresh interpreter
+                if server_ref:
+                    os.environ["SMITHERY_SERVER_REF"] = server_ref
+
+                console.info(f"Starting MCP server with reload on {host}:{port}")
+                console.info("Transport: streamable HTTP (uvicorn --reload)", muted=True)
+
+                # Use import string + factory so uvicorn can reload cleanly
+                uvicorn.run(
+                    "smithery.cli.dev:get_reloader_streamable_http_app",
+                    host=host,
+                    port=port,
+                    reload=True,
+                    factory=True,
+                )
+            else:
+                server.settings.port = port
+                server.settings.host = host
 
-            console.rich_console.print(f"MCP server starting on [green]{host}:{port}[/green]")
-            console.rich_console.print("Transport: [cyan]streamable HTTP[/cyan]")
+                console.info(f"Starting MCP server on {host}:{port}")
+                console.info("Transport: streamable HTTP", muted=True)
 
-            # Run with streamable HTTP transport
-            server.run(transport="streamable-http")
+                server.run(transport="streamable-http")
 
         elif transport == "stdio":
-            console.rich_console.print("MCP server starting with [cyan]stdio[/cyan] transport")
-
-            # Run with stdio transport
+            console.info("Starting MCP server with stdio transport")
             server.run(transport="stdio")
 
         else:
-            raise ValueError(f"Unsupported transport: {transport}")
+            console.error(f"Unsupported transport: {transport}")
+            console.nested("Supported transports: shttp, stdio")
+            sys.exit(1)
+
+    except Exception as e:
+        console.error(f"Failed to create or start server: {e}")
+        console.nested("Check your server function implementation")
+        sys.exit(1)
+
+
+def run_server(server_ref: str | None = None, transport: str = "shttp", port: int = 8081, host: str = "127.0.0.1", reload: bool = False) -> None:
+    """Run Smithery MCP server using clean 3-stage approach."""
+    console.rich_console.print(f"Starting [cyan]Python MCP server[/cyan] with [yellow]{transport}[/yellow] transport...")
+
+    try:
+        # Stage 1: Project Discovery & Validation
+        if server_ref is None:
+            server_ref = validate_project_setup()
+        else:
+            console.info(f"Using provided server reference: {server_ref}")
+
+        # Stage 2: Module Resolution & Import
+        server_module = import_server_module(server_ref)
+
+        # Stage 3: Server Creation & Execution
+        create_and_run_server(server_module, transport, port, host, reload, server_ref)
 
     except KeyboardInterrupt:
         console.info("\nServer stopped by user")
         sys.exit(0)
-    except Exception as e:
-        console.error(f"Failed to start MCP server: {e}")
-        sys.exit(1)
 
 
 def main() -> None:
@@ -174,15 +256,38 @@ def dev_cmd(
         server_ref: str | None = typer.Argument(None, help="Server reference (module:function)"),
         transport: str = typer.Option("shttp", help="Transport type (shttp or stdio)"),
         port: int = typer.Option(8081, help="Port to run on (shttp only)"),
-        host: str = typer.Option("127.0.0.1", help="Host to bind to (shttp only)")
+        host: str = typer.Option("127.0.0.1", help="Host to bind to (shttp only)"),
+        reload: bool = typer.Option(False, "--reload", help="Enable auto-reload (shttp only, requires uvicorn)")
     ):
         """Run Smithery MCP servers in development mode (like uvicorn)."""
-        # Get server reference from config if not provided explicitly
-        server_reference = server_ref or get_server_ref_from_config()
-        run_server(server_reference, transport, port, host)
+        if reload and transport != "shttp":
+            console.warning("--reload is only supported with 'shttp' transport; ignoring for stdio")
+        if reload and transport == "shttp":
+            console.warning(
+                "Hot reload resets in-memory server state; stateful clients may need to reinitialize their session after a reload."
+            )
+        run_server(server_ref, transport, port, host, reload)
 
     app()
 
 
 if __name__ == "__main__":
     main()
+
+# Factory used by uvicorn --reload (import-string target)
+def get_reloader_streamable_http_app():
+    """Return a fresh ASGI app for streamable HTTP using env SMITHERY_SERVER_REF.
+
+    This function is imported by Uvicorn in a fresh interpreter on reload.
+    It reconstructs the server from the configured server reference and returns
+    a new ASGI application callable.
+    """
+    server_ref = os.environ.get("SMITHERY_SERVER_REF")
+    if not server_ref:
+        raise RuntimeError("SMITHERY_SERVER_REF not set for reloader")
+
+    # Resolve and import
+    server_module = import_server_module(server_ref)
+    create_server = server_module['create_server']
+    server = create_server()
+    return server.streamable_http_app()