fastmcp 2.4.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

fastmcp/server/openapi.py

@@ -5,8 +5,10 @@ from __future__ import annotations
 import enum
 import json
 import re
+import warnings
+from collections import Counter
 from collections.abc import Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from re import Pattern
 from typing import TYPE_CHECKING, Any, Literal
 
@@ -16,11 +18,13 @@ from pydantic.networks import AnyUrl
 
 from fastmcp.exceptions import ToolError
 from fastmcp.resources import Resource, ResourceTemplate
+from fastmcp.server.dependencies import get_http_request
 from fastmcp.server.server import FastMCP
 from fastmcp.tools.tool import Tool, _convert_to_content
 from fastmcp.utilities import openapi
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.openapi import (
+    HTTPRoute,
     _combine_schemas,
     format_description_with_responses,
 )
@@ -33,13 +37,88 @@ logger = get_logger(__name__)
 HttpMethod = Literal["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"]
 
 
+def _slugify(text: str) -> str:
+    """
+    Convert text to a URL-friendly slug format that only contains lowercase
+    letters, uppercase letters, numbers, and underscores.
+    """
+    if not text:
+        return ""
+
+    # Replace spaces and common separators with underscores
+    slug = re.sub(r"[\s\-\.]+", "_", text)
+
+    # Remove non-alphanumeric characters except underscores
+    slug = re.sub(r"[^a-zA-Z0-9_]", "", slug)
+
+    # Remove multiple consecutive underscores
+    slug = re.sub(r"_+", "_", slug)
+
+    # Remove leading/trailing underscores
+    slug = slug.strip("_")
+
+    return slug
+
+
+def _get_mcp_client_headers() -> dict[str, str]:
+    """
+    Extract headers from the current MCP client HTTP request if available.
+
+    These headers will take precedence over OpenAPI-defined headers when both are present.
+
+    Returns:
+        Dictionary of header name-value pairs (lowercased names), or empty dict if no HTTP request is active.
+    """
+    try:
+        http_request = get_http_request()
+        return {
+            name.lower(): str(value) for name, value in http_request.headers.items()
+        }
+    except RuntimeError:
+        # No active HTTP request (e.g., STDIO transport), return empty dict
+        return {}
+
+
+# Type definitions for the mapping functions
+RouteMapFn = Callable[[HTTPRoute, "MCPType"], "MCPType | None"]
+ComponentFn = Callable[
+    [
+        HTTPRoute,
+        "OpenAPITool | OpenAPIResource | OpenAPIResourceTemplate",
+    ],
+    None,
+]
+
+
+class MCPType(enum.Enum):
+    """Type of FastMCP component to create from a route.
+
+    Enum values:
+        TOOL: Convert the route to a callable Tool
+        RESOURCE: Convert the route to a Resource (typically GET endpoints)
+        RESOURCE_TEMPLATE: Convert the route to a ResourceTemplate (typically GET with path params)
+        EXCLUDE: Exclude the route from being converted to any MCP component
+        IGNORE: Deprecated, use EXCLUDE instead
+    """
+
+    TOOL = "TOOL"
+    RESOURCE = "RESOURCE"
+    RESOURCE_TEMPLATE = "RESOURCE_TEMPLATE"
+    # PROMPT = "PROMPT"
+    EXCLUDE = "EXCLUDE"
+
+
+# Keep RouteType as an alias to MCPType for backward compatibility
 class RouteType(enum.Enum):
-    """Type of FastMCP component to create from a route."""
+    """
+    Deprecated: Use MCPType instead.
+
+    This enum is kept for backward compatibility and will be removed in a future version.
+    """
 
     TOOL = "TOOL"
     RESOURCE = "RESOURCE"
     RESOURCE_TEMPLATE = "RESOURCE_TEMPLATE"
-    PROMPT = "PROMPT"
     IGNORE = "IGNORE"
 
 
@@ -47,32 +126,71 @@ class RouteType(enum.Enum):
 class RouteMap:
     """Mapping configuration for HTTP routes to FastMCP component types."""
 
-    methods: list[HttpMethod] | Literal["*"]
-    pattern: Pattern[str] | str
-    route_type: RouteType
+    methods: list[HttpMethod] | Literal["*"] = field(default="*")
+    pattern: Pattern[str] | str = field(default=r".*")
+    mcp_type: MCPType | None = field(default=None)
+    route_type: RouteType | MCPType | None = field(default=None)
+    tags: set[str] = field(default_factory=set)
+
+    def __post_init__(self):
+        """Validate and process the route map after initialization."""
+        # Handle backward compatibility for route_type, deprecated in 2.5.0
+        if self.mcp_type is None and self.route_type is not None:
+            warnings.warn(
+                "The 'route_type' parameter is deprecated and will be removed in a future version. "
+                "Use 'mcp_type' instead with the appropriate MCPType value.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+            if isinstance(self.route_type, RouteType):
+                warnings.warn(
+                    "The RouteType class is deprecated and will be removed in a future version. "
+                    "Use MCPType instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            # Check for the deprecated IGNORE value
+            if self.route_type == RouteType.IGNORE:
+                warnings.warn(
+                    "RouteType.IGNORE is deprecated and will be removed in a future version. "
+                    "Use MCPType.EXCLUDE instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+            # Convert from RouteType to MCPType if needed
+            if isinstance(self.route_type, RouteType):
+                route_type_name = self.route_type.name
+                if route_type_name == "IGNORE":
+                    route_type_name = "EXCLUDE"
+                self.mcp_type = getattr(MCPType, route_type_name)
+            else:
+                self.mcp_type = self.route_type
+        elif self.mcp_type is None:
+            raise ValueError("`mcp_type` must be provided")
+
+        # Set route_type to match mcp_type for backward compatibility
+        if self.route_type is None:
+            self.route_type = self.mcp_type
 
 
 # Default route mappings as a list, where order determines priority
 DEFAULT_ROUTE_MAPPINGS = [
     # GET requests with path parameters go to ResourceTemplate
     RouteMap(
-        methods=["GET"], pattern=r".*\{.*\}.*", route_type=RouteType.RESOURCE_TEMPLATE
+        methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE
     ),
     # GET requests without path parameters go to Resource
-    RouteMap(methods=["GET"], pattern=r".*", route_type=RouteType.RESOURCE),
+    RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
     # All other HTTP methods go to Tool
-    RouteMap(
-        methods=["POST", "PUT", "PATCH", "DELETE", "OPTIONS", "HEAD"],
-        pattern=r".*",
-        route_type=RouteType.TOOL,
-    ),
+    RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL),
 ]
 
 
 def _determine_route_type(
     route: openapi.HTTPRoute,
     mappings: list[RouteMap],
-) -> RouteType:
+) -> MCPType:
     """
     Determines the FastMCP component type based on the route and mappings.
 
@@ -81,7 +199,7 @@ def _determine_route_type(
         mappings: List of RouteMap objects in priority order
 
     Returns:
-        RouteType for this route
+        MCPType for this route
     """
     # Check mappings in priority order (first match wins)
     for route_map in mappings:
@@ -94,20 +212,24 @@ def _determine_route_type(
                 pattern_matches = re.search(route_map.pattern, route.path)
 
             if pattern_matches:
+                # Check if tags match (if specified)
+                # If route_map.tags is empty, tags are not matched
+                # If route_map.tags is non-empty, all tags must be present in route.tags (AND condition)
+                if route_map.tags:
+                    route_tags_set = set(route.tags or [])
+                    if not route_map.tags.issubset(route_tags_set):
+                        # Tags don't match, continue to next mapping
+                        continue
+
+                # We know mcp_type is not None here due to post_init validation
+                assert route_map.mcp_type is not None
                 logger.debug(
-                    f"Route {route.method} {route.path} matched mapping to {route_map.route_type.name}"
+                    f"Route {route.method} {route.path} matched mapping to {route_map.mcp_type.name}"
                 )
-                return route_map.route_type
+                return route_map.mcp_type
 
     # Default fallback
-    return RouteType.TOOL
-
-
-# Placeholder function to provide function metadata
-async def _openapi_passthrough(*args, **kwargs):
-    """Placeholder function for OpenAPI endpoints."""
-    # This is kept for metadata generation purposes
-    pass
+    return MCPType.TOOL
 
 
 class OpenAPITool(Tool):
@@ -288,13 +410,21 @@ class OpenAPITool(Tool):
 
         # Prepare headers - fix typing by ensuring all values are strings
         headers = {}
+
+        # Start with OpenAPI-defined header parameters
+        openapi_headers = {}
         for p in self._route.parameters:
             if (
                 p.location == "header"
                 and p.name in kwargs
                 and kwargs[p.name] is not None
             ):
-                headers[p.name] = str(kwargs[p.name])
+                openapi_headers[p.name.lower()] = str(kwargs[p.name])
+        headers.update(openapi_headers)
+
+        # Add headers from the current MCP client HTTP request (these take precedence)
+        mcp_headers = _get_mcp_client_headers()
+        headers.update(mcp_headers)
 
         # Prepare request body
         json_data = None
@@ -442,10 +572,16 @@ class OpenAPIResource(Resource):
                     if value is not None and value != "":
                         query_params[param.name] = value
 
+            # Prepare headers from MCP client request if available
+            headers = {}
+            mcp_headers = _get_mcp_client_headers()
+            headers.update(mcp_headers)
+
             response = await self._client.request(
                 method=self._route.method,
                 url=path,
                 params=query_params,
+                headers=headers,
                 timeout=self._timeout,
             )
 
@@ -546,7 +682,7 @@ class FastMCPOpenAPI(FastMCP):
 
     Example:
         ```python
-        from fastmcp.server.openapi import FastMCPOpenAPI, RouteMap, RouteType
+        from fastmcp.server.openapi import FastMCPOpenAPI, RouteMap, MCPType
         import httpx
 
         # Define custom route mappings
@@ -555,17 +691,17 @@ class FastMCPOpenAPI(FastMCP):
             RouteMap(
                 methods=["GET", "POST", "PATCH"],
                 pattern=r".*/users/.*",
-                route_type=RouteType.RESOURCE_TEMPLATE
+                mcp_type=MCPType.RESOURCE_TEMPLATE
             ),
             # Map all analytics endpoints to Tool
             RouteMap(
                 methods=["GET"],
                 pattern=r".*/analytics/.*",
-                route_type=RouteType.TOOL
+                mcp_type=MCPType.TOOL
             ),
         ]
 
-        # Create server with custom mappings
+        # Create server with custom mappings and route mapper
         server = FastMCPOpenAPI(
             openapi_spec=spec,
             client=httpx.AsyncClient(),
@@ -581,6 +717,9 @@ class FastMCPOpenAPI(FastMCP):
         client: httpx.AsyncClient,
         name: str | None = None,
         route_maps: list[RouteMap] | None = None,
+        route_map_fn: RouteMapFn | None = None,
+        mcp_component_fn: ComponentFn | None = None,
+        mcp_names: dict[str, str] | None = None,
         timeout: float | None = None,
         **settings: Any,
     ):
@@ -592,6 +731,17 @@ class FastMCPOpenAPI(FastMCP):
             client: httpx AsyncClient for making HTTP requests
             name: Optional name for the server
             route_maps: Optional list of RouteMap objects defining route mappings
+            route_map_fn: Optional callable for advanced route type mapping.
+                Receives (route, mcp_type) and returns MCPType or None.
+                Called on every route, including excluded ones.
+            mcp_component_fn: Optional callable for component customization.
+                Receives (route, component) and can modify the component in-place.
+                Called on every created component.
+            mcp_names: Optional dictionary mapping operationId to desired component names.
+                If an operationId is not in the dictionary, falls back to using the
+                operationId up to the first double underscore. If no operationId exists,
+                falls back to slugified summary or path-based naming.
+                All names are truncated to 56 characters maximum.
             timeout: Optional timeout (in seconds) for all requests
             **settings: Additional settings for FastMCP
         """
@@ -599,6 +749,18 @@ class FastMCPOpenAPI(FastMCP):
 
         self._client = client
         self._timeout = timeout
+        self._route_map_fn = route_map_fn
+        self._mcp_component_fn = mcp_component_fn
+        self._mcp_names = mcp_names or {}
+
+        # Keep track of names to detect collisions
+        self._used_names = {
+            "tool": Counter(),
+            "resource": Counter(),
+            "resource_template": Counter(),
+            "prompt": Counter(),
+        }
+
         http_routes = openapi.parse_openapi_to_http_routes(openapi_spec)
 
         # Process routes
@@ -607,34 +769,97 @@ class FastMCPOpenAPI(FastMCP):
             # Determine route type based on mappings or default rules
             route_type = _determine_route_type(route, route_maps)
 
-            # Use operation_id if available, otherwise generate a name
-            operation_id = route.operation_id
-            if not operation_id:
-                # Generate operation ID from method and path
-                path_parts = route.path.strip("/").split("/")
-                path_name = "_".join(p for p in path_parts if not p.startswith("{"))
-                operation_id = f"{route.method.lower()}_{path_name}"
-
-            if route_type == RouteType.TOOL:
-                self._create_openapi_tool(route, operation_id)
-            elif route_type == RouteType.RESOURCE:
-                self._create_openapi_resource(route, operation_id)
-            elif route_type == RouteType.RESOURCE_TEMPLATE:
-                self._create_openapi_template(route, operation_id)
-            elif route_type == RouteType.PROMPT:
-                # Not implemented yet
-                logger.warning(
-                    f"PROMPT route type not implemented: {route.method} {route.path}"
-                )
-            elif route_type == RouteType.IGNORE:
-                logger.info(f"Ignoring route: {route.method} {route.path}")
+            # Call route_map_fn if provided
+            if self._route_map_fn is not None:
+                try:
+                    result = self._route_map_fn(route, route_type)
+                    if result is not None:
+                        route_type = result
+                        logger.debug(
+                            f"Route {route.method} {route.path} mapping customized by route_map_fn: "
+                            f"type={route_type.name}"
+                        )
+                except Exception as e:
+                    logger.warning(
+                        f"Error in route_map_fn for {route.method} {route.path}: {e}. "
+                        f"Using default values."
+                    )
+
+            # Generate a default name from the route
+            component_name = self._generate_default_name(route, route_type)
+
+            if route_type == MCPType.TOOL:
+                self._create_openapi_tool(route, component_name)
+            elif route_type == MCPType.RESOURCE:
+                self._create_openapi_resource(route, component_name)
+            elif route_type == MCPType.RESOURCE_TEMPLATE:
+                self._create_openapi_template(route, component_name)
+            elif route_type == MCPType.EXCLUDE:
+                logger.info(f"Excluding route: {route.method} {route.path}")
 
         logger.info(f"Created FastMCP OpenAPI server with {len(http_routes)} routes")
 
-    def _create_openapi_tool(self, route: openapi.HTTPRoute, operation_id: str):
+    def _generate_default_name(
+        self, route: openapi.HTTPRoute, mcp_type: MCPType
+    ) -> str:
+        """Generate a default name from the route using the configured strategy."""
+        name = ""
+
+        # First check if there's a custom mapping for this operationId
+        if route.operation_id:
+            if route.operation_id in self._mcp_names:
+                name = self._mcp_names[route.operation_id]
+            else:
+                # If there's a double underscore in the operationId, use the first part
+                name = route.operation_id.split("__")[0]
+        else:
+            name = route.summary or f"{route.method}_{route.path}"
+
+        name = _slugify(name)
+
+        # Truncate to 56 characters maximum
+        if len(name) > 56:
+            name = name[:56]
+
+        return name
+
+    def _get_unique_name(
+        self,
+        name: str,
+        component_type: Literal["tool", "resource", "resource_template", "prompt"],
+    ) -> str:
+        """
+        Ensure the name is unique within its component type by appending numbers if needed.
+
+        Args:
+            name: The proposed name
+            component_type: The type of component ("tools", "resources", or "templates")
+
+        Returns:
+            str: A unique name for the component
+        """
+        # Check if the name is already used
+        self._used_names[component_type][name] += 1
+        if self._used_names[component_type][name] == 1:
+            return name
+
+        else:
+            # Create the new name
+            new_name = f"{name}_{self._used_names[component_type][name]}"
+            logger.debug(
+                f"Name collision detected: '{name}' already exists as a {component_type[:-1]}. "
+                f"Using '{new_name}' instead."
+            )
+
+        return new_name
+
+    def _create_openapi_tool(self, route: openapi.HTTPRoute, name: str):
         """Creates and registers an OpenAPITool with enhanced description."""
         combined_schema = _combine_schemas(route)
-        tool_name = operation_id
+
+        # Get a unique tool name
+        tool_name = self._get_unique_name(name, "tool")
+
         base_description = (
             route.description
             or route.summary
@@ -658,16 +883,30 @@ class FastMCPOpenAPI(FastMCP):
             tags=set(route.tags or []),
             timeout=self._timeout,
         )
+
+        # Call component_fn if provided
+        if self._mcp_component_fn is not None:
+            try:
+                self._mcp_component_fn(route, tool)
+                logger.debug(f"Tool {tool_name} customized by component_fn")
+            except Exception as e:
+                logger.warning(
+                    f"Error in component_fn for tool {tool_name}: {e}. "
+                    f"Using component as-is."
+                )
+
         # Register the tool by directly assigning to the tools dictionary
         self._tool_manager._tools[tool_name] = tool
         logger.debug(
             f"Registered TOOL: {tool_name} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
-    def _create_openapi_resource(self, route: openapi.HTTPRoute, operation_id: str):
+    def _create_openapi_resource(self, route: openapi.HTTPRoute, name: str):
         """Creates and registers an OpenAPIResource with enhanced description."""
-        resource_name = operation_id
-        resource_uri = f"resource://openapi/{resource_name}"
+        # Get a unique resource name
+        resource_name = self._get_unique_name(name, "resource")
+
+        resource_uri = f"resource://{resource_name}"
         base_description = (
             route.description or route.summary or f"Represents {route.path}"
         )
@@ -689,19 +928,33 @@ class FastMCPOpenAPI(FastMCP):
             tags=set(route.tags or []),
             timeout=self._timeout,
         )
+
+        # Call component_fn if provided
+        if self._mcp_component_fn is not None:
+            try:
+                self._mcp_component_fn(route, resource)
+                logger.debug(f"Resource {resource_uri} customized by component_fn")
+            except Exception as e:
+                logger.warning(
+                    f"Error in component_fn for resource {resource_uri}: {e}. "
+                    f"Using component as-is."
+                )
+
         # Register the resource by directly assigning to the resources dictionary
         self._resource_manager._resources[str(resource.uri)] = resource
         logger.debug(
             f"Registered RESOURCE: {resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
-    def _create_openapi_template(self, route: openapi.HTTPRoute, operation_id: str):
+    def _create_openapi_template(self, route: openapi.HTTPRoute, name: str):
         """Creates and registers an OpenAPIResourceTemplate with enhanced description."""
-        template_name = operation_id
+        # Get a unique template name
+        template_name = self._get_unique_name(name, "resource_template")
+
         path_params = [p.name for p in route.parameters if p.location == "path"]
         path_params.sort()  # Sort for consistent URIs
 
-        uri_template_str = f"resource://openapi/{template_name}"
+        uri_template_str = f"resource://{template_name}"
         if path_params:
             uri_template_str += "/" + "/".join(f"{{{p}}}" for p in path_params)
 
@@ -749,13 +1002,20 @@ class FastMCPOpenAPI(FastMCP):
             tags=set(route.tags or []),
             timeout=self._timeout,
         )
+
+        # Call component_fn if provided
+        if self._mcp_component_fn is not None:
+            try:
+                self._mcp_component_fn(route, template)
+                logger.debug(f"Template {uri_template_str} customized by component_fn")
+            except Exception as e:
+                logger.warning(
+                    f"Error in component_fn for template {uri_template_str}: {e}. "
+                    f"Using component as-is."
+                )
+
         # Register the template by directly assigning to the templates dictionary
         self._resource_manager._templates[uri_template_str] = template
         logger.debug(
             f"Registered TEMPLATE: {uri_template_str} ({route.method} {route.path}) with tags: {route.tags}"
         )
-
-    async def _mcp_call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
-        """Override the call_tool method to return the raw result without converting to content."""
-        result = await self._tool_manager.call_tool(name, arguments)
-        return result