fastmcp 2.10.1__tar.gz → 2.10.2__tar.gz

{fastmcp-2.10.1 → fastmcp-2.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastmcp
-Version: 2.10.1
+Version: 2.10.2
 Summary: The fast, Pythonic way to build MCP servers.
 Project-URL: Homepage, https://gofastmcp.com
 Project-URL: Repository, https://github.com/jlowin/fastmcp

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/clients/client.mdx

@@ -176,7 +176,7 @@ async with client:
     
     # Execute a tool
     result = await client.call_tool("multiply", {"a": 5, "b": 3})
-    print(result[0].text)  # "15"
+    print(result.data)  # 15
 ```
 
 See [Tools](/clients/tools) for detailed documentation.

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/integrations/chatgpt.mdx

@@ -135,7 +135,8 @@ Replace `https://your-server-url.com` with the actual URL of your server (such a
 2. Click **Add custom connector**
 3. Enter your server details:
    - **Name**: Library Catalog
-   - **URL**: Your server URL (e.g., `https://abc123.ngrok.io`)
+   - **URL**: Your server URL, including the path.
+        - **Note**: Ensure your URL includes the correct path for the transport you’re using. The defaults are /sse/ for SSE (e.g., https://abc123.ngrok.io/sse/) and /mcp/ for HTTP (e.g., https://abc123.ngrok.io/mcp/).
    - **Description**: A library catalog for searching and retrieving books
 
 #### Test the Connection

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/patterns/cli.mdx

@@ -46,6 +46,7 @@ This command runs the server directly in your current Python environment. You ar
 | Host | `--host` | Host to bind to when using http transport (default: 127.0.0.1) |
 | Port | `--port`, `-p` | Port to bind to when using http transport (default: 8000) |
 | Log Level | `--log-level`, `-l` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
+| No Banner | `--no-banner` | Disable the startup banner display |
 
 
 #### Server Specification

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/patterns/testing.mdx

@@ -22,7 +22,7 @@ from fastmcp import FastMCP, Client
 def mcp_server():
     server = FastMCP("TestServer")
     
-@server.tool
+    @server.tool
     def greet(name: str) -> str:
         return f"Hello, {name}!"
         
@@ -32,7 +32,17 @@ async def test_tool_functionality(mcp_server):
     # Pass the server directly to the Client constructor
     async with Client(mcp_server) as client:
         result = await client.call_tool("greet", {"name": "World"})
-        assert result[0].text == "Hello, World!"
+        assert result.data == "Hello, World!"
 ```
 
 This pattern creates a direct connection between the client and server, allowing you to test your server's functionality efficiently.
+
+<Tip>
+If you're using pytest for async tests, as shown above, you may need to configure appropriate markers or set `asyncio_mode = "auto"` in your pytest configuration in order to handle async test functions automatically.
+</Tip> 
+
+
+## Mocking
+
+FastMCP servers are designed to work seamlessly with standard Python testing tools and patterns. There's nothing special about testing FastMCP servers - you can use all the familiar Python mocking, patching, and testing techniques you already know.
+

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/servers/composition.mdx

@@ -180,7 +180,7 @@ async def test_dynamic_mount():
     
     async with Client(main_mcp) as client:
         result = await client.call_tool("dynamic_added_later")
-        print("Result:", result[0].text)
+        print("Result:", result.data)
         # Shows: "Tool Added Dynamically!"
 
 if __name__ == "__main__":

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/servers/proxy.mdx

@@ -162,6 +162,12 @@ composite_proxy = FastMCP.as_proxy(config, name="Composite Proxy")
 # - weather://weather/icons/sunny, calendar://calendar/events/today
 ```
 
+## Forwarding Interactions
+
+`ProxyClient` is a subclass of `Client` that implements a set of default handlers to forward advanced interactions between the backend server and the client connected to the proxy. These handlers receive requests or notifications from the backend server and forward them to the client through the related request context, relaying the response back to the backend server if needed. This setup enables the proxy to support advanced MCP features, including roots, sampling, elicitation, logging, and progress.
+
+To prevent the forwarding of any interaction, pass `None` to the corresponding handler when creating the `ProxyClient`. Typically, you should use `ProxyClient` to establish a proxy unless there is a specific reason not to. If the `transport` parameter is not an instance of `Client`, `FastMCP.as_proxy()` will automatically instantiate a `ProxyClient`.
+
 ## `FastMCPProxy` Class
 
 Internally, `FastMCP.as_proxy()` uses the `FastMCPProxy` class. You generally don't need to interact with this class directly, but it's available if needed.

{fastmcp-2.10.1 → fastmcp-2.10.2}/docs/tutorials/rest-api.mdx

@@ -114,7 +114,7 @@ async def main():
         # Call one of the generated tools
         print("\n\nCalling tool 'get_user_by_id'...")
         user = await client.call_tool("get_user_by_id", {"id": 1})
-        print(f"Result:\n{user[0].text}")
+        print(f"Result:\n{user.data}")
 
 if __name__ == "__main__":
     asyncio.run(main())

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/cli/cli.py

@@ -64,6 +64,7 @@ def _build_uv_command(
     server_spec: str,
     with_editable: Path | None = None,
     with_packages: list[str] | None = None,
+    no_banner: bool = False,
 ) -> list[str]:
     """Build the uv run command that runs a MCP server through mcp run."""
     cmd = ["uv"]
@@ -80,6 +81,10 @@ def _build_uv_command(
 
     # Add mcp run command
     cmd.extend(["fastmcp", "run", server_spec])
+
+    if no_banner:
+        cmd.append("--no-banner")
+
     return cmd
 
 
@@ -192,7 +197,9 @@ def dev(
         if inspector_version:
             inspector_cmd += f"@{inspector_version}"
 
-        uv_cmd = _build_uv_command(server_spec, with_editable, with_packages)
+        uv_cmd = _build_uv_command(
+            server_spec, with_editable, with_packages, no_banner=True
+        )
 
         # Run the MCP Inspector command with shell=True on Windows
         shell = sys.platform == "win32"
@@ -261,6 +268,13 @@ def run(
             help="Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)",
         ),
     ] = None,
+    no_banner: Annotated[
+        bool,
+        typer.Option(
+            "--no-banner",
+            help="Don't show the server banner",
+        ),
+    ] = False,
 ) -> None:
     """Run a MCP server or connect to a remote one.
 
@@ -297,6 +311,7 @@ def run(
             port=port,
             log_level=log_level,
             server_args=server_args,
+            show_banner=not no_banner,
         )
     except Exception as e:
         logger.error(

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/cli/run.py

@@ -169,6 +169,7 @@ def run_command(
     port: int | None = None,
     log_level: str | None = None,
     server_args: list[str] | None = None,
+    show_banner: bool = True,
 ) -> None:
     """Run a MCP server or connect to a remote one.
 
@@ -201,6 +202,9 @@ def run_command(
     if log_level:
         kwargs["log_level"] = log_level
 
+    if not show_banner:
+        kwargs["show_banner"] = False
+
     try:
         server.run(**kwargs)
     except Exception as e:

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/client/elicitation.py

@@ -53,6 +53,11 @@ def create_elicitation_callback(
             if not isinstance(result, ElicitResult):
                 result = ElicitResult(action="accept", content=result)
             content = to_jsonable_python(result.content)
+            if not isinstance(content, dict | None):
+                raise ValueError(
+                    "Elicitation responses must be serializable as a JSON object (dict). Received: "
+                    f"{result.content!r}"
+                )
             return MCPElicitResult(**result.model_dump() | {"content": content})
         except Exception as e:
             return mcp.types.ErrorData(

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/client/transports.py

@@ -773,8 +773,6 @@ class MCPConfigTransport(ClientTransport):
     """
 
     def __init__(self, config: MCPConfig | dict):
-        from fastmcp.client.client import Client
-
         if isinstance(config, dict):
             config = MCPConfig.from_dict(config)
         self.config = config
@@ -792,9 +790,9 @@ class MCPConfigTransport(ClientTransport):
             composite_server = FastMCP()
 
             for name, server in self.config.mcpServers.items():
-                server_client = Client(transport=server.to_transport())
                 composite_server.mount(
-                    prefix=name, server=FastMCP.as_proxy(server_client)
+                    prefix=name,
+                    server=FastMCP.as_proxy(backend=server.to_transport()),
                 )
 
             self.transport = FastMCPTransport(mcp=composite_server)

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/server/auth/providers/bearer.py

@@ -399,12 +399,21 @@ class BearerAuthProvider(OAuthProvider):
             return None
 
     def _extract_scopes(self, claims: dict[str, Any]) -> list[str]:
-        """Extract scopes from JWT claims."""
-        scope_claim = claims.get("scope", "")
-        if isinstance(scope_claim, str):
-            return scope_claim.split()
-        elif isinstance(scope_claim, list):
-            return scope_claim
+        """
+        Extract scopes from JWT claims. Supports both 'scope' and 'scp'
+        claims.
+
+        Checks the `scope` claim first (standard OAuth2 claim), then the `scp`
+        claim (used by some Identity Providers).
+        """
+
+        for claim in ["scope", "scp"]:
+            if claim in claims:
+                if isinstance(claims[claim], str):
+                    return claims[claim].split()
+                elif isinstance(claims[claim], list):
+                    return claims[claim]
+
         return []
 
     async def verify_token(self, token: str) -> AccessToken | None:

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/server/proxy.py

@@ -1,9 +1,12 @@
 from __future__ import annotations
 
+from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 from urllib.parse import quote
 
 import mcp.types
+from mcp.client.session import ClientSession
+from mcp.shared.context import LifespanContextT, RequestContext
 from mcp.shared.exceptions import McpError
 from mcp.types import (
     METHOD_NOT_FOUND,
@@ -14,6 +17,10 @@ from mcp.types import (
 from pydantic.networks import AnyUrl
 
 from fastmcp.client import Client
+from fastmcp.client.elicitation import ElicitResult
+from fastmcp.client.logging import LogMessage
+from fastmcp.client.roots import RootsList
+from fastmcp.client.transports import ClientTransportT
 from fastmcp.exceptions import NotFoundError, ResourceError, ToolError
 from fastmcp.prompts import Prompt, PromptMessage
 from fastmcp.prompts.prompt import PromptArgument
@@ -21,10 +28,12 @@ from fastmcp.prompts.prompt_manager import PromptManager
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.resources.resource_manager import ResourceManager
 from fastmcp.server.context import Context
+from fastmcp.server.dependencies import get_context
 from fastmcp.server.server import FastMCP
 from fastmcp.tools.tool import Tool, ToolResult
 from fastmcp.tools.tool_manager import ToolManager
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.mcp_config import MCPConfig
 
 if TYPE_CHECKING:
     from fastmcp.server import Context
@@ -406,3 +415,110 @@ class FastMCPProxy(FastMCP):
         self._tool_manager = ProxyToolManager(client=self.client)
         self._resource_manager = ProxyResourceManager(client=self.client)
         self._prompt_manager = ProxyPromptManager(client=self.client)
+
+
+async def default_proxy_roots_handler(
+    context: RequestContext[ClientSession, LifespanContextT],
+) -> RootsList:
+    """
+    A handler that forwards the list roots request from the remote server to the proxy's connected clients and relays the response back to the remote server.
+    """
+    ctx = get_context()
+    return await ctx.list_roots()
+
+
+class ProxyClient(Client[ClientTransportT]):
+    """
+    A proxy client that forwards advanced interactions between a remote MCP server and the proxy's connected clients.
+    Supports forwarding roots, sampling, elicitation, logging, and progress.
+    """
+
+    def __init__(
+        self,
+        transport: (
+            ClientTransportT
+            | FastMCP
+            | AnyUrl
+            | Path
+            | MCPConfig
+            | dict[str, Any]
+            | str
+        ),
+        **kwargs,
+    ):
+        if "roots" not in kwargs:
+            kwargs["roots"] = default_proxy_roots_handler
+        if "sampling_handler" not in kwargs:
+            kwargs["sampling_handler"] = ProxyClient.default_sampling_handler
+        if "elicitation_handler" not in kwargs:
+            kwargs["elicitation_handler"] = ProxyClient.default_elicitation_handler
+        if "log_handler" not in kwargs:
+            kwargs["log_handler"] = ProxyClient.default_log_handler
+        if "progress_handler" not in kwargs:
+            kwargs["progress_handler"] = ProxyClient.default_progress_handler
+        super().__init__(transport, **kwargs)
+
+    @classmethod
+    async def default_sampling_handler(
+        cls,
+        messages: list[mcp.types.SamplingMessage],
+        params: mcp.types.CreateMessageRequestParams,
+        context: RequestContext[ClientSession, LifespanContextT],
+    ) -> mcp.types.CreateMessageResult:
+        """
+        A handler that forwards the sampling request from the remote server to the proxy's connected clients and relays the response back to the remote server.
+        """
+        ctx = get_context()
+        content = await ctx.sample(
+            [msg for msg in messages],
+            system_prompt=params.systemPrompt,
+            temperature=params.temperature,
+            max_tokens=params.maxTokens,
+            model_preferences=params.modelPreferences,
+        )
+        if isinstance(content, mcp.types.ResourceLink | mcp.types.EmbeddedResource):
+            raise RuntimeError("Content is not supported")
+        return mcp.types.CreateMessageResult(
+            role="assistant",
+            model="fastmcp-client",
+            content=content,
+        )
+
+    @classmethod
+    async def default_elicitation_handler(
+        cls,
+        message: str,
+        response_type: type,
+        params: mcp.types.ElicitRequestParams,
+        context: RequestContext[ClientSession, LifespanContextT],
+    ) -> ElicitResult:
+        """
+        A handler that forwards the elicitation request from the remote server to the proxy's connected clients and relays the response back to the remote server.
+        """
+        ctx = get_context()
+        result = await ctx.elicit(message, response_type)
+        if result.action == "accept":
+            return result.data
+        else:
+            return ElicitResult(action=result.action)
+
+    @classmethod
+    async def default_log_handler(cls, message: LogMessage) -> None:
+        """
+        A handler that forwards the log notification from the remote server to the proxy's connected clients.
+        """
+        ctx = get_context()
+        await ctx.log(message.data, level=message.level, logger_name=message.logger)
+
+    @classmethod
+    async def default_progress_handler(
+        cls,
+        progress: float,
+        total: float | None,
+        message: str | None,
+    ) -> None:
+        """
+        A handler that forwards the progress notification from the remote server to the proxy's connected clients.
+        """
+        ctx = get_context()
+        await ctx.report_progress(progress, total, message)

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/server/server.py

@@ -60,6 +60,7 @@ from fastmcp.settings import Settings
 from fastmcp.tools import ToolManager
 from fastmcp.tools.tool import FunctionTool, Tool, ToolResult
 from fastmcp.utilities.cache import TimedCache
+from fastmcp.utilities.cli import log_server_banner
 from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.mcp_config import MCPConfig
@@ -285,6 +286,7 @@ class FastMCP(Generic[LifespanResultT]):
     async def run_async(
         self,
         transport: Transport | None = None,
+        show_banner: bool = True,
         **transport_kwargs: Any,
     ) -> None:
         """Run the FastMCP server asynchronously.
@@ -298,15 +300,23 @@ class FastMCP(Generic[LifespanResultT]):
             raise ValueError(f"Unknown transport: {transport}")
 
         if transport == "stdio":
-            await self.run_stdio_async(**transport_kwargs)
+            await self.run_stdio_async(
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
         elif transport in {"http", "sse", "streamable-http"}:
-            await self.run_http_async(transport=transport, **transport_kwargs)
+            await self.run_http_async(
+                transport=transport,
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
         else:
             raise ValueError(f"Unknown transport: {transport}")
 
     def run(
         self,
         transport: Transport | None = None,
+        show_banner: bool = True,
         **transport_kwargs: Any,
     ) -> None:
         """Run the FastMCP server. Note this is a synchronous function.
@@ -315,7 +325,14 @@ class FastMCP(Generic[LifespanResultT]):
             transport: Transport protocol to use ("stdio", "sse", or "streamable-http")
         """
 
-        anyio.run(partial(self.run_async, transport, **transport_kwargs))
+        anyio.run(
+            partial(
+                self.run_async,
+                transport,
+                show_banner=show_banner,
+                **transport_kwargs,
+            )
+        )
 
     def _setup_handlers(self) -> None:
         """Set up core MCP protocol handlers."""
@@ -1321,8 +1338,16 @@ class FastMCP(Generic[LifespanResultT]):
             enabled=enabled,
         )
 
-    async def run_stdio_async(self) -> None:
+    async def run_stdio_async(self, show_banner: bool = True) -> None:
         """Run the server using stdio transport."""
+
+        # Display server banner
+        if show_banner:
+            log_server_banner(
+                server=self,
+                transport="stdio",
+            )
+
         async with stdio_server() as (read_stream, write_stream):
             logger.info(f"Starting MCP server {self.name!r} with transport 'stdio'")
             await self._mcp_server.run(
@@ -1335,6 +1360,7 @@ class FastMCP(Generic[LifespanResultT]):
 
     async def run_http_async(
         self,
+        show_banner: bool = True,
         transport: Literal["http", "streamable-http", "sse"] = "http",
         host: str | None = None,
         port: int | None = None,
@@ -1342,6 +1368,7 @@ class FastMCP(Generic[LifespanResultT]):
         path: str | None = None,
         uvicorn_config: dict[str, Any] | None = None,
         middleware: list[ASGIMiddleware] | None = None,
+        stateless_http: bool | None = None,
     ) -> None:
         """Run the server using HTTP transport.
 
@@ -1352,15 +1379,39 @@ class FastMCP(Generic[LifespanResultT]):
             log_level: Log level for the server (defaults to settings.log_level)
             path: Path for the endpoint (defaults to settings.streamable_http_path or settings.sse_path)
             uvicorn_config: Additional configuration for the Uvicorn server
+            middleware: A list of middleware to apply to the app
+            stateless_http: Whether to use stateless HTTP (defaults to settings.stateless_http)
         """
+
         host = host or self._deprecated_settings.host
         port = port or self._deprecated_settings.port
         default_log_level_to_use = (
             log_level or self._deprecated_settings.log_level
         ).lower()
 
-        app = self.http_app(path=path, transport=transport, middleware=middleware)
+        app = self.http_app(
+            path=path,
+            transport=transport,
+            middleware=middleware,
+            stateless_http=stateless_http,
+        )
+
+        # Get the path for the server URL
+        server_path = (
+            app.state.path.lstrip("/")
+            if hasattr(app, "state") and hasattr(app.state, "path")
+            else path or ""
+        )
 
+        # Display server banner
+        if show_banner:
+            log_server_banner(
+                server=self,
+                transport=transport,
+                host=host,
+                port=port,
+                path=server_path,
+            )
         _uvicorn_config_from_user = uvicorn_config or {}
 
         config_kwargs: dict[str, Any] = {
@@ -1378,6 +1429,7 @@ class FastMCP(Generic[LifespanResultT]):
         logger.info(
             f"Starting MCP server {self.name!r} with transport {transport!r} on http://{host}:{port}/{path}"
         )
+
         await server.serve()
 
     async def run_sse_async(
@@ -1591,9 +1643,8 @@ class FastMCP(Generic[LifespanResultT]):
             resource_separator: Deprecated. Separator character for resource URIs.
             prompt_separator: Deprecated. Separator character for prompt names.
         """
-        from fastmcp import Client
         from fastmcp.client.transports import FastMCPTransport
-        from fastmcp.server.proxy import FastMCPProxy
+        from fastmcp.server.proxy import FastMCPProxy, ProxyClient
 
         # Deprecated since 2.9.0
         # Prior to 2.9.0, the first positional argument was the prefix and the
@@ -1645,7 +1696,7 @@ class FastMCP(Generic[LifespanResultT]):
             as_proxy = server._has_lifespan
 
         if as_proxy and not isinstance(server, FastMCPProxy):
-            server = FastMCPProxy(Client(transport=FastMCPTransport(server)))
+            server = FastMCPProxy(ProxyClient(transport=FastMCPTransport(server)))
 
         # Delegate mounting to all three managers
         mounted_server = MountedServer(
@@ -1856,14 +1907,16 @@ class FastMCP(Generic[LifespanResultT]):
     @classmethod
     def as_proxy(
         cls,
-        backend: Client[ClientTransportT]
-        | ClientTransport
-        | FastMCP[Any]
-        | AnyUrl
-        | Path
-        | MCPConfig
-        | dict[str, Any]
-        | str,
+        backend: (
+            Client[ClientTransportT]
+            | ClientTransport
+            | FastMCP[Any]
+            | AnyUrl
+            | Path
+            | MCPConfig
+            | dict[str, Any]
+            | str
+        ),
         **settings: Any,
     ) -> FastMCPProxy:
         """Create a FastMCP proxy server for the given backend.
@@ -1874,12 +1927,12 @@ class FastMCP(Generic[LifespanResultT]):
         `fastmcp.client.Client` constructor.
         """
         from fastmcp.client.client import Client
-        from fastmcp.server.proxy import FastMCPProxy
+        from fastmcp.server.proxy import FastMCPProxy, ProxyClient
 
         if isinstance(backend, Client):
             client = backend
         else:
-            client = Client(backend)
+            client = ProxyClient(backend)
 
         return FastMCPProxy(client=client, **settings)
 

{fastmcp-2.10.1 → fastmcp-2.10.2}/src/fastmcp/settings.py

@@ -1,6 +1,7 @@
 from __future__ import annotations as _annotations
 
 import inspect
+import warnings
 from pathlib import Path
 from typing import Annotated, Any, Literal
 
@@ -258,4 +259,21 @@ class Settings(BaseSettings):
     ] = None
 
 
-settings = Settings()
+def __getattr__(name: str):
+    """
+    Used to deprecate the module-level Image class; can be removed once it is no longer imported to root.
+    """
+    if name == "settings":
+        import fastmcp
+
+        settings = fastmcp.settings
+        # Deprecated in 2.10.2
+        if settings.deprecation_warnings:
+            warnings.warn(
+                "`from fastmcp.settings import settings` is deprecated. use `fasmtpc.settings` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return settings
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")