fastmcp 2.8.1__py3-none-any.whl → 2.9.1__py3-none-any.whl

fastmcp/utilities/inspect.py

@@ -0,0 +1,326 @@
+"""Utilities for inspecting FastMCP instances."""
+
+from __future__ import annotations
+
+import importlib.metadata
+from dataclasses import dataclass
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP as FastMCP1x
+
+import fastmcp
+from fastmcp.server.server import FastMCP
+
+
+@dataclass
+class ToolInfo:
+    """Information about a tool."""
+
+    key: str
+    name: str
+    description: str | None
+    input_schema: dict[str, Any]
+    annotations: dict[str, Any] | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class PromptInfo:
+    """Information about a prompt."""
+
+    key: str
+    name: str
+    description: str | None
+    arguments: list[dict[str, Any]] | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class ResourceInfo:
+    """Information about a resource."""
+
+    key: str
+    uri: str
+    name: str | None
+    description: str | None
+    mime_type: str | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class TemplateInfo:
+    """Information about a resource template."""
+
+    key: str
+    uri_template: str
+    name: str | None
+    description: str | None
+    mime_type: str | None = None
+    tags: list[str] | None = None
+    enabled: bool | None = None
+
+
+@dataclass
+class FastMCPInfo:
+    """Information extracted from a FastMCP instance."""
+
+    name: str
+    instructions: str | None
+    fastmcp_version: str
+    mcp_version: str
+    server_version: str
+    tools: list[ToolInfo]
+    prompts: list[PromptInfo]
+    resources: list[ResourceInfo]
+    templates: list[TemplateInfo]
+    capabilities: dict[str, Any]
+
+
+async def inspect_fastmcp_v2(mcp: FastMCP[Any]) -> FastMCPInfo:
+    """Extract information from a FastMCP v2.x instance.
+
+    Args:
+        mcp: The FastMCP v2.x instance to inspect
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    # Get all the components using FastMCP2's direct methods
+    tools_dict = await mcp.get_tools()
+    prompts_dict = await mcp.get_prompts()
+    resources_dict = await mcp.get_resources()
+    templates_dict = await mcp.get_resource_templates()
+
+    # Extract detailed tool information
+    tool_infos = []
+    for key, tool in tools_dict.items():
+        # Convert to MCP tool to get input schema
+        mcp_tool = tool.to_mcp_tool(name=key)
+        tool_infos.append(
+            ToolInfo(
+                key=key,
+                name=tool.name or key,
+                description=tool.description,
+                input_schema=mcp_tool.inputSchema if mcp_tool.inputSchema else {},
+                annotations=tool.annotations.model_dump() if tool.annotations else None,
+                tags=list(tool.tags) if tool.tags else None,
+                enabled=tool.enabled,
+            )
+        )
+
+    # Extract detailed prompt information
+    prompt_infos = []
+    for key, prompt in prompts_dict.items():
+        prompt_infos.append(
+            PromptInfo(
+                key=key,
+                name=prompt.name or key,
+                description=prompt.description,
+                arguments=[arg.model_dump() for arg in prompt.arguments]
+                if prompt.arguments
+                else None,
+                tags=list(prompt.tags) if prompt.tags else None,
+                enabled=prompt.enabled,
+            )
+        )
+
+    # Extract detailed resource information
+    resource_infos = []
+    for key, resource in resources_dict.items():
+        resource_infos.append(
+            ResourceInfo(
+                key=key,
+                uri=key,  # For v2, key is the URI
+                name=resource.name,
+                description=resource.description,
+                mime_type=resource.mime_type,
+                tags=list(resource.tags) if resource.tags else None,
+                enabled=resource.enabled,
+            )
+        )
+
+    # Extract detailed template information
+    template_infos = []
+    for key, template in templates_dict.items():
+        template_infos.append(
+            TemplateInfo(
+                key=key,
+                uri_template=key,  # For v2, key is the URI template
+                name=template.name,
+                description=template.description,
+                mime_type=template.mime_type,
+                tags=list(template.tags) if template.tags else None,
+                enabled=template.enabled,
+            )
+        )
+
+    # Basic MCP capabilities that FastMCP supports
+    capabilities = {
+        "tools": {"listChanged": True},
+        "resources": {"subscribe": False, "listChanged": False},
+        "prompts": {"listChanged": False},
+        "logging": {},
+    }
+
+    return FastMCPInfo(
+        name=mcp.name,
+        instructions=mcp.instructions,
+        fastmcp_version=fastmcp.__version__,
+        mcp_version=importlib.metadata.version("mcp"),
+        server_version=fastmcp.__version__,  # v2.x uses FastMCP version
+        tools=tool_infos,
+        prompts=prompt_infos,
+        resources=resource_infos,
+        templates=template_infos,
+        capabilities=capabilities,
+    )
+
+
+async def inspect_fastmcp_v1(mcp: Any) -> FastMCPInfo:
+    """Extract information from a FastMCP v1.x instance using a Client.
+
+    Args:
+        mcp: The FastMCP v1.x instance to inspect
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    from fastmcp import Client
+
+    # Use a client to interact with the FastMCP1x server
+    async with Client(mcp) as client:
+        # Get components via client calls (these return MCP objects)
+        mcp_tools = await client.list_tools()
+        mcp_prompts = await client.list_prompts()
+        mcp_resources = await client.list_resources()
+
+        # Try to get resource templates (FastMCP 1.x does have templates)
+        try:
+            mcp_templates = await client.list_resource_templates()
+        except Exception:
+            mcp_templates = []
+
+        # Extract detailed tool information from MCP Tool objects
+        tool_infos = []
+        for mcp_tool in mcp_tools:
+            # Extract annotations if they exist
+            annotations = None
+            if hasattr(mcp_tool, "annotations") and mcp_tool.annotations:
+                if hasattr(mcp_tool.annotations, "model_dump"):
+                    annotations = mcp_tool.annotations.model_dump()
+                elif isinstance(mcp_tool.annotations, dict):
+                    annotations = mcp_tool.annotations
+                else:
+                    annotations = None
+
+            tool_infos.append(
+                ToolInfo(
+                    key=mcp_tool.name,  # For 1.x, key and name are the same
+                    name=mcp_tool.name,
+                    description=mcp_tool.description,
+                    input_schema=mcp_tool.inputSchema if mcp_tool.inputSchema else {},
+                    annotations=annotations,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Extract detailed prompt information from MCP Prompt objects
+        prompt_infos = []
+        for mcp_prompt in mcp_prompts:
+            # Convert arguments if they exist
+            arguments = None
+            if hasattr(mcp_prompt, "arguments") and mcp_prompt.arguments:
+                arguments = [arg.model_dump() for arg in mcp_prompt.arguments]
+
+            prompt_infos.append(
+                PromptInfo(
+                    key=mcp_prompt.name,  # For 1.x, key and name are the same
+                    name=mcp_prompt.name,
+                    description=mcp_prompt.description,
+                    arguments=arguments,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Extract detailed resource information from MCP Resource objects
+        resource_infos = []
+        for mcp_resource in mcp_resources:
+            resource_infos.append(
+                ResourceInfo(
+                    key=str(mcp_resource.uri),  # For 1.x, key and uri are the same
+                    uri=str(mcp_resource.uri),
+                    name=mcp_resource.name,
+                    description=mcp_resource.description,
+                    mime_type=mcp_resource.mimeType,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Extract detailed template information from MCP ResourceTemplate objects
+        template_infos = []
+        for mcp_template in mcp_templates:
+            template_infos.append(
+                TemplateInfo(
+                    key=str(
+                        mcp_template.uriTemplate
+                    ),  # For 1.x, key and uriTemplate are the same
+                    uri_template=str(mcp_template.uriTemplate),
+                    name=mcp_template.name,
+                    description=mcp_template.description,
+                    mime_type=mcp_template.mimeType,
+                    tags=None,  # 1.x doesn't have tags
+                    enabled=None,  # 1.x doesn't have enabled field
+                )
+            )
+
+        # Basic MCP capabilities
+        capabilities = {
+            "tools": {"listChanged": True},
+            "resources": {"subscribe": False, "listChanged": False},
+            "prompts": {"listChanged": False},
+            "logging": {},
+        }
+
+        return FastMCPInfo(
+            name=mcp.name,
+            instructions=getattr(mcp, "instructions", None),
+            fastmcp_version=fastmcp.__version__,  # Report current fastmcp version
+            mcp_version=importlib.metadata.version("mcp"),
+            server_version="1.0",  # FastMCP 1.x version
+            tools=tool_infos,
+            prompts=prompt_infos,
+            resources=resource_infos,
+            templates=template_infos,  # FastMCP1x does have templates
+            capabilities=capabilities,
+        )
+
+
+def _is_fastmcp_v1(mcp: Any) -> bool:
+    """Check if the given instance is a FastMCP v1.x instance."""
+
+    # Check if it's an instance of FastMCP1x and not FastMCP2
+    return isinstance(mcp, FastMCP1x) and not isinstance(mcp, FastMCP)
+
+
+async def inspect_fastmcp(mcp: FastMCP[Any] | Any) -> FastMCPInfo:
+    """Extract information from a FastMCP instance into a dataclass.
+
+    This function automatically detects whether the instance is FastMCP v1.x or v2.x
+    and uses the appropriate extraction method.
+
+    Args:
+        mcp: The FastMCP instance to inspect (v1.x or v2.x)
+
+    Returns:
+        FastMCPInfo dataclass containing the extracted information
+    """
+    if _is_fastmcp_v1(mcp):
+        return await inspect_fastmcp_v1(mcp)
+    else:
+        return await inspect_fastmcp_v2(mcp)

fastmcp/utilities/json_schema.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import copy
+from collections import defaultdict
 
 
 def _prune_param(schema: dict, param: str) -> dict:
@@ -24,25 +25,77 @@ def _prune_param(schema: dict, param: str) -> dict:
     return schema
 
 
+def _prune_unused_defs(schema: dict) -> dict:
+    """Walk the schema and prune unused defs."""
+
+    root_defs: set[str] = set()
+    referenced_by: defaultdict[str, list] = defaultdict(list)
+
+    defs = schema.get("$defs")
+    if defs is None:
+        return schema
+
+    def walk(
+        node: object, current_def: str | None = None, skip_defs: bool = False
+    ) -> None:
+        if isinstance(node, dict):
+            # Process $ref for definition tracking
+            ref = node.get("$ref")
+            if isinstance(ref, str) and ref.startswith("#/$defs/"):
+                def_name = ref.split("/")[-1]
+                if current_def:
+                    referenced_by[def_name].append(current_def)
+                else:
+                    root_defs.add(def_name)
+
+            # Walk children
+            for k, v in node.items():
+                if skip_defs and k == "$defs":
+                    continue
+
+                walk(v, current_def=current_def)
+
+        elif isinstance(node, list):
+            for v in node:
+                walk(v)
+
+    # Traverse the schema once, skipping the $defs
+    walk(schema, skip_defs=True)
+
+    # Now figure out what defs reference other defs
+    for def_name, value in defs.items():
+        walk(value, current_def=def_name)
+
+    # Figure out what defs were referenced directly or recursively
+    def def_is_referenced(def_name):
+        if def_name in root_defs:
+            return True
+        references = referenced_by.get(def_name)
+        if references:
+            for reference in references:
+                if def_is_referenced(reference):
+                    return True
+        return False
+
+    # Remove orphaned definitions if requested
+    for def_name in list(defs):
+        if not def_is_referenced(def_name):
+            defs.pop(def_name)
+    if not defs:
+        schema.pop("$defs", None)
+
+    return schema
+
+
 def _walk_and_prune(
     schema: dict,
-    prune_defs: bool = False,
     prune_titles: bool = False,
     prune_additional_properties: bool = False,
 ) -> dict:
-    """Walk the schema and optionally prune titles, unused definitions, and additionalProperties: false."""
-
-    # Will only be used if prune_defs is True
-    used_defs: set[str] = set()
+    """Walk the schema and optionally prune titles and additionalProperties: false."""
 
     def walk(node: object) -> None:
         if isinstance(node, dict):
-            # Process $ref for definition tracking
-            if prune_defs:
-                ref = node.get("$ref")
-                if isinstance(ref, str) and ref.startswith("#/$defs/"):
-                    used_defs.add(ref.split("/")[-1])
-
             # Remove title if requested
             if prune_titles and "title" in node:
                 node.pop("title")
@@ -62,18 +115,8 @@ def _walk_and_prune(
             for v in node:
                 walk(v)
 
-    # Traverse the schema once
     walk(schema)
 
-    # Remove orphaned definitions if requested
-    if prune_defs:
-        defs = schema.get("$defs", {})
-        for def_name in list(defs):
-            if def_name not in used_defs:
-                defs.pop(def_name)
-        if not defs:
-            schema.pop("$defs", None)
-
     return schema
 
 
@@ -109,12 +152,13 @@ def compress_schema(
         schema = _prune_param(schema, param=param)
 
     # Do a single walk to handle pruning operations
-    if prune_defs or prune_titles or prune_additional_properties:
+    if prune_titles or prune_additional_properties:
         schema = _walk_and_prune(
             schema,
-            prune_defs=prune_defs,
             prune_titles=prune_titles,
             prune_additional_properties=prune_additional_properties,
         )
+    if prune_defs:
+        schema = _prune_unused_defs(schema)
 
     return schema

fastmcp/utilities/mcp_config.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import re
 from typing import TYPE_CHECKING, Annotated, Any, Literal
 from urllib.parse import urlparse
 
-from pydantic import AnyUrl, Field
+import httpx
+from pydantic import AnyUrl, ConfigDict, Field
 
 from fastmcp.utilities.types import FastMCPBaseModel
 
@@ -17,7 +19,7 @@ if TYPE_CHECKING:
 
 def infer_transport_type_from_url(
     url: str | AnyUrl,
-) -> Literal["streamable-http", "sse"]:
+) -> Literal["http", "sse"]:
     """
     Infer the appropriate transport type from the given URL.
     """
@@ -28,10 +30,11 @@ def infer_transport_type_from_url(
     parsed_url = urlparse(url)
     path = parsed_url.path
 
-    if "/sse/" in path or path.rstrip("/").endswith("/sse"):
+    # Match /sse followed by /, ?, &, or end of string
+    if re.search(r"/sse(/|\?|&|$)", path):
         return "sse"
     else:
-        return "streamable-http"
+        return "http"
 
 
 class StdioMCPServer(FastMCPBaseModel):
@@ -55,14 +58,16 @@ class StdioMCPServer(FastMCPBaseModel):
 class RemoteMCPServer(FastMCPBaseModel):
     url: str
     headers: dict[str, str] = Field(default_factory=dict)
-    transport: Literal["streamable-http", "sse"] | None = None
+    transport: Literal["http", "streamable-http", "sse"] | None = None
     auth: Annotated[
-        str | Literal["oauth"] | None,
+        str | Literal["oauth"] | httpx.Auth | None,
         Field(
-            description='Either a string representing a Bearer token or the literal "oauth" to use OAuth authentication.'
+            description='Either a string representing a Bearer token, the literal "oauth" to use OAuth authentication, or an httpx.Auth instance for custom authentication.',
         ),
     ] = None
 
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     def to_transport(self) -> StreamableHttpTransport | SSETransport:
         from fastmcp.client.transports import SSETransport, StreamableHttpTransport
 
@@ -74,6 +79,7 @@ class RemoteMCPServer(FastMCPBaseModel):
         if transport == "sse":
             return SSETransport(self.url, headers=self.headers, auth=self.auth)
         else:
+            # Both "http" and "streamable-http" map to StreamableHttpTransport
             return StreamableHttpTransport(
                 self.url, headers=self.headers, auth=self.auth
             )

fastmcp/utilities/openapi.py

@@ -262,16 +262,24 @@ class OpenAPIParser(
 
             if isinstance(resolved_schema, (self.schema_cls)):
                 # Convert schema to dictionary
-                return resolved_schema.model_dump(
+                result = resolved_schema.model_dump(
                     mode="json", by_alias=True, exclude_none=True
                 )
             elif isinstance(resolved_schema, dict):
-                return resolved_schema
+                result = resolved_schema
             else:
                 logger.warning(
                     f"Expected Schema after resolving, got {type(resolved_schema)}. Returning empty dict."
                 )
-                return {}
+                result = {}
+
+            return _replace_ref_with_defs(result)
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors and other validation issues
+            if "External or non-local reference not supported" in str(e):
+                raise
+            logger.error(f"Failed to extract schema as dict: {e}", exc_info=False)
+            return {}
         except Exception as e:
             logger.error(f"Failed to extract schema as dict: {e}", exc_info=False)
             return {}
@@ -300,11 +308,17 @@ class OpenAPIParser(
 
                 # Extract parameter info - handle both 3.0 and 3.1 parameter models
                 param_in = parameter.param_in  # Both use param_in
-                param_location = self._convert_to_parameter_location(param_in)
+                # Handle enum or string parameter locations
+                from enum import Enum
+
+                param_in_str = (
+                    param_in.value if isinstance(param_in, Enum) else param_in
+                )
+                param_location = self._convert_to_parameter_location(param_in_str)
                 param_schema_obj = parameter.param_schema  # Both use param_schema
 
                 # Skip duplicate parameters (same name and location)
-                param_key = (parameter.name, param_in)
+                param_key = (parameter.name, param_in_str)
                 if param_key in seen_params:
                     continue
                 seen_params[param_key] = True
@@ -398,12 +412,30 @@ class OpenAPIParser(
                             request_body_info.content_schema[media_type_str] = (
                                 schema_dict
                             )
+                        except ValueError as e:
+                            # Re-raise ValueError for external reference errors
+                            if "External or non-local reference not supported" in str(
+                                e
+                            ):
+                                raise
+                            logger.error(
+                                f"Failed to extract schema for media type '{media_type_str}': {e}"
+                            )
                         except Exception as e:
                             logger.error(
                                 f"Failed to extract schema for media type '{media_type_str}': {e}"
                             )
 
             return request_body_info
+        except ValueError as e:
+            # Re-raise ValueError for external reference errors
+            if "External or non-local reference not supported" in str(e):
+                raise
+            ref_name = getattr(request_body_or_ref, "ref", "unknown")
+            logger.error(
+                f"Failed to extract request body '{ref_name}': {e}", exc_info=False
+            )
+            return None
         except Exception as e:
             ref_name = getattr(request_body_or_ref, "ref", "unknown")
             logger.error(
@@ -447,6 +479,17 @@ class OpenAPIParser(
                                     media_type_obj.media_type_schema
                                 )
                                 resp_info.content_schema[media_type_str] = schema_dict
+                            except ValueError as e:
+                                # Re-raise ValueError for external reference errors
+                                if (
+                                    "External or non-local reference not supported"
+                                    in str(e)
+                                ):
+                                    raise
+                                logger.error(
+                                    f"Failed to extract schema for media type '{media_type_str}' "
+                                    f"in response {status_code}: {e}"
+                                )
                             except Exception as e:
                                 logger.error(
                                     f"Failed to extract schema for media type '{media_type_str}' "
@@ -454,6 +497,16 @@ class OpenAPIParser(
                                 )
 
                 extracted_responses[str(status_code)] = resp_info
+            except ValueError as e:
+                # Re-raise ValueError for external reference errors
+                if "External or non-local reference not supported" in str(e):
+                    raise
+                ref_name = getattr(resp_or_ref, "ref", "unknown")
+                logger.error(
+                    f"Failed to extract response for status code {status_code} "
+                    f"from reference '{ref_name}': {e}",
+                    exc_info=False,
+                )
             except Exception as e:
                 ref_name = getattr(resp_or_ref, "ref", "unknown")
                 logger.error(
@@ -554,6 +607,17 @@ class OpenAPIParser(
                         logger.info(
                             f"Successfully extracted route: {method_upper} {path_str}"
                         )
+                    except ValueError as op_error:
+                        # Re-raise ValueError for external reference errors
+                        if "External or non-local reference not supported" in str(
+                            op_error
+                        ):
+                            raise
+                        op_id = getattr(operation, "operationId", "unknown")
+                        logger.error(
+                            f"Failed to process operation {method_upper} {path_str} (ID: {op_id}): {op_error}",
+                            exc_info=True,
+                        )
                     except Exception as op_error:
                         op_id = getattr(operation, "operationId", "unknown")
                         logger.error(
@@ -899,6 +963,12 @@ def _replace_ref_with_defs(
         if ref_path.startswith("#/components/schemas/"):
             schema_name = ref_path.split("/")[-1]
             schema["$ref"] = f"#/$defs/{schema_name}"
+        elif not ref_path.startswith("#/"):
+            raise ValueError(
+                f"External or non-local reference not supported: {ref_path}. "
+                f"FastMCP only supports local schema references starting with '#/'. "
+                f"Please include all schema definitions within the OpenAPI document."
+            )
     elif properties := schema.get("properties"):
         if "$ref" in properties:
             schema["properties"] = _replace_ref_with_defs(properties)

fastmcp/utilities/tests.py

@@ -20,7 +20,7 @@ if TYPE_CHECKING:
 @contextmanager
 def temporary_settings(**kwargs: Any):
     """
-    Temporarily override ControlFlow setting values.
+    Temporarily override FastMCP setting values.
 
     Args:
         **kwargs: The settings to override, including nested settings.