awslabs.openapi-mcp-server 0.1.1__py3-none-any.whl

awslabs/openapi_mcp_server/utils/openapi.py

@@ -0,0 +1,217 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Utilities for working with OpenAPI specifications."""
+
+import httpx
+import json
+import tempfile
+import time
+from awslabs.openapi_mcp_server import logger
+from awslabs.openapi_mcp_server.utils.cache_provider import cached
+from awslabs.openapi_mcp_server.utils.openapi_validator import validate_openapi_spec
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+def extract_api_name_from_spec(spec: Dict[str, Any]) -> Optional[str]:
+    """Extract the API name from an OpenAPI specification.
+
+    Args:
+        spec: The OpenAPI specification dictionary
+
+    Returns:
+        Optional[str]: The API name extracted from the specification, or None if not found
+
+    """
+    if not spec or not isinstance(spec, dict):
+        logger.warning('Invalid OpenAPI spec format')
+        return None
+
+    # Extract from info.title
+    if 'info' in spec and isinstance(spec['info'], dict) and 'title' in spec['info']:
+        return spec['info']['title']
+
+    logger.debug('No API name found in OpenAPI spec')
+    return None
+
+
+# Import yaml conditionally to avoid errors if it's not installed
+try:
+    import yaml
+except ImportError:
+    yaml = None  # type: Optional[Any]
+
+
+# Try to import prance, but don't fail if it's not installed
+try:
+    from prance import ResolvingParser
+
+    PRANCE_AVAILABLE = True
+except ImportError:
+    PRANCE_AVAILABLE = False
+    logger.warning('Prance library not found. Reference resolution will be limited.')
+
+
+@cached(ttl_seconds=3600)  # Cache OpenAPI specs for 1 hour
+def load_openapi_spec(url: str = '', path: str = '') -> Dict[str, Any]:
+    """Load an OpenAPI specification from a URL or file path.
+
+    If prance is available, it will be used to resolve references in the OpenAPI spec.
+    Otherwise, falls back to basic JSON/YAML parsing.
+
+    Args:
+        url: URL to the OpenAPI specification
+        path: Path to the OpenAPI specification file
+
+    Returns:
+        Dict[str, Any]: The parsed OpenAPI specification
+
+    Raises:
+        ValueError: If neither url nor path are provided
+        FileNotFoundError: If the file at path does not exist
+        httpx.HTTPError: If there's an HTTP error when fetching the spec
+        httpx.TimeoutException: If there's a timeout when fetching the spec
+
+    """
+    if not url and not path:
+        logger.error('Neither URL nor path provided')
+        raise ValueError('Either url or path must be provided')
+
+    # Load from URL
+    if url:
+        logger.info(f'Fetching OpenAPI spec from URL: {url}')
+        last_exception = None
+
+        # Use retry logic for network resilience
+        for attempt in range(3):
+            try:
+                response = httpx.get(url, timeout=10.0)
+                response.raise_for_status()
+
+                if PRANCE_AVAILABLE:
+                    logger.info('Using prance for reference resolution')
+                    # Use prance for reference resolution if available
+                    with tempfile.NamedTemporaryFile(suffix='.yaml', delete=False) as temp_file:
+                        temp_path = temp_file.name
+                        temp_file.write(response.content)
+
+                    try:
+                        parser = ResolvingParser(temp_path)
+                        spec = parser.specification
+
+                        # Clean up the temporary file
+                        Path(temp_path).unlink(missing_ok=True)
+                    except Exception as e:
+                        logger.warning(
+                            f'Failed to parse with prance: {e}. Falling back to basic parsing.'
+                        )
+                        # Clean up the temporary file
+                        Path(temp_path).unlink(missing_ok=True)
+                        # Fall back to basic parsing
+                        spec = response.json()
+                else:
+                    # Basic parsing without reference resolution
+                    spec = response.json()
+
+                # Validate the spec
+                if validate_openapi_spec(spec):
+                    return spec
+                else:
+                    logger.error('Invalid OpenAPI specification')
+                    raise ValueError('Invalid OpenAPI specification')
+
+            except (httpx.TimeoutException, httpx.HTTPError) as e:
+                last_exception = e
+                if attempt < 2:  # Don't log on the last attempt
+                    logger.warning(f'Attempt {attempt + 1} failed: {e}. Retrying...')
+                    time.sleep(1 * (2**attempt))  # Exponential backoff
+                else:
+                    # Re-raise the exception on the last attempt
+                    logger.error(f'All retry attempts failed: {e}')
+                    raise
+
+        # This will only be reached if all retries fail and no exception is raised
+        if last_exception:
+            raise last_exception
+        else:
+            raise httpx.HTTPError('All retry attempts failed')
+
+    # Load from file
+    if path:
+        spec_path = Path(path)
+        if not spec_path.exists():
+            logger.error(f'OpenAPI spec file not found: {path}')
+            raise FileNotFoundError(f'File not found: {path}')
+
+        logger.info(f'Loading OpenAPI spec from file: {path}')
+        try:
+            if PRANCE_AVAILABLE:
+                logger.info('Using prance for reference resolution')
+                # Use prance for reference resolution if available
+                try:
+                    parser = ResolvingParser(path)
+                    spec = parser.specification
+                except Exception as e:
+                    logger.warning(
+                        f'Failed to parse with prance: {e}. Falling back to basic parsing.'
+                    )
+                    # Fall back to basic parsing
+                    with open(spec_path, 'r') as f:
+                        content = f.read()
+                        try:
+                            spec = json.loads(content)
+                        except json.JSONDecodeError as json_err:
+                            # If it's not JSON, try to parse as YAML
+                            try:
+                                import yaml
+
+                                spec = yaml.safe_load(content)
+                            except ImportError:
+                                logger.error('YAML parsing requires pyyaml to be installed')
+                                raise ImportError(
+                                    "Required dependency 'pyyaml' not installed. Install it with: pip install pyyaml"
+                                ) from json_err
+                            except Exception as yaml_err:
+                                logger.error(f'Failed to parse YAML: {yaml_err}')
+                                raise ValueError(f'Invalid YAML: {yaml_err}') from yaml_err
+            else:
+                # Basic parsing without reference resolution
+                with open(spec_path, 'r') as f:
+                    content = f.read()
+                    try:
+                        spec = json.loads(content)
+                    except json.JSONDecodeError as json_err:
+                        # If it's not JSON, try to parse as YAML
+                        try:
+                            import yaml
+
+                            spec = yaml.safe_load(content)
+                        except ImportError:
+                            logger.error('YAML parsing requires pyyaml to be installed')
+                            raise ImportError(
+                                "Required dependency 'pyyaml' not installed. Install it with: pip install pyyaml"
+                            ) from json_err
+                        except Exception as yaml_err:
+                            logger.error(f'Failed to parse YAML: {yaml_err}')
+                            raise ValueError(f'Invalid YAML: {yaml_err}') from yaml_err
+
+            # Validate the spec
+            if validate_openapi_spec(spec):
+                return spec
+            else:
+                raise ValueError('Invalid OpenAPI specification')
+
+        except Exception as e:
+            logger.error(f'Failed to load OpenAPI spec from file: {path} - Error: {e}')
+            raise

awslabs/openapi_mcp_server/utils/openapi_validator.py

@@ -0,0 +1,253 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""OpenAPI validation utilities.
+
+This module provides validation for OpenAPI specifications using openapi-core
+when available, with a simple fallback implementation.
+"""
+
+import os
+from awslabs.openapi_mcp_server import logger
+from typing import Any, Dict, List, Tuple
+
+
+# Check if openapi-core is available
+openapi_core = None
+try:
+    import openapi_core
+
+    OPENAPI_CORE_AVAILABLE = True
+    logger.debug('Using openapi-core for validation')
+except ImportError:
+    OPENAPI_CORE_AVAILABLE = False
+    logger.debug('openapi-core not available, using simple validation')
+
+# Use openapi-core if available and not explicitly disabled
+USE_OPENAPI_CORE = OPENAPI_CORE_AVAILABLE and os.environ.get(
+    'MCP_USE_OPENAPI_CORE', 'true'
+).lower() in ('true', '1', 'yes')
+
+
+def validate_openapi_spec(spec: Dict[str, Any]) -> bool:
+    """Validate an OpenAPI specification.
+
+    Args:
+        spec: The OpenAPI specification to validate
+
+    Returns:
+        bool: True if the specification is valid, False otherwise
+
+    """
+    # Basic validation first
+    # Check for required fields
+    if 'openapi' not in spec:
+        logger.error("Missing 'openapi' field in OpenAPI spec")
+        return False
+
+    if 'info' not in spec:
+        logger.error("Missing 'info' field in OpenAPI spec")
+        return False
+
+    if 'paths' not in spec:
+        logger.error("Missing 'paths' field in OpenAPI spec")
+        return False
+
+    # Check OpenAPI version
+    version = spec['openapi']
+    if not version.startswith('3.'):
+        logger.warning(f'OpenAPI version {version} may not be fully supported')
+
+    # Use openapi-core for additional validation if available
+    if USE_OPENAPI_CORE and openapi_core is not None:
+        try:
+            # Create spec object - this will validate the spec
+            if hasattr(openapi_core, 'create_spec'):
+                # Ignore type error since we're checking dynamically
+                openapi_core.create_spec(spec)  # type: ignore
+            # For older versions of openapi-core
+            elif hasattr(openapi_core, 'Spec'):
+                spec_class = getattr(openapi_core, 'Spec')
+                if hasattr(spec_class, 'create'):
+                    # Ignore type error since we're checking dynamically
+                    spec_class.create(spec)  # type: ignore
+            # For newer versions of openapi-core
+            elif hasattr(openapi_core, 'OpenAPISpec'):
+                # Ignore type error since we're checking dynamically
+                getattr(openapi_core, 'OpenAPISpec').create(spec)  # type: ignore
+            else:
+                logger.warning('Unsupported openapi-core version - skipping additional validation')
+            logger.debug('OpenAPI spec validated with openapi-core')
+        except Exception as e:
+            logger.error(f'Error validating OpenAPI spec with openapi-core: {e}')
+            # We already did basic validation, so we'll still return True
+            return True
+
+    # Return True if we've passed all validations
+    return True
+
+
+def extract_api_structure(spec: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract the structure of an API from its OpenAPI specification.
+
+    Args:
+        spec: The OpenAPI specification
+
+    Returns:
+        Dict[str, Any]: A structured representation of the API
+
+    """
+    result = {
+        'info': {
+            'title': spec.get('info', {}).get('title', 'Unknown API'),
+            'version': spec.get('info', {}).get('version', 'Unknown'),
+            'description': spec.get('info', {}).get('description', ''),
+        },
+        'paths': {},
+        'operations': [],
+        'schemas': [],
+    }
+
+    # Extract paths and operations
+    for path, path_item in spec.get('paths', {}).items():
+        path_info = {'path': path, 'methods': {}}
+
+        for method in ['get', 'post', 'put', 'delete', 'patch', 'options', 'head']:
+            if method in path_item:
+                operation = path_item[method]
+                operation_id = operation.get('operationId', f'{method}{path}')
+                summary = operation.get('summary', '')
+                description = operation.get('description', '')
+
+                # Extract parameters
+                parameters = []
+                for param in operation.get('parameters', []):
+                    parameters.append(
+                        {
+                            'name': param.get('name', ''),
+                            'in': param.get('in', ''),
+                            'required': param.get('required', False),
+                            'description': param.get('description', ''),
+                        }
+                    )
+
+                # Extract request body if present
+                request_body = None
+                if 'requestBody' in operation:
+                    request_body = {
+                        'required': operation['requestBody'].get('required', False),
+                        'content_types': list(operation['requestBody'].get('content', {}).keys()),
+                    }
+
+                # Extract responses
+                responses = {}
+                for status_code, response in operation.get('responses', {}).items():
+                    responses[status_code] = {
+                        'description': response.get('description', ''),
+                        'content_types': list(response.get('content', {}).keys()),
+                    }
+
+                # Add to path methods
+                path_info['methods'][method] = {
+                    'operationId': operation_id,
+                    'summary': summary,
+                    'description': description,
+                    'parameters': parameters,
+                    'requestBody': request_body,
+                    'responses': responses,
+                }
+
+                # Add to operations list
+                result['operations'].append(
+                    {
+                        'operationId': operation_id,
+                        'method': method.upper(),
+                        'path': path,
+                        'summary': summary,
+                    }
+                )
+
+        result['paths'][path] = path_info
+
+    # Extract schemas
+    if 'components' in spec and 'schemas' in spec['components']:
+        for schema_name, schema in spec['components']['schemas'].items():
+            result['schemas'].append(
+                {
+                    'name': schema_name,
+                    'type': schema.get('type', 'object'),
+                    'properties': len(schema.get('properties', {})),
+                    'required': schema.get('required', []),
+                }
+            )
+
+    return result
+
+
+def find_pagination_endpoints(spec: Dict[str, Any]) -> List[Tuple[str, str, Dict[str, Any]]]:
+    """Find endpoints that likely support pagination.
+
+    Args:
+        spec: The OpenAPI specification
+
+    Returns:
+        List[Tuple[str, str, Dict[str, Any]]]: List of (path, method, operation) tuples
+
+    """
+    pagination_endpoints = []
+
+    for path, path_item in spec.get('paths', {}).items():
+        for method, operation in path_item.items():
+            if method.lower() != 'get':
+                continue
+
+            # Check for pagination parameters
+            has_pagination = False
+            for param in operation.get('parameters', []):
+                param_name = param.get('name', '').lower()
+                if param_name in [
+                    'page',
+                    'limit',
+                    'offset',
+                    'size',
+                    'per_page',
+                    'pagesize',
+                    'page_size',
+                    'next',
+                    'cursor',
+                ]:
+                    has_pagination = True
+                    break
+
+            # Check for array responses
+            has_array_response = False
+            for response in operation.get('responses', {}).values():
+                for content_type, content in response.get('content', {}).items():
+                    if 'application/json' in content_type:
+                        schema = content.get('schema', {})
+                        if schema.get('type') == 'array' or 'items' in schema:
+                            has_array_response = True
+                            break
+                        # Check for common pagination response structures
+                        properties = schema.get('properties', {})
+                        for prop_name in properties:
+                            if prop_name.lower() in ['items', 'data', 'results', 'content']:
+                                prop_schema = properties[prop_name]
+                                if prop_schema.get('type') == 'array' or 'items' in prop_schema:
+                                    has_array_response = True
+                                    break
+
+            if has_pagination or has_array_response:
+                pagination_endpoints.append((path, method, operation))
+
+    return pagination_endpoints