fastmcp 2.11.3__py3-none-any.whl → 2.12.0__py3-none-any.whl

fastmcp/cli/install/mcp_json.py

@@ -10,6 +10,7 @@ import pyperclip
 from rich import print
 
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
 
 from .shared import process_common_args
 
@@ -21,7 +22,7 @@ def install_mcp_json(
     server_object: str | None,
     name: str,
     *,
-    with_editable: Path | None = None,
+    with_editable: list[Path] | None = None,
     with_packages: list[str] | None = None,
     env_vars: dict[str, str] | None = None,
     copy: bool = False,
@@ -35,7 +36,7 @@ def install_mcp_json(
         file: Path to the server file
         server_object: Optional server object name (for :object suffix)
         name: Name for the server in MCP config
-        with_editable: Optional directory to install in editable mode
+        with_editable: Optional list of directories to install in editable mode
         with_packages: Optional list of additional packages to install
         env_vars: Optional dictionary of environment variables
         copy: If True, copy to clipboard instead of printing to stdout
@@ -47,45 +48,34 @@ def install_mcp_json(
         True if generation was successful, False otherwise
     """
     try:
-        # Build uv run command
-        args = ["run"]
-
-        # Add Python version if specified
-        if python_version:
-            args.extend(["--python", python_version])
-
-        # Add project if specified
-        if project:
-            args.extend(["--project", str(project)])
-
-        # Collect all packages in a set to deduplicate
-        packages = {"fastmcp"}
+        # Deduplicate packages and exclude 'fastmcp' since Environment adds it automatically
+        deduplicated_packages = None
         if with_packages:
-            packages.update(pkg for pkg in with_packages if pkg)
-
-        # Add all packages with --with
-        for pkg in sorted(packages):
-            args.extend(["--with", pkg])
-
-        if with_editable:
-            args.extend(["--with-editable", str(with_editable)])
-
-        if with_requirements:
-            args.extend(["--with-requirements", str(with_requirements)])
-
+            deduplicated = list(dict.fromkeys(with_packages))
+            deduplicated_packages = [pkg for pkg in deduplicated if pkg != "fastmcp"]
+            if not deduplicated_packages:
+                deduplicated_packages = None
+
+        env_config = UVEnvironment(
+            python=python_version,
+            dependencies=deduplicated_packages,
+            requirements=str(with_requirements) if with_requirements else None,
+            project=str(project) if project else None,
+            editable=[str(p) for p in with_editable] if with_editable else None,
+        )
         # Build server spec from parsed components
         if server_object:
             server_spec = f"{file.resolve()}:{server_object}"
         else:
             server_spec = str(file.resolve())
 
-        # Add fastmcp run command
-        args.extend(["fastmcp", "run", server_spec])
+        # Build the full command
+        full_command = env_config.build_command(["fastmcp", "run", server_spec])
 
         # Build MCP server configuration
         server_config = {
-            "command": "uv",
-            "args": args,
+            "command": full_command[0],
+            "args": full_command[1:],
         }
 
         # Add environment variables if provided
@@ -124,28 +114,29 @@ async def mcp_json_command(
         ),
     ] = None,
     with_editable: Annotated[
-        Path | None,
+        list[Path] | None,
         cyclopts.Parameter(
-            name=["--with-editable", "-e"],
-            help="Directory with pyproject.toml to install in editable mode",
+            "--with-editable",
+            help="Directory with pyproject.toml to install in editable mode (can be used multiple times)",
+            negative="",
         ),
     ] = None,
     with_packages: Annotated[
-        list[str],
+        list[str] | None,
         cyclopts.Parameter(
             "--with",
-            help="Additional packages to install",
-            negative=False,
+            help="Additional packages to install (can be used multiple times)",
+            negative="",
         ),
-    ] = [],
+    ] = None,
     env_vars: Annotated[
-        list[str],
+        list[str] | None,
         cyclopts.Parameter(
             "--env",
-            help="Environment variables in KEY=VALUE format",
-            negative=False,
+            help="Environment variables in KEY=VALUE format (can be used multiple times)",
+            negative="",
         ),
-    ] = [],
+    ] = None,
     env_file: Annotated[
         Path | None,
         cyclopts.Parameter(
@@ -158,7 +149,7 @@ async def mcp_json_command(
         cyclopts.Parameter(
             "--copy",
             help="Copy configuration to clipboard instead of printing to stdout",
-            negative=False,
+            negative="",
         ),
     ] = False,
     python: Annotated[
@@ -188,6 +179,10 @@ async def mcp_json_command(
     Args:
         server_spec: Python file to install, optionally with :object suffix
     """
+    # Convert None to empty lists for list parameters
+    with_editable = with_editable or []
+    with_packages = with_packages or []
+    env_vars = env_vars or []
     file, server_object, name, packages, env_dict = await process_common_args(
         server_spec, server_name, with_packages, env_vars, env_file
     )

fastmcp/cli/install/shared.py

@@ -1,13 +1,16 @@
 """Shared utilities for install commands."""
 
+import json
 import sys
 from pathlib import Path
 
 from dotenv import dotenv_values
+from pydantic import ValidationError
 from rich import print
 
-from fastmcp.cli.run import import_server, parse_file_path
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config import MCPServerConfig
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
 
 logger = get_logger(__name__)
 
@@ -26,13 +29,57 @@ def parse_env_var(env_var: str) -> tuple[str, str]:
 async def process_common_args(
     server_spec: str,
     server_name: str | None,
-    with_packages: list[str],
-    env_vars: list[str],
+    with_packages: list[str] | None,
+    env_vars: list[str] | None,
     env_file: Path | None,
 ) -> tuple[Path, str | None, str, list[str], dict[str, str] | None]:
-    """Process common arguments shared by all install commands."""
-    # Parse server spec
-    file, server_object = parse_file_path(server_spec)
+    """Process common arguments shared by all install commands.
+
+    Handles both fastmcp.json config files and traditional file.py:object syntax.
+    """
+    # Convert None to empty lists for list parameters
+    with_packages = with_packages or []
+    env_vars = env_vars or []
+    # Create MCPServerConfig from server_spec
+    config = None
+    if server_spec.endswith(".json"):
+        config_path = Path(server_spec).resolve()
+        if not config_path.exists():
+            print(f"[red]Configuration file not found: {config_path}[/red]")
+            sys.exit(1)
+
+        try:
+            with open(config_path) as f:
+                data = json.load(f)
+
+            # Check if it's an MCPConfig (has mcpServers key)
+            if "mcpServers" in data:
+                # MCPConfig files aren't supported for install
+                print("[red]MCPConfig files are not supported for installation[/red]")
+                sys.exit(1)
+            else:
+                # It's a MCPServerConfig
+                config = MCPServerConfig.from_file(config_path)
+
+                # Merge packages from config if not overridden
+                if config.environment.dependencies:
+                    # Merge with CLI packages (CLI takes precedence)
+                    config_packages = list(config.environment.dependencies)
+                    with_packages = list(set(with_packages + config_packages))
+        except (json.JSONDecodeError, ValidationError) as e:
+            print(f"[red]Invalid configuration file: {e}[/red]")
+            sys.exit(1)
+    else:
+        # Create config from file path
+        source = FileSystemSource(path=server_spec)
+        config = MCPServerConfig(source=source)
+
+    # Extract file and server_object from the source
+    # The FileSystemSource handles parsing path:object syntax
+    file = Path(config.source.path).resolve()
+    server_object = (
+        config.source.entrypoint if hasattr(config.source, "entrypoint") else None
+    )
 
     logger.debug(
         "Installing server",
@@ -49,7 +96,7 @@ async def process_common_args(
     server = None
     if not name:
         try:
-            server = await import_server(file, server_object)
+            server = await config.source.load_server()
             name = server.name
         except (ImportError, ModuleNotFoundError) as e:
             logger.debug(
@@ -59,8 +106,18 @@ async def process_common_args(
             name = file.stem
 
     # Get server dependencies if available
+    # TODO: Remove dependencies handling (deprecated in v2.11.4)
     server_dependencies = getattr(server, "dependencies", []) if server else []
     if server_dependencies:
+        import warnings
+
+        warnings.warn(
+            "Server uses deprecated 'dependencies' parameter (deprecated in FastMCP 2.11.4). "
+            "Please migrate to fastmcp.json configuration file. "
+            "See https://gofastmcp.com/docs/deployment/server-configuration for details.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         with_packages = list(set(with_packages + server_dependencies))
 
     # Process environment variables if provided

fastmcp/cli/run.py

@@ -1,12 +1,10 @@
 """FastMCP run command implementation with enhanced type hints."""
 
-import importlib.util
-import inspect
 import json
+import os
 import re
 import subprocess
 import sys
-from functools import partial
 from pathlib import Path
 from typing import Any, Literal
 
@@ -14,6 +12,11 @@ from mcp.server.fastmcp import FastMCP as FastMCP1x
 
 from fastmcp.server.server import FastMCP
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_server_config import (
+    MCPServerConfig,
+)
+from fastmcp.utilities.mcp_server_config.v1.environments.uv import UVEnvironment
+from fastmcp.utilities.mcp_server_config.v1.sources.filesystem import FileSystemSource
 
 logger = get_logger("cli.run")
 
@@ -28,154 +31,6 @@ def is_url(path: str) -> bool:
     return bool(url_pattern.match(path))
 
 
-def parse_file_path(server_spec: str) -> tuple[Path, str | None]:
-    """Parse a file path that may include a server object specification.
-
-    Args:
-        server_spec: Path to file, optionally with :object suffix
-
-    Returns:
-        Tuple of (file_path, server_object)
-    """
-    # First check if we have a Windows path (e.g., C:\...)
-    has_windows_drive = len(server_spec) > 1 and server_spec[1] == ":"
-
-    # Split on the last colon, but only if it's not part of the Windows drive letter
-    # and there's actually another colon in the string after the drive letter
-    if ":" in (server_spec[2:] if has_windows_drive else server_spec):
-        file_str, server_object = server_spec.rsplit(":", 1)
-    else:
-        file_str, server_object = server_spec, None
-
-    # Resolve the file path
-    file_path = Path(file_str).expanduser().resolve()
-    if not file_path.exists():
-        logger.error(f"File not found: {file_path}")
-        sys.exit(1)
-    if not file_path.is_file():
-        logger.error(f"Not a file: {file_path}")
-        sys.exit(1)
-
-    return file_path, server_object
-
-
-async def import_server(file: Path, server_or_factory: str | None = None) -> Any:
-    """Import a MCP server from a file.
-
-    Args:
-        file: Path to the file
-        server_or_factory: Optional object name in format "module:object" or just "object"
-
-    Returns:
-        The server object (or result of calling a factory function)
-    """
-    # Add parent directory to Python path so imports can be resolved
-    file_dir = str(file.parent)
-    if file_dir not in sys.path:
-        sys.path.insert(0, file_dir)
-
-    # Import the module
-    spec = importlib.util.spec_from_file_location("server_module", file)
-    if not spec or not spec.loader:
-        logger.error("Could not load module", extra={"file": str(file)})
-        sys.exit(1)
-
-    assert spec is not None
-    assert spec.loader is not None
-
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-
-    # If no object specified, try common server names
-    if not server_or_factory:
-        # Look for common server instance names
-        for name in ["mcp", "server", "app"]:
-            if hasattr(module, name):
-                obj = getattr(module, name)
-                return await _resolve_server_or_factory(obj, file, name)
-
-        logger.error(
-            f"No server object found in {file}. Please either:\n"
-            "1. Use a standard variable name (mcp, server, or app)\n"
-            "2. Specify the object name with file:object syntax",
-            extra={"file": str(file)},
-        )
-        sys.exit(1)
-
-    assert server_or_factory is not None
-
-    # Handle module:object syntax
-    if ":" in server_or_factory:
-        module_name, object_name = server_or_factory.split(":", 1)
-        try:
-            server_module = importlib.import_module(module_name)
-            obj = getattr(server_module, object_name, None)
-        except ImportError:
-            logger.error(
-                f"Could not import module '{module_name}'",
-                extra={"file": str(file)},
-            )
-            sys.exit(1)
-    else:
-        # Just object name
-        obj = getattr(module, server_or_factory, None)
-
-    if obj is None:
-        logger.error(
-            f"Server object '{server_or_factory}' not found",
-            extra={"file": str(file)},
-        )
-        sys.exit(1)
-
-    return await _resolve_server_or_factory(obj, file, server_or_factory)
-
-
-async def _resolve_server_or_factory(obj: Any, file: Path, name: str) -> Any:
-    """Resolve a server object or factory function to a server instance.
-
-    Args:
-        obj: The object that might be a server or factory function
-        file: Path to the file for error messages
-        name: Name of the object for error messages
-
-    Returns:
-        A server instance
-    """
-    # Check if it's a function or coroutine function
-    if inspect.isfunction(obj) or inspect.iscoroutinefunction(obj):
-        logger.debug(f"Found factory function '{name}' in {file}")
-
-        try:
-            if inspect.iscoroutinefunction(obj):
-                # Async factory function
-                server = await obj()
-            else:
-                # Sync factory function
-                server = obj()
-
-            # Validate the result is a FastMCP server
-            if not isinstance(server, FastMCP | FastMCP1x):
-                logger.error(
-                    f"Factory function '{name}' must return a FastMCP server instance, "
-                    f"got {type(server).__name__}",
-                    extra={"file": str(file)},
-                )
-                sys.exit(1)
-
-            logger.debug(f"Factory function '{name}' created server: {server.name}")
-            return server
-
-        except Exception as e:
-            logger.error(
-                f"Failed to call factory function '{name}': {e}",
-                extra={"file": str(file)},
-            )
-            sys.exit(1)
-
-    # Not a function, return as-is (should be a server instance)
-    return obj
-
-
 def run_with_uv(
     server_spec: str,
     python_version: str | None = None,
@@ -188,11 +43,16 @@ def run_with_uv(
     path: str | None = None,
     log_level: LogLevelType | None = None,
     show_banner: bool = True,
+    editable: str | list[str] | None = None,
 ) -> None:
     """Run a MCP server using uv run subprocess.
 
+    This function is called when we need to set up a Python environment with specific
+    dependencies before running the server. The config parsing and merging should already
+    be done by the caller.
+
     Args:
-        server_spec: Python file, object specification (file:obj), or URL
+        server_spec: Python file, object specification (file:obj), config file, or URL
         python_version: Python version to use (e.g. "3.10")
         with_packages: Additional packages to install
         with_requirements: Requirements file to use
@@ -203,51 +63,49 @@ def run_with_uv(
         path: Path to bind to when using http transport
         log_level: Log level
         show_banner: Whether to show the server banner
+        editable: Editable package paths
     """
-    cmd = ["uv", "run"]
-
-    # Add Python version if specified
-    if python_version:
-        cmd.extend(["--python", python_version])
-
-    # Add project if specified
-    if project:
-        cmd.extend(["--project", str(project)])
-
-    # Add fastmcp package
-    cmd.extend(["--with", "fastmcp"])
-
-    # Add additional packages
-    if with_packages:
-        for pkg in with_packages:
-            if pkg:
-                cmd.extend(["--with", pkg])
-
-    # Add requirements file
-    if with_requirements:
-        cmd.extend(["--with-requirements", str(with_requirements)])
 
-    # Add fastmcp run command
-    cmd.extend(["fastmcp", "run", server_spec])
-
-    # Add transport options
+    # Build uv command using Environment.build_uv_run_command()
+    env_config = UVEnvironment(
+        python=python_version,
+        dependencies=with_packages if with_packages else None,
+        requirements=str(with_requirements.resolve()) if with_requirements else None,
+        project=str(project.resolve()) if project else None,
+        editable=editable
+        if isinstance(editable, list)
+        else ([editable] if editable else None),
+    )
+
+    # Build the inner fastmcp command (environment variable prevents infinite recursion)
+    inner_cmd = ["fastmcp", "run", server_spec]
+
+    # Add transport options to the inner command
     if transport:
-        cmd.extend(["--transport", transport])
-    if host:
-        cmd.extend(["--host", host])
-    if port:
-        cmd.extend(["--port", str(port)])
-    if path:
-        cmd.extend(["--path", path])
+        inner_cmd.extend(["--transport", transport])
+    # Only add HTTP-specific options for non-stdio transports
+    if transport != "stdio":
+        if host:
+            inner_cmd.extend(["--host", host])
+        if port:
+            inner_cmd.extend(["--port", str(port)])
+        if path:
+            inner_cmd.extend(["--path", path])
     if log_level:
-        cmd.extend(["--log-level", log_level])
+        inner_cmd.extend(["--log-level", log_level])
     if not show_banner:
-        cmd.append("--no-banner")
+        inner_cmd.append("--no-banner")
+
+    # Build the full uv command
+    cmd = env_config.build_command(inner_cmd)
+
+    # Set marker to prevent infinite loops when subprocess calls FastMCP again
+    env = os.environ | {"FASTMCP_UV_SPAWNED": "1"}
 
     # Run the command
     logger.debug(f"Running command: {' '.join(cmd)}")
     try:
-        process = subprocess.run(cmd, check=True)
+        process = subprocess.run(cmd, check=True, env=env)
         sys.exit(process.returncode)
     except subprocess.CalledProcessError as e:
         logger.error(f"Failed to run server: {e}")
@@ -285,30 +143,21 @@ def create_mcp_config_server(mcp_config_path: Path) -> FastMCP[None]:
     return server
 
 
-async def import_server_with_args(
-    file: Path,
-    server_or_factory: str | None = None,
-    server_args: list[str] | None = None,
-) -> Any:
-    """Import a server with optional command line arguments.
+def load_mcp_server_config(config_path: Path) -> MCPServerConfig:
+    """Load a FastMCP configuration from a fastmcp.json file.
 
     Args:
-        file: Path to the server file
-        server_or_factory: Optional server object or factory function name
-        server_args: Optional command line arguments to inject
+        config_path: Path to fastmcp.json file
 
     Returns:
-        The imported server object
+        MCPServerConfig object
     """
-    if server_args:
-        original_argv = sys.argv[:]
-        try:
-            sys.argv = [str(file)] + server_args
-            return await import_server(file, server_or_factory)
-        finally:
-            sys.argv = original_argv
-    else:
-        return await import_server(file, server_or_factory)
+    config = MCPServerConfig.from_file(config_path)
+
+    # Apply runtime settings from deployment config
+    config.deployment.apply_runtime_settings(config_path)
+
+    return config
 
 
 async def run_command(
@@ -321,11 +170,12 @@ async def run_command(
     server_args: list[str] | None = None,
     show_banner: bool = True,
     use_direct_import: bool = False,
+    skip_source: bool = False,
 ) -> None:
     """Run a MCP server or connect to a remote one.
 
     Args:
-        server_spec: Python file, object specification (file:obj), MCPConfig file, or URL
+        server_spec: Python file, object specification (file:obj), config file, or URL
         transport: Transport protocol to use
         host: Host to bind to when using http transport
         port: Port to bind to when using http transport
@@ -334,18 +184,73 @@ async def run_command(
         server_args: Additional arguments to pass to the server
         show_banner: Whether to show the server banner
         use_direct_import: Whether to use direct import instead of subprocess
+        skip_source: Whether to skip source preparation step
     """
+    # Special case: URLs
     if is_url(server_spec):
         # Handle URL case
         server = create_client_server(server_spec)
         logger.debug(f"Created client proxy server for {server_spec}")
+    # Special case: MCPConfig files (legacy)
     elif server_spec.endswith(".json"):
-        server = create_mcp_config_server(Path(server_spec))
+        # Load JSON and check which type of config it is
+        config_path = Path(server_spec)
+        with open(config_path) as f:
+            data = json.load(f)
+
+        # Check if it's an MCPConfig first (has canonical mcpServers key)
+        if "mcpServers" in data:
+            # It's an MCP config
+            server = create_mcp_config_server(config_path)
+        else:
+            # It's a FastMCP config - load it properly
+            config = load_mcp_server_config(config_path)
+
+            # Merge deployment config with CLI arguments (CLI takes precedence)
+            transport = transport or config.deployment.transport
+            host = host or config.deployment.host
+            port = port or config.deployment.port
+            path = path or config.deployment.path
+            log_level = log_level or config.deployment.log_level
+            server_args = (
+                server_args if server_args is not None else config.deployment.args
+            )
+
+            # Prepare source only (environment is handled by uv run)
+            await config.prepare_source() if not skip_source else None
+
+            # Load the server using the source
+            from contextlib import nullcontext
+
+            from fastmcp.cli.cli import with_argv
+
+            # Use sys.argv context manager if deployment args specified
+            argv_context = with_argv(server_args) if server_args else nullcontext()
+
+            with argv_context:
+                server = await config.source.load_server()
+
+            logger.debug(f'Found server "{server.name}" from config {config_path}')
     else:
-        # Handle file case
-        file, server_or_factory = parse_file_path(server_spec)
-        server = await import_server_with_args(file, server_or_factory, server_args)
-        logger.debug(f'Found server "{server.name}" in {file}')
+        # Regular file case - create a MCPServerConfig with FileSystemSource
+        source = FileSystemSource(path=server_spec)
+        config = MCPServerConfig(source=source)
+
+        # Prepare source only (environment is handled by uv run)
+        await config.prepare_source() if not skip_source else None
+
+        # Load the server
+        from contextlib import nullcontext
+
+        from fastmcp.cli.cli import with_argv
+
+        # Use sys.argv context manager if server_args specified
+        argv_context = with_argv(server_args) if server_args else nullcontext()
+
+        with argv_context:
+            server = await config.source.load_server()
+
+        logger.debug(f'Found server "{server.name}" in {source.path}')
 
     # Run the server
 
@@ -363,8 +268,8 @@ async def run_command(
         kwargs["port"] = port
     if path:
         kwargs["path"] = path
-    if log_level:
-        kwargs["log_level"] = log_level
+    # Note: log_level is not currently supported by run_async
+    # TODO: Add log_level support to server.run_async
 
     if not show_banner:
         kwargs["show_banner"] = False
@@ -382,6 +287,8 @@ def run_v1_server(
     port: int | None = None,
     transport: TransportType | None = None,
 ) -> None:
+    from functools import partial
+
     if host:
         server.settings.host = host
     if port: