fix: resolve include_extras parameter validation in resolve_dependencies

- Fix extra dependencies being filtered out by Python version checks
- Add proper handling for extra markers in dependency parsing
- Update parameter descriptions and documentation
- Add comprehensive examples and demo script
- Test with requests[socks], django[argon2,bcrypt], setuptools[test]

pypi_query_mcp/core/dependency_parser.py

@@ -81,6 +81,13 @@ class DependencyParser:
         if not req.marker:
             return True
 
+        # If the marker contains 'extra ==', this is an extra dependency
+        # and should not be filtered by Python version. Extra dependencies
+        # are handled separately based on user selection.
+        marker_str = str(req.marker)
+        if "extra ==" in marker_str:
+            return True
+
         # Create environment for marker evaluation
         env = {
             "python_version": str(python_version),

pypi_query_mcp/server.py

@@ -305,7 +305,10 @@ async def resolve_dependencies(
     Args:
         package_name: The name of the PyPI package to analyze (e.g., 'pyside2', 'django')
         python_version: Target Python version for dependency filtering (e.g., '3.10', '3.11')
-        include_extras: List of extra dependency groups to include (e.g., ['dev', 'test'])
+        include_extras: List of extra dependency groups to include. These are optional 
+            dependency groups defined by the package (e.g., ['socks'] for requests, 
+            ['argon2', 'bcrypt'] for django, ['test', 'doc'] for setuptools). Check the 
+            package's PyPI page or use the provides_extra field to see available extras.
         include_dev: Whether to include development dependencies (default: False)
         max_depth: Maximum recursion depth for dependency resolution (default: 5)
 
@@ -373,7 +376,9 @@ async def download_package(
         package_name: The name of the PyPI package to download (e.g., 'pyside2', 'requests')
         download_dir: Local directory to download packages to (default: './downloads')
         python_version: Target Python version for compatibility (e.g., '3.10', '3.11')
-        include_extras: List of extra dependency groups to include (e.g., ['dev', 'test'])
+        include_extras: List of extra dependency groups to include. These are optional 
+            dependency groups defined by the package (e.g., ['socks'] for requests, 
+            ['argon2', 'bcrypt'] for django). Check the package's PyPI page to see available extras.
         include_dev: Whether to include development dependencies (default: False)
         prefer_wheel: Whether to prefer wheel files over source distributions (default: True)
         verify_checksums: Whether to verify downloaded file checksums (default: True)

pypi_query_mcp/tools/dependency_resolver.py

@@ -35,7 +35,8 @@ class DependencyResolver:
         Args:
             package_name: Name of the package to resolve
             python_version: Target Python version (e.g., "3.10")
-            include_extras: List of extra dependencies to include
+            include_extras: List of extra dependency groups to include (e.g., ['socks'] for requests, 
+                ['test', 'doc'] for setuptools). These are optional dependencies defined by the package.
             include_dev: Whether to include development dependencies
             max_depth: Maximum recursion depth (overrides instance default)
 
@@ -242,7 +243,8 @@ async def resolve_package_dependencies(
     Args:
         package_name: Name of the package to resolve
         python_version: Target Python version (e.g., "3.10")
-        include_extras: List of extra dependencies to include
+        include_extras: List of extra dependency groups to include (e.g., ['socks'] for requests, 
+            ['test', 'doc'] for setuptools). These are optional dependencies defined by the package.
         include_dev: Whether to include development dependencies
         max_depth: Maximum recursion depth