feat: Complete PyPI Query MCP Server Implementation (#3)

Merge pull request implementing complete PyPI query MCP server with comprehensive features and CI/CD pipeline.

pypi_query_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""PyPI Query MCP Server.
+
+A Model Context Protocol (MCP) server for querying PyPI package information,
+dependencies, and compatibility checking.
+"""
+
+__version__ = "0.1.0"
+__author__ = "Hal"
+__email__ = "hal.long@outlook.com"
+
+from pypi_query_mcp.server import app
+
+__all__ = ["app", "__version__"]

pypi_query_mcp/config/__init__.py

@@ -0,0 +1,8 @@
+"""Configuration management for PyPI Query MCP Server.
+
+This package handles configuration loading, validation, and management
+for the MCP server, including private registry settings.
+"""
+
+# Configuration exports will be added as modules are implemented
+__all__ = []

pypi_query_mcp/core/__init__.py

@@ -0,0 +1,27 @@
+"""Core modules for PyPI Query MCP Server.
+
+This package contains the core business logic for PyPI package queries,
+including API clients, data processing, and utility functions.
+"""
+
+from .exceptions import (
+    InvalidPackageNameError,
+    NetworkError,
+    PackageNotFoundError,
+    PyPIError,
+    PyPIServerError,
+    RateLimitError,
+)
+from .pypi_client import PyPIClient
+from .version_utils import VersionCompatibility
+
+__all__ = [
+    "PyPIClient",
+    "VersionCompatibility",
+    "PyPIError",
+    "PackageNotFoundError",
+    "NetworkError",
+    "RateLimitError",
+    "InvalidPackageNameError",
+    "PyPIServerError",
+]

pypi_query_mcp/core/exceptions.py

@@ -0,0 +1,56 @@
+"""Custom exceptions for PyPI Query MCP Server."""
+
+
+class PyPIError(Exception):
+    """Base exception for PyPI-related errors."""
+
+    def __init__(self, message: str, status_code: int = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+
+
+class PackageNotFoundError(PyPIError):
+    """Raised when a package is not found on PyPI."""
+
+    def __init__(self, package_name: str):
+        message = f"Package '{package_name}' not found on PyPI"
+        super().__init__(message, status_code=404)
+        self.package_name = package_name
+
+
+class NetworkError(PyPIError):
+    """Raised when network-related errors occur."""
+
+    def __init__(self, message: str, original_error: Exception = None):
+        super().__init__(message)
+        self.original_error = original_error
+
+
+class RateLimitError(PyPIError):
+    """Raised when API rate limit is exceeded."""
+
+    def __init__(self, retry_after: int = None):
+        message = "PyPI API rate limit exceeded"
+        if retry_after:
+            message += f". Retry after {retry_after} seconds"
+        super().__init__(message, status_code=429)
+        self.retry_after = retry_after
+
+
+class InvalidPackageNameError(PyPIError):
+    """Raised when package name is invalid."""
+
+    def __init__(self, package_name: str):
+        message = f"Invalid package name: '{package_name}'"
+        super().__init__(message, status_code=400)
+        self.package_name = package_name
+
+
+class PyPIServerError(PyPIError):
+    """Raised when PyPI server returns a server error."""
+
+    def __init__(self, status_code: int, message: str = None):
+        if not message:
+            message = f"PyPI server error (HTTP {status_code})"
+        super().__init__(message, status_code=status_code)

pypi_query_mcp/core/pypi_client.py

@@ -0,0 +1,238 @@
+"""PyPI API client for package information retrieval."""
+
+import asyncio
+import logging
+import re
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from .exceptions import (
+    InvalidPackageNameError,
+    NetworkError,
+    PackageNotFoundError,
+    PyPIServerError,
+    RateLimitError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PyPIClient:
+    """Async client for PyPI JSON API."""
+
+    def __init__(
+        self,
+        base_url: str = "https://pypi.org/pypi",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+    ):
+        """Initialize PyPI client.
+
+        Args:
+            base_url: Base URL for PyPI API
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts
+            retry_delay: Delay between retries in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+
+        # Simple in-memory cache
+        self._cache: dict[str, dict[str, Any]] = {}
+        self._cache_ttl = 300  # 5 minutes
+
+        # HTTP client configuration
+        self._client = httpx.AsyncClient(
+            timeout=httpx.Timeout(timeout),
+            headers={
+                "User-Agent": "pypi-query-mcp-server/0.1.0",
+                "Accept": "application/json",
+            },
+            follow_redirects=True,
+        )
+
+    async def __aenter__(self):
+        """Async context manager entry."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager exit."""
+        await self.close()
+
+    async def close(self):
+        """Close the HTTP client."""
+        await self._client.aclose()
+
+    def _validate_package_name(self, package_name: str) -> str:
+        """Validate and normalize package name.
+
+        Args:
+            package_name: Package name to validate
+
+        Returns:
+            Normalized package name
+
+        Raises:
+            InvalidPackageNameError: If package name is invalid
+        """
+        if not package_name or not package_name.strip():
+            raise InvalidPackageNameError(package_name)
+
+        # Normalize package name (convert to lowercase, replace _ with -)
+        normalized = re.sub(r"[-_.]+", "-", package_name.lower())
+
+        # Basic validation - package names should contain only alphanumeric, hyphens, dots, underscores
+        if not re.match(r"^[a-zA-Z0-9]([a-zA-Z0-9._-]*[a-zA-Z0-9])?$", package_name):
+            raise InvalidPackageNameError(package_name)
+
+        return normalized
+
+    def _get_cache_key(self, package_name: str, endpoint: str = "info") -> str:
+        """Generate cache key for package data."""
+        return f"{endpoint}:{package_name}"
+
+    def _is_cache_valid(self, cache_entry: dict[str, Any]) -> bool:
+        """Check if cache entry is still valid."""
+        import time
+        return time.time() - cache_entry.get("timestamp", 0) < self._cache_ttl
+
+    async def _make_request(self, url: str) -> dict[str, Any]:
+        """Make HTTP request with retry logic.
+
+        Args:
+            url: URL to request
+
+        Returns:
+            JSON response data
+
+        Raises:
+            NetworkError: For network-related errors
+            PackageNotFoundError: When package is not found
+            RateLimitError: When rate limit is exceeded
+            PyPIServerError: For server errors
+        """
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                logger.debug(f"Making request to {url} (attempt {attempt + 1})")
+
+                response = await self._client.get(url)
+
+                # Handle different HTTP status codes
+                if response.status_code == 200:
+                    return response.json()
+                elif response.status_code == 404:
+                    # Extract package name from URL for better error message
+                    package_name = url.split("/")[-2] if "/" in url else "unknown"
+                    raise PackageNotFoundError(package_name)
+                elif response.status_code == 429:
+                    retry_after = response.headers.get("Retry-After")
+                    retry_after_int = int(retry_after) if retry_after else None
+                    raise RateLimitError(retry_after_int)
+                elif response.status_code >= 500:
+                    raise PyPIServerError(response.status_code)
+                else:
+                    raise PyPIServerError(
+                        response.status_code,
+                        f"Unexpected status code: {response.status_code}"
+                    )
+
+            except httpx.TimeoutException as e:
+                last_exception = NetworkError(f"Request timeout: {e}", e)
+            except httpx.NetworkError as e:
+                last_exception = NetworkError(f"Network error: {e}", e)
+            except (PackageNotFoundError, RateLimitError, PyPIServerError):
+                # Don't retry these errors
+                raise
+            except Exception as e:
+                last_exception = NetworkError(f"Unexpected error: {e}", e)
+
+            # Wait before retry (except on last attempt)
+            if attempt < self.max_retries:
+                await asyncio.sleep(self.retry_delay * (2 ** attempt))  # Exponential backoff
+
+        # If we get here, all retries failed
+        raise last_exception
+
+    async def get_package_info(self, package_name: str, use_cache: bool = True) -> dict[str, Any]:
+        """Get comprehensive package information from PyPI.
+
+        Args:
+            package_name: Name of the package to query
+            use_cache: Whether to use cached data if available
+
+        Returns:
+            Dictionary containing package information
+
+        Raises:
+            InvalidPackageNameError: If package name is invalid
+            PackageNotFoundError: If package is not found
+            NetworkError: For network-related errors
+        """
+        normalized_name = self._validate_package_name(package_name)
+        cache_key = self._get_cache_key(normalized_name, "info")
+
+        # Check cache first
+        if use_cache and cache_key in self._cache:
+            cache_entry = self._cache[cache_key]
+            if self._is_cache_valid(cache_entry):
+                logger.debug(f"Using cached data for package: {normalized_name}")
+                return cache_entry["data"]
+
+        # Make API request
+        url = f"{self.base_url}/{quote(normalized_name)}/json"
+        logger.info(f"Fetching package info for: {normalized_name}")
+
+        try:
+            data = await self._make_request(url)
+
+            # Cache the result
+            import time
+            self._cache[cache_key] = {
+                "data": data,
+                "timestamp": time.time()
+            }
+
+            return data
+
+        except Exception as e:
+            logger.error(f"Failed to fetch package info for {normalized_name}: {e}")
+            raise
+
+    async def get_package_versions(self, package_name: str, use_cache: bool = True) -> list[str]:
+        """Get list of available versions for a package.
+
+        Args:
+            package_name: Name of the package to query
+            use_cache: Whether to use cached data if available
+
+        Returns:
+            List of version strings
+        """
+        package_info = await self.get_package_info(package_name, use_cache)
+        releases = package_info.get("releases", {})
+        return list(releases.keys())
+
+    async def get_latest_version(self, package_name: str, use_cache: bool = True) -> str:
+        """Get the latest version of a package.
+
+        Args:
+            package_name: Name of the package to query
+            use_cache: Whether to use cached data if available
+
+        Returns:
+            Latest version string
+        """
+        package_info = await self.get_package_info(package_name, use_cache)
+        return package_info.get("info", {}).get("version", "")
+
+    def clear_cache(self):
+        """Clear the internal cache."""
+        self._cache.clear()
+        logger.debug("Cache cleared")

pypi_query_mcp/core/version_utils.py

@@ -0,0 +1,274 @@
+"""Version parsing and compatibility checking utilities."""
+
+import logging
+import re
+from typing import Any
+
+from packaging.specifiers import SpecifierSet
+from packaging.version import InvalidVersion, Version
+
+logger = logging.getLogger(__name__)
+
+
+class VersionCompatibility:
+    """Utility class for Python version compatibility checking."""
+
+    def __init__(self):
+        """Initialize version compatibility checker."""
+        # Common Python version patterns in classifiers
+        self.python_classifier_pattern = re.compile(
+            r"Programming Language :: Python :: (\d+(?:\.\d+)*)"
+        )
+
+        # Implementation-specific classifiers
+        self.implementation_pattern = re.compile(
+            r"Programming Language :: Python :: Implementation :: (\w+)"
+        )
+
+    def parse_requires_python(self, requires_python: str) -> SpecifierSet | None:
+        """Parse requires_python field into a SpecifierSet.
+
+        Args:
+            requires_python: The requires_python string from package metadata
+
+        Returns:
+            SpecifierSet object or None if parsing fails
+        """
+        if not requires_python or not requires_python.strip():
+            return None
+
+        try:
+            # Clean up the version specification
+            cleaned = requires_python.strip()
+            return SpecifierSet(cleaned)
+        except Exception as e:
+            logger.warning(f"Failed to parse requires_python '{requires_python}': {e}")
+            return None
+
+    def extract_python_versions_from_classifiers(self, classifiers: list[str]) -> set[str]:
+        """Extract Python version information from classifiers.
+
+        Args:
+            classifiers: List of classifier strings
+
+        Returns:
+            Set of Python version strings
+        """
+        versions = set()
+
+        for classifier in classifiers:
+            match = self.python_classifier_pattern.search(classifier)
+            if match:
+                version = match.group(1)
+                versions.add(version)
+
+        return versions
+
+    def extract_python_implementations(self, classifiers: list[str]) -> set[str]:
+        """Extract Python implementation information from classifiers.
+
+        Args:
+            classifiers: List of classifier strings
+
+        Returns:
+            Set of Python implementation names (CPython, PyPy, etc.)
+        """
+        implementations = set()
+
+        for classifier in classifiers:
+            match = self.implementation_pattern.search(classifier)
+            if match:
+                implementation = match.group(1)
+                implementations.add(implementation)
+
+        return implementations
+
+    def check_version_compatibility(
+        self,
+        target_version: str,
+        requires_python: str | None = None,
+        classifiers: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Check if a target Python version is compatible with package requirements.
+
+        Args:
+            target_version: Target Python version (e.g., "3.9", "3.10.5")
+            requires_python: The requires_python specification
+            classifiers: List of package classifiers
+
+        Returns:
+            Dictionary containing compatibility information
+        """
+        result = {
+            "target_version": target_version,
+            "is_compatible": False,
+            "compatibility_source": None,
+            "details": {},
+            "warnings": [],
+            "suggestions": []
+        }
+
+        try:
+            target_ver = Version(target_version)
+        except InvalidVersion as e:
+            result["warnings"].append(f"Invalid target version format: {e}")
+            return result
+
+        # Check requires_python first (more authoritative)
+        if requires_python:
+            spec_set = self.parse_requires_python(requires_python)
+            if spec_set:
+                is_compatible = target_ver in spec_set
+                result.update({
+                    "is_compatible": is_compatible,
+                    "compatibility_source": "requires_python",
+                    "details": {
+                        "requires_python": requires_python,
+                        "parsed_spec": str(spec_set),
+                        "check_result": is_compatible
+                    }
+                })
+
+                if not is_compatible:
+                    result["suggestions"].append(
+                        f"Package requires Python {requires_python}, "
+                        f"but target is {target_version}"
+                    )
+
+                return result
+
+        # Fall back to classifiers if no requires_python
+        if classifiers:
+            supported_versions = self.extract_python_versions_from_classifiers(classifiers)
+            implementations = self.extract_python_implementations(classifiers)
+
+            if supported_versions:
+                # Check if target version matches any supported version
+                target_major_minor = f"{target_ver.major}.{target_ver.minor}"
+                target_major = str(target_ver.major)
+
+                is_compatible = (
+                    target_version in supported_versions or
+                    target_major_minor in supported_versions or
+                    target_major in supported_versions
+                )
+
+                result.update({
+                    "is_compatible": is_compatible,
+                    "compatibility_source": "classifiers",
+                    "details": {
+                        "supported_versions": sorted(supported_versions),
+                        "implementations": sorted(implementations),
+                        "target_major_minor": target_major_minor,
+                        "check_result": is_compatible
+                    }
+                })
+
+                if not is_compatible:
+                    result["suggestions"].append(
+                        f"Package supports Python versions: {', '.join(sorted(supported_versions))}, "
+                        f"but target is {target_version}"
+                    )
+
+                return result
+
+        # No version information available
+        result["warnings"].append(
+            "No Python version requirements found in package metadata"
+        )
+        result["suggestions"].append(
+            "Consider checking package documentation for Python version compatibility"
+        )
+
+        return result
+
+    def get_compatible_versions(
+        self,
+        requires_python: str | None = None,
+        classifiers: list[str] | None = None,
+        available_pythons: list[str] | None = None
+    ) -> dict[str, Any]:
+        """Get list of compatible Python versions for a package.
+
+        Args:
+            requires_python: The requires_python specification
+            classifiers: List of package classifiers
+            available_pythons: List of Python versions to check against
+
+        Returns:
+            Dictionary containing compatible versions and recommendations
+        """
+        if available_pythons is None:
+            # Default Python versions to check
+            available_pythons = [
+                "3.7", "3.8", "3.9", "3.10", "3.11", "3.12", "3.13"
+            ]
+
+        compatible = []
+        incompatible = []
+
+        for python_version in available_pythons:
+            result = self.check_version_compatibility(
+                python_version, requires_python, classifiers
+            )
+
+            if result["is_compatible"]:
+                compatible.append({
+                    "version": python_version,
+                    "source": result["compatibility_source"]
+                })
+            else:
+                incompatible.append({
+                    "version": python_version,
+                    "reason": result["suggestions"][0] if result["suggestions"] else "Unknown"
+                })
+
+        return {
+            "compatible_versions": compatible,
+            "incompatible_versions": incompatible,
+            "total_checked": len(available_pythons),
+            "compatibility_rate": len(compatible) / len(available_pythons) if available_pythons else 0,
+            "recommendations": self._generate_recommendations(compatible, incompatible)
+        }
+
+    def _generate_recommendations(
+        self,
+        compatible: list[dict[str, Any]],
+        incompatible: list[dict[str, Any]]
+    ) -> list[str]:
+        """Generate recommendations based on compatibility results.
+
+        Args:
+            compatible: List of compatible versions
+            incompatible: List of incompatible versions
+
+        Returns:
+            List of recommendation strings
+        """
+        recommendations = []
+
+        if not compatible:
+            recommendations.append(
+                "⚠️  No compatible Python versions found. "
+                "Check package documentation for requirements."
+            )
+        elif len(compatible) == 1:
+            version = compatible[0]["version"]
+            recommendations.append(
+                f"📌 Only Python {version} is compatible with this package."
+            )
+        else:
+            versions = [v["version"] for v in compatible]
+            latest = max(versions, key=lambda x: tuple(map(int, x.split("."))))
+            recommendations.append(
+                f"✅ Compatible with Python {', '.join(versions)}. "
+                f"Recommended: Python {latest}"
+            )
+
+        if len(incompatible) > len(compatible):
+            recommendations.append(
+                "⚠️  This package has limited Python version support. "
+                "Consider using a more recent version of the package if available."
+            )
+
+        return recommendations

pypi_query_mcp/server.py

@@ -0,0 +1,295 @@
+"""FastMCP server for PyPI package queries."""
+
+import logging
+from typing import Any
+
+import click
+from fastmcp import FastMCP
+
+from .core.exceptions import InvalidPackageNameError, NetworkError, PackageNotFoundError
+from .tools import (
+    check_python_compatibility,
+    get_compatible_python_versions,
+    query_package_dependencies,
+    query_package_info,
+    query_package_versions,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+# Create FastMCP application
+app = FastMCP("PyPI Query MCP Server")
+
+
+@app.tool()
+async def get_package_info(package_name: str) -> dict[str, Any]:
+    """Query comprehensive information about a PyPI package.
+
+    This tool retrieves detailed information about a Python package from PyPI,
+    including metadata, description, author information, dependencies, and more.
+
+    Args:
+        package_name: The name of the PyPI package to query (e.g., 'requests', 'django')
+
+    Returns:
+        Dictionary containing comprehensive package information including:
+        - Basic metadata (name, version, summary, description)
+        - Author and maintainer information
+        - License and project URLs
+        - Python version requirements
+        - Dependencies and classifiers
+        - Version history summary
+
+    Raises:
+        InvalidPackageNameError: If package name is empty or invalid
+        PackageNotFoundError: If package is not found on PyPI
+        NetworkError: For network-related errors
+    """
+    try:
+        logger.info(f"MCP tool: Querying package info for {package_name}")
+        result = await query_package_info(package_name)
+        logger.info(f"Successfully retrieved info for package: {package_name}")
+        return result
+    except (InvalidPackageNameError, PackageNotFoundError, NetworkError) as e:
+        logger.error(f"Error querying package {package_name}: {e}")
+        return {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "package_name": package_name
+        }
+    except Exception as e:
+        logger.error(f"Unexpected error querying package {package_name}: {e}")
+        return {
+            "error": f"Unexpected error: {e}",
+            "error_type": "UnexpectedError",
+            "package_name": package_name
+        }
+
+
+@app.tool()
+async def get_package_versions(package_name: str) -> dict[str, Any]:
+    """Get version information for a PyPI package.
+
+    This tool retrieves comprehensive version information for a Python package,
+    including all available versions, release details, and distribution formats.
+
+    Args:
+        package_name: The name of the PyPI package to query (e.g., 'requests', 'numpy')
+
+    Returns:
+        Dictionary containing version information including:
+        - Latest version and total version count
+        - List of all available versions (sorted)
+        - Recent versions with release details
+        - Distribution format information (wheel, source)
+
+    Raises:
+        InvalidPackageNameError: If package name is empty or invalid
+        PackageNotFoundError: If package is not found on PyPI
+        NetworkError: For network-related errors
+    """
+    try:
+        logger.info(f"MCP tool: Querying versions for {package_name}")
+        result = await query_package_versions(package_name)
+        logger.info(f"Successfully retrieved versions for package: {package_name}")
+        return result
+    except (InvalidPackageNameError, PackageNotFoundError, NetworkError) as e:
+        logger.error(f"Error querying versions for {package_name}: {e}")
+        return {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "package_name": package_name
+        }
+    except Exception as e:
+        logger.error(f"Unexpected error querying versions for {package_name}: {e}")
+        return {
+            "error": f"Unexpected error: {e}",
+            "error_type": "UnexpectedError",
+            "package_name": package_name
+        }
+
+
+@app.tool()
+async def get_package_dependencies(package_name: str, version: str | None = None) -> dict[str, Any]:
+    """Get dependency information for a PyPI package.
+
+    This tool retrieves comprehensive dependency information for a Python package,
+    including runtime dependencies, development dependencies, and optional dependencies.
+
+    Args:
+        package_name: The name of the PyPI package to query (e.g., 'django', 'flask')
+        version: Specific version to query (optional, defaults to latest version)
+
+    Returns:
+        Dictionary containing dependency information including:
+        - Runtime dependencies and development dependencies
+        - Optional dependency groups
+        - Python version requirements
+        - Dependency counts and summary statistics
+
+    Raises:
+        InvalidPackageNameError: If package name is empty or invalid
+        PackageNotFoundError: If package is not found on PyPI
+        NetworkError: For network-related errors
+    """
+    try:
+        logger.info(f"MCP tool: Querying dependencies for {package_name}" +
+                   (f" version {version}" if version else " (latest)"))
+        result = await query_package_dependencies(package_name, version)
+        logger.info(f"Successfully retrieved dependencies for package: {package_name}")
+        return result
+    except (InvalidPackageNameError, PackageNotFoundError, NetworkError) as e:
+        logger.error(f"Error querying dependencies for {package_name}: {e}")
+        return {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "package_name": package_name,
+            "version": version
+        }
+    except Exception as e:
+        logger.error(f"Unexpected error querying dependencies for {package_name}: {e}")
+        return {
+            "error": f"Unexpected error: {e}",
+            "error_type": "UnexpectedError",
+            "package_name": package_name,
+            "version": version
+        }
+
+
+@app.tool()
+async def check_package_python_compatibility(
+    package_name: str,
+    target_python_version: str,
+    use_cache: bool = True
+) -> dict[str, Any]:
+    """Check if a package is compatible with a specific Python version.
+
+    This tool analyzes a package's Python version requirements and determines
+    if it's compatible with your target Python version.
+
+    Args:
+        package_name: The name of the PyPI package to check (e.g., 'django', 'requests')
+        target_python_version: Target Python version to check (e.g., '3.9', '3.10.5', '3.11')
+        use_cache: Whether to use cached package data (default: True)
+
+    Returns:
+        Dictionary containing detailed compatibility information including:
+        - Compatibility status (True/False)
+        - Source of compatibility information (requires_python or classifiers)
+        - Detailed analysis and suggestions
+        - Package version requirements
+
+    Raises:
+        InvalidPackageNameError: If package name is empty or invalid
+        PackageNotFoundError: If package is not found on PyPI
+        NetworkError: For network-related errors
+    """
+    try:
+        logger.info(f"MCP tool: Checking Python {target_python_version} compatibility for {package_name}")
+        result = await check_python_compatibility(package_name, target_python_version, use_cache)
+        logger.info(f"Compatibility check completed for {package_name}")
+        return result
+    except (InvalidPackageNameError, PackageNotFoundError, NetworkError) as e:
+        logger.error(f"Error checking compatibility for {package_name}: {e}")
+        return {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "package_name": package_name,
+            "target_python_version": target_python_version
+        }
+    except Exception as e:
+        logger.error(f"Unexpected error checking compatibility for {package_name}: {e}")
+        return {
+            "error": f"Unexpected error: {e}",
+            "error_type": "UnexpectedError",
+            "package_name": package_name,
+            "target_python_version": target_python_version
+        }
+
+
+@app.tool()
+async def get_package_compatible_python_versions(
+    package_name: str,
+    python_versions: list[str] | None = None,
+    use_cache: bool = True
+) -> dict[str, Any]:
+    """Get all Python versions compatible with a package.
+
+    This tool analyzes a package and returns which Python versions are
+    compatible with it, along with recommendations.
+
+    Args:
+        package_name: The name of the PyPI package to analyze (e.g., 'numpy', 'pandas')
+        python_versions: List of Python versions to check (optional, defaults to common versions)
+        use_cache: Whether to use cached package data (default: True)
+
+    Returns:
+        Dictionary containing compatibility information including:
+        - List of compatible Python versions
+        - List of incompatible versions with reasons
+        - Compatibility rate and recommendations
+        - Package version requirements
+
+    Raises:
+        InvalidPackageNameError: If package name is empty or invalid
+        PackageNotFoundError: If package is not found on PyPI
+        NetworkError: For network-related errors
+    """
+    try:
+        logger.info(f"MCP tool: Getting compatible Python versions for {package_name}")
+        result = await get_compatible_python_versions(package_name, python_versions, use_cache)
+        logger.info(f"Compatible versions analysis completed for {package_name}")
+        return result
+    except (InvalidPackageNameError, PackageNotFoundError, NetworkError) as e:
+        logger.error(f"Error getting compatible versions for {package_name}: {e}")
+        return {
+            "error": str(e),
+            "error_type": type(e).__name__,
+            "package_name": package_name
+        }
+    except Exception as e:
+        logger.error(f"Unexpected error getting compatible versions for {package_name}: {e}")
+        return {
+            "error": f"Unexpected error: {e}",
+            "error_type": "UnexpectedError",
+            "package_name": package_name
+        }
+
+
+@click.command()
+@click.option(
+    "--host",
+    default="localhost",
+    help="Host to bind the server to"
+)
+@click.option(
+    "--port",
+    default=8000,
+    type=int,
+    help="Port to bind the server to"
+)
+@click.option(
+    "--log-level",
+    default="INFO",
+    type=click.Choice(["DEBUG", "INFO", "WARNING", "ERROR"]),
+    help="Logging level"
+)
+def main(host: str, port: int, log_level: str) -> None:
+    """Start the PyPI Query MCP Server."""
+    # Set logging level
+    logging.getLogger().setLevel(getattr(logging, log_level))
+
+    logger.info(f"Starting PyPI Query MCP Server on {host}:{port}")
+    logger.info(f"Log level set to: {log_level}")
+
+    # Run the FastMCP server
+    app.run(host=host, port=port)
+
+
+if __name__ == "__main__":
+    main()

pypi_query_mcp/tools/__init__.py

@@ -0,0 +1,25 @@
+"""MCP tools for PyPI package queries.
+
+This package contains the FastMCP tool implementations that provide
+the user-facing interface for PyPI package operations.
+"""
+
+from .compatibility_check import (
+    check_python_compatibility,
+    get_compatible_python_versions,
+    suggest_python_version_for_packages,
+)
+from .package_query import (
+    query_package_dependencies,
+    query_package_info,
+    query_package_versions,
+)
+
+__all__ = [
+    "query_package_info",
+    "query_package_versions",
+    "query_package_dependencies",
+    "check_python_compatibility",
+    "get_compatible_python_versions",
+    "suggest_python_version_for_packages",
+]

pypi_query_mcp/tools/compatibility_check.py

@@ -0,0 +1,260 @@
+"""Python version compatibility checking tools for PyPI MCP server."""
+
+import logging
+from typing import Any
+
+from ..core import (
+    InvalidPackageNameError,
+    NetworkError,
+    PyPIClient,
+    PyPIError,
+)
+from ..core.version_utils import VersionCompatibility
+
+logger = logging.getLogger(__name__)
+
+
+async def check_python_compatibility(
+    package_name: str,
+    target_python_version: str,
+    use_cache: bool = True
+) -> dict[str, Any]:
+    """Check if a package is compatible with a specific Python version.
+
+    Args:
+        package_name: Name of the package to check
+        target_python_version: Target Python version (e.g., "3.9", "3.10.5")
+        use_cache: Whether to use cached package data
+
+    Returns:
+        Dictionary containing compatibility information
+
+    Raises:
+        InvalidPackageNameError: If package name is invalid
+        PackageNotFoundError: If package is not found
+        NetworkError: For network-related errors
+    """
+    if not package_name or not package_name.strip():
+        raise InvalidPackageNameError(package_name)
+
+    if not target_python_version or not target_python_version.strip():
+        raise ValueError("Target Python version cannot be empty")
+
+    logger.info(f"Checking Python {target_python_version} compatibility for package: {package_name}")
+
+    try:
+        async with PyPIClient() as client:
+            package_data = await client.get_package_info(package_name, use_cache)
+
+            info = package_data.get("info", {})
+            requires_python = info.get("requires_python")
+            classifiers = info.get("classifiers", [])
+
+            # Perform compatibility check
+            compat_checker = VersionCompatibility()
+            result = compat_checker.check_version_compatibility(
+                target_python_version,
+                requires_python,
+                classifiers
+            )
+
+            # Add package information to result
+            result.update({
+                "package_name": info.get("name", package_name),
+                "package_version": info.get("version", ""),
+                "requires_python": requires_python,
+                "supported_implementations": compat_checker.extract_python_implementations(classifiers),
+                "classifier_versions": sorted(compat_checker.extract_python_versions_from_classifiers(classifiers))
+            })
+
+            return result
+
+    except PyPIError:
+        # Re-raise PyPI-specific errors
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error checking compatibility for {package_name}: {e}")
+        raise NetworkError(f"Failed to check Python compatibility: {e}", e) from e
+
+
+async def get_compatible_python_versions(
+    package_name: str,
+    python_versions: list[str] | None = None,
+    use_cache: bool = True
+) -> dict[str, Any]:
+    """Get list of Python versions compatible with a package.
+
+    Args:
+        package_name: Name of the package to check
+        python_versions: List of Python versions to check (optional)
+        use_cache: Whether to use cached package data
+
+    Returns:
+        Dictionary containing compatibility information for multiple versions
+
+    Raises:
+        InvalidPackageNameError: If package name is invalid
+        PackageNotFoundError: If package is not found
+        NetworkError: For network-related errors
+    """
+    if not package_name or not package_name.strip():
+        raise InvalidPackageNameError(package_name)
+
+    logger.info(f"Getting compatible Python versions for package: {package_name}")
+
+    try:
+        async with PyPIClient() as client:
+            package_data = await client.get_package_info(package_name, use_cache)
+
+            info = package_data.get("info", {})
+            requires_python = info.get("requires_python")
+            classifiers = info.get("classifiers", [])
+
+            # Get compatibility information
+            compat_checker = VersionCompatibility()
+            result = compat_checker.get_compatible_versions(
+                requires_python,
+                classifiers,
+                python_versions
+            )
+
+            # Add package information to result
+            result.update({
+                "package_name": info.get("name", package_name),
+                "package_version": info.get("version", ""),
+                "requires_python": requires_python,
+                "supported_implementations": sorted(compat_checker.extract_python_implementations(classifiers)),
+                "classifier_versions": sorted(compat_checker.extract_python_versions_from_classifiers(classifiers))
+            })
+
+            return result
+
+    except PyPIError:
+        # Re-raise PyPI-specific errors
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error getting compatible versions for {package_name}: {e}")
+        raise NetworkError(f"Failed to get compatible Python versions: {e}", e) from e
+
+
+async def suggest_python_version_for_packages(
+    package_names: list[str],
+    use_cache: bool = True
+) -> dict[str, Any]:
+    """Suggest optimal Python version for a list of packages.
+
+    Args:
+        package_names: List of package names to analyze
+        use_cache: Whether to use cached package data
+
+    Returns:
+        Dictionary containing version suggestions and compatibility matrix
+
+    Raises:
+        ValueError: If package_names is empty
+        NetworkError: For network-related errors
+    """
+    if not package_names:
+        raise ValueError("Package names list cannot be empty")
+
+    logger.info(f"Analyzing Python version compatibility for {len(package_names)} packages")
+
+    # Default Python versions to analyze
+    python_versions = ["3.7", "3.8", "3.9", "3.10", "3.11", "3.12"]
+
+    compatibility_matrix = {}
+    package_details = {}
+    errors = {}
+
+    async with PyPIClient() as client:
+        for package_name in package_names:
+            try:
+                package_data = await client.get_package_info(package_name, use_cache)
+                info = package_data.get("info", {})
+
+                requires_python = info.get("requires_python")
+                classifiers = info.get("classifiers", [])
+
+                compat_checker = VersionCompatibility()
+                compat_result = compat_checker.get_compatible_versions(
+                    requires_python,
+                    classifiers,
+                    python_versions
+                )
+
+                # Store compatibility for this package
+                compatible_versions = [v["version"] for v in compat_result["compatible_versions"]]
+                compatibility_matrix[package_name] = compatible_versions
+
+                package_details[package_name] = {
+                    "version": info.get("version", ""),
+                    "requires_python": requires_python,
+                    "compatible_versions": compatible_versions,
+                    "compatibility_rate": compat_result["compatibility_rate"]
+                }
+
+            except Exception as e:
+                logger.warning(f"Failed to analyze package {package_name}: {e}")
+                errors[package_name] = str(e)
+                compatibility_matrix[package_name] = []
+
+    # Find common compatible versions
+    if compatibility_matrix:
+        all_versions = set(python_versions)
+        common_versions = all_versions.copy()
+
+        for _package_name, compatible in compatibility_matrix.items():
+            if compatible:  # Only consider packages with known compatibility
+                common_versions &= set(compatible)
+    else:
+        common_versions = set()
+
+    # Generate recommendations
+    recommendations = []
+    if common_versions:
+        latest_common = max(common_versions, key=lambda x: tuple(map(int, x.split("."))))
+        recommendations.append(
+            f"✅ Recommended Python version: {latest_common} "
+            f"(compatible with all {len([p for p in compatibility_matrix if compatibility_matrix[p]])} packages)"
+        )
+
+        if len(common_versions) > 1:
+            all_common = sorted(common_versions, key=lambda x: tuple(map(int, x.split("."))))
+            recommendations.append(
+                f"📋 All compatible versions: {', '.join(all_common)}"
+            )
+    else:
+        recommendations.append(
+            "⚠️  No Python version is compatible with all packages. "
+            "Consider updating packages or using different versions."
+        )
+
+        # Find the version compatible with most packages
+        version_scores = {}
+        for version in python_versions:
+            score = sum(1 for compatible in compatibility_matrix.values() if version in compatible)
+            version_scores[version] = score
+
+        if version_scores:
+            best_version = max(version_scores, key=version_scores.get)
+            best_score = version_scores[best_version]
+            total_packages = len([p for p in compatibility_matrix if compatibility_matrix[p]])
+
+            if best_score > 0:
+                recommendations.append(
+                    f"📊 Best compromise: Python {best_version} "
+                    f"(compatible with {best_score}/{total_packages} packages)"
+                )
+
+    return {
+        "analyzed_packages": len(package_names),
+        "successful_analyses": len(package_details),
+        "failed_analyses": len(errors),
+        "common_compatible_versions": sorted(common_versions),
+        "recommended_version": max(common_versions, key=lambda x: tuple(map(int, x.split(".")))) if common_versions else None,
+        "compatibility_matrix": compatibility_matrix,
+        "package_details": package_details,
+        "errors": errors,
+        "recommendations": recommendations,
+        "python_versions_analyzed": python_versions
+    }

pypi_query_mcp/tools/package_query.py

@@ -0,0 +1,253 @@
+"""Package query tools for PyPI MCP server."""
+
+import logging
+from typing import Any
+
+from ..core import (
+    InvalidPackageNameError,
+    NetworkError,
+    PyPIClient,
+    PyPIError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def format_package_info(package_data: dict[str, Any]) -> dict[str, Any]:
+    """Format package information for MCP response.
+
+    Args:
+        package_data: Raw package data from PyPI API
+
+    Returns:
+        Formatted package information
+    """
+    info = package_data.get("info", {})
+
+    # Extract basic information
+    formatted = {
+        "name": info.get("name", ""),
+        "version": info.get("version", ""),
+        "summary": info.get("summary", ""),
+        "description": info.get("description", "")[:500] + "..." if len(info.get("description", "")) > 500 else info.get("description", ""),
+        "author": info.get("author", ""),
+        "author_email": info.get("author_email", ""),
+        "maintainer": info.get("maintainer", ""),
+        "maintainer_email": info.get("maintainer_email", ""),
+        "license": info.get("license", ""),
+        "home_page": info.get("home_page", ""),
+        "project_url": info.get("project_url", ""),
+        "download_url": info.get("download_url", ""),
+        "requires_python": info.get("requires_python", ""),
+        "platform": info.get("platform", ""),
+        "keywords": info.get("keywords", ""),
+        "classifiers": info.get("classifiers", []),
+        "requires_dist": info.get("requires_dist", []),
+        "project_urls": info.get("project_urls", {}),
+    }
+
+    # Add release information
+    releases = package_data.get("releases", {})
+    formatted["total_versions"] = len(releases)
+    formatted["available_versions"] = list(releases.keys())[-10:]  # Last 10 versions
+
+    # Add download statistics if available
+    if "urls" in package_data:
+        urls = package_data["urls"]
+        if urls:
+            formatted["download_info"] = {
+                "files_count": len(urls),
+                "file_types": list({url.get("packagetype", "") for url in urls}),
+                "python_versions": list({url.get("python_version", "") for url in urls if url.get("python_version")}),
+            }
+
+    return formatted
+
+
+def format_version_info(package_data: dict[str, Any]) -> dict[str, Any]:
+    """Format version information for MCP response.
+
+    Args:
+        package_data: Raw package data from PyPI API
+
+    Returns:
+        Formatted version information
+    """
+    info = package_data.get("info", {})
+    releases = package_data.get("releases", {})
+
+    # Sort versions (basic sorting, could be improved with proper version parsing)
+    sorted_versions = sorted(releases.keys(), reverse=True)
+
+    return {
+        "package_name": info.get("name", ""),
+        "latest_version": info.get("version", ""),
+        "total_versions": len(releases),
+        "versions": sorted_versions,
+        "recent_versions": sorted_versions[:20],  # Last 20 versions
+        "version_details": {
+            version: {
+                "release_count": len(releases[version]),
+                "has_wheel": any(file.get("packagetype") == "bdist_wheel" for file in releases[version]),
+                "has_source": any(file.get("packagetype") == "sdist" for file in releases[version]),
+            }
+            for version in sorted_versions[:10]  # Details for last 10 versions
+        }
+    }
+
+
+def format_dependency_info(package_data: dict[str, Any]) -> dict[str, Any]:
+    """Format dependency information for MCP response.
+
+    Args:
+        package_data: Raw package data from PyPI API
+
+    Returns:
+        Formatted dependency information
+    """
+    info = package_data.get("info", {})
+    requires_dist = info.get("requires_dist", []) or []
+
+    # Parse dependencies
+    runtime_deps = []
+    dev_deps = []
+    optional_deps = {}
+
+    for dep in requires_dist:
+        if not dep:
+            continue
+
+        # Basic parsing - could be improved with proper dependency parsing
+        if "extra ==" in dep:
+            # Optional dependency
+            parts = dep.split(";")
+            dep_name = parts[0].strip()
+            extra_part = parts[1] if len(parts) > 1 else ""
+
+            if "extra ==" in extra_part:
+                extra_name = extra_part.split("extra ==")[1].strip().strip('"\'')
+                if extra_name not in optional_deps:
+                    optional_deps[extra_name] = []
+                optional_deps[extra_name].append(dep_name)
+        elif "dev" in dep.lower() or "test" in dep.lower():
+            dev_deps.append(dep)
+        else:
+            runtime_deps.append(dep)
+
+    return {
+        "package_name": info.get("name", ""),
+        "version": info.get("version", ""),
+        "requires_python": info.get("requires_python", ""),
+        "runtime_dependencies": runtime_deps,
+        "development_dependencies": dev_deps,
+        "optional_dependencies": optional_deps,
+        "total_dependencies": len(requires_dist),
+        "dependency_summary": {
+            "runtime_count": len(runtime_deps),
+            "dev_count": len(dev_deps),
+            "optional_groups": len(optional_deps),
+            "total_optional": sum(len(deps) for deps in optional_deps.values()),
+        }
+    }
+
+
+async def query_package_info(package_name: str) -> dict[str, Any]:
+    """Query comprehensive package information from PyPI.
+
+    Args:
+        package_name: Name of the package to query
+
+    Returns:
+        Formatted package information
+
+    Raises:
+        InvalidPackageNameError: If package name is invalid
+        PackageNotFoundError: If package is not found
+        NetworkError: For network-related errors
+    """
+    if not package_name or not package_name.strip():
+        raise InvalidPackageNameError(package_name)
+
+    logger.info(f"Querying package info for: {package_name}")
+
+    try:
+        async with PyPIClient() as client:
+            package_data = await client.get_package_info(package_name)
+            return format_package_info(package_data)
+    except PyPIError:
+        # Re-raise PyPI-specific errors
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error querying package {package_name}: {e}")
+        raise NetworkError(f"Failed to query package information: {e}", e) from e
+
+
+async def query_package_versions(package_name: str) -> dict[str, Any]:
+    """Query package version information from PyPI.
+
+    Args:
+        package_name: Name of the package to query
+
+    Returns:
+        Formatted version information
+
+    Raises:
+        InvalidPackageNameError: If package name is invalid
+        PackageNotFoundError: If package is not found
+        NetworkError: For network-related errors
+    """
+    if not package_name or not package_name.strip():
+        raise InvalidPackageNameError(package_name)
+
+    logger.info(f"Querying versions for package: {package_name}")
+
+    try:
+        async with PyPIClient() as client:
+            package_data = await client.get_package_info(package_name)
+            return format_version_info(package_data)
+    except PyPIError:
+        # Re-raise PyPI-specific errors
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error querying versions for {package_name}: {e}")
+        raise NetworkError(f"Failed to query package versions: {e}", e) from e
+
+
+async def query_package_dependencies(package_name: str, version: str | None = None) -> dict[str, Any]:
+    """Query package dependency information from PyPI.
+
+    Args:
+        package_name: Name of the package to query
+        version: Specific version to query (optional, defaults to latest)
+
+    Returns:
+        Formatted dependency information
+
+    Raises:
+        InvalidPackageNameError: If package name is invalid
+        PackageNotFoundError: If package is not found
+        NetworkError: For network-related errors
+    """
+    if not package_name or not package_name.strip():
+        raise InvalidPackageNameError(package_name)
+
+    logger.info(f"Querying dependencies for package: {package_name}" +
+                (f" version {version}" if version else " (latest)"))
+
+    try:
+        async with PyPIClient() as client:
+            package_data = await client.get_package_info(package_name)
+
+            # TODO: In future, support querying specific version dependencies
+            # For now, we return dependencies for the latest version
+            if version and version != package_data.get("info", {}).get("version"):
+                logger.warning(f"Specific version {version} requested but not implemented yet. "
+                             f"Returning dependencies for latest version.")
+
+            return format_dependency_info(package_data)
+    except PyPIError:
+        # Re-raise PyPI-specific errors
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error querying dependencies for {package_name}: {e}")
+        raise NetworkError(f"Failed to query package dependencies: {e}", e) from e