fastmcp 2.10.4__py3-none-any.whl → 2.10.6__py3-none-any.whl

fastmcp/__init__.py

@@ -1,10 +1,15 @@
 """FastMCP - An ergonomic MCP interface."""
 
 import warnings
-from importlib.metadata import version
+from importlib.metadata import version as _version
 from fastmcp.settings import Settings
+from fastmcp.utilities.logging import configure_logging as _configure_logging
 
 settings = Settings()
+_configure_logging(
+    level=settings.log_level,
+    enable_rich_tracebacks=settings.enable_rich_tracebacks,
+)
 
 from fastmcp.server.server import FastMCP
 from fastmcp.server.context import Context
@@ -13,7 +18,7 @@ import fastmcp.server
 from fastmcp.client import Client
 from . import client
 
-__version__ = version("fastmcp")
+__version__ = _version("fastmcp")
 
 
 # ensure deprecation warnings are displayed by default

fastmcp/cli/install/__init__.py

@@ -5,7 +5,7 @@ import cyclopts
 from .claude_code import claude_code_command
 from .claude_desktop import claude_desktop_command
 from .cursor import cursor_command
-from .mcp_config import mcp_config_command
+from .mcp_json import mcp_json_command
 
 # Create a cyclopts app for install subcommands
 install_app = cyclopts.App(
@@ -17,4 +17,4 @@ install_app = cyclopts.App(
 install_app.command(claude_code_command, name="claude-code")
 install_app.command(claude_desktop_command, name="claude-desktop")
 install_app.command(cursor_command, name="cursor")
-install_app.command(mcp_config_command, name="mcp-json")
+install_app.command(mcp_json_command, name="mcp-json")

fastmcp/cli/install/claude_code.py

@@ -1,5 +1,6 @@
 """Claude Code integration for FastMCP install using Cyclopts."""
 
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -16,22 +17,50 @@ logger = get_logger(__name__)
 
 
 def find_claude_command() -> str | None:
-    """Find the Claude Code CLI command."""
-    # Check the default installation location
-    default_path = Path.home() / ".claude" / "local" / "claude"
-    if default_path.exists():
+    """Find the Claude Code CLI command.
+
+    Checks common installation locations since 'claude' is often a shell alias
+    that doesn't work with subprocess calls.
+    """
+    # First try shutil.which() in case it's a real executable in PATH
+    claude_in_path = shutil.which("claude")
+    if claude_in_path:
         try:
             result = subprocess.run(
-                [str(default_path), "--version"],
+                [claude_in_path, "--version"],
                 check=True,
                 capture_output=True,
                 text=True,
             )
             if "Claude Code" in result.stdout:
-                return str(default_path)
+                return claude_in_path
         except (subprocess.CalledProcessError, FileNotFoundError):
             pass
 
+    # Check common installation locations (aliases don't work with subprocess)
+    potential_paths = [
+        # Default Claude Code installation location (after migration)
+        Path.home() / ".claude" / "local" / "claude",
+        # npm global installation on macOS/Linux (default)
+        Path("/usr/local/bin/claude"),
+        # npm global installation with custom prefix
+        Path.home() / ".npm-global" / "bin" / "claude",
+    ]
+
+    for path in potential_paths:
+        if path.exists():
+            try:
+                result = subprocess.run(
+                    [str(path), "--version"],
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                )
+                if "Claude Code" in result.stdout:
+                    return str(path)
+            except (subprocess.CalledProcessError, FileNotFoundError):
+                continue
+
     return None
 
 

fastmcp/cli/install/{mcp_config.py → mcp_json.py}

@@ -16,7 +16,7 @@ from .shared import process_common_args
 logger = get_logger(__name__)
 
 
-def install_mcp_config(
+def install_mcp_json(
     file: Path,
     server_object: str | None,
     name: str,
@@ -65,15 +65,18 @@ def install_mcp_config(
         # Add fastmcp run command
         args.extend(["fastmcp", "run", server_spec])
 
-        # Build MCP server configuration (just the server object, not the wrapper)
-        config = {
+        # Build MCP server configuration
+        server_config = {
             "command": "uv",
             "args": args,
         }
 
         # Add environment variables if provided
         if env_vars:
-            config["env"] = env_vars
+            server_config["env"] = env_vars
+
+        # Wrap with server name as root key
+        config = {name: server_config}
 
         # Convert to JSON
         json_output = json.dumps(config, indent=2)
@@ -93,13 +96,13 @@ def install_mcp_config(
         return False
 
 
-def mcp_config_command(
+def mcp_json_command(
     server_spec: str,
     *,
     server_name: Annotated[
         str | None,
         cyclopts.Parameter(
-            name=["--server-name", "-n"],
+            name=["--name", "-n"],
             help="Custom name for the server in MCP config",
         ),
     ] = None,
@@ -151,7 +154,7 @@ def mcp_config_command(
         server_spec, server_name, with_packages, env_vars, env_file
     )
 
-    success = install_mcp_config(
+    success = install_mcp_json(
         file=file,
         server_object=server_object,
         name=name,

fastmcp/prompts/prompt_manager.py

@@ -78,7 +78,7 @@ class PromptManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get prompts from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get prompts from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 

fastmcp/resources/resource_manager.py

@@ -109,7 +109,7 @@ class ResourceManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get resources from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get resources from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 
@@ -157,7 +157,7 @@ class ResourceManager:
             except Exception as e:
                 # Skip failed mounts silently, matches existing behavior
                 logger.warning(
-                    f"Failed to get templates from mounted server '{mounted.prefix}': {e}"
+                    f"Failed to get templates from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
                 continue
 

fastmcp/server/context.py

@@ -16,6 +16,7 @@ from mcp.shared.context import RequestContext
 from mcp.types import (
     ContentBlock,
     CreateMessageResult,
+    IncludeContext,
     ModelHint,
     ModelPreferences,
     Root,
@@ -272,6 +273,7 @@ class Context:
         self,
         messages: str | list[str | SamplingMessage],
         system_prompt: str | None = None,
+        include_context: IncludeContext | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
         model_preferences: ModelPreferences | str | list[str] | None = None,
@@ -304,6 +306,7 @@ class Context:
         result: CreateMessageResult = await self.session.create_message(
             messages=sampling_messages,
             system_prompt=system_prompt,
+            include_context=include_context,
             temperature=temperature,
             max_tokens=max_tokens,
             model_preferences=self._parse_model_preferences(model_preferences),

fastmcp/server/middleware/__init__.py

@@ -2,18 +2,10 @@ from .middleware import (
     Middleware,
     MiddlewareContext,
     CallNext,
-    ListToolsResult,
-    ListResourcesResult,
-    ListResourceTemplatesResult,
-    ListPromptsResult,
 )
 
 __all__ = [
     "Middleware",
     "MiddlewareContext",
     "CallNext",
-    "ListToolsResult",
-    "ListResourcesResult",
-    "ListResourceTemplatesResult",
-    "ListPromptsResult",
 ]

fastmcp/server/middleware/middleware.py

@@ -29,10 +29,6 @@ __all__ = [
     "Middleware",
     "MiddlewareContext",
     "CallNext",
-    "ListToolsResult",
-    "ListResourcesResult",
-    "ListResourceTemplatesResult",
-    "ListPromptsResult",
 ]
 
 logger = logging.getLogger(__name__)
@@ -62,26 +58,6 @@ ServerResultT = TypeVar(
 )
 
 
-@dataclass(kw_only=True)
-class ListToolsResult:
-    tools: dict[str, Tool]
-
-
-@dataclass(kw_only=True)
-class ListResourcesResult:
-    resources: list[Resource]
-
-
-@dataclass(kw_only=True)
-class ListResourceTemplatesResult:
-    resource_templates: list[ResourceTemplate]
-
-
-@dataclass(kw_only=True)
-class ListPromptsResult:
-    prompts: list[Prompt]
-
-
 @runtime_checkable
 class ServerResultProtocol(Protocol[ServerResultT]):
     root: ServerResultT
@@ -212,29 +188,27 @@ class Middleware:
     async def on_list_tools(
         self,
         context: MiddlewareContext[mt.ListToolsRequest],
-        call_next: CallNext[mt.ListToolsRequest, ListToolsResult],
-    ) -> ListToolsResult:
+        call_next: CallNext[mt.ListToolsRequest, list[Tool]],
+    ) -> list[Tool]:
         return await call_next(context)
 
     async def on_list_resources(
         self,
         context: MiddlewareContext[mt.ListResourcesRequest],
-        call_next: CallNext[mt.ListResourcesRequest, ListResourcesResult],
-    ) -> ListResourcesResult:
+        call_next: CallNext[mt.ListResourcesRequest, list[Resource]],
+    ) -> list[Resource]:
         return await call_next(context)
 
     async def on_list_resource_templates(
         self,
         context: MiddlewareContext[mt.ListResourceTemplatesRequest],
-        call_next: CallNext[
-            mt.ListResourceTemplatesRequest, ListResourceTemplatesResult
-        ],
-    ) -> ListResourceTemplatesResult:
+        call_next: CallNext[mt.ListResourceTemplatesRequest, list[ResourceTemplate]],
+    ) -> list[ResourceTemplate]:
         return await call_next(context)
 
     async def on_list_prompts(
         self,
         context: MiddlewareContext[mt.ListPromptsRequest],
-        call_next: CallNext[mt.ListPromptsRequest, ListPromptsResult],
-    ) -> ListPromptsResult:
+        call_next: CallNext[mt.ListPromptsRequest, list[Prompt]],
+    ) -> list[Prompt]:
         return await call_next(context)

fastmcp/server/openapi.py

@@ -29,6 +29,7 @@ from fastmcp.utilities.openapi import (
     _combine_schemas,
     extract_output_schema_from_responses,
     format_array_parameter,
+    format_deep_object_parameter,
     format_description_with_responses,
 )
 
@@ -261,19 +262,45 @@ class OpenAPITool(Tool):
     async def run(self, arguments: dict[str, Any]) -> ToolResult:
         """Execute the HTTP request based on the route configuration."""
 
+        # Create mapping from suffixed parameter names back to original names and locations
+        # This handles parameter collisions where suffixes were added during schema generation
+        param_mapping = {}  # suffixed_name -> (original_name, location)
+
+        # First, check if we have request body properties to detect collisions
+        body_props = set()
+        if self._route.request_body and self._route.request_body.content_schema:
+            content_type = next(iter(self._route.request_body.content_schema))
+            body_schema = self._route.request_body.content_schema[content_type]
+            body_props = set(body_schema.get("properties", {}).keys())
+
+        # Build parameter mapping for potentially suffixed parameters
+        for param in self._route.parameters:
+            original_name = param.name
+            suffixed_name = f"{param.name}__{param.location}"
+
+            # If parameter name collides with body property, it would have been suffixed
+            if param.name in body_props:
+                param_mapping[suffixed_name] = (original_name, param.location)
+            # Also map original name for backward compatibility when no collision
+            param_mapping[original_name] = (original_name, param.location)
+
         # Prepare URL
         path = self._route.path
 
-        # Replace path parameters with values from kwargs
-        # Path parameters should never be None as they're typically required
-        # but we'll handle that case anyway
-        path_params = {
-            p.name: arguments.get(p.name)
-            for p in self._route.parameters
-            if p.location == "path"
-            and p.name in arguments
-            and arguments.get(p.name) is not None
-        }
+        # Replace path parameters with values from arguments
+        # Look for both original and suffixed parameter names
+        path_params = {}
+        for p in self._route.parameters:
+            if p.location == "path":
+                # Try suffixed name first, then original name
+                suffixed_name = f"{p.name}__{p.location}"
+                if (
+                    suffixed_name in arguments
+                    and arguments.get(suffixed_name) is not None
+                ):
+                    path_params[p.name] = arguments[suffixed_name]
+                elif p.name in arguments and arguments.get(p.name) is not None:
+                    path_params[p.name] = arguments[p.name]
 
         # Ensure all path parameters are provided
         required_path_params = {
@@ -312,35 +339,82 @@ class OpenAPITool(Tool):
         # Prepare query parameters - filter out None and empty strings
         query_params = {}
         for p in self._route.parameters:
-            if (
-                p.location == "query"
-                and p.name in arguments
-                and arguments.get(p.name) is not None
-                and arguments.get(p.name) != ""
-            ):
-                param_value = arguments.get(p.name)
-
-                # Format array query parameters as comma-separated strings
-                # following OpenAPI form style (default for query parameters)
-                if isinstance(param_value, list) and p.schema_.get("type") == "array":
-                    # Get explode parameter from the parameter info, default is True for query parameters
-                    # If explode is True, the array is serialized as separate parameters
-                    # If explode is False, the array is serialized as a comma-separated string
-                    explode = p.explode if p.explode is not None else True
-
-                    if explode:
-                        # When explode=True, we pass the array directly, which HTTPX will serialize
-                        # as multiple parameters with the same name
-                        query_params[p.name] = param_value
-                    else:
-                        # Format array as comma-separated string when explode=False
-                        formatted_value = format_array_parameter(
-                            param_value, p.name, is_query_parameter=True
-                        )
-                        query_params[p.name] = formatted_value
+            if p.location == "query":
+                # Try suffixed name first, then original name
+                suffixed_name = f"{p.name}__{p.location}"
+                param_value = None
+
+                suffixed_value = arguments.get(suffixed_name)
+                if (
+                    suffixed_name in arguments
+                    and suffixed_value is not None
+                    and suffixed_value != ""
+                    and not (
+                        isinstance(suffixed_value, list | dict)
+                        and len(suffixed_value) == 0
+                    )
+                ):
+                    param_value = arguments[suffixed_name]
                 else:
-                    # Non-array parameters are passed as is
-                    query_params[p.name] = param_value
+                    name_value = arguments.get(p.name)
+                    if (
+                        p.name in arguments
+                        and name_value is not None
+                        and name_value != ""
+                        and not (
+                            isinstance(name_value, list | dict) and len(name_value) == 0
+                        )
+                    ):
+                        param_value = arguments[p.name]
+
+                if param_value is not None:
+                    # Handle different parameter styles and types
+                    param_style = (
+                        p.style or "form"
+                    )  # Default style for query parameters is "form"
+                    param_explode = (
+                        p.explode if p.explode is not None else True
+                    )  # Default explode for query is True
+
+                    # Handle deepObject style for object parameters
+                    if (
+                        param_style == "deepObject"
+                        and isinstance(param_value, dict)
+                        and len(param_value) > 0
+                    ):
+                        if param_explode:
+                            # deepObject with explode=true: object properties become separate parameters
+                            # e.g., target[id]=123&target[type]=user
+                            deep_obj_params = format_deep_object_parameter(
+                                param_value, p.name
+                            )
+                            query_params.update(deep_obj_params)
+                        else:
+                            # deepObject with explode=false is not commonly used, fallback to JSON
+                            logger.warning(
+                                f"deepObject style with explode=false for parameter '{p.name}' is not standard. "
+                                f"Using JSON serialization fallback."
+                            )
+                            query_params[p.name] = json.dumps(param_value)
+                    # Handle array parameters with form style (default)
+                    elif (
+                        isinstance(param_value, list)
+                        and p.schema_.get("type") == "array"
+                        and len(param_value) > 0
+                    ):
+                        if param_explode:
+                            # When explode=True, we pass the array directly, which HTTPX will serialize
+                            # as multiple parameters with the same name
+                            query_params[p.name] = param_value
+                        else:
+                            # Format array as comma-separated string when explode=False
+                            formatted_value = format_array_parameter(
+                                param_value, p.name, is_query_parameter=True
+                            )
+                            query_params[p.name] = formatted_value
+                    else:
+                        # Non-array, non-deepObject parameters are passed as is
+                        query_params[p.name] = param_value
 
         # Prepare headers - fix typing by ensuring all values are strings
         headers = {}
@@ -348,12 +422,21 @@ class OpenAPITool(Tool):
         # Start with OpenAPI-defined header parameters
         openapi_headers = {}
         for p in self._route.parameters:
-            if (
-                p.location == "header"
-                and p.name in arguments
-                and arguments[p.name] is not None
-            ):
-                openapi_headers[p.name.lower()] = str(arguments[p.name])
+            if p.location == "header":
+                # Try suffixed name first, then original name
+                suffixed_name = f"{p.name}__{p.location}"
+                param_value = None
+
+                if (
+                    suffixed_name in arguments
+                    and arguments.get(suffixed_name) is not None
+                ):
+                    param_value = arguments[suffixed_name]
+                elif p.name in arguments and arguments.get(p.name) is not None:
+                    param_value = arguments[p.name]
+
+                if param_value is not None:
+                    openapi_headers[p.name.lower()] = str(param_value)
         headers.update(openapi_headers)
 
         # Add headers from the current MCP client HTTP request (these take precedence)
@@ -363,16 +446,20 @@ class OpenAPITool(Tool):
         # Prepare request body
         json_data = None
         if self._route.request_body and self._route.request_body.content_schema:
-            # Extract body parameters, excluding path/query/header params that were already used
-            path_query_header_params = {
-                p.name
-                for p in self._route.parameters
-                if p.location in ("path", "query", "header")
-            }
+            # Extract body parameters with collision-aware logic
+            # Exclude all parameter names that belong to path/query/header locations
+            params_to_exclude = set()
+
+            for p in self._route.parameters:
+                if (
+                    p.name in body_props
+                ):  # This parameter had a collision, so it was suffixed
+                    params_to_exclude.add(f"{p.name}__{p.location}")
+                else:  # No collision, parameter keeps original name but should still be excluded from body
+                    params_to_exclude.add(p.name)
+
             body_params = {
-                k: v
-                for k, v in arguments.items()
-                if k not in path_query_header_params and k != "context"
+                k: v for k, v in arguments.items() if k not in params_to_exclude
             }
 
             if body_params:

fastmcp/server/proxy.py

@@ -36,6 +36,7 @@ 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.components import MirroredComponent
 from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
@@ -226,7 +227,7 @@ class ProxyPromptManager(PromptManager):
                 return result
 
 
-class ProxyTool(Tool):
+class ProxyTool(Tool, MirroredComponent):
     """
     A Tool that represents and executes a tool on a remote server.
     """
@@ -245,6 +246,7 @@ class ProxyTool(Tool):
             parameters=mcp_tool.inputSchema,
             annotations=mcp_tool.annotations,
             output_schema=mcp_tool.outputSchema,
+            _mirrored=True,
         )
 
     async def run(
@@ -266,7 +268,7 @@ class ProxyTool(Tool):
         )
 
 
-class ProxyResource(Resource):
+class ProxyResource(Resource, MirroredComponent):
     """
     A Resource that represents and reads a resource from a remote server.
     """
@@ -298,6 +300,7 @@ class ProxyResource(Resource):
             name=mcp_resource.name,
             description=mcp_resource.description,
             mime_type=mcp_resource.mimeType or "text/plain",
+            _mirrored=True,
         )
 
     async def read(self) -> str | bytes:
@@ -315,7 +318,7 @@ class ProxyResource(Resource):
             raise ResourceError(f"Unsupported content type: {type(result[0])}")
 
 
-class ProxyTemplate(ResourceTemplate):
+class ProxyTemplate(ResourceTemplate, MirroredComponent):
     """
     A ResourceTemplate that represents and creates resources from a remote server template.
     """
@@ -336,6 +339,7 @@ class ProxyTemplate(ResourceTemplate):
             description=mcp_template.description,
             mime_type=mcp_template.mimeType or "text/plain",
             parameters={},  # Remote templates don't have local parameters
+            _mirrored=True,
         )
 
     async def create_resource(
@@ -371,7 +375,7 @@ class ProxyTemplate(ResourceTemplate):
         )
 
 
-class ProxyPrompt(Prompt):
+class ProxyPrompt(Prompt, MirroredComponent):
     """
     A Prompt that represents and renders a prompt from a remote server.
     """
@@ -400,6 +404,7 @@ class ProxyPrompt(Prompt):
             name=mcp_prompt.name,
             description=mcp_prompt.description,
             arguments=arguments,
+            _mirrored=True,
         )
 
     async def render(self, arguments: dict[str, Any]) -> list[PromptMessage]:
@@ -575,3 +580,45 @@ class ProxyClient(Client[ClientTransportT]):
         """
         ctx = get_context()
         await ctx.report_progress(progress, total, message)
+
+
+class StatefulProxyClient(ProxyClient[ClientTransportT]):
+    """
+    A proxy client that provides a stateful client factory for the proxy server.
+
+    The stateful proxy client bound its copy to the server session.
+    And it will be disconnected when the session is exited.
+
+    This is useful to proxy a stateful mcp server such as the Playwright MCP server.
+    Note that it is essential to ensure that the proxy server itself is also stateful.
+    """
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        """
+        The stateful proxy client will be forced disconnected when the session is exited.
+        So we do nothing here.
+        """
+        pass
+
+    def new_stateful(self) -> Client[ClientTransportT]:
+        """
+        Create a new stateful proxy client instance with the same configuration.
+
+        Use this method as the client factory for stateful proxy server.
+        """
+        session = get_context().session
+        proxy_client = session.__dict__.get("_proxy_client", None)
+
+        if proxy_client is None:
+            proxy_client = self.new()
+            logger.debug(f"{proxy_client} created for {session}")
+            session.__dict__["_proxy_client"] = proxy_client
+
+            async def _on_session_exit():
+                proxy_client: Client = session.__dict__.pop("_proxy_client")
+                logger.debug(f"{proxy_client} will be disconnect")
+                await proxy_client._disconnect(force=True)
+
+            session._exit_stack.push_async_callback(_on_session_exit)
+
+        return proxy_client