fastmcp 2.10.5__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/experimental/server/openapi/README.md

@@ -0,0 +1,266 @@
+# OpenAPI Server Implementation (New)
+
+This directory contains the next-generation FastMCP server implementation for OpenAPI integration, designed to replace the legacy implementation in `/server/openapi.py`.
+
+## Architecture Overview
+
+The new implementation uses a **stateless request building approach** with `openapi-core` and `RequestDirector`, providing zero-latency startup and robust OpenAPI support optimized for serverless environments.
+
+### Core Components
+
+1. **`server.py`** - `FastMCPOpenAPI` main server class with RequestDirector integration
+2. **`components.py`** - Simplified component implementations using RequestDirector
+3. **`routing.py`** - Route mapping and component selection logic
+
+### Key Architecture Principles
+
+#### 1. Stateless Performance
+- **Zero Startup Latency**: No code generation or heavy initialization
+- **RequestDirector**: Stateless HTTP request building using openapi-core
+- **Pre-calculated Schemas**: All complex processing done during parsing
+
+#### 2. Unified Implementation
+- **Single Code Path**: All components use RequestDirector consistently
+- **No Fallbacks**: Simplified architecture without hybrid complexity
+- **Performance First**: Optimized for cold starts and serverless deployments
+
+#### 3. OpenAPI Compliance
+- **openapi-core Integration**: Leverages proven library for parameter serialization
+- **Full Feature Support**: Complete OpenAPI 3.0/3.1 support including deepObject
+- **Error Handling**: Comprehensive HTTP error mapping to MCP errors
+
+## Component Classes
+
+### RequestDirector-Based Components
+
+#### `OpenAPITool`
+- Executes operations using RequestDirector for HTTP request building
+- Automatic parameter validation and OpenAPI-compliant serialization
+- Built-in error handling and structured response processing
+- **Advantages**: Zero latency, robust, comprehensive OpenAPI support
+
+#### `OpenAPIResource` / `OpenAPIResourceTemplate`  
+- Provides resource access using RequestDirector
+- Consistent parameter handling across all resource types
+- Support for complex parameter patterns and collision resolution
+- **Advantages**: High performance, simplified architecture, reliable error handling
+
+## Server Implementation
+
+### `FastMCPOpenAPI` Class
+
+The main server class orchestrates the stateless request building approach:
+
+```python
+class FastMCPOpenAPI(FastMCP):
+    def __init__(self, openapi_spec: dict, client: httpx.AsyncClient, **kwargs):
+        # 1. Parse OpenAPI spec to HTTP routes with pre-calculated schemas
+        self._routes = parse_openapi_to_http_routes(openapi_spec)
+        
+        # 2. Initialize RequestDirector with openapi-core Spec
+        self._spec = Spec.from_dict(openapi_spec)
+        self._director = RequestDirector(self._spec)
+            
+        # 3. Create components using RequestDirector
+        self._create_components()
+```
+
+### Component Creation Logic
+
+```python
+def _create_tool(self, route: HTTPRoute) -> Tool:
+    # All tools use RequestDirector for consistent, high-performance request building
+    return OpenAPITool(
+        client=self._client, 
+        route=route, 
+        director=self._director,
+        name=tool_name,
+        description=description,
+        parameters=flat_param_schema
+    )
+```
+
+## Data Flow
+
+### Stateless Request Building
+
+```
+OpenAPI Spec → HTTPRoute with Pre-calculated Fields → RequestDirector → HTTP Request → Structured Response
+```
+
+1. **Spec Parsing**: OpenAPI spec parsed to `HTTPRoute` models with pre-calculated schemas
+2. **RequestDirector Setup**: openapi-core Spec initialized for request building
+3. **Component Creation**: Create components with RequestDirector reference
+4. **Request Building**: RequestDirector builds HTTP request from flat parameters
+5. **Request Execution**: Execute request with httpx client
+6. **Response Processing**: Return structured MCP response
+
+## Key Features
+
+### 1. Enhanced Parameter Handling
+
+#### Parameter Collision Resolution
+- **Automatic Suffixing**: Colliding parameters get location-based suffixes
+- **Example**: `id` in path and body becomes `id__path` and `id`
+- **Transparent**: LLMs see suffixed parameters, implementation routes correctly
+
+#### DeepObject Style Support
+- **Native Support**: Generated client handles all deepObject variations
+- **Explode Handling**: Proper support for explode=true/false
+- **Complex Objects**: Nested object serialization works correctly
+
+### 2. Robust Error Handling
+
+#### HTTP Error Mapping
+- **Status Code Mapping**: HTTP errors mapped to appropriate MCP errors
+- **Structured Responses**: Error details preserved in tool results
+- **Timeout Handling**: Network timeouts handled gracefully
+
+#### Request Building Error Handling
+- **Parameter Validation**: Invalid parameters caught during request building
+- **Schema Validation**: openapi-core validates all OpenAPI constraints
+- **Graceful Degradation**: Missing optional parameters handled smoothly
+
+### 3. Performance Optimizations
+
+#### Efficient Client Reuse
+- **Connection Pooling**: HTTP connections reused across requests
+- **Client Caching**: Generated clients cached for performance
+- **Async Support**: Full async/await throughout
+
+#### Request Optimization
+- **Pre-calculated Schemas**: All complex processing done during initialization
+- **Parameter Mapping**: Collision resolution handled upfront
+- **Zero Latency**: No runtime code generation or complex schema processing
+
+## Configuration
+
+### Server Options
+
+```python
+server = FastMCPOpenAPI(
+    openapi_spec=spec,           # Required: OpenAPI specification
+    client=httpx_client,         # Required: HTTP client instance
+    name="API Server",           # Optional: Server name
+    route_map=custom_routes,     # Optional: Custom route mappings
+    enable_caching=True,         # Optional: Enable response caching
+)
+```
+
+### Route Mapping Customization
+
+```python
+from fastmcp.server.openapi_new.routing import RouteMap
+
+custom_routes = RouteMap({
+    "GET:/users": "tool",        # Force specific operations to be tools
+    "GET:/status": "resource",   # Force specific operations to be resources
+})
+```
+
+## Testing Strategy
+
+### Test Structure
+
+Tests are organized by functionality:
+- `test_server.py` - Server integration and RequestDirector behavior
+- `test_parameter_collisions.py` - Parameter collision handling
+- `test_deepobject_style.py` - DeepObject parameter style support
+- `test_openapi_features.py` - General OpenAPI feature compliance
+
+### Testing Philosophy
+
+1. **Real Integration**: Test with real OpenAPI specs and HTTP clients
+2. **Minimal Mocking**: Only mock external API endpoints
+3. **Behavioral Focus**: Test behavior, not implementation details
+4. **Performance Focus**: Test that initialization is fast and stateless
+
+### Example Test Pattern
+
+```python
+async def test_stateless_request_building():
+    """Test that server works with stateless RequestDirector approach."""
+    
+    # Test server initialization is fast
+    start_time = time.time()
+    server = FastMCPOpenAPI(spec=valid_spec, client=client)
+    init_time = time.time() - start_time
+    assert init_time < 0.01  # Should be very fast
+    
+    # Verify RequestDirector functionality
+    assert hasattr(server, '_director')
+    assert hasattr(server, '_spec')
+```
+
+## Migration Benefits
+
+### From Legacy Implementation
+
+1. **Eliminated Startup Latency**: Zero code generation overhead (100-200ms improvement)
+2. **Better OpenAPI Compliance**: openapi-core handles all OpenAPI features correctly
+3. **Serverless Friendly**: Perfect for cold-start environments
+4. **Simplified Architecture**: Single RequestDirector approach eliminates complexity
+5. **Enhanced Reliability**: No dynamic code generation failures
+
+### Backward Compatibility
+
+- **Same Interface**: Public API unchanged from legacy implementation
+- **Performance Improvement**: Significantly faster initialization
+- **No Breaking Changes**: Existing code works without modification
+
+## Monitoring and Debugging
+
+### Logging
+
+```python
+# Enable debug logging to see implementation choices
+import logging
+logging.getLogger("fastmcp.server.openapi_new").setLevel(logging.DEBUG)
+```
+
+### Key Log Messages
+- **RequestDirector Initialization**: Success/failure of RequestDirector setup
+- **Schema Pre-calculation**: Pre-calculated schema and parameter map status
+- **Request Building**: Parameter mapping and URL construction details
+- **Performance Metrics**: Request timing and error rates
+
+### Debugging Common Issues
+
+1. **RequestDirector Initialization Fails**
+   - Check OpenAPI spec validity with `openapi-core`
+   - Verify spec format is correct JSON/YAML
+   - Ensure all required OpenAPI fields are present
+
+2. **Parameter Issues**
+   - Enable debug logging for parameter processing
+   - Check for parameter collision warnings
+   - Verify OpenAPI spec parameter definitions
+
+3. **Performance Issues**
+   - Monitor RequestDirector request building timing
+   - Check HTTP client configuration
+   - Review response processing timing
+
+## Future Enhancements
+
+### Planned Features
+
+1. **Advanced Caching**: Intelligent response caching with TTL
+2. **Streaming Support**: Handle streaming API responses
+3. **Batch Operations**: Optimize multiple operation calls
+4. **Enhanced Monitoring**: Detailed metrics and health checks
+5. **Configuration Management**: Dynamic configuration updates
+
+### Performance Improvements
+
+1. **Enhanced Schema Caching**: More aggressive schema pre-calculation
+2. **Parallel Processing**: Concurrent operation execution
+3. **Memory Optimization**: Further reduce memory footprint
+4. **Request Optimization**: Smart request batching and deduplication
+
+## Related Documentation
+
+- `/utilities/openapi_new/README.md` - Utility implementation details
+- `/server/openapi/README.md` - Legacy implementation reference
+- `/tests/server/openapi_new/` - Comprehensive test suite
+- Project documentation on OpenAPI integration patterns

fastmcp/experimental/server/openapi/__init__.py

@@ -0,0 +1,38 @@
+"""OpenAPI server implementation for FastMCP - refactored for better maintainability."""
+
+# Import from server
+from .server import FastMCPOpenAPI
+
+# Import from routing
+from .routing import (
+    MCPType,
+    RouteMap,
+    RouteMapFn,
+    ComponentFn,
+    DEFAULT_ROUTE_MAPPINGS,
+    _determine_route_type,
+)
+
+# Import from components
+from .components import (
+    OpenAPITool,
+    OpenAPIResource,
+    OpenAPIResourceTemplate,
+)
+
+# Export public symbols - maintaining backward compatibility
+__all__ = [
+    # Server
+    "FastMCPOpenAPI",
+    # Routing
+    "MCPType",
+    "RouteMap",
+    "RouteMapFn",
+    "ComponentFn",
+    "DEFAULT_ROUTE_MAPPINGS",
+    "_determine_route_type",
+    # Components
+    "OpenAPITool",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+]

fastmcp/experimental/server/openapi/components.py

@@ -0,0 +1,348 @@
+"""OpenAPI component implementations: Tool, Resource, and ResourceTemplate classes."""
+
+import json
+import re
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+import httpx
+from mcp.types import ToolAnnotations
+from pydantic.networks import AnyUrl
+
+# Import from our new utilities
+from fastmcp.experimental.utilities.openapi import HTTPRoute
+from fastmcp.experimental.utilities.openapi.director import RequestDirector
+from fastmcp.resources import Resource, ResourceTemplate
+from fastmcp.server.dependencies import get_http_headers
+from fastmcp.tools.tool import Tool, ToolResult
+from fastmcp.utilities.logging import get_logger
+
+if TYPE_CHECKING:
+    from fastmcp.server import Context
+
+logger = get_logger(__name__)
+
+
+class OpenAPITool(Tool):
+    """Tool implementation for OpenAPI endpoints."""
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        route: HTTPRoute,
+        director: RequestDirector,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        output_schema: dict[str, Any] | None = None,
+        tags: set[str] | None = None,
+        timeout: float | None = None,
+        annotations: ToolAnnotations | None = None,
+        serializer: Callable[[Any], str] | None = None,
+    ):
+        super().__init__(
+            name=name,
+            description=description,
+            parameters=parameters,
+            output_schema=output_schema,
+            tags=tags or set(),
+            annotations=annotations,
+            serializer=serializer,
+        )
+        self._client = client
+        self._route = route
+        self._director = director
+        self._timeout = timeout
+
+    def __repr__(self) -> str:
+        """Custom representation to prevent recursion errors when printing."""
+        return f"OpenAPITool(name={self.name!r}, method={self._route.method}, path={self._route.path})"
+
+    async def run(self, arguments: dict[str, Any]) -> ToolResult:
+        """Execute the HTTP request using RequestDirector for simplified parameter handling."""
+        try:
+            # Get base URL from client
+            base_url = (
+                str(self._client.base_url)
+                if hasattr(self._client, "base_url") and self._client.base_url
+                else "http://localhost"
+            )
+
+            # Get Headers from client
+            cli_headers = (
+                self._client.headers
+                if hasattr(self._client, "headers") and self._client.headers
+                else {}
+            )
+
+            # Build the request using RequestDirector
+            request = self._director.build(self._route, arguments, base_url)
+
+            # First add server headers (lowest precedence)
+            if cli_headers:
+                # Merge with existing headers, _client headers as base
+                if request.headers:
+                    # Start with request headers, then add client headers
+                    for key, value in cli_headers.items():
+                        if key not in request.headers:
+                            request.headers[key] = value
+                else:
+                    # Create new headers from cli_headers
+                    for key, value in cli_headers.items():
+                        request.headers[key] = value
+
+            # Then add MCP client transport headers (highest precedence)
+            mcp_headers = get_http_headers()
+            if mcp_headers:
+                # Merge with existing headers, MCP headers take precedence over all
+                if request.headers:
+                    request.headers.update(mcp_headers)
+                else:
+                    # Create new headers from mcp_headers
+                    for key, value in mcp_headers.items():
+                        request.headers[key] = value
+            # print logger
+            logger.debug(f"run - sending request; headers: {request.headers}")
+
+            # Execute the request
+            # Note: httpx.AsyncClient.send() doesn't accept timeout parameter
+            # The timeout should be configured on the client itself
+            response = await self._client.send(request)
+
+            # Raise for 4xx/5xx responses
+            response.raise_for_status()
+
+            # Try to parse as JSON first
+            try:
+                result = response.json()
+
+                # Handle structured content based on output schema, if any
+                structured_output = None
+                if self.output_schema is not None:
+                    if self.output_schema.get("x-fastmcp-wrap-result"):
+                        # Schema says wrap - always wrap in result key
+                        structured_output = {"result": result}
+                    else:
+                        structured_output = result
+                # If no output schema, use fallback logic for backward compatibility
+                elif not isinstance(result, dict):
+                    structured_output = {"result": result}
+                else:
+                    structured_output = result
+
+                return ToolResult(structured_content=structured_output)
+            except json.JSONDecodeError:
+                return ToolResult(content=response.text)
+
+        except httpx.HTTPStatusError as e:
+            # Handle HTTP errors (4xx, 5xx)
+            error_message = (
+                f"HTTP error {e.response.status_code}: {e.response.reason_phrase}"
+            )
+            try:
+                error_data = e.response.json()
+                error_message += f" - {error_data}"
+            except (json.JSONDecodeError, ValueError):
+                if e.response.text:
+                    error_message += f" - {e.response.text}"
+
+            raise ValueError(error_message)
+
+        except httpx.RequestError as e:
+            # Handle request errors (connection, timeout, etc.)
+            raise ValueError(f"Request error: {str(e)}")
+
+
+class OpenAPIResource(Resource):
+    """Resource implementation for OpenAPI endpoints."""
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        route: HTTPRoute,
+        director: RequestDirector,
+        uri: str,
+        name: str,
+        description: str,
+        mime_type: str = "application/json",
+        tags: set[str] = set(),
+        timeout: float | None = None,
+    ):
+        super().__init__(
+            uri=AnyUrl(uri),  # Convert string to AnyUrl
+            name=name,
+            description=description,
+            mime_type=mime_type,
+            tags=tags,
+        )
+        self._client = client
+        self._route = route
+        self._director = director
+        self._timeout = timeout
+
+    def __repr__(self) -> str:
+        """Custom representation to prevent recursion errors when printing."""
+        return f"OpenAPIResource(name={self.name!r}, uri={self.uri!r}, path={self._route.path})"
+
+    async def read(self) -> str | bytes:
+        """Fetch the resource data by making an HTTP request."""
+        try:
+            # Extract path parameters from the URI if present
+            path = self._route.path
+            resource_uri = str(self.uri)
+
+            # If this is a templated resource, extract path parameters from the URI
+            if "{" in path and "}" in path:
+                # Extract the resource ID from the URI (the last part after the last slash)
+                parts = resource_uri.split("/")
+
+                if len(parts) > 1:
+                    # Find all path parameters in the route path
+                    path_params = {}
+
+                    # Find the path parameter names from the route path
+                    param_matches = re.findall(r"\{([^}]+)\}", path)
+                    if param_matches:
+                        # Reverse sorting from creation order (traversal is backwards)
+                        param_matches.sort(reverse=True)
+                        # Number of sent parameters is number of parts -1 (assuming first part is resource identifier)
+                        expected_param_count = len(parts) - 1
+                        # Map parameters from the end of the URI to the parameters in the path
+                        # Last parameter in URI (parts[-1]) maps to last parameter in path, and so on
+                        for i, param_name in enumerate(param_matches):
+                            # Ensure we don't use resource identifier as parameter
+                            if i < expected_param_count:
+                                # Get values from the end of parts
+                                param_value = parts[-1 - i]
+                                path_params[param_name] = param_value
+
+                    # Replace path parameters with their values
+                    for param_name, param_value in path_params.items():
+                        path = path.replace(f"{{{param_name}}}", str(param_value))
+
+            # Filter any query parameters - get query parameters and filter out None/empty values
+            query_params = {}
+            for param in self._route.parameters:
+                if param.location == "query" and hasattr(self, f"_{param.name}"):
+                    value = getattr(self, f"_{param.name}")
+                    if value is not None and value != "":
+                        query_params[param.name] = value
+
+            # Prepare headers with correct precedence: server < client transport
+            headers = {}
+            # Start with server headers (lowest precedence)
+            cli_headers = (
+                self._client.headers
+                if hasattr(self._client, "headers") and self._client.headers
+                else {}
+            )
+            headers.update(cli_headers)
+
+            # Add MCP client transport headers (highest precedence)
+            mcp_headers = get_http_headers()
+            headers.update(mcp_headers)
+
+            response = await self._client.request(
+                method=self._route.method,
+                url=path,
+                params=query_params,
+                headers=headers,
+                timeout=self._timeout,
+            )
+
+            # Raise for 4xx/5xx responses
+            response.raise_for_status()
+
+            # Determine content type and return appropriate format
+            content_type = response.headers.get("content-type", "").lower()
+
+            if "application/json" in content_type:
+                result = response.json()
+                return json.dumps(result)
+            elif any(ct in content_type for ct in ["text/", "application/xml"]):
+                return response.text
+            else:
+                return response.content
+
+        except httpx.HTTPStatusError as e:
+            # Handle HTTP errors (4xx, 5xx)
+            error_message = (
+                f"HTTP error {e.response.status_code}: {e.response.reason_phrase}"
+            )
+            try:
+                error_data = e.response.json()
+                error_message += f" - {error_data}"
+            except (json.JSONDecodeError, ValueError):
+                if e.response.text:
+                    error_message += f" - {e.response.text}"
+
+            raise ValueError(error_message)
+
+        except httpx.RequestError as e:
+            # Handle request errors (connection, timeout, etc.)
+            raise ValueError(f"Request error: {str(e)}")
+
+
+class OpenAPIResourceTemplate(ResourceTemplate):
+    """Resource template implementation for OpenAPI endpoints."""
+
+    def __init__(
+        self,
+        client: httpx.AsyncClient,
+        route: HTTPRoute,
+        director: RequestDirector,
+        uri_template: str,
+        name: str,
+        description: str,
+        parameters: dict[str, Any],
+        tags: set[str] = set(),
+        timeout: float | None = None,
+    ):
+        super().__init__(
+            uri_template=uri_template,
+            name=name,
+            description=description,
+            parameters=parameters,
+            tags=tags,
+        )
+        self._client = client
+        self._route = route
+        self._director = director
+        self._timeout = timeout
+
+    def __repr__(self) -> str:
+        """Custom representation to prevent recursion errors when printing."""
+        return f"OpenAPIResourceTemplate(name={self.name!r}, uri_template={self.uri_template!r}, path={self._route.path})"
+
+    async def create_resource(
+        self,
+        uri: str,
+        params: dict[str, Any],
+        context: "Context | None" = None,
+    ) -> Resource:
+        """Create a resource with the given parameters."""
+        # Generate a URI for this resource instance
+        uri_parts = []
+        for key, value in params.items():
+            uri_parts.append(f"{key}={value}")
+
+        # Create and return a resource
+        return OpenAPIResource(
+            client=self._client,
+            route=self._route,
+            director=self._director,
+            uri=uri,
+            name=f"{self.name}-{'-'.join(uri_parts)}",
+            description=self.description or f"Resource for {self._route.path}",
+            mime_type="application/json",
+            tags=set(self._route.tags or []),
+            timeout=self._timeout,
+        )
+
+
+# Export public symbols
+__all__ = [
+    "OpenAPITool",
+    "OpenAPIResource",
+    "OpenAPIResourceTemplate",
+]