fastmcp 2.12.5__py3-none-any.whl → 2.13.2__py3-none-any.whl

fastmcp/contrib/component_manager/component_manager.py

@@ -97,11 +97,11 @@ def make_endpoint(action, component, config):
             return JSONResponse(
                 {"message": f"{action.capitalize()}d {component}: {name}"}
             )
-        except NotFoundError:
+        except NotFoundError as e:
             raise StarletteHTTPException(
                 status_code=404,
                 detail=f"Unknown {component}: {name}",
-            )
+            ) from e
 
     return endpoint
 

fastmcp/contrib/component_manager/component_service.py

@@ -41,7 +41,7 @@ class ComponentService:
             return tool
 
         # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._tool_manager._mounted_servers):
+        for mounted in reversed(self._server._mounted_servers):
             if mounted.prefix:
                 if key.startswith(f"{mounted.prefix}_"):
                     tool_key = key.removeprefix(f"{mounted.prefix}_")
@@ -70,7 +70,7 @@ class ComponentService:
             return tool
 
         # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._tool_manager._mounted_servers):
+        for mounted in reversed(self._server._mounted_servers):
             if mounted.prefix:
                 if key.startswith(f"{mounted.prefix}_"):
                     tool_key = key.removeprefix(f"{mounted.prefix}_")
@@ -103,7 +103,7 @@ class ComponentService:
             return template
 
         # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._resource_manager._mounted_servers):
+        for mounted in reversed(self._server._mounted_servers):
             if mounted.prefix:
                 if has_resource_prefix(
                     key,
@@ -146,7 +146,7 @@ class ComponentService:
             return template
 
         # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._resource_manager._mounted_servers):
+        for mounted in reversed(self._server._mounted_servers):
             if mounted.prefix:
                 if has_resource_prefix(
                     key,
@@ -185,7 +185,7 @@ class ComponentService:
             return prompt
 
         # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._prompt_manager._mounted_servers):
+        for mounted in reversed(self._server._mounted_servers):
             if mounted.prefix:
                 if key.startswith(f"{mounted.prefix}_"):
                     prompt_key = key.removeprefix(f"{mounted.prefix}_")
@@ -213,7 +213,7 @@ class ComponentService:
             return prompt
 
         # 2. Check mounted servers using the filtered protocol path.
-        for mounted in reversed(self._prompt_manager._mounted_servers):
+        for mounted in reversed(self._server._mounted_servers):
             if mounted.prefix:
                 if key.startswith(f"{mounted.prefix}_"):
                     prompt_key = key.removeprefix(f"{mounted.prefix}_")

fastmcp/contrib/mcp_mixin/README.md

@@ -11,12 +11,15 @@ Tools:
 * [enable/disable](https://gofastmcp.com/servers/tools#disabling-tools)
 * [annotations](https://gofastmcp.com/servers/tools#annotations-2)
 * [excluded arguments](https://gofastmcp.com/servers/tools#excluding-arguments)
+* [meta](https://gofastmcp.com/servers/tools#param-meta)
 
 Prompts:
 * [enable/disable](https://gofastmcp.com/servers/prompts#disabling-prompts)
+* [meta](https://gofastmcp.com/servers/prompts#param-meta)
 
 Resources:
 * [enable/disable](https://gofastmcp.com/servers/resources#disabling-resources)
+* [meta](https://gofastmcp.com/servers/resources#param-meta)
   
 ## Usage
 
@@ -78,7 +81,16 @@ class MyComponent(MCPMixin):
         if delete_all:
             return "99 records deleted. I bet you're not a tool :)"
         return "Tool executed, but you might be a tool!"
-    
+
+    # example tool w/ meta
+    @mcp_tool(
+        name="data_tool",
+        description="Fetches user data from database",
+        meta={"version": "2.0", "category": "database", "author": "dev-team"}
+    )
+    def data_tool_method(self, user_id: int):
+        return f"Fetching data for user {user_id}"
+
     @mcp_resource(uri="component://data")
     def resource_method(self):
         return {"data": "some data"}
@@ -88,6 +100,15 @@ class MyComponent(MCPMixin):
     def resource_method(self):
         return {"data": "some data"}
 
+    # example resource w/meta and title
+    @mcp_resource(
+        uri="component://config",
+        title="Data resource Title,
+        meta={"internal": True, "cache_ttl": 3600, "priority": "high"}
+    )
+    def config_resource_method(self):
+        return {"config": "data"}
+
     # prompt
     @mcp_prompt(name="A prompt")
     def prompt_method(self, name):
@@ -98,6 +119,16 @@ class MyComponent(MCPMixin):
     def prompt_method(self, name):
         return f"What's up {name}?"
 
+    # example prompt w/title and meta
+    @mcp_prompt(
+        name="analysis_prompt",
+        title="Data Analysis Prompt",
+        description="Analyzes data patterns",
+        meta={"complexity": "high", "domain": "analytics", "requires_context": True}
+    )
+    def analysis_prompt_method(self, dataset: str):
+        return f"Analyze the patterns in {dataset}"
+
 mcp_server = FastMCP()
 component = MyComponent()
 

fastmcp/contrib/mcp_mixin/__init__.py

@@ -2,7 +2,7 @@ from .mcp_mixin import MCPMixin, mcp_tool, mcp_resource, mcp_prompt
 
 __all__ = [
     "MCPMixin",
-    "mcp_tool",
-    "mcp_resource",
     "mcp_prompt",
+    "mcp_resource",
+    "mcp_tool",
 ]

fastmcp/contrib/mcp_mixin/mcp_mixin.py

@@ -3,7 +3,7 @@
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
 
-from mcp.types import ToolAnnotations
+from mcp.types import Annotations, ToolAnnotations
 
 from fastmcp.prompts.prompt import Prompt
 from fastmcp.resources.resource import Resource
@@ -29,6 +29,7 @@ def mcp_tool(
     annotations: ToolAnnotations | dict[str, Any] | None = None,
     exclude_args: list[str] | None = None,
     serializer: Callable[[Any], str] | None = None,
+    meta: dict[str, Any] | None = None,
     enabled: bool | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to mark a method as an MCP tool for later registration."""
@@ -41,6 +42,7 @@ def mcp_tool(
             "annotations": annotations,
             "exclude_args": exclude_args,
             "serializer": serializer,
+            "meta": meta,
             "enabled": enabled,
         }
         call_args = {k: v for k, v in call_args.items() if v is not None}
@@ -54,9 +56,12 @@ def mcp_resource(
     uri: str,
     *,
     name: str | None = None,
+    title: str | None = None,
     description: str | None = None,
     mime_type: str | None = None,
     tags: set[str] | None = None,
+    annotations: Annotations | None = None,
+    meta: dict[str, Any] | None = None,
     enabled: bool | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to mark a method as an MCP resource for later registration."""
@@ -65,9 +70,12 @@ def mcp_resource(
         call_args = {
             "uri": uri,
             "name": name or get_fn_name(func),
+            "title": title,
             "description": description,
             "mime_type": mime_type,
             "tags": tags,
+            "annotations": annotations,
+            "meta": meta,
             "enabled": enabled,
         }
         call_args = {k: v for k, v in call_args.items() if v is not None}
@@ -81,8 +89,10 @@ def mcp_resource(
 
 def mcp_prompt(
     name: str | None = None,
+    title: str | None = None,
     description: str | None = None,
     tags: set[str] | None = None,
+    meta: dict[str, Any] | None = None,
     enabled: bool | None = None,
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """Decorator to mark a method as an MCP prompt for later registration."""
@@ -90,8 +100,10 @@ def mcp_prompt(
     def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
         call_args = {
             "name": name or get_fn_name(func),
+            "title": title,
             "description": description,
             "tags": tags,
+            "meta": meta,
             "enabled": enabled,
         }
 
@@ -151,7 +163,6 @@ class MCPMixin:
             tool = Tool.from_function(
                 fn=method,
                 name=registration_info.get("name"),
-                title=registration_info.get("title"),
                 description=registration_info.get("description"),
                 tags=registration_info.get("tags"),
                 annotations=registration_info.get("annotations"),
@@ -195,6 +206,7 @@ class MCPMixin:
                 fn=method,
                 uri=registration_info["uri"],
                 name=registration_info.get("name"),
+                title=registration_info.get("title"),
                 description=registration_info.get("description"),
                 mime_type=registration_info.get("mime_type"),
                 tags=registration_info.get("tags"),

fastmcp/experimental/sampling/handlers/openai.py

@@ -21,10 +21,10 @@ try:
         ChatCompletionUserMessageParam,
     )
     from openai.types.shared.chat_model import ChatModel
-except ImportError:
+except ImportError as e:
     raise ImportError(
         "The `openai` package is not installed. Please install `fastmcp[openai]` or add `openai` to your dependencies manually."
-    )
+    ) from e
 
 from typing_extensions import override
 

fastmcp/experimental/server/openapi/__init__.py

@@ -22,17 +22,14 @@ from .components import (
 
 # Export public symbols - maintaining backward compatibility
 __all__ = [
-    # Server
+    "DEFAULT_ROUTE_MAPPINGS",
+    "ComponentFn",
     "FastMCPOpenAPI",
-    # Routing
     "MCPType",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+    "OpenAPITool",
     "RouteMap",
     "RouteMapFn",
-    "ComponentFn",
-    "DEFAULT_ROUTE_MAPPINGS",
     "_determine_route_type",
-    # Components
-    "OpenAPITool",
-    "OpenAPIResource",
-    "OpenAPIResourceTemplate",
 ]

fastmcp/experimental/server/openapi/components.py

@@ -146,11 +146,11 @@ class OpenAPITool(Tool):
                 if e.response.text:
                     error_message += f" - {e.response.text}"
 
-            raise ValueError(error_message)
+            raise ValueError(error_message) from e
 
         except httpx.RequestError as e:
             # Handle request errors (connection, timeout, etc.)
-            raise ValueError(f"Request error: {str(e)}")
+            raise ValueError(f"Request error: {e!s}") from e
 
 
 class OpenAPIResource(Resource):
@@ -165,9 +165,11 @@ class OpenAPIResource(Resource):
         name: str,
         description: str,
         mime_type: str = "application/json",
-        tags: set[str] = set(),
+        tags: set[str] | None = None,
         timeout: float | None = None,
     ):
+        if tags is None:
+            tags = set()
         super().__init__(
             uri=AnyUrl(uri),  # Convert string to AnyUrl
             name=name,
@@ -276,11 +278,11 @@ class OpenAPIResource(Resource):
                 if e.response.text:
                     error_message += f" - {e.response.text}"
 
-            raise ValueError(error_message)
+            raise ValueError(error_message) from e
 
         except httpx.RequestError as e:
             # Handle request errors (connection, timeout, etc.)
-            raise ValueError(f"Request error: {str(e)}")
+            raise ValueError(f"Request error: {e!s}") from e
 
 
 class OpenAPIResourceTemplate(ResourceTemplate):
@@ -295,9 +297,11 @@ class OpenAPIResourceTemplate(ResourceTemplate):
         name: str,
         description: str,
         parameters: dict[str, Any],
-        tags: set[str] = set(),
+        tags: set[str] | None = None,
         timeout: float | None = None,
     ):
+        if tags is None:
+            tags = set()
         super().__init__(
             uri_template=uri_template,
             name=name,
@@ -342,7 +346,7 @@ class OpenAPIResourceTemplate(ResourceTemplate):
 
 # Export public symbols
 __all__ = [
-    "OpenAPITool",
     "OpenAPIResource",
     "OpenAPIResourceTemplate",
+    "OpenAPITool",
 ]

fastmcp/experimental/server/openapi/routing.py

@@ -121,10 +121,10 @@ def _determine_route_type(
 
 # Export public symbols
 __all__ = [
+    "DEFAULT_ROUTE_MAPPINGS",
+    "ComponentFn",
     "MCPType",
     "RouteMap",
     "RouteMapFn",
-    "ComponentFn",
-    "DEFAULT_ROUTE_MAPPINGS",
     "_determine_route_type",
 ]

fastmcp/experimental/utilities/openapi/__init__.py

@@ -40,29 +40,24 @@ from .json_schema_converter import (
 
 # Export public symbols - maintaining backward compatibility
 __all__ = [
-    # Models
     "HTTPRoute",
+    "HttpMethod",
+    "JsonSchema",
     "ParameterInfo",
+    "ParameterLocation",
     "RequestBodyInfo",
     "ResponseInfo",
-    "HttpMethod",
-    "ParameterLocation",
-    "JsonSchema",
-    # Parser
-    "parse_openapi_to_http_routes",
-    # Formatters
+    "_combine_schemas",
+    "_make_optional_parameter_nullable",
+    "clean_schema_for_display",
+    "convert_openapi_schema_to_json_schema",
+    "convert_schema_definitions",
+    "extract_output_schema_from_responses",
     "format_array_parameter",
     "format_deep_object_parameter",
     "format_description_with_responses",
     "format_json_for_description",
     "format_simple_description",
     "generate_example_from_schema",
-    # Schemas
-    "_combine_schemas",
-    "extract_output_schema_from_responses",
-    "clean_schema_for_display",
-    "_make_optional_parameter_nullable",
-    # JSON Schema Converter
-    "convert_openapi_schema_to_json_schema",
-    "convert_schema_definitions",
+    "parse_openapi_to_http_routes",
 ]

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) or isinstance(body, list):
-                request_data["json"] = body
+            if isinstance(body, dict | list):
+                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/json_schema_converter.py

@@ -164,10 +164,10 @@ def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
         if isinstance(current_type, str):
             result["type"] = [current_type, "null"]
         elif isinstance(current_type, list) and "null" not in current_type:
-            result["type"] = current_type + ["null"]
+            result["type"] = [*current_type, "null"]
     elif "oneOf" in result:
         # Convert oneOf to anyOf with null
-        result["anyOf"] = result.pop("oneOf") + [{"type": "null"}]
+        result["anyOf"] = [*result.pop("oneOf"), {"type": "null"}]
     elif "anyOf" in result:
         # Add null to anyOf if not present
         if not any(item.get("type") == "null" for item in result["anyOf"]):
@@ -176,6 +176,10 @@ def _convert_nullable_field(schema: dict[str, Any]) -> dict[str, Any]:
         # Wrap allOf in anyOf with null option
         result["anyOf"] = [{"allOf": result.pop("allOf")}, {"type": "null"}]
 
+    # Handle enum fields - add null to enum values if present
+    if "enum" in result and None not in result["enum"]:
+        result["enum"] = result["enum"] + [None]
+
     return result
 
 

fastmcp/experimental/utilities/openapi/models.py

@@ -79,10 +79,10 @@ class HTTPRoute(FastMCPBaseModel):
 # Export public symbols
 __all__ = [
     "HTTPRoute",
+    "HttpMethod",
+    "JsonSchema",
     "ParameterInfo",
+    "ParameterLocation",
     "RequestBodyInfo",
     "ResponseInfo",
-    "HttpMethod",
-    "ParameterLocation",
-    "JsonSchema",
 ]

fastmcp/experimental/utilities/openapi/parser.py

@@ -178,7 +178,7 @@ class OpenAPIParser(
                         else:
                             # Special handling for components
                             if part == "components" and hasattr(target, "components"):
-                                target = getattr(target, "components")
+                                target = target.components
                             elif hasattr(target, part):  # Fallback check
                                 target = getattr(target, part, None)
                             else:
@@ -474,9 +474,22 @@ class OpenAPIParser(
                         and media_type_obj.media_type_schema
                     ):
                         try:
-                            schema_dict = self._extract_schema_as_dict(
-                                media_type_obj.media_type_schema
-                            )
+                            # Track if this is a top-level $ref before resolution
+                            top_level_schema_name = None
+                            media_schema = media_type_obj.media_type_schema
+                            if isinstance(media_schema, self.reference_cls):
+                                ref_str = media_schema.ref
+                                if isinstance(ref_str, str) and ref_str.startswith(
+                                    "#/components/schemas/"
+                                ):
+                                    top_level_schema_name = ref_str.split("/")[-1]
+
+                            schema_dict = self._extract_schema_as_dict(media_schema)
+                            # Add marker for top-level schema if it was a ref
+                            if top_level_schema_name:
+                                schema_dict["x-fastmcp-top-level-schema"] = (
+                                    top_level_schema_name
+                                )
                             resp_info.content_schema[media_type_str] = schema_dict
                         except ValueError as e:
                             # Re-raise ValueError for external reference errors
@@ -541,9 +554,7 @@ class OpenAPIParser(
                 if "$ref" in obj and isinstance(obj["$ref"], str):
                     ref = obj["$ref"]
                     # Handle both converted and unconverted refs
-                    if ref.startswith("#/$defs/"):
-                        schema_name = ref.split("/")[-1]
-                    elif ref.startswith("#/components/schemas/"):
+                    if ref.startswith(("#/$defs/", "#/components/schemas/")):
                         schema_name = ref.split("/")[-1]
                     else:
                         return
@@ -619,18 +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():
-                    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
         }
@@ -795,6 +816,6 @@ class OpenAPIParser(
 
 # Export public symbols
 __all__ = [
-    "parse_openapi_to_http_routes",
     "OpenAPIParser",
+    "parse_openapi_to_http_routes",
 ]

fastmcp/experimental/utilities/openapi/schemas.py

@@ -585,9 +585,9 @@ def extract_output_schema_from_responses(
 
 # Export public symbols
 __all__ = [
-    "clean_schema_for_display",
     "_combine_schemas",
     "_combine_schemas_and_map_params",
-    "extract_output_schema_from_responses",
     "_make_optional_parameter_nullable",
+    "clean_schema_for_display",
+    "extract_output_schema_from_responses",
 ]

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)
@@ -288,9 +288,8 @@ class MCPConfig(BaseModel):
     @classmethod
     def from_file(cls, file_path: Path) -> Self:
         """Load configuration from JSON file."""
-        if file_path.exists():
-            if content := file_path.read_text().strip():
-                return cls.model_validate_json(content)
+        if file_path.exists() and (content := file_path.read_text().strip()):
+            return cls.model_validate_json(content)
 
         raise ValueError(f"No MCP servers defined in the config: {file_path}")
 

fastmcp/prompts/__init__.py

@@ -2,8 +2,8 @@ from .prompt import Prompt, PromptMessage, Message
 from .prompt_manager import PromptManager
 
 __all__ = [
+    "Message",
     "Prompt",
     "PromptManager",
     "PromptMessage",
-    "Message",
 ]