fastmcp 1.0__py3-none-any.whl → 2.1.0__py3-none-any.whl

fastmcp/__init__.py

@@ -1,8 +1,19 @@
-"""FastMCP - A more ergonomic interface for MCP servers."""
+"""FastMCP - An ergonomic MCP interface."""
 
 from importlib.metadata import version
-from .server import FastMCP, Context
-from .utilities.types import Image
+
+
+from fastmcp.server.server import FastMCP
+from fastmcp.server.context import Context
+from fastmcp.client import Client
+from fastmcp.utilities.types import Image
+from . import client, settings
 
 __version__ = version("fastmcp")
-__all__ = ["FastMCP", "Context", "Image"]
+__all__ = [
+    "FastMCP",
+    "Context",
+    "client",
+    "settings",
+    "Image",
+]

fastmcp/cli/__init__.py

@@ -2,6 +2,5 @@
 
 from .cli import app
 
-
 if __name__ == "__main__":
     app()

fastmcp/cli/claude.py

@@ -1,11 +1,12 @@
 """Claude app integration utilities."""
 
 import json
+import os
 import sys
 from pathlib import Path
-from typing import Optional, Dict
+from typing import Any
 
-from ..utilities.logging import get_logger
+from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
 
@@ -16,6 +17,10 @@ def get_claude_config_path() -> Path | None:
         path = Path(Path.home(), "AppData", "Roaming", "Claude")
     elif sys.platform == "darwin":
         path = Path(Path.home(), "Library", "Application Support", "Claude")
+    elif sys.platform.startswith("linux"):
+        path = Path(
+            os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"), "Claude"
+        )
     else:
         return None
 
@@ -28,9 +33,9 @@ def update_claude_config(
     file_spec: str,
     server_name: str,
     *,
-    with_editable: Optional[Path] = None,
-    with_packages: Optional[list[str]] = None,
-    env_vars: Optional[Dict[str, str]] = None,
+    with_editable: Path | None = None,
+    with_packages: list[str] | None = None,
+    env_vars: dict[str, str] | None = None,
 ) -> bool:
     """Add or update a FastMCP server in Claude's configuration.
 
@@ -49,8 +54,8 @@ def update_claude_config(
     config_dir = get_claude_config_path()
     if not config_dir:
         raise RuntimeError(
-            "Claude Desktop config directory not found. Please ensure Claude Desktop "
-            "is installed and has been run at least once to initialize its configuration."
+            "Claude Desktop config directory not found. Please ensure Claude Desktop"
+            " is installed and has been run at least once to initialize its config."
         )
 
     config_file = config_dir / "claude_desktop_config.json"
@@ -110,10 +115,7 @@ def update_claude_config(
         # Add fastmcp run command
         args.extend(["fastmcp", "run", file_spec])
 
-        server_config = {
-            "command": "uv",
-            "args": args,
-        }
+        server_config: dict[str, Any] = {"command": "uv", "args": args}
 
         # Add environment variables if specified
         if env_vars:

fastmcp/cli/cli.py

@@ -1,25 +1,30 @@
-"""FastMCP CLI tools."""
+"""FastmMCP CLI tools."""
 
 import importlib.metadata
 import importlib.util
 import os
+import platform
 import subprocess
 import sys
 from pathlib import Path
-from typing import Dict, Optional, Tuple
+from typing import Annotated
 
 import dotenv
 import typer
-from typing_extensions import Annotated
+from rich.console import Console
+from rich.table import Table
+from typer import Context, Exit
 
+import fastmcp
 from fastmcp.cli import claude
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger("cli")
+console = Console()
 
 app = typer.Typer(
     name="fastmcp",
-    help="FastMCP development tools",
+    help="FastMCP CLI",
     add_completion=False,
     no_args_is_help=True,  # Show help if no args provided
 )
@@ -41,7 +46,7 @@ def _get_npx_command():
     return "npx"  # On Unix-like systems, just use npx
 
 
-def _parse_env_var(env_var: str) -> Tuple[str, str]:
+def _parse_env_var(env_var: str) -> tuple[str, str]:
     """Parse environment variable string in format KEY=VALUE."""
     if "=" not in env_var:
         logger.error(
@@ -54,10 +59,10 @@ def _parse_env_var(env_var: str) -> Tuple[str, str]:
 
 def _build_uv_command(
     file_spec: str,
-    with_editable: Optional[Path] = None,
-    with_packages: Optional[list[str]] = None,
+    with_editable: Path | None = None,
+    with_packages: list[str] | None = None,
 ) -> list[str]:
-    """Build the uv run command that runs a FastMCP server through fastmcp run."""
+    """Build the uv run command that runs a MCP server through mcp run."""
     cmd = ["uv"]
 
     cmd.extend(["run", "--with", "fastmcp"])
@@ -70,12 +75,12 @@ def _build_uv_command(
             if pkg:
                 cmd.extend(["--with", pkg])
 
-    # Add fastmcp run command
+    # Add mcp run command
     cmd.extend(["fastmcp", "run", file_spec])
     return cmd
 
 
-def _parse_file_path(file_spec: str) -> Tuple[Path, Optional[str]]:
+def _parse_file_path(file_spec: str) -> tuple[Path, str | None]:
     """Parse a file path that may include a server object specification.
 
     Args:
@@ -106,8 +111,8 @@ def _parse_file_path(file_spec: str) -> Tuple[Path, Optional[str]]:
     return file_path, server_object
 
 
-def _import_server(file: Path, server_object: Optional[str] = None):
-    """Import a FastMCP server from a file.
+def _import_server(file: Path, server_object: str | None = None):
+    """Import a MCP server from a file.
 
     Args:
         file: Path to the file
@@ -172,14 +177,26 @@ def _import_server(file: Path, server_object: Optional[str] = None):
 
 
 @app.command()
-def version() -> None:
-    """Show the FastMCP version."""
-    try:
-        version = importlib.metadata.version("fastmcp")
-        print(f"FastMCP version {version}")
-    except importlib.metadata.PackageNotFoundError:
-        print("FastMCP version unknown (package not installed)")
-        sys.exit(1)
+def version(ctx: Context):
+    if ctx.resilient_parsing:
+        return
+
+    info = {
+        "FastMCP version": fastmcp.__version__,
+        "MCP version": importlib.metadata.version("mcp"),
+        "Python version": platform.python_version(),
+        "Platform": platform.platform(),
+        "FastMCP root path": f"~/{Path(__file__).resolve().parents[3].relative_to(Path.home())}",
+    }
+
+    g = Table.grid(padding=(0, 1))
+    g.add_column(style="bold", justify="left")
+    g.add_column(style="cyan", justify="right")
+    for k, v in info.items():
+        g.add_row(k + ":", str(v).replace("\n", " "))
+    console.print(g)
+
+    raise Exit()
 
 
 @app.command()
@@ -189,7 +206,7 @@ def dev(
         help="Python file to run, optionally with :object suffix",
     ),
     with_editable: Annotated[
-        Optional[Path],
+        Path | None,
         typer.Option(
             "--with-editable",
             "-e",
@@ -207,7 +224,7 @@ def dev(
         ),
     ] = [],
 ) -> None:
-    """Run a FastMCP server with the MCP Inspector."""
+    """Run a MCP server with the MCP Inspector."""
     file, server_object = _parse_file_path(file_spec)
 
     logger.debug(
@@ -273,7 +290,7 @@ def run(
         help="Python file to run, optionally with :object suffix",
     ),
     transport: Annotated[
-        Optional[str],
+        str | None,
         typer.Option(
             "--transport",
             "-t",
@@ -281,16 +298,16 @@ def run(
         ),
     ] = None,
 ) -> None:
-    """Run a FastMCP server.
+    """Run a MCP server.
 
-    The server can be specified in two ways:
-    1. Module approach: server.py - runs the module directly, expecting a server.run() call
-    2. Import approach: server.py:app - imports and runs the specified server object
+    The server can be specified in two ways:\n
+    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
 
     Note: This command runs the server directly. You are responsible for ensuring
-    all dependencies are available. For dependency management, use fastmcp install
-    or fastmcp dev instead.
-    """
+    all dependencies are available.\n
+    For dependency management, use `mcp install` or `mcp dev` instead.
+    """  # noqa: E501
     file, server_object = _parse_file_path(file_spec)
 
     logger.debug(
@@ -331,15 +348,16 @@ def install(
         help="Python file to run, optionally with :object suffix",
     ),
     server_name: Annotated[
-        Optional[str],
+        str | None,
         typer.Option(
             "--name",
             "-n",
-            help="Custom name for the server (defaults to server's name attribute or file name)",
+            help="Custom name for the server (defaults to server's name attribute or"
+            " file name)",
         ),
     ] = None,
     with_editable: Annotated[
-        Optional[Path],
+        Path | None,
         typer.Option(
             "--with-editable",
             "-e",
@@ -360,12 +378,12 @@ def install(
         list[str],
         typer.Option(
             "--env-var",
-            "-e",
+            "-v",
             help="Environment variables in KEY=VALUE format",
         ),
     ] = [],
     env_file: Annotated[
-        Optional[Path],
+        Path | None,
         typer.Option(
             "--env-file",
             "-f",
@@ -377,7 +395,7 @@ def install(
         ),
     ] = None,
 ) -> None:
-    """Install a FastMCP server in the Claude desktop app.
+    """Install a MCP server in the Claude desktop app.
 
     Environment variables are preserved once added and only updated if new values
     are explicitly provided.
@@ -399,7 +417,8 @@ def install(
         logger.error("Claude app not found")
         sys.exit(1)
 
-    # Try to import server to get its name, but fall back to file name if dependencies missing
+    # Try to import server to get its name, but fall back to file name if dependencies
+    # missing
     name = server_name
     server = None
     if not name:
@@ -408,7 +427,8 @@ def install(
             name = server.name
         except (ImportError, ModuleNotFoundError) as e:
             logger.debug(
-                "Could not import server (likely missing dependencies), using file name",
+                "Could not import server (likely missing dependencies), using file"
+                " name",
                 extra={"error": str(e)},
             )
             name = file.stem
@@ -419,7 +439,7 @@ def install(
         with_packages = list(set(with_packages + server_dependencies))
 
     # Process environment variables if provided
-    env_dict: Optional[Dict[str, str]] = None
+    env_dict: dict[str, str] | None = None
     if env_file or env_vars:
         env_dict = {}
         # Load from .env file if specified

fastmcp/client/__init__.py

@@ -0,0 +1,25 @@
+from .client import Client
+from .transports import (
+    ClientTransport,
+    WSTransport,
+    SSETransport,
+    StdioTransport,
+    PythonStdioTransport,
+    NodeStdioTransport,
+    UvxStdioTransport,
+    NpxStdioTransport,
+    FastMCPTransport,
+)
+
+__all__ = [
+    "Client",
+    "ClientTransport",
+    "WSTransport",
+    "SSETransport",
+    "StdioTransport",
+    "PythonStdioTransport",
+    "NodeStdioTransport",
+    "UvxStdioTransport",
+    "NpxStdioTransport",
+    "FastMCPTransport",
+]

fastmcp/client/base.py

@@ -0,0 +1 @@
+

fastmcp/client/client.py

@@ -0,0 +1,226 @@
+import datetime
+from contextlib import AbstractAsyncContextManager
+from pathlib import Path
+from typing import Any, Literal, cast, overload
+
+import mcp.types
+from mcp import ClientSession
+from mcp.client.session import (
+    LoggingFnT,
+    MessageHandlerFnT,
+)
+from pydantic import AnyUrl
+
+from fastmcp.client.roots import (
+    RootsHandler,
+    RootsList,
+    create_roots_callback,
+)
+from fastmcp.client.sampling import SamplingHandler, create_sampling_callback
+from fastmcp.server import FastMCP
+
+from .transports import ClientTransport, SessionKwargs, infer_transport
+
+__all__ = ["Client", "RootsHandler", "RootsList"]
+
+
+class ClientError(ValueError):
+    """Base class for errors raised by the client."""
+
+
+class Client:
+    """
+    MCP client that delegates connection management to a Transport instance.
+
+    The Client class is primarily concerned with MCP protocol logic,
+    while the Transport handles connection establishment and management.
+    """
+
+    def __init__(
+        self,
+        transport: ClientTransport | FastMCP | AnyUrl | Path | str,
+        # Common args
+        roots: RootsList | RootsHandler | None = None,
+        sampling_handler: SamplingHandler | None = None,
+        log_handler: LoggingFnT | None = None,
+        message_handler: MessageHandlerFnT | None = None,
+        read_timeout_seconds: datetime.timedelta | None = None,
+    ):
+        self.transport = infer_transport(transport)
+        self._session: ClientSession | None = None
+        self._session_cm: AbstractAsyncContextManager[ClientSession] | None = None
+
+        self._session_kwargs: SessionKwargs = {
+            "sampling_callback": None,
+            "list_roots_callback": None,
+            "logging_callback": log_handler,
+            "message_handler": message_handler,
+            "read_timeout_seconds": read_timeout_seconds,
+        }
+
+        if roots is not None:
+            self.set_roots(roots)
+
+        if sampling_handler is not None:
+            self.set_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."
+            )
+        return self._session
+
+    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)
+
+    def set_sampling_callback(self, sampling_callback: SamplingHandler) -> None:
+        """Set the sampling callback for the client."""
+        self._session_kwargs["sampling_callback"] = create_sampling_callback(
+            sampling_callback
+        )
+
+    def is_connected(self) -> bool:
+        """Check if the client is currently connected."""
+        return self._session is not None
+
+    async def __aenter__(self):
+        if self.is_connected():
+            raise RuntimeError("Client is already connected in an async context.")
+        try:
+            self._session_cm = self.transport.connect_session(**self._session_kwargs)
+            self._session = await self._session_cm.__aenter__()
+            return self
+        except Exception as e:
+            # Ensure cleanup if __aenter__ fails partially
+            self._session = None
+            self._session_cm = None
+            raise ConnectionError(
+                f"Failed to connect using {self.transport}: {e}"
+            ) from e
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        if self._session_cm:
+            await self._session_cm.__aexit__(exc_type, exc_val, exc_tb)
+        self._session = None
+        self._session_cm = None
+
+    # --- MCP Client Methods ---
+    async def ping(self) -> None:
+        """Send a ping request."""
+        await self.session.send_ping()
+
+    async def progress(
+        self,
+        progress_token: str | int,
+        progress: float,
+        total: float | None = None,
+    ) -> None:
+        """Send a progress notification."""
+        await self.session.send_progress_notification(progress_token, progress, total)
+
+    async def set_logging_level(self, level: mcp.types.LoggingLevel) -> None:
+        """Send a logging/setLevel request."""
+        await self.session.set_logging_level(level)
+
+    async def send_roots_list_changed(self) -> None:
+        """Send a roots/list_changed notification."""
+        await self.session.send_roots_list_changed()
+
+    async def list_resources(self) -> list[mcp.types.Resource]:
+        """Send a resources/list request."""
+        result = await self.session.list_resources()
+        return result.resources
+
+    async def list_resource_templates(self) -> list[mcp.types.ResourceTemplate]:
+        """Send a resources/listResourceTemplates request."""
+        result = await self.session.list_resource_templates()
+        return result.resourceTemplates
+
+    async def read_resource(
+        self, uri: AnyUrl | str
+    ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]:
+        """Send a resources/read request."""
+        if isinstance(uri, str):
+            uri = AnyUrl(uri)  # Ensure AnyUrl
+        result = await self.session.read_resource(uri)
+        return result.contents
+
+    # async def subscribe_resource(self, uri: AnyUrl | str) -> None:
+    #     """Send a resources/subscribe request."""
+    #     if isinstance(uri, str):
+    #         uri = AnyUrl(uri)
+    #     await self.session.subscribe_resource(uri)
+
+    # async def unsubscribe_resource(self, uri: AnyUrl | str) -> None:
+    #     """Send a resources/unsubscribe request."""
+    #     if isinstance(uri, str):
+    #         uri = AnyUrl(uri)
+    #     await self.session.unsubscribe_resource(uri)
+
+    async def list_prompts(self) -> list[mcp.types.Prompt]:
+        """Send a prompts/list request."""
+        result = await self.session.list_prompts()
+        return result.prompts
+
+    async def get_prompt(
+        self, name: str, arguments: dict[str, str] | None = None
+    ) -> mcp.types.GetPromptResult:
+        """Send a prompts/get request."""
+        result = await self.session.get_prompt(name, arguments)
+        return result
+
+    async def complete(
+        self,
+        ref: mcp.types.ResourceReference | mcp.types.PromptReference,
+        argument: dict[str, str],
+    ) -> mcp.types.Completion:
+        """Send a completion request."""
+        result = await self.session.complete(ref, argument)
+        return result.completion
+
+    async def list_tools(self) -> list[mcp.types.Tool]:
+        """Send a tools/list request."""
+        result = await self.session.list_tools()
+        return result.tools
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        _return_raw_result: Literal[False] = False,
+    ) -> list[
+        mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
+    ]: ...
+
+    @overload
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        _return_raw_result: Literal[True] = True,
+    ) -> mcp.types.CallToolResult: ...
+
+    async def call_tool(
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        _return_raw_result: bool = False,
+    ) -> (
+        list[
+            mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
+        ]
+        | mcp.types.CallToolResult
+    ):
+        """Send a tools/call request."""
+        result = await self.session.call_tool(name, arguments)
+        if _return_raw_result:
+            return result
+        elif result.isError:
+            msg = cast(mcp.types.TextContent, result.content[0]).text
+            raise ClientError(msg)
+        return result.content

fastmcp/client/roots.py

@@ -0,0 +1,75 @@
+import inspect
+from collections.abc import Awaitable, Callable
+from typing import TypeAlias
+
+import mcp.types
+import pydantic
+from mcp import ClientSession
+from mcp.client.session import ListRootsFnT
+from mcp.shared.context import LifespanContextT, RequestContext
+
+RootsList: TypeAlias = list[str] | list[mcp.types.Root] | list[str | mcp.types.Root]
+
+RootsHandler: TypeAlias = (
+    Callable[[RequestContext[ClientSession, LifespanContextT]], RootsList]
+    | Callable[[RequestContext[ClientSession, LifespanContextT]], Awaitable[RootsList]]
+)
+
+
+def convert_roots_list(roots: RootsList) -> list[mcp.types.Root]:
+    roots_list = []
+    for r in roots:
+        if isinstance(r, mcp.types.Root):
+            roots_list.append(r)
+        elif isinstance(r, pydantic.FileUrl):
+            roots_list.append(mcp.types.Root(uri=r))
+        elif isinstance(r, str):
+            roots_list.append(mcp.types.Root(uri=pydantic.FileUrl(r)))
+        else:
+            raise ValueError(f"Invalid root: {r}")
+    return roots_list
+
+
+def create_roots_callback(
+    handler: RootsList | RootsHandler,
+) -> ListRootsFnT:
+    if isinstance(handler, list):
+        return _create_roots_callback_from_roots(handler)
+    elif inspect.isfunction(handler):
+        return _create_roots_callback_from_fn(handler)
+    else:
+        raise ValueError(f"Invalid roots handler: {handler}")
+
+
+def _create_roots_callback_from_roots(
+    roots: RootsList,
+) -> ListRootsFnT:
+    roots = convert_roots_list(roots)
+
+    async def _roots_callback(
+        context: RequestContext[ClientSession, LifespanContextT],
+    ) -> mcp.types.ListRootsResult:
+        return mcp.types.ListRootsResult(roots=roots)
+
+    return _roots_callback
+
+
+def _create_roots_callback_from_fn(
+    fn: Callable[[RequestContext[ClientSession, LifespanContextT]], RootsList]
+    | Callable[[RequestContext[ClientSession, LifespanContextT]], Awaitable[RootsList]],
+) -> ListRootsFnT:
+    async def _roots_callback(
+        context: RequestContext[ClientSession, LifespanContextT],
+    ) -> mcp.types.ListRootsResult | mcp.types.ErrorData:
+        try:
+            roots = fn(context)
+            if inspect.isawaitable(roots):
+                roots = await roots
+            return mcp.types.ListRootsResult(roots=convert_roots_list(roots))
+        except Exception as e:
+            return mcp.types.ErrorData(
+                code=mcp.types.INTERNAL_ERROR,
+                message=str(e),
+            )
+
+    return _roots_callback