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

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

.github/workflows/build-exe.yml

@@ -1,60 +0,0 @@
-name: Build Executable
-
-on:
-  workflow_run:
-    workflows: ["Python Package"]
-    types:
-      - completed
-    branches:
-      - "main"
-
-jobs:
-  build:
-    # Only run if the python-publish workflow succeeded
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
-    strategy:
-      fail-fast: false
-      matrix:
-        target:
-          - os: windows-2022
-            triple: x86_64-pc-windows-msvc
-          - os: ubuntu-22.04
-            triple: x86_64-unknown-linux-gnu
-          - os: macos-12
-            triple: x86_64-apple-darwin
-    runs-on: ${{ matrix.target.os }}
-    permissions:
-      contents: write
-    
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        fetch-depth: 0
-        
-    - uses: olegtarasov/get-tag@v2.1.4
-      id: get_tag_name
-      with:
-        tagRegex: "v(?<version>.*)"
-        
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: "3.10"
-        cache: pip
-        
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install nox
-
-    - name: Build exe
-      run: |
-        nox -s build-exe -- --release --version ${{ steps.get_tag_name.outputs.version }}
-
-    - uses: ncipollo/release-action@v1
-      with:
-        allowUpdates: true
-        updateOnlyUnreleased: false
-        omitBody: true
-        artifacts: ".zip/*.zip"
-        token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}

.github/workflows/bumpversion.yml

@@ -1,23 +0,0 @@
-name: Bump version
-
-on:
-  push:
-    branches:
-      - main
-
-jobs:
-  bump-version:
-    if: "!startsWith(github.event.head_commit.message, 'bump:')"
-    runs-on: ubuntu-latest
-    name: "Bump version and create changelog with commitizen"
-    steps:
-      - name: Check out
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-        with:
-          fetch-depth: 0
-          token: '${{ secrets.PERSONAL_ACCESS_TOKEN }}'
-      - name: Create bump and changelog
-        uses: commitizen-tools/commitizen-action@master
-        with:
-          github_token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-          branch: main

.github/workflows/codecov.yml

@@ -1,34 +0,0 @@
-name: Codecov
-on: [push, pull_request]
-jobs:
-  run:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Get repository name
-        id: repo-name
-        uses: MariachiBear/get-repo-name-action@v1.3.0
-        with:
-          with-owner: 'true'
-          string-case: 'uppercase'
-      - name: Set up Python 3.10
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.10'
-      - name: Install dependencies
-        run: |
-          python -m pip install -r requirements-dev.txt
-          poetry --version
-      - name: Run tests and collect coverage
-        run: |
-          nox -s pytest
-      - name: Upload coverage reports to Codecov
-        uses: codecov/codecov-action@v5
-        with:
-          slug: loonghao/${{ steps.repo-name.outputs.repository-name }}
-          files: 'coverage.xml'
-        env:
-          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/issue-translator.yml

@@ -1,18 +0,0 @@
-name: 'issue-translator'
-on:
-  issue_comment:
-    types: [created]
-  issues:
-    types: [opened]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: usthe/issues-translate-action@v2.7
-        with:
-          IS_MODIFY_TITLE: false
-          # not require, default false, . Decide whether to modify the issue title
-          # if true, the robot account @Issues-translate-bot must have modification permissions, invite @Issues-translate-bot to your project or use your custom bot.
-          CUSTOM_BOT_NOTE: Bot detected the issue body's language is not English, translate it automatically. 👯👭🏻🧑‍🤝‍🧑👫🧑🏿‍🤝‍🧑🏻👩🏾‍🤝‍👨🏿👬🏿
-          # not require. Customize the translation robot prefix message.

.github/workflows/mr-test.yml

@@ -1,35 +0,0 @@
-name: MR Checks
-on: [ pull_request ]
-
-jobs:
-  python-check:
-    strategy:
-      max-parallel: 3
-      matrix:
-        target:
-          - os: 'ubuntu-22.04'
-            triple: 'x86_64-unknown-linux-gnu'
-          - os: 'macos-12'
-            triple: 'x86_64-apple-darwin'
-          - os: 'windows-2022'
-            triple: 'x86_64-pc-windows-msvc'
-        python-version: ["3.10"]
-      fail-fast: false
-    runs-on: ${{ matrix.target.os }}
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-      - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install dependencies
-        run: |
-          python -m pip install -r requirements-dev.txt
-          poetry --version
-      - name: lint
-        run: |
-          nox -s lint
-      - name: test build
-        run: |
-          nox -s build-exe -- --test

.github/workflows/python-publish.yml

@@ -1,66 +0,0 @@
-name: Upload Python Package
-
-on:
-  push:
-    tags:
-      - "v*"
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    permissions:
-      # IMPORTANT: this permission is mandatory for trusted publishing
-      id-token: write
-      contents: write
-
-    steps:
-    - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4
-      with:
-        token: "${{ secrets.GITHUB_TOKEN }}"
-        fetch-depth: 0
-        ref: main
-    - uses: olegtarasov/get-tag@v2.1.4
-      id: get_tag_name
-      with:
-        tagRegex: "v(?<version>.*)"
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install -r requirements-dev.txt
-        poetry --version
-        poetry build
-    # Note that we don't need credentials.
-    # We rely on https://docs.pypi.org/trusted-publishers/.
-    - name: Upload to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        packages-dir: dist
-    - name: Generate changelog
-      id: changelog
-      uses: jaywcjlove/changelog-generator@main
-      with:
-        token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-        filter-author: (|dependabot|renovate\\[bot\\]|dependabot\\[bot\\]|Renovate Bot)
-        filter: '[R|r]elease[d]\s+[v|V]\d(\.\d+){0,2}'
-        template: |
-          ## Bugs
-          {{fix}}
-          ## Feature
-          {{feat}}
-          ## Improve
-          {{refactor,perf,clean}}
-          ## Misc
-          {{chore,style,ci||🔶 Nothing change}}
-          ## Unknown
-          {{__unknown__}}
-    - uses: ncipollo/release-action@v1
-      with:
-        artifacts: "dist/*"
-        token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
-        body: |
-          Comparing Changes: ${{ steps.changelog.outputs.compareurl }}
-
-          ${{ steps.changelog.outputs.changelog }}

.github/workflows/release.yml

@@ -0,0 +1,102 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    uses: ./.github/workflows/test.yml
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    
+    - name: Install uv
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+    
+    - name: Install dependencies
+      run: |
+        uvx poetry install
+    
+    - name: Build package
+      run: |
+        uvx poetry build
+    
+    - name: Check package
+      run: |
+        uvx poetry run twine check dist/*
+    
+    - name: Upload build artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+    - name: Download build artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+    
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Generate changelog
+      id: changelog
+      run: |
+        # Extract version from tag
+        VERSION=${GITHUB_REF#refs/tags/v}
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        
+        # Generate changelog (basic implementation)
+        echo "## Changes in v$VERSION" > CHANGELOG.md
+        echo "" >> CHANGELOG.md
+        git log --pretty=format:"- %s" $(git describe --tags --abbrev=0 HEAD^)..HEAD >> CHANGELOG.md || echo "- Initial release" >> CHANGELOG.md
+    
+    - name: Create GitHub Release
+      uses: actions/create-release@v1
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      with:
+        tag_name: ${{ github.ref }}
+        release_name: Release v${{ steps.changelog.outputs.version }}
+        body_path: CHANGELOG.md
+        draft: false
+        prerelease: false

.github/workflows/test.yml

@@ -0,0 +1,104 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    strategy:
+      max-parallel: 6
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12"]
+      fail-fast: false
+    
+    runs-on: ${{ matrix.os }}
+    
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+        cache: 'pip'
+        cache-dependency-path: '**/pyproject.toml'
+    
+    # Cache Poetry dependencies
+    - name: Cache Poetry dependencies
+      uses: actions/cache@v4
+      with:
+        path: ~/.cache/pypoetry
+        key: ${{ runner.os }}-poetry-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+        restore-keys: |
+          ${{ runner.os }}-poetry-${{ matrix.python-version }}-
+    
+    # Cache nox environments
+    - name: Cache nox environments
+      uses: actions/cache@v4
+      with:
+        path: .nox
+        key: ${{ runner.os }}-nox-${{ matrix.python-version }}-${{ hashFiles('**/noxfile.py') }}
+        restore-keys: |
+          ${{ runner.os }}-nox-${{ matrix.python-version }}-
+    
+    - name: Install uv
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+        uv --version
+    
+    - name: Install dependencies
+      run: |
+        uvx poetry install
+    
+    - name: Lint with ruff
+      run: |
+        uvx nox -s lint
+    
+    - name: Type check with mypy
+      run: |
+        uvx nox -s mypy
+    
+    - name: Run tests
+      run: |
+        uvx nox -s pytest
+    
+    - name: Upload coverage to Codecov
+      if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+
+  security:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+    
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+    
+    - name: Install uv
+      run: |
+        python -m pip install --upgrade pip
+        pip install uv
+    
+    - name: Install dependencies
+      run: |
+        uvx poetry install
+    
+    - name: Run security checks
+      run: |
+        uvx nox -s safety

.gitignore

@@ -20,3 +20,5 @@ target/*
 /build/
 /coverage.xml
 /.zip/
+.env
+

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ default_language_version:
   python: python3.10
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.5.0
     hooks:
       - id: no-commit-to-branch # prevent direct commits to main branch
       - id: check-yaml
@@ -10,3 +10,26 @@ repos:
       - id: check-toml
       - id: end-of-file-fixer
       - id: trailing-whitespace
+      - id: check-added-large-files
+      - id: check-merge-conflict
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.8
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+        args: ["--profile", "black"]
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-requests]
+        args: [--ignore-missing-imports]

README.md

@@ -1,2 +1,82 @@
-# repo-template
+# PyPI Query MCP Server
-This is a boilerplate git repository for creating new project
+
+A Model Context Protocol (MCP) server for querying PyPI package information, dependencies, and compatibility checking.
+
+## Features
+
+- 📦 Query PyPI package information (name, version, description, dependencies)
+- 🐍 Python version compatibility checking
+- 🔍 Dependency analysis and resolution
+- 🏢 Private PyPI repository support
+- ⚡ Fast async operations with caching
+- 🛠️ Easy integration with MCP clients
+
+## Quick Start
+
+### Installation
+
+```bash
+# Install from PyPI (coming soon)
+pip install pypi-query-mcp-server
+
+# Or install from source
+git clone https://github.com/loonghao/pypi-query-mcp-server.git
+cd pypi-query-mcp-server
+poetry install
+```
+
+### Usage
+
+```bash
+# Start the MCP server
+pypi-query-mcp
+
+# Or run directly with Python
+python -m pypi_query_mcp.server
+```
+
+### Available MCP Tools
+
+The server provides the following MCP tools:
+
+1. **get_package_info** - Get comprehensive package information
+2. **get_package_versions** - List all available versions for a package
+3. **get_package_dependencies** - Analyze package dependencies
+4. **check_package_python_compatibility** - Check Python version compatibility
+5. **get_package_compatible_python_versions** - Get all compatible Python versions
+
+### Example Usage with MCP Client
+
+```python
+# Example: Check if Django is compatible with Python 3.9
+result = await mcp_client.call_tool("check_package_python_compatibility", {
+    "package_name": "django",
+    "target_python_version": "3.9"
+})
+
+# Example: Get package information
+info = await mcp_client.call_tool("get_package_info", {
+    "package_name": "requests"
+})
+```
+
+## Development Status
+
+🎉 **Core functionality implemented and ready for use!**
+
+Current implementation status:
+- ✅ Basic project structure
+- ✅ PyPI API client with caching
+- ✅ MCP tools implementation (package info, versions, dependencies)
+- ✅ Python version compatibility checking
+- ✅ CI/CD pipeline with multi-platform testing
+- ⏳ Private repository support (planned)
+- ⏳ Advanced dependency analysis (planned)
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

nox_actions/codetest.py

@@ -8,10 +8,26 @@ from nox_actions.utils import THIS_ROOT
 
 
 def pytest(session: nox.Session) -> None:
+    """Run pytest with coverage reporting."""
     session.install(".")
-    session.install("pytest", "pytest_cov", "pytest_mock")
+    session.install("pytest", "pytest-cov", "pytest-mock", "pytest-asyncio")
     test_root = os.path.join(THIS_ROOT, "tests")
     session.run("pytest", f"--cov={PACKAGE_NAME}",
                 "--cov-report=xml:coverage.xml",
+                "--cov-report=term-missing",
                 f"--rootdir={test_root}",
                 env={"PYTHONPATH": THIS_ROOT.as_posix()})
+
+
+def mypy(session: nox.Session) -> None:
+    """Run mypy type checking."""
+    session.install(".")
+    session.install("mypy", "types-requests")
+    session.run("mypy", PACKAGE_NAME, "--ignore-missing-imports")
+
+
+def safety(session: nox.Session) -> None:
+    """Run safety security checks."""
+    session.install(".")
+    session.install("safety")
+    session.run("safety", "check", "--json")

nox_actions/release.py

@@ -10,6 +10,13 @@ from nox_actions.utils import PACKAGE_NAME
 from nox_actions.utils import THIS_ROOT
 
 
+def build(session: nox.Session) -> None:
+    """Build Python package distributions."""
+    session.install("build", "twine")
+    session.run("python", "-m", "build")
+    session.run("twine", "check", "dist/*")
+
+
 @nox.session(name="build-exe", reuse_venv=True)
 def build_exe(session: nox.Session) -> None:
     parser = argparse.ArgumentParser(prog="nox -s build-exe --release")

nox_actions/utils.py

@@ -2,7 +2,7 @@
 from pathlib import Path
 
 
-PACKAGE_NAME = ""
+PACKAGE_NAME = "pypi_query_mcp"
 THIS_ROOT = Path(__file__).parent.parent
 PROJECT_ROOT = THIS_ROOT.parent
 

noxfile.py

@@ -8,7 +8,7 @@ import nox
 
 ROOT = os.path.dirname(__file__)
 
-# Ensure maya_umbrella is importable.
+# Ensure pypi_query_mcp is importable.
 if ROOT not in sys.path:
     sys.path.append(ROOT)
 
@@ -18,7 +18,10 @@ from nox_actions import lint  # noqa: E402
 from nox_actions import release  # noqa: E402
 
 
+# Configure nox sessions
 nox.session(lint.lint, name="lint")
 nox.session(lint.lint_fix, name="lint-fix")
 nox.session(codetest.pytest, name="pytest")
-nox.session(release.build_exe, name="build-exe")
+nox.session(codetest.mypy, name="mypy")
+nox.session(codetest.safety, name="safety")
+nox.session(release.build, name="build")

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

pyproject.toml

@@ -0,0 +1,102 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "pypi-query-mcp-server"
+version = "0.1.0"
+description = "A Model Context Protocol (MCP) server for querying PyPI package information, dependencies, and compatibility"
+authors = ["Hal <hal.long@outlook.com>"]
+readme = "README.md"
+license = "MIT"
+homepage = "https://github.com/loonghao/pypi-query-mcp-server"
+repository = "https://github.com/loonghao/pypi-query-mcp-server"
+documentation = "https://github.com/loonghao/pypi-query-mcp-server"
+keywords = ["mcp", "pypi", "package", "dependency", "python"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: System :: Software Distribution",
+]
+packages = [{include = "pypi_query_mcp"}]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+fastmcp = "^0.2.0"
+httpx = "^0.27.0"
+packaging = "^24.0"
+pydantic = "^2.0.0"
+click = "^8.1.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-asyncio = "^0.23.0"
+pytest-cov = "^4.0.0"
+pytest-mock = "^3.12.0"
+ruff = "^0.1.0"
+mypy = "^1.8.0"
+pre-commit = "^3.6.0"
+nox = "^2024.3.2"
+
+[tool.poetry.scripts]
+pypi-query-mcp = "pypi_query_mcp.server:main"
+
+[tool.ruff]
+target-version = "py310"
+line-length = 88
+select = [
+    "E",  # pycodestyle errors
+    "W",  # pycodestyle warnings
+    "F",  # pyflakes
+    "I",  # isort
+    "B",  # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "UP", # pyupgrade
+]
+ignore = [
+    "E501",  # line too long, handled by black
+    "B008",  # do not perform function calls in argument defaults
+    "C901",  # too complex
+]
+
+[tool.ruff.per-file-ignores]
+"__init__.py" = ["F401"]
+
+[tool.mypy]
+python_version = "3.10"
+check_untyped_defs = true
+disallow_any_generics = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+no_implicit_optional = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra -q --strict-markers --strict-config"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.coverage.run]
+source = ["pypi_query_mcp"]
+omit = ["tests/*"]
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "if self.debug:",
+    "if settings.DEBUG",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "if 0:",
+    "if __name__ == .__main__.:",
+]

requirements-dev.txt

@@ -1,3 +0,0 @@
-poetry
-nox
-pytest

tests/__init__.py

@@ -0,0 +1 @@
+"""Test package for PyPI Query MCP Server."""

tests/conftest.py

@@ -0,0 +1,63 @@
+"""Pytest configuration and fixtures."""
+
+import pytest
+
+
+@pytest.fixture
+def sample_package_data():
+    """Sample package data for testing."""
+    return {
+        "info": {
+            "name": "test-package",
+            "version": "1.0.0",
+            "summary": "A test package",
+            "description": "This is a test package for testing purposes.",
+            "author": "Test Author",
+            "author_email": "test@example.com",
+            "license": "MIT",
+            "requires_python": ">=3.8",
+            "requires_dist": [
+                "requests>=2.25.0",
+                "click>=8.0.0",
+                "pytest>=6.0.0; extra == 'test'"
+            ],
+            "classifiers": [
+                "Development Status :: 4 - Beta",
+                "Intended Audience :: Developers",
+                "License :: OSI Approved :: MIT License",
+                "Programming Language :: Python :: 3",
+                "Programming Language :: Python :: 3.8",
+                "Programming Language :: Python :: 3.9",
+                "Programming Language :: Python :: 3.10",
+                "Programming Language :: Python :: 3.11",
+                "Programming Language :: Python :: Implementation :: CPython"
+            ]
+        },
+        "releases": {
+            "1.0.0": [
+                {
+                    "filename": "test_package-1.0.0-py3-none-any.whl",
+                    "packagetype": "bdist_wheel",
+                    "python_version": "py3"
+                },
+                {
+                    "filename": "test-package-1.0.0.tar.gz",
+                    "packagetype": "sdist",
+                    "python_version": "source"
+                }
+            ],
+            "0.9.0": [
+                {
+                    "filename": "test-package-0.9.0.tar.gz",
+                    "packagetype": "sdist",
+                    "python_version": "source"
+                }
+            ]
+        }
+    }
+
+
+@pytest.fixture
+def mock_pypi_response(sample_package_data):
+    """Mock PyPI API response."""
+    return sample_package_data

tests/test_basic.py

@@ -0,0 +1,78 @@
+"""Basic tests for PyPI Query MCP Server."""
+
+import pytest
+
+from pypi_query_mcp import __version__
+
+
+def test_version():
+    """Test that version is defined."""
+    assert __version__ == "0.1.0"
+
+
+def test_import():
+    """Test that main modules can be imported."""
+    from pypi_query_mcp.core import PyPIClient, VersionCompatibility
+    from pypi_query_mcp.server import app
+    
+    assert PyPIClient is not None
+    assert VersionCompatibility is not None
+    assert app is not None
+
+
+@pytest.mark.asyncio
+async def test_pypi_client_basic():
+    """Test basic PyPI client functionality."""
+    from pypi_query_mcp.core import PyPIClient
+    
+    async with PyPIClient() as client:
+        # Test that client can be created and closed
+        assert client is not None
+        
+        # Test cache clearing
+        client.clear_cache()
+
+
+def test_version_compatibility():
+    """Test version compatibility utility."""
+    from pypi_query_mcp.core import VersionCompatibility
+    
+    compat = VersionCompatibility()
+    
+    # Test requires_python parsing
+    spec = compat.parse_requires_python(">=3.8")
+    assert spec is not None
+    
+    # Test classifier extraction
+    classifiers = [
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: Implementation :: CPython"
+    ]
+    
+    versions = compat.extract_python_versions_from_classifiers(classifiers)
+    assert "3.8" in versions
+    assert "3.9" in versions
+    
+    implementations = compat.extract_python_implementations(classifiers)
+    assert "CPython" in implementations
+
+
+def test_mcp_tools_import():
+    """Test that MCP tools can be imported."""
+    from pypi_query_mcp.tools import (
+        check_python_compatibility,
+        get_compatible_python_versions,
+        query_package_dependencies,
+        query_package_info,
+        query_package_versions,
+        suggest_python_version_for_packages,
+    )
+    
+    # Test that all tools are callable
+    assert callable(query_package_info)
+    assert callable(query_package_versions)
+    assert callable(query_package_dependencies)
+    assert callable(check_python_compatibility)
+    assert callable(get_compatible_python_versions)
+    assert callable(suggest_python_version_for_packages)