fastmcp 2.13.0.1__py3-none-any.whl → 2.13.1__py3-none-any.whl

fastmcp/cli/cli.py

@@ -502,7 +502,7 @@ async def run(
             process = subprocess.run(cmd, check=True, env=env)
             sys.exit(process.returncode)
         except subprocess.CalledProcessError as e:
-            logger.error(
+            logger.exception(
                 f"Failed to run: {e}",
                 extra={
                     "server_spec": server_spec,
@@ -526,7 +526,7 @@ async def run(
                 skip_source=skip_source,
             )
         except Exception as e:
-            logger.error(
+            logger.exception(
                 f"Failed to run: {e}",
                 extra={
                     "server_spec": server_spec,
@@ -766,13 +766,12 @@ async def inspect(
             console.print(formatted_json.decode("utf-8"))
 
     except Exception as e:
-        logger.error(
+        logger.exception(
             f"Failed to inspect server: {e}",
             extra={
                 "server_spec": server_spec,
                 "error": str(e),
             },
-            exc_info=True,
         )
         console.print(f"[bold red]✗[/bold red] Failed to inspect server: {e}")
         sys.exit(1)

fastmcp/cli/install/cursor.py

@@ -1,10 +1,12 @@
 """Cursor integration for FastMCP install using Cyclopts."""
 
 import base64
+import os
 import subprocess
 import sys
 from pathlib import Path
 from typing import Annotated
+from urllib.parse import quote, urlparse
 
 import cyclopts
 from rich import print
@@ -36,8 +38,9 @@ def generate_cursor_deeplink(
     config_json = server_config.model_dump_json(exclude_none=True)
     config_b64 = base64.urlsafe_b64encode(config_json.encode()).decode()
 
-    # Generate the deeplink URL
-    deeplink = f"cursor://anysphere.cursor-deeplink/mcp/install?name={server_name}&config={config_b64}"
+    # Generate the deeplink URL with properly encoded server name
+    encoded_name = quote(server_name, safe="")
+    deeplink = f"cursor://anysphere.cursor-deeplink/mcp/install?name={encoded_name}&config={config_b64}"
 
     return deeplink
 
@@ -51,17 +54,20 @@ def open_deeplink(deeplink: str) -> bool:
     Returns:
         True if the command succeeded, False otherwise
     """
+    parsed = urlparse(deeplink)
+    if parsed.scheme != "cursor":
+        logger.warning(f"Invalid deeplink scheme: {parsed.scheme}")
+        return False
+
     try:
         if sys.platform == "darwin":  # macOS
             subprocess.run(["open", deeplink], check=True, capture_output=True)
         elif sys.platform == "win32":  # Windows
-            subprocess.run(
-                ["cmd", "/c", "start", deeplink], check=True, capture_output=True
-            )
+            os.startfile(deeplink)
         else:  # Linux and others
             subprocess.run(["xdg-open", deeplink], check=True, capture_output=True)
         return True
-    except (subprocess.CalledProcessError, FileNotFoundError):
+    except (subprocess.CalledProcessError, FileNotFoundError, OSError):
         return False
 
 

fastmcp/client/auth/oauth.py

@@ -12,6 +12,7 @@ from key_value.aio.adapters.pydantic import PydanticAdapter
 from key_value.aio.protocols import AsyncKeyValue
 from key_value.aio.stores.memory import MemoryStore
 from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.shared._httpx_utils import McpHttpClientFactory
 from mcp.shared.auth import (
     OAuthClientInformationFull,
     OAuthClientMetadata,
@@ -147,6 +148,7 @@ class OAuth(OAuthClientProvider):
         token_storage: AsyncKeyValue | None = None,
         additional_client_metadata: dict[str, Any] | None = None,
         callback_port: int | None = None,
+        httpx_client_factory: McpHttpClientFactory | None = None,
     ):
         """
         Initialize OAuth client provider for an MCP server.
@@ -164,6 +166,7 @@ class OAuth(OAuthClientProvider):
         server_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}"
 
         # Setup OAuth client
+        self.httpx_client_factory = httpx_client_factory or httpx.AsyncClient
         self.redirect_port = callback_port or find_available_port()
         redirect_uri = f"http://localhost:{self.redirect_port}/callback"
 
@@ -192,8 +195,9 @@ class OAuth(OAuthClientProvider):
             from warnings import warn
 
             warn(
-                message="Using in-memory token storage is not recommended for production use -- "
-                + "tokens will be lost on server restart.",
+                message="Using in-memory token storage -- tokens will be lost when the client restarts. "
+                + "For persistent storage across multiple MCP servers, provide an encrypted AsyncKeyValue backend. "
+                + "See https://gofastmcp.com/clients/auth/oauth#token-storage for details.",
                 stacklevel=2,
             )
 
@@ -225,7 +229,7 @@ class OAuth(OAuthClientProvider):
     async def redirect_handler(self, authorization_url: str) -> None:
         """Open browser for authorization, with pre-flight check for invalid client."""
         # Pre-flight check to detect invalid client_id before opening browser
-        async with httpx.AsyncClient() as client:
+        async with self.httpx_client_factory() as client:
             response = await client.get(authorization_url, follow_redirects=False)
 
             # Check for client not found error (400 typically means bad client_id)
@@ -296,7 +300,8 @@ class OAuth(OAuthClientProvider):
             response = None
             while True:
                 try:
-                    yielded_request = await gen.asend(response)
+                    # First iteration sends None, subsequent iterations send response
+                    yielded_request = await gen.asend(response)  # ty: ignore[invalid-argument-type]
                     response = yield yielded_request
                 except StopAsyncIteration:
                     break
@@ -305,16 +310,16 @@ class OAuth(OAuthClientProvider):
             logger.debug(
                 "OAuth client not found on server, clearing cache and retrying..."
             )
-
             # Clear cached state and retry once
             self._initialized = False
             await self.token_storage_adapter.clear()
 
+            # Retry with fresh registration
             gen = super().async_auth_flow(request)
             response = None
             while True:
                 try:
-                    yielded_request = await gen.asend(response)
+                    yielded_request = await gen.asend(response)  # ty: ignore[invalid-argument-type]
                     response = yield yielded_request
                 except StopAsyncIteration:
                     break

fastmcp/client/client.py

@@ -77,6 +77,16 @@ logger = get_logger(__name__)
 T = TypeVar("T", bound="ClientTransport")
 
 
+def _timeout_to_seconds(
+    timeout: datetime.timedelta | float | int | None,
+) -> float | None:
+    if timeout is None:
+        return None
+    if isinstance(timeout, datetime.timedelta):
+        return timeout.total_seconds()
+    return float(timeout)
+
+
 @dataclass
 class ClientSessionState:
     """Holds all session-related state for a Client instance.
@@ -222,6 +232,7 @@ class Client(Generic[ClientTransportT]):
         message_handler: MessageHandlerT | MessageHandler | None = None,
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        auto_initialize: bool = True,
         init_timeout: datetime.timedelta | float | int | None = None,
         client_info: mcp.types.Implementation | None = None,
         auth: httpx.Auth | Literal["oauth"] | str | None = None,
@@ -240,26 +251,23 @@ class Client(Generic[ClientTransportT]):
 
         self._progress_handler = progress_handler
 
+        # Convert timeout to timedelta if needed
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=float(timeout))
 
         # handle init handshake timeout
         if init_timeout is None:
             init_timeout = fastmcp.settings.client_init_timeout
-        if isinstance(init_timeout, datetime.timedelta):
-            init_timeout = init_timeout.total_seconds()
-        elif not init_timeout:
-            init_timeout = None
-        else:
-            init_timeout = float(init_timeout)
-        self._init_timeout = init_timeout
+        self._init_timeout = _timeout_to_seconds(init_timeout)
+
+        self.auto_initialize = auto_initialize
 
         self._session_kwargs: SessionKwargs = {
             "sampling_callback": None,
             "list_roots_callback": None,
             "logging_callback": create_log_callback(log_handler),
             "message_handler": message_handler,
-            "read_timeout_seconds": timeout,
+            "read_timeout_seconds": timeout,  # ty: ignore[invalid-argument-type]
             "client_info": client_info,
         }
 
@@ -290,12 +298,8 @@ class Client(Generic[ClientTransportT]):
         return self._session_state.session
 
     @property
-    def initialize_result(self) -> mcp.types.InitializeResult:
+    def initialize_result(self) -> mcp.types.InitializeResult | None:
         """Get the result of the initialization request."""
-        if self._session_state.initialize_result is None:
-            raise RuntimeError(
-                "Client is not connected. Use the 'async with client:' context manager first."
-            )
         return self._session_state.initialize_result
 
     def set_roots(self, roots: RootsList | RootsHandler) -> None:
@@ -357,15 +361,11 @@ class Client(Generic[ClientTransportT]):
                 self._session_state.session = session
                 # Initialize the session
                 try:
-                    with anyio.fail_after(self._init_timeout):
-                        self._session_state.initialize_result = (
-                            await self._session_state.session.initialize()
-                        )
+                    if self.auto_initialize:
+                        await self.initialize()
                     yield
                 except anyio.ClosedResourceError as e:
                     raise RuntimeError("Server session was closed unexpectedly") from e
-                except TimeoutError as e:
-                    raise RuntimeError("Failed to initialize server session") from e
                 finally:
                     self._session_state.session = None
                     self._session_state.initialize_result = None
@@ -493,6 +493,55 @@ class Client(Generic[ClientTransportT]):
 
     # --- MCP Client Methods ---
 
+    async def initialize(
+        self,
+        timeout: datetime.timedelta | float | int | None = None,
+    ) -> mcp.types.InitializeResult:
+        """Send an initialize request to the server.
+
+        This method performs the MCP initialization handshake with the server,
+        exchanging capabilities and server information. It is idempotent - calling
+        it multiple times returns the cached result from the first call.
+
+        The initialization happens automatically when entering the client context
+        manager unless `auto_initialize=False` was set during client construction.
+        Manual calls to this method are only needed when auto-initialization is disabled.
+
+        Args:
+            timeout: Optional timeout for the initialization request (seconds or timedelta).
+                If None, uses the client's init_timeout setting.
+
+        Returns:
+            InitializeResult: The server's initialization response containing server info,
+                capabilities, protocol version, and optional instructions.
+
+        Raises:
+            RuntimeError: If the client is not connected or initialization times out.
+
+        Example:
+            ```python
+            # With auto-initialization disabled
+            client = Client(server, auto_initialize=False)
+            async with client:
+                result = await client.initialize()
+                print(f"Server: {result.serverInfo.name}")
+                print(f"Instructions: {result.instructions}")
+            ```
+        """
+
+        if self.initialize_result is not None:
+            return self.initialize_result
+
+        if timeout is None:
+            timeout = self._init_timeout
+        try:
+            with anyio.fail_after(_timeout_to_seconds(timeout)):
+                initialize_result = await self.session.initialize()
+                self._session_state.initialize_result = initialize_result
+                return initialize_result
+        except TimeoutError as e:
+            raise RuntimeError("Failed to initialize server session") from e
+
     async def ping(self) -> bool:
         """Send a ping request."""
         result = await self.session.send_ping()
@@ -831,6 +880,7 @@ class Client(Generic[ClientTransportT]):
         arguments: dict[str, Any],
         progress_handler: ProgressHandler | None = None,
         timeout: datetime.timedelta | float | int | None = None,
+        meta: dict[str, Any] | None = None,
     ) -> mcp.types.CallToolResult:
         """Send a tools/call request and return the complete MCP protocol result.
 
@@ -842,6 +892,10 @@ class Client(Generic[ClientTransportT]):
             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.
+            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
+                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
+                that shouldn't be tool arguments but may influence server-side processing. The server
+                can access this via `context.request_context.meta`. Defaults to None.
 
         Returns:
             mcp.types.CallToolResult: The complete response object from the protocol,
@@ -852,13 +906,16 @@ class Client(Generic[ClientTransportT]):
         """
         logger.debug(f"[{self.name}] called call_tool: {name}")
 
+        # Convert timeout to timedelta if needed
         if isinstance(timeout, int | float):
             timeout = datetime.timedelta(seconds=float(timeout))
+
         result = await self.session.call_tool(
             name=name,
             arguments=arguments,
-            read_timeout_seconds=timeout,
+            read_timeout_seconds=timeout,  # ty: ignore[invalid-argument-type]
             progress_callback=progress_handler or self._progress_handler,
+            meta=meta,
         )
         return result
 
@@ -869,6 +926,7 @@ class Client(Generic[ClientTransportT]):
         timeout: datetime.timedelta | float | int | None = None,
         progress_handler: ProgressHandler | None = None,
         raise_on_error: bool = True,
+        meta: dict[str, Any] | None = None,
     ) -> CallToolResult:
         """Call a tool on the server.
 
@@ -879,6 +937,11 @@ class Client(Generic[ClientTransportT]):
             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.
+            raise_on_error (bool, optional): Whether to raise a ToolError if the tool call results in an error. Defaults to True.
+            meta (dict[str, Any] | None, optional): Additional metadata to include with the request.
+                This is useful for passing contextual information (like user IDs, trace IDs, or preferences)
+                that shouldn't be tool arguments but may influence server-side processing. The server
+                can access this via `context.request_context.meta`. Defaults to None.
 
         Returns:
             CallToolResult:
@@ -898,6 +961,7 @@ class Client(Generic[ClientTransportT]):
             arguments=arguments or {},
             timeout=timeout,
             progress_handler=progress_handler,
+            meta=meta,
         )
         data = None
         if result.isError and raise_on_error:
@@ -928,6 +992,7 @@ class Client(Generic[ClientTransportT]):
         return CallToolResult(
             content=result.content,
             structured_content=result.structuredContent,
+            meta=result.meta,
             data=data,
             is_error=result.isError,
         )
@@ -945,5 +1010,6 @@ class Client(Generic[ClientTransportT]):
 class CallToolResult:
     content: list[mcp.types.ContentBlock]
     structured_content: dict[str, Any] | None
+    meta: dict[str, Any] | None
     data: Any = None
     is_error: bool = False

fastmcp/client/transports.py

@@ -177,8 +177,8 @@ class SSETransport(ClientTransport):
 
         self.url = url
         self.headers = headers or {}
-        self._set_auth(auth)
         self.httpx_client_factory = httpx_client_factory
+        self._set_auth(auth)
 
         if isinstance(sse_read_timeout, int | float):
             sse_read_timeout = datetime.timedelta(seconds=float(sse_read_timeout))
@@ -186,7 +186,7 @@ class SSETransport(ClientTransport):
 
     def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
         if auth == "oauth":
-            auth = OAuth(self.url)
+            auth = OAuth(self.url, httpx_client_factory=self.httpx_client_factory)
         elif isinstance(auth, str):
             auth = BearerAuth(auth)
         self.auth = auth
@@ -247,8 +247,8 @@ class StreamableHttpTransport(ClientTransport):
 
         self.url = url
         self.headers = headers or {}
-        self._set_auth(auth)
         self.httpx_client_factory = httpx_client_factory
+        self._set_auth(auth)
 
         if isinstance(sse_read_timeout, int | float):
             sse_read_timeout = datetime.timedelta(seconds=float(sse_read_timeout))
@@ -256,7 +256,7 @@ class StreamableHttpTransport(ClientTransport):
 
     def _set_auth(self, auth: httpx.Auth | Literal["oauth"] | str | None):
         if auth == "oauth":
-            auth = OAuth(self.url)
+            auth = OAuth(self.url, httpx_client_factory=self.httpx_client_factory)
         elif isinstance(auth, str):
             auth = BearerAuth(auth)
         self.auth = auth

fastmcp/experimental/utilities/openapi/director.py

@@ -54,28 +54,27 @@ class RequestDirector:
         url = self._build_url(route.path, path_params, base_url)
 
         # Step 3: Prepare request data
-        request_data = {
-            "method": route.method.upper(),
-            "url": url,
-            "params": query_params if query_params else None,
-            "headers": header_params if header_params else None,
-        }
+        method: str = route.method.upper()
+        params = query_params if query_params else None
+        headers = header_params if header_params else None
+        json_body: dict[str, Any] | list[Any] | None = None
+        content: str | bytes | None = None
 
         # Step 4: Handle request body
         if body is not None:
             if isinstance(body, dict | list):
-                request_data["json"] = body
+                json_body = body
             else:
-                request_data["content"] = body
+                content = body
 
         # Step 5: Create httpx.Request
         return httpx.Request(
-            method=request_data["method"],
-            url=request_data["url"],
-            params=request_data.get("params"),
-            headers=request_data.get("headers"),
-            json=request_data.get("json"),
-            content=request_data.get("content"),
+            method=method,
+            url=url,
+            params=params,
+            headers=headers,
+            json=json_body,
+            content=content,
         )
 
     def _unflatten_arguments(

fastmcp/experimental/utilities/openapi/parser.py

@@ -630,25 +630,28 @@ class OpenAPIParser(
         Returns:
             Dictionary containing only the schemas needed for outputs
         """
-        needed_schemas = set()
+        if not responses or not all_schemas:
+            return {}
+
+        needed_schemas: set[str] = set()
 
-        # Check responses for schema references
         for response in responses.values():
-            if response.content_schema:
-                for content_schema in response.content_schema.values():
-                    # Check if this schema was originally a top-level $ref
-                    if "x-fastmcp-top-level-schema" in content_schema:
-                        schema_name = content_schema["x-fastmcp-top-level-schema"]
-                        if schema_name in all_schemas:
-                            needed_schemas.add(schema_name)
-
-                    # Extract all dependencies (transitive refs within the schema)
-                    deps = self._extract_schema_dependencies(
-                        content_schema, all_schemas
+            if not response.content_schema:
+                continue
+
+            for content_schema in response.content_schema.values():
+                deps = self._extract_schema_dependencies(content_schema, all_schemas)
+                needed_schemas.update(deps)
+
+                schema_name = content_schema.get("x-fastmcp-top-level-schema")
+                if isinstance(schema_name, str) and schema_name in all_schemas:
+                    needed_schemas.add(schema_name)
+                    self._extract_schema_dependencies(
+                        all_schemas[schema_name],
+                        all_schemas,
+                        collected=needed_schemas,
                     )
-                    needed_schemas.update(deps)
 
-        # Return only the needed output schemas
         return {
             name: all_schemas[name] for name in needed_schemas if name in all_schemas
         }

fastmcp/mcp_config.py

@@ -101,7 +101,7 @@ class _TransformingMCPServerMixin(FastMCPBaseModel):
             ClientTransport,  # pyright: ignore[reportUnusedImport]
         )
 
-        transport: ClientTransport = super().to_transport()  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownVariableType]
+        transport: ClientTransport = super().to_transport()  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownVariableType]  # ty: ignore[unresolved-attribute]
         transport = cast(ClientTransport, transport)
 
         client: Client[ClientTransport] = Client(transport=transport, name=client_name)

fastmcp/resources/resource_manager.py

@@ -236,7 +236,7 @@ class ResourceManager:
         # Then check templates (local and mounted) only if not found in concrete resources
         templates = await self.get_resource_templates()
         for template_key in templates:
-            if match_uri_template(uri_str, template_key):
+            if match_uri_template(uri_str, template_key) is not None:
                 return True
 
         return False
@@ -262,7 +262,7 @@ class ResourceManager:
         templates = await self.get_resource_templates()
         for storage_key, template in templates.items():
             # Try to match against the storage key (which might be a custom key)
-            if params := match_uri_template(uri_str, storage_key):
+            if (params := match_uri_template(uri_str, storage_key)) is not None:
                 try:
                     return await template.create_resource(
                         uri_str,
@@ -318,7 +318,7 @@ class ResourceManager:
 
         # 1b. Check local templates if not found in concrete resources
         for key, template in self._templates.items():
-            if params := match_uri_template(uri_str, key):
+            if (params := match_uri_template(uri_str, key)) is not None:
                 try:
                     resource = await template.create_resource(uri_str, params=params)
                     return await resource.read()

fastmcp/server/auth/__init__.py

@@ -5,16 +5,20 @@ from .auth import (
     AccessToken,
     AuthProvider,
 )
+from .providers.debug import DebugTokenVerifier
 from .providers.jwt import JWTVerifier, StaticTokenVerifier
 from .oauth_proxy import OAuthProxy
+from .oidc_proxy import OIDCProxy
 
 
 __all__ = [
     "AccessToken",
     "AuthProvider",
+    "DebugTokenVerifier",
     "JWTVerifier",
     "OAuthProvider",
     "OAuthProxy",
+    "OIDCProxy",
     "RemoteAuthProvider",
     "StaticTokenVerifier",
     "TokenVerifier",

fastmcp/server/auth/auth.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, cast
 
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import BearerAuthBackend
@@ -28,6 +28,10 @@ from starlette.middleware import Middleware
 from starlette.middleware.authentication import AuthenticationMiddleware
 from starlette.routing import Route
 
+from fastmcp.utilities.logging import get_logger
+
+logger = get_logger(__name__)
+
 
 class AccessToken(_SDKAccessToken):
     """AccessToken that includes all JWT claims."""
@@ -294,20 +298,27 @@ class OAuthProvider(
             required_scopes: Scopes that are required for all requests.
         """
 
-        # Convert URLs to proper types
-        if isinstance(base_url, str):
-            base_url = AnyHttpUrl(base_url)
-
         super().__init__(base_url=base_url, required_scopes=required_scopes)
-        self.base_url = base_url
 
         if issuer_url is None:
-            self.issuer_url = base_url
+            self.issuer_url = self.base_url
         elif isinstance(issuer_url, str):
             self.issuer_url = AnyHttpUrl(issuer_url)
         else:
             self.issuer_url = issuer_url
 
+        # Log if issuer_url and base_url differ (requires additional setup)
+        if (
+            self.base_url is not None
+            and self.issuer_url is not None
+            and str(self.base_url) != str(self.issuer_url)
+        ):
+            logger.info(
+                f"OAuth endpoints at {self.base_url}, issuer at {self.issuer_url}. "
+                f"Ensure well-known routes are accessible at root ({self.issuer_url}/.well-known/). "
+                f"See: https://gofastmcp.com/deployment/http#mounting-authenticated-servers"
+            )
+
         # Initialize OAuth Authorization Server Provider
         OAuthAuthorizationServerProvider.__init__(self)
 
@@ -348,9 +359,17 @@ class OAuthProvider(
         """
 
         # Create standard OAuth authorization server routes
+        # Pass base_url as issuer_url to ensure metadata declares endpoints where
+        # they're actually accessible (operational routes are mounted at
+        # base_url)
+        assert self.base_url is not None  # typing check
+        assert (
+            self.issuer_url is not None
+        )  # typing check (issuer_url defaults to base_url)
+
         oauth_routes = create_auth_routes(
             provider=self,
-            issuer_url=self.issuer_url,
+            issuer_url=self.base_url,
             service_documentation_url=self.service_documentation_url,
             client_registration_options=self.client_registration_options,
             revocation_options=self.revocation_options,
@@ -369,7 +388,7 @@ class OAuthProvider(
             )
             protected_routes = create_protected_resource_routes(
                 resource_url=resource_url,
-                authorization_servers=[self.issuer_url],
+                authorization_servers=[cast(AnyHttpUrl, self.issuer_url)],
                 scopes_supported=supported_scopes,
             )
             oauth_routes.extend(protected_routes)