fastmcp 2.3.4__py3-none-any.whl → 2.3.5__py3-none-any.whl

fastmcp/cli/cli.py

@@ -17,6 +17,7 @@ from typer import Context, Exit
 
 import fastmcp
 from fastmcp.cli import claude
+from fastmcp.cli import run as run_module
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger("cli")
@@ -58,7 +59,7 @@ def _parse_env_var(env_var: str) -> tuple[str, str]:
 
 
 def _build_uv_command(
-    file_spec: str,
+    server_spec: str,
     with_editable: Path | None = None,
     with_packages: list[str] | None = None,
 ) -> list[str]:
@@ -76,106 +77,10 @@ def _build_uv_command(
                 cmd.extend(["--with", pkg])
 
     # Add mcp run command
-    cmd.extend(["fastmcp", "run", file_spec])
+    cmd.extend(["fastmcp", "run", server_spec])
     return cmd
 
 
-def _parse_file_path(file_spec: str) -> tuple[Path, str | None]:
-    """Parse a file path that may include a server object specification.
-
-    Args:
-        file_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(file_spec) > 1 and file_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 (file_spec[2:] if has_windows_drive else file_spec):
-        file_str, server_object = file_spec.rsplit(":", 1)
-    else:
-        file_str, server_object = file_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
-
-
-def _import_server(file: Path, server_object: str | None = None):
-    """Import a MCP server from a file.
-
-    Args:
-        file: Path to the file
-        server_object: Optional object name in format "module:object" or just "object"
-
-    Returns:
-        The server object
-    """
-    # 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)
-
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-
-    # If no object specified, try common server names
-    if not server_object:
-        # Look for the most common server object names
-        for name in ["mcp", "server", "app"]:
-            if hasattr(module, name):
-                return getattr(module, 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)
-
-    # Handle module:object syntax
-    if ":" in server_object:
-        module_name, object_name = server_object.split(":", 1)
-        try:
-            server_module = importlib.import_module(module_name)
-            server = 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
-        server = getattr(module, server_object, None)
-
-    if server is None:
-        logger.error(
-            f"Server object '{server_object}' not found",
-            extra={"file": str(file)},
-        )
-        sys.exit(1)
-
-    return server
-
-
 @app.command()
 def version(ctx: Context):
     if ctx.resilient_parsing:
@@ -201,7 +106,7 @@ def version(ctx: Context):
 
 @app.command()
 def dev(
-    file_spec: str = typer.Argument(
+    server_spec: str = typer.Argument(
         ...,
         help="Python file to run, optionally with :object suffix",
     ),
@@ -246,7 +151,7 @@ def dev(
     ] = None,
 ) -> None:
     """Run a MCP server with the MCP Inspector."""
-    file, server_object = _parse_file_path(file_spec)
+    file, server_object = run_module.parse_file_path(server_spec)
 
     logger.debug(
         "Starting dev server",
@@ -262,8 +167,8 @@ def dev(
 
     try:
         # Import server to get dependencies
-        server = _import_server(file, server_object)
-        if hasattr(server, "dependencies"):
+        server = run_module.import_server(file, server_object)
+        if hasattr(server, "dependencies") and server.dependencies is not None:
             with_packages = list(set(with_packages + server.dependencies))
 
         env_vars = {}
@@ -285,7 +190,7 @@ def dev(
         if inspector_version:
             inspector_cmd += f"@{inspector_version}"
 
-        uv_cmd = _build_uv_command(file_spec, with_editable, with_packages)
+        uv_cmd = _build_uv_command(server_spec, with_editable, with_packages)
 
         # Run the MCP Inspector command with shell=True on Windows
         shell = sys.platform == "win32"
@@ -318,9 +223,9 @@ def dev(
 
 @app.command()
 def run(
-    file_spec: str = typer.Argument(
+    server_spec: str = typer.Argument(
         ...,
-        help="Python file to run, optionally with :object suffix",
+        help="Python file, object specification (file:obj), or URL",
     ),
     transport: Annotated[
         str | None,
@@ -354,22 +259,20 @@ def run(
         ),
     ] = None,
 ) -> None:
-    """Run a MCP server.
+    """Run a MCP server or connect to a remote one.
 
-    The server can be specified in two ways:
-    1. Module approach: server.py - runs the module directly, expecting a server.run() call.\n
-    2. Import approach: server.py:app - imports and runs the specified server object.\n\n
+    The server can be specified in three ways:
+    1. Module approach: server.py - runs the module directly, looking for an object named mcp/server/app.\n
+    2. Import approach: server.py:app - imports and runs the specified server object.\n
+    3. URL approach: http://server-url - connects to a remote server and creates a proxy.\n\n
 
     Note: This command runs the server directly. You are responsible for ensuring
     all dependencies are available.
     """
-    file, server_object = _parse_file_path(file_spec)
-
     logger.debug(
-        "Running server",
+        "Running server or client",
         extra={
-            "file": str(file),
-            "server_object": server_object,
+            "server_spec": server_spec,
             "transport": transport,
             "host": host,
             "port": port,
@@ -378,29 +281,18 @@ def run(
     )
 
     try:
-        # Import and get server object
-        server = _import_server(file, server_object)
-
-        logger.info(f'Found server "{server.name}" in {file}')
-
-        # Run the server
-        kwargs = {}
-        if transport:
-            kwargs["transport"] = transport
-        if host:
-            kwargs["host"] = host
-        if port:
-            kwargs["port"] = port
-        if log_level:
-            kwargs["log_level"] = log_level
-
-        server.run(**kwargs)
-
+        run_module.run_command(
+            server_spec=server_spec,
+            transport=transport,
+            host=host,
+            port=port,
+            log_level=log_level,
+        )
     except Exception as e:
         logger.error(
-            f"Failed to run server: {e}",
+            f"Failed to run: {e}",
             extra={
-                "file": str(file),
+                "server_spec": server_spec,
                 "error": str(e),
             },
         )
@@ -409,7 +301,7 @@ def run(
 
 @app.command()
 def install(
-    file_spec: str = typer.Argument(
+    server_spec: str = typer.Argument(
         ...,
         help="Python file to run, optionally with :object suffix",
     ),
@@ -466,7 +358,7 @@ def install(
     Environment variables are preserved once added and only updated if new values
     are explicitly provided.
     """
-    file, server_object = _parse_file_path(file_spec)
+    file, server_object = run_module.parse_file_path(server_spec)
 
     logger.debug(
         "Installing server",
@@ -489,7 +381,7 @@ def install(
     server = None
     if not name:
         try:
-            server = _import_server(file, server_object)
+            server = run_module.import_server(file, server_object)
             name = server.name
         except (ImportError, ModuleNotFoundError) as e:
             logger.debug(
@@ -526,7 +418,7 @@ def install(
             env_dict[key] = value
 
     if claude.update_claude_config(
-        file_spec,
+        server_spec,
         name,
         with_editable=with_editable,
         with_packages=with_packages,

fastmcp/cli/run.py

@@ -0,0 +1,179 @@
+"""FastMCP run command implementation."""
+
+import importlib.util
+import re
+import sys
+from pathlib import Path
+from typing import Any, Literal
+
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger("cli.run")
+
+TransportType = Literal["stdio", "streamable-http", "sse"]
+
+
+def is_url(path: str) -> bool:
+    """Check if a string is a URL."""
+    url_pattern = re.compile(r"^https?://")
+    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
+
+
+def import_server(file: Path, server_object: str | None = None) -> Any:
+    """Import a MCP server from a file.
+
+    Args:
+        file: Path to the file
+        server_object: Optional object name in format "module:object" or just "object"
+
+    Returns:
+        The server object
+    """
+    # 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)
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    # If no object specified, try common server names
+    if not server_object:
+        # Look for the most common server object names
+        for name in ["mcp", "server", "app"]:
+            if hasattr(module, name):
+                return getattr(module, 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)
+
+    # Handle module:object syntax
+    if ":" in server_object:
+        module_name, object_name = server_object.split(":", 1)
+        try:
+            server_module = importlib.import_module(module_name)
+            server = 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
+        server = getattr(module, server_object, None)
+
+    if server is None:
+        logger.error(
+            f"Server object '{server_object}' not found",
+            extra={"file": str(file)},
+        )
+        sys.exit(1)
+
+    return server
+
+
+def create_client_server(url: str) -> Any:
+    """Create a FastMCP server from a client URL.
+
+    Args:
+        url: The URL to connect to
+
+    Returns:
+        A FastMCP server instance
+    """
+    try:
+        import fastmcp
+
+        client = fastmcp.Client(url)
+        server = fastmcp.FastMCP.from_client(client)
+        return server
+    except Exception as e:
+        logger.error(f"Failed to create client for URL {url}: {e}")
+        sys.exit(1)
+
+
+def run_command(
+    server_spec: str,
+    transport: str | None = None,
+    host: str | None = None,
+    port: int | None = None,
+    log_level: str | None = None,
+) -> None:
+    """Run a MCP server or connect to a remote one.
+
+    Args:
+        server_spec: Python file, object specification (file:obj), 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
+        log_level: Log level
+    """
+    if is_url(server_spec):
+        # Handle URL case
+        server = create_client_server(server_spec)
+        logger.debug(f"Created client proxy server for {server_spec}")
+    else:
+        # Handle file case
+        file, server_object = parse_file_path(server_spec)
+        server = import_server(file, server_object)
+        logger.debug(f'Found server "{server.name}" in {file}')
+
+    # Run the server
+    kwargs = {}
+    if transport:
+        kwargs["transport"] = transport
+    if host:
+        kwargs["host"] = host
+    if port:
+        kwargs["port"] = port
+    if log_level:
+        kwargs["log_level"] = log_level
+
+    try:
+        server.run(**kwargs)
+    except Exception as e:
+        logger.error(f"Failed to run server: {e}")
+        sys.exit(1)

fastmcp/client/client.py

@@ -1,5 +1,5 @@
 import datetime
-from contextlib import AsyncExitStack
+from contextlib import AsyncExitStack, asynccontextmanager
 from pathlib import Path
 from typing import Any, cast
 
@@ -8,7 +8,8 @@ from exceptiongroup import catch
 from mcp import ClientSession
 from pydantic import AnyUrl
 
-from fastmcp.client.logging import LogHandler, MessageHandler
+from fastmcp.client.logging import LogHandler, MessageHandler, default_log_handler
+from fastmcp.client.progress import ProgressHandler, default_progress_handler
 from fastmcp.client.roots import (
     RootsHandler,
     RootsList,
@@ -28,6 +29,7 @@ __all__ = [
     "LogHandler",
     "MessageHandler",
     "SamplingHandler",
+    "ProgressHandler",
 ]
 
 
@@ -50,6 +52,7 @@ class Client:
         sampling_handler: Optional handler for sampling requests
         log_handler: Optional handler for log messages
         message_handler: Optional handler for protocol messages
+        progress_handler: Optional handler for progress notifications
         timeout: Optional timeout for requests (seconds or timedelta)
 
     Examples:
@@ -74,12 +77,22 @@ class Client:
         sampling_handler: SamplingHandler | None = None,
         log_handler: LogHandler | None = None,
         message_handler: MessageHandler | None = None,
+        progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
     ):
         self.transport = infer_transport(transport)
         self._session: ClientSession | None = None
         self._exit_stack: AsyncExitStack | None = None
         self._nesting_counter: int = 0
+        self._initialize_result: mcp.types.InitializeResult | None = None
+
+        if log_handler is None:
+            log_handler = default_log_handler
+
+        if progress_handler is None:
+            progress_handler = default_progress_handler
+
+        self._progress_handler = progress_handler
 
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=timeout)
@@ -96,17 +109,28 @@ class Client:
             self.set_roots(roots)
 
         if sampling_handler is not None:
-            self.set_sampling_callback(sampling_handler)
+            self._session_kwargs["sampling_callback"] = create_sampling_callback(
+                sampling_handler
+            )
 
     @property
     def session(self) -> ClientSession:
         """Get the current active session. Raises RuntimeError if not connected."""
         if self._session is None:
             raise RuntimeError(
-                "Client is not connected. Use 'async with client:' context manager first."
+                "Client is not connected. Use the 'async with client:' context manager first."
             )
         return self._session
 
+    @property
+    def initialize_result(self) -> mcp.types.InitializeResult:
+        """Get the result of the initialization request."""
+        if self._initialize_result is None:
+            raise RuntimeError(
+                "Client is not connected. Use the 'async with client:' context manager first."
+            )
+        return self._initialize_result
+
     def set_roots(self, roots: RootsList | RootsHandler) -> None:
         """Set the roots for the client. This does not automatically call `send_roots_list_changed`."""
         self._session_kwargs["list_roots_callback"] = create_roots_callback(roots)
@@ -121,27 +145,35 @@ class Client:
         """Check if the client is currently connected."""
         return self._session is not None
 
+    @asynccontextmanager
+    async def _context_manager(self):
+        with catch(get_catch_handlers()):
+            async with self.transport.connect_session(
+                **self._session_kwargs
+            ) as session:
+                self._session = session
+                # Initialize the session
+                self._initialize_result = await self._session.initialize()
+
+                try:
+                    yield
+                finally:
+                    self._exit_stack = None
+                    self._session = None
+                    self._initialize_result = None
+
     async def __aenter__(self):
         if self._nesting_counter == 0:
             # Create exit stack to manage both context managers
             stack = AsyncExitStack()
             await stack.__aenter__()
 
-            # Add the exception handling context
-            stack.enter_context(catch(get_catch_handlers()))
+            await stack.enter_async_context(self._context_manager())
 
-            # the above catch will only apply once this __aenter__ finishes so
-            # we need to wrap the session creation in a new context in case it
-            # raises errors itself
-            with catch(get_catch_handlers()):
-                # Create and enter the transport session using the exit stack
-                session_cm = self.transport.connect_session(**self._session_kwargs)
-                self._session = await stack.enter_async_context(session_cm)
-
-            # Store the stack for cleanup in __aexit__
             self._exit_stack = stack
 
         self._nesting_counter += 1
+
         return self
 
     async def __aexit__(self, exc_type, exc_val, exc_tb):
@@ -154,7 +186,6 @@ class Client:
                     await self._exit_stack.__aexit__(exc_type, exc_val, exc_tb)
                 finally:
                     self._exit_stack = None
-                    self._session = None
 
     # --- MCP Client Methods ---
 
@@ -168,9 +199,12 @@ class Client:
         progress_token: str | int,
         progress: float,
         total: float | None = None,
+        message: str | None = None,
     ) -> None:
         """Send a progress notification."""
-        await self.session.send_progress_notification(progress_token, progress, total)
+        await self.session.send_progress_notification(
+            progress_token, progress, total, message
+        )
 
     async def set_logging_level(self, level: mcp.types.LoggingLevel) -> None:
         """Send a logging/setLevel request."""
@@ -430,6 +464,7 @@ class Client:
         self,
         name: str,
         arguments: dict[str, Any],
+        progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
     ) -> mcp.types.CallToolResult:
         """Send a tools/call request and return the complete MCP protocol result.
@@ -441,6 +476,8 @@ class Client:
             name (str): The name of the tool to call.
             arguments (dict[str, Any]): Arguments to pass to the tool.
             timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
+            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
+
         Returns:
             mcp.types.CallToolResult: The complete response object from the protocol,
                 containing the tool result and any additional metadata.
@@ -452,7 +489,10 @@ class Client:
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=timeout)
         result = await self.session.call_tool(
-            name=name, arguments=arguments, read_timeout_seconds=timeout
+            name=name,
+            arguments=arguments,
+            read_timeout_seconds=timeout,
+            progress_callback=progress_handler or self._progress_handler,
         )
         return result
 
@@ -461,6 +501,7 @@ class Client:
         name: str,
         arguments: dict[str, Any] | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        progress_handler: ProgressHandler | None = None,
     ) -> list[
         mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
     ]:
@@ -471,6 +512,8 @@ class Client:
         Args:
             name (str): The name of the tool to call.
             arguments (dict[str, Any] | None, optional): Arguments to pass to the tool. Defaults to None.
+            timeout (datetime.timedelta | float | int | None, optional): The timeout for the tool call. Defaults to None.
+            progress_handler (ProgressHandler | None, optional): The progress handler to use for the tool call. Defaults to None.
 
         Returns:
             list[mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource]:
@@ -484,6 +527,7 @@ class Client:
             name=name,
             arguments=arguments or {},
             timeout=timeout,
+            progress_handler=progress_handler,
         )
         if result.isError:
             msg = cast(mcp.types.TextContent, result.content[0]).text

fastmcp/client/logging.py

@@ -6,8 +6,16 @@ from mcp.client.session import (
 )
 from mcp.types import LoggingMessageNotificationParams
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 LogMessage: TypeAlias = LoggingMessageNotificationParams
 LogHandler: TypeAlias = LoggingFnT
 MessageHandler: TypeAlias = MessageHandlerFnT
 
 __all__ = ["LogMessage", "LogHandler", "MessageHandler"]
+
+
+async def default_log_handler(params: LogMessage) -> None:
+    logger.debug(f"Log received: {params}")