src/fastmcp/experimental/server/openapi/README.md

# 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