fastmcp 2.11.2__py3-none-any.whl → 2.12.0__py3-none-any.whl

fastmcp/experimental/utilities/openapi/schemas.py

@@ -75,7 +75,7 @@ def _replace_ref_with_defs(
     info: dict[str, Any], description: str | None = None
 ) -> dict[str, Any]:
     """
-    Replace openapi $ref with jsonschema $defs
+    Replace openapi $ref with jsonschema $defs recursively.
 
     Examples:
     - {"type": "object", "properties": {"$ref": "#/components/schemas/..."}}
@@ -202,6 +202,7 @@ def _make_optional_parameter_nullable(schema: dict[str, Any]) -> dict[str, Any]:
 
 def _combine_schemas_and_map_params(
     route: HTTPRoute,
+    convert_refs: bool = True,
 ) -> tuple[dict[str, Any], dict[str, dict[str, str]]]:
     """
     Combines parameter and request body schemas into a single schema.
@@ -233,10 +234,43 @@ def _combine_schemas_and_map_params(
 
     if route.request_body and route.request_body.content_schema:
         content_type = next(iter(route.request_body.content_schema))
-        body_schema = _replace_ref_with_defs(
-            route.request_body.content_schema[content_type].copy(),
-            route.request_body.description,
-        )
+
+        # Convert refs if needed
+        if convert_refs:
+            body_schema = _replace_ref_with_defs(
+                route.request_body.content_schema[content_type]
+            )
+        else:
+            body_schema = route.request_body.content_schema[content_type]
+
+        if route.request_body.description and not body_schema.get("description"):
+            body_schema["description"] = route.request_body.description
+
+        # Handle allOf at the top level by merging all schemas
+        if "allOf" in body_schema and isinstance(body_schema["allOf"], list):
+            merged_props = {}
+            merged_required = []
+
+            for sub_schema in body_schema["allOf"]:
+                if isinstance(sub_schema, dict):
+                    # Merge properties
+                    if "properties" in sub_schema:
+                        merged_props.update(sub_schema["properties"])
+                    # Merge required fields
+                    if "required" in sub_schema:
+                        merged_required.extend(sub_schema["required"])
+
+            # Update body_schema with merged properties
+            body_schema["properties"] = merged_props
+            if merged_required:
+                # Remove duplicates while preserving order
+                seen = set()
+                body_schema["required"] = [
+                    x for x in merged_required if not (x in seen or seen.add(x))
+                ]
+            # Remove the allOf since we've merged it
+            body_schema.pop("allOf", None)
+
         body_props = body_schema.get("properties", {})
 
     # Detect collisions: parameters that exist in both body and path/query/header
@@ -261,10 +295,11 @@ def _combine_schemas_and_map_params(
                 "openapi_name": param.name,
             }
 
-            # Add location info to description
-            param_schema = _replace_ref_with_defs(
-                param.schema_.copy(), param.description
-            )
+            # Convert refs if needed
+            if convert_refs:
+                param_schema = _replace_ref_with_defs(param.schema_)
+            else:
+                param_schema = param.schema_
             original_desc = param_schema.get("description", "")
             location_desc = f"({param.location.capitalize()} parameter)"
             if original_desc:
@@ -287,9 +322,11 @@ def _combine_schemas_and_map_params(
                 "openapi_name": param.name,
             }
 
-            param_schema = _replace_ref_with_defs(
-                param.schema_.copy(), param.description
-            )
+            # Convert refs if needed
+            if convert_refs:
+                param_schema = _replace_ref_with_defs(param.schema_)
+            else:
+                param_schema = param.schema_
 
             # Don't make optional parameters nullable - they can simply be omitted
             # The OpenAPI specification doesn't require optional parameters to accept null values
@@ -298,14 +335,28 @@ def _combine_schemas_and_map_params(
 
     # Add request body properties (no suffixes for body parameters)
     if route.request_body and route.request_body.content_schema:
-        for prop_name, prop_schema in body_props.items():
-            properties[prop_name] = prop_schema
+        # If body is just a $ref, we need to handle it differently
+        if "$ref" in body_schema and not body_props:
+            # The entire body is a reference to a schema
+            # We need to expand this inline or keep the ref
+            # For simplicity, we'll keep it as a single property
+            properties["body"] = body_schema
+            if route.request_body.required:
+                required.append("body")
+            parameter_map["body"] = {"location": "body", "openapi_name": "body"}
+        else:
+            # Normal case: body has properties
+            for prop_name, prop_schema in body_props.items():
+                properties[prop_name] = prop_schema
 
-            # Track parameter mapping for body properties
-            parameter_map[prop_name] = {"location": "body", "openapi_name": prop_name}
+                # Track parameter mapping for body properties
+                parameter_map[prop_name] = {
+                    "location": "body",
+                    "openapi_name": prop_name,
+                }
 
-        if route.request_body.required:
-            required.extend(body_schema.get("required", []))
+            if route.request_body.required:
+                required.extend(body_schema.get("required", []))
 
     result = {
         "type": "object",
@@ -313,43 +364,53 @@ def _combine_schemas_and_map_params(
         "required": required,
     }
     # Add schema definitions if available
-    if route.schema_definitions:
-        result["$defs"] = route.schema_definitions.copy()
-
-    # Use lightweight compression - prune additionalProperties and unused definitions
-    if result.get("additionalProperties") is False:
-        result.pop("additionalProperties")
-
-    # Remove unused definitions (lightweight approach - just check direct $ref usage)
-    if "$defs" in result:
-        used_refs = set()
-
-        def find_refs_in_value(value):
-            if isinstance(value, dict):
-                if "$ref" in value and isinstance(value["$ref"], str):
-                    ref = value["$ref"]
-                    if ref.startswith("#/$defs/"):
-                        used_refs.add(ref.split("/")[-1])
-                for v in value.values():
-                    find_refs_in_value(v)
-            elif isinstance(value, list):
-                for item in value:
-                    find_refs_in_value(item)
-
-        # Find refs in the main schema (excluding $defs section)
-        for key, value in result.items():
-            if key != "$defs":
-                find_refs_in_value(value)
-
-        # Remove unused definitions
-        if used_refs:
-            result["$defs"] = {
-                name: def_schema
-                for name, def_schema in result["$defs"].items()
-                if name in used_refs
-            }
+    schema_defs = route.request_schemas
+    if schema_defs:
+        if convert_refs:
+            # Need to convert refs and prune
+            all_defs = schema_defs.copy()
+            # Convert each schema definition recursively
+            for name, schema in all_defs.items():
+                if isinstance(schema, dict):
+                    all_defs[name] = _replace_ref_with_defs(schema)
+
+            # Prune to only needed schemas
+            used_refs = set()
+
+            def find_refs_in_value(value):
+                """Recursively find all $ref references."""
+                if isinstance(value, dict):
+                    if "$ref" in value and isinstance(value["$ref"], str):
+                        ref = value["$ref"]
+                        if ref.startswith("#/$defs/"):
+                            used_refs.add(ref.split("/")[-1])
+                    for v in value.values():
+                        find_refs_in_value(v)
+                elif isinstance(value, list):
+                    for item in value:
+                        find_refs_in_value(item)
+
+            # Find refs in properties
+            find_refs_in_value(properties)
+
+            # Collect transitive dependencies
+            if used_refs:
+                collected_all = False
+                while not collected_all:
+                    initial_count = len(used_refs)
+                    for name in list(used_refs):
+                        if name in all_defs:
+                            find_refs_in_value(all_defs[name])
+                    collected_all = len(used_refs) == initial_count
+
+                result["$defs"] = {
+                    name: def_schema
+                    for name, def_schema in all_defs.items()
+                    if name in used_refs
+                }
         else:
-            result.pop("$defs")
+            # From parser - already converted and pruned
+            result["$defs"] = schema_defs
 
     return result, parameter_map
 
@@ -440,17 +501,17 @@ def extract_output_schema_from_responses(
     if not schema or not isinstance(schema, dict):
         return None
 
-    # Clean and copy the schema
-    output_schema = schema.copy()
+    # Convert refs if needed
+    output_schema = _replace_ref_with_defs(schema)
 
     # If schema has a $ref, resolve it first before processing nullable fields
     if "$ref" in output_schema and schema_definitions:
         ref_path = output_schema["$ref"]
-        if ref_path.startswith("#/components/schemas/"):
+        if ref_path.startswith("#/$defs/"):
             schema_name = ref_path.split("/")[-1]
             if schema_name in schema_definitions:
                 # Replace $ref with the actual schema definition
-                output_schema = schema_definitions[schema_name].copy()
+                output_schema = _replace_ref_with_defs(schema_definitions[schema_name])
 
     # Convert OpenAPI schema to JSON Schema format
     # Only needed for OpenAPI 3.0 - 3.1 uses standard JSON Schema null types
@@ -473,56 +534,25 @@ def extract_output_schema_from_responses(
         }
         output_schema = wrapped_schema
 
-    # Add schema definitions if available and handle nullable fields in them
-    # Only add $defs if we didn't resolve the $ref inline above
-    if schema_definitions and "$ref" not in schema.copy():
-        processed_defs = {}
-        for def_name, def_schema in schema_definitions.items():
-            # Convert OpenAPI schema definitions to JSON Schema format
-            if openapi_version and openapi_version.startswith("3.0"):
-                from .json_schema_converter import convert_openapi_schema_to_json_schema
-
+    # Add schema definitions if available
+    if schema_definitions:
+        # Convert refs if needed
+        processed_defs = schema_definitions.copy()
+        # Convert each schema definition recursively
+        for name, schema in processed_defs.items():
+            if isinstance(schema, dict):
+                processed_defs[name] = _replace_ref_with_defs(schema)
+
+        # Convert OpenAPI schema definitions to JSON Schema format if needed
+        if openapi_version and openapi_version.startswith("3.0"):
+            from .json_schema_converter import convert_openapi_schema_to_json_schema
+
+            for def_name in list(processed_defs.keys()):
                 processed_defs[def_name] = convert_openapi_schema_to_json_schema(
-                    def_schema, openapi_version
+                    processed_defs[def_name], openapi_version
                 )
-            else:
-                processed_defs[def_name] = def_schema
-        output_schema["$defs"] = processed_defs
 
-    # Use lightweight compression - prune additionalProperties and unused definitions
-    if output_schema.get("additionalProperties") is False:
-        output_schema.pop("additionalProperties")
-
-    # Remove unused definitions (lightweight approach - just check direct $ref usage)
-    if "$defs" in output_schema:
-        used_refs = set()
-
-        def find_refs_in_value(value):
-            if isinstance(value, dict):
-                if "$ref" in value and isinstance(value["$ref"], str):
-                    ref = value["$ref"]
-                    if ref.startswith("#/$defs/"):
-                        used_refs.add(ref.split("/")[-1])
-                for v in value.values():
-                    find_refs_in_value(v)
-            elif isinstance(value, list):
-                for item in value:
-                    find_refs_in_value(item)
-
-        # Find refs in the main schema (excluding $defs section)
-        for key, value in output_schema.items():
-            if key != "$defs":
-                find_refs_in_value(value)
-
-        # Remove unused definitions
-        if used_refs:
-            output_schema["$defs"] = {
-                name: def_schema
-                for name, def_schema in output_schema["$defs"].items()
-                if name in used_refs
-            }
-        else:
-            output_schema.pop("$defs")
+        output_schema["$defs"] = processed_defs
 
     return output_schema
 
@@ -533,6 +563,5 @@ __all__ = [
     "_combine_schemas",
     "_combine_schemas_and_map_params",
     "extract_output_schema_from_responses",
-    "_replace_ref_with_defs",
     "_make_optional_parameter_nullable",
 ]

fastmcp/mcp_config.py

@@ -27,7 +27,7 @@ from __future__ import annotations
 import datetime
 import re
 from pathlib import Path
-from typing import TYPE_CHECKING, Annotated, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal, cast
 from urllib.parse import urlparse
 
 import httpx
@@ -36,7 +36,6 @@ from pydantic import (
     BaseModel,
     ConfigDict,
     Field,
-    ValidationInfo,
     model_validator,
 )
 from typing_extensions import Self, override
@@ -47,11 +46,11 @@ from fastmcp.utilities.types import FastMCPBaseModel
 if TYPE_CHECKING:
     from fastmcp.client.transports import (
         ClientTransport,
-        FastMCPTransport,
         SSETransport,
         StdioTransport,
         StreamableHttpTransport,
     )
+    from fastmcp.server.server import FastMCP
 
 
 def infer_transport_type_from_url(
@@ -90,21 +89,38 @@ class _TransformingMCPServerMixin(FastMCPBaseModel):
         description="The tags to exclude in the proxy.",
     )
 
-    def to_transport(self) -> FastMCPTransport:
-        """Get the transport for the server."""
-        from fastmcp.client.transports import FastMCPTransport
-        from fastmcp.server.server import FastMCP
+    def _to_server_and_underlying_transport(
+        self,
+        server_name: str | None = None,
+        client_name: str | None = None,
+    ) -> tuple[FastMCP[Any], ClientTransport]:
+        """Turn the Transforming MCPServer into a FastMCP Server and also return the underlying transport."""
+        from fastmcp import FastMCP
+        from fastmcp.client import Client
+        from fastmcp.client.transports import (
+            ClientTransport,  # pyright: ignore[reportUnusedImport]
+        )
 
         transport: ClientTransport = super().to_transport()  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue, reportUnknownVariableType]
+        transport = cast(ClientTransport, transport)
+
+        client: Client[ClientTransport] = Client(transport=transport, name=client_name)
 
         wrapped_mcp_server = FastMCP.as_proxy(
-            transport,
+            name=server_name,
+            backend=client,
             tool_transformations=self.tools,
             include_tags=self.include_tags,
             exclude_tags=self.exclude_tags,
         )
 
-        return FastMCPTransport(wrapped_mcp_server)
+        return wrapped_mcp_server, transport
+
+    def to_transport(self) -> ClientTransport:
+        """Get the transport for the transforming MCP server."""
+        from fastmcp.client.transports import FastMCPTransport
+
+        return FastMCPTransport(mcp=self._to_server_and_underlying_transport()[0])
 
 
 class StdioMCPServer(BaseModel):
@@ -232,20 +248,24 @@ class MCPConfig(BaseModel):
     For an MCPConfig that is strictly canonical, see the `CanonicalMCPConfig` class.
     """
 
-    mcpServers: dict[str, MCPServerTypes]
+    mcpServers: dict[str, MCPServerTypes] = Field(default_factory=dict)
 
     model_config = ConfigDict(extra="allow")  # Preserve unknown top-level fields
 
     @model_validator(mode="before")
-    def validate_mcp_servers(self, info: ValidationInfo) -> dict[str, Any]:
-        """Validate the MCP servers."""
-        if not isinstance(self, dict):
-            raise ValueError("MCPConfig format requires a dictionary of servers.")
-
-        if "mcpServers" not in self:
-            self = {"mcpServers": self}
-
-        return self
+    @classmethod
+    def wrap_servers_at_root(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """If there's no mcpServers key but there are server configs at root, wrap them."""
+        if "mcpServers" not in values:
+            # Check if any values look like server configs
+            has_servers = any(
+                isinstance(v, dict) and ("command" in v or "url" in v)
+                for v in values.values()
+            )
+            if has_servers:
+                # Move all server-like configs under mcpServers
+                return {"mcpServers": values}
+        return values
 
     def add_server(self, name: str, server: MCPServerTypes) -> None:
         """Add or update a server in the configuration."""
@@ -282,7 +302,7 @@ class CanonicalMCPConfig(MCPConfig):
     The format is designed to be client-agnostic and extensible for future use cases.
     """
 
-    mcpServers: dict[str, CanonicalMCPServerTypes]
+    mcpServers: dict[str, CanonicalMCPServerTypes] = Field(default_factory=dict)
 
     @override
     def add_server(self, name: str, server: CanonicalMCPServerTypes) -> None:

fastmcp/prompts/prompt_manager.py

@@ -69,8 +69,8 @@ class PromptManager:
                 child_dict = {p.key: p for p in child_results}
                 if mounted.prefix:
                     for prompt in child_dict.values():
-                        prefixed_prompt = prompt.with_key(
-                            f"{mounted.prefix}_{prompt.key}"
+                        prefixed_prompt = prompt.model_copy(
+                            key=f"{mounted.prefix}_{prompt.key}"
                         )
                         all_prompts[prefixed_prompt.key] = prefixed_prompt
                 else:
@@ -80,6 +80,8 @@ class PromptManager:
                 logger.warning(
                     f"Failed to get prompts from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
+                if settings.mounted_components_raise_on_load_error:
+                    raise
                 continue
 
         # Finally, add local prompts, which always take precedence

fastmcp/resources/resource_manager.py

@@ -101,8 +101,11 @@ class ResourceManager:
                         prefixed_uri = add_resource_prefix(
                             uri, mounted.prefix, mounted.resource_prefix_format
                         )
-                        # Create a copy of the resource with the prefixed key
-                        prefixed_resource = resource.with_key(prefixed_uri)
+                        # Create a copy of the resource with the prefixed key and name
+                        prefixed_resource = resource.model_copy(
+                            update={"name": f"{mounted.prefix}_{resource.name}"},
+                            key=prefixed_uri,
+                        )
                         all_resources[prefixed_uri] = prefixed_resource
                 else:
                     all_resources.update(child_resources)
@@ -111,6 +114,8 @@ class ResourceManager:
                 logger.warning(
                     f"Failed to get resources from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
+                if settings.mounted_components_raise_on_load_error:
+                    raise
                 continue
 
         # Finally, add local resources, which always take precedence
@@ -149,8 +154,11 @@ class ResourceManager:
                         prefixed_uri_template = add_resource_prefix(
                             uri_template, mounted.prefix, mounted.resource_prefix_format
                         )
-                        # Create a copy of the template with the prefixed key
-                        prefixed_template = template.with_key(prefixed_uri_template)
+                        # Create a copy of the template with the prefixed key and name
+                        prefixed_template = template.model_copy(
+                            update={"name": f"{mounted.prefix}_{template.name}"},
+                            key=prefixed_uri_template,
+                        )
                         all_templates[prefixed_uri_template] = prefixed_template
                 else:
                     all_templates.update(child_dict)
@@ -159,6 +167,8 @@ class ResourceManager:
                 logger.warning(
                     f"Failed to get templates from server: {mounted.server.name!r}, mounted at: {mounted.prefix!r}: {e}"
                 )
+                if settings.mounted_components_raise_on_load_error:
+                    raise
                 continue
 
         # Finally, add local templates, which always take precedence
@@ -273,7 +283,7 @@ class ResourceManager:
         Args:
             resource: A Resource instance to add. The resource's .key attribute
                 will be used as the storage key. To overwrite it, call
-                Resource.with_key() before calling this method.
+                Resource.model_copy(key=new_key) before calling this method.
         """
         existing = self._resources.get(resource.key)
         if existing:
@@ -322,7 +332,7 @@ class ResourceManager:
         Args:
             template: A ResourceTemplate instance to add. The template's .key attribute
                 will be used as the storage key. To overwrite it, call
-                ResourceTemplate.with_key() before calling this method.
+                ResourceTemplate.model_copy(key=new_key) before calling this method.
 
         Returns:
             The added template. If a template with the same URI already exists,

fastmcp/server/auth/__init__.py

@@ -1,13 +1,23 @@
-from .auth import OAuthProvider, TokenVerifier, RemoteAuthProvider
+from .auth import (
+    OAuthProvider,
+    TokenVerifier,
+    RemoteAuthProvider,
+    AccessToken,
+    AuthProvider,
+)
 from .providers.jwt import JWTVerifier, StaticTokenVerifier
+from .oauth_proxy import OAuthProxy
 
 
 __all__ = [
+    "AuthProvider",
     "OAuthProvider",
     "TokenVerifier",
     "JWTVerifier",
     "StaticTokenVerifier",
     "RemoteAuthProvider",
+    "AccessToken",
+    "OAuthProxy",
 ]
 
 

fastmcp/server/auth/auth.py

@@ -1,7 +1,11 @@
 from __future__ import annotations
 
+from typing import Any
+
+from mcp.server.auth.provider import (
+    AccessToken as _SDKAccessToken,
+)
 from mcp.server.auth.provider import (
-    AccessToken,
     AuthorizationCode,
     OAuthAuthorizationServerProvider,
     RefreshToken,
@@ -21,6 +25,12 @@ from pydantic import AnyHttpUrl
 from starlette.routing import Route
 
 
+class AccessToken(_SDKAccessToken):
+    """AccessToken that includes all JWT claims."""
+
+    claims: dict[str, Any] = {}
+
+
 class AuthProvider(TokenVerifierProtocol):
     """Base class for all FastMCP authentication providers.
 
@@ -125,11 +135,15 @@ class RemoteAuthProvider(AuthProvider):
     the authorization servers that issue valid tokens.
     """
 
+    resource_server_url: AnyHttpUrl
+
     def __init__(
         self,
         token_verifier: TokenVerifier,
         authorization_servers: list[AnyHttpUrl],
         resource_server_url: AnyHttpUrl | str,
+        resource_name: str | None = None,
+        resource_documentation: AnyHttpUrl | None = None,
     ):
         """Initialize the remote auth provider.
 
@@ -143,6 +157,8 @@ class RemoteAuthProvider(AuthProvider):
         super().__init__(resource_server_url=resource_server_url)
         self.token_verifier = token_verifier
         self.authorization_servers = authorization_servers
+        self.resource_name = resource_name
+        self.resource_documentation = resource_documentation
 
     async def verify_token(self, token: str) -> AccessToken | None:
         """Verify token using the configured token verifier."""
@@ -155,12 +171,13 @@ class RemoteAuthProvider(AuthProvider):
         Subclasses can override this method to add additional routes by calling
         super().get_routes() and extending the returned list.
         """
-        assert self.resource_server_url is not None
 
         return create_protected_resource_routes(
             resource_url=self.resource_server_url,
             authorization_servers=self.authorization_servers,
             scopes_supported=self.token_verifier.required_scopes,
+            resource_name=self.resource_name,
+            resource_documentation=self.resource_documentation,
         )