From d4c1512271945b1506b795668344a44b78b5cb31 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Sat, 6 Sep 2025 10:35:05 -0600 Subject: [PATCH] docs: add Claude Code integration instructions and comprehensive tool documentation - Add claude mcp command usage instructions for Claude Code integration - Document all 37 MCP tools across 8 categories including new security, license, health, and requirements analysis tools - Add comprehensive usage examples for all tool categories - Update tool descriptions to reflect current comprehensive capabilities --- README.md | 138 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 113 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 43f4e94..e55c1e2 100644 --- a/README.md +++ b/README.md @@ -150,6 +150,33 @@ Add to your Windsurf MCP configuration (`~/.codeium/windsurf/mcp_config.json`): } ``` +### Claude Code + +If you're using [Claude Code](https://claude.ai/code), you can connect to this MCP server using the `claude mcp` command: + +```bash +# Connect to the PyPI Query MCP server +claude mcp add pypi-query uvx --from pypi-query-mcp-server pypi-query-mcp + +# Or with custom environment variables +claude mcp add pypi-query uvx --from pypi-query-mcp-server pypi-query-mcp \ + --env PYPI_INDEX_URL=https://pypi.org/pypi \ + --env PYPI_CACHE_TTL=3600 \ + --env PYPI_LOG_LEVEL=INFO + +# List connected MCP servers +claude mcp list + +# Remove the server if needed +claude mcp remove pypi-query +``` + +Once connected, you can use all the MCP tools directly in Claude Code sessions by asking questions like: +- "What are the dependencies of Django?" +- "Check if numpy is compatible with Python 3.11" +- "Show me the top downloaded packages this month" +- "Analyze the security vulnerabilities in my requirements.txt file" + ### Environment Variables #### Basic Configuration @@ -187,45 +214,82 @@ export PYPI_PRIVATE_PYPI_PASSWORD="your_password" ## Available MCP Tools -The server provides the following MCP tools: +The server provides **37 comprehensive MCP tools** across **8 categories**: -### Core Package Information +### Core Package Information (11 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 - -### Python Compatibility 4. **check_package_python_compatibility** - Check Python version compatibility 5. **get_package_compatible_python_versions** - Get all compatible Python versions - -### Advanced Dependency Analysis 6. **resolve_dependencies** - Recursively resolve all package dependencies with detailed analysis 7. **download_package** - Download package and all dependencies to local directory - -### Download Statistics & Popularity 8. **get_download_statistics** - Get comprehensive download statistics for any package 9. **get_download_trends** - Analyze download trends and time series data (last 180 days) 10. **get_top_downloaded_packages** - Get the most popular packages by download count +11. **search_pypi_packages** - Advanced PyPI package search with intelligent fallbacks -### MCP Prompt Templates -11. **analyze_package_quality** - Generate comprehensive package quality analysis prompts -12. **compare_packages** - Generate detailed package comparison prompts -13. **suggest_alternatives** - Generate prompts for finding package alternatives -14. **resolve_dependency_conflicts** - Generate prompts for resolving dependency conflicts -15. **plan_version_upgrade** - Generate prompts for planning package version upgrades -16. **audit_security_risks** - Generate prompts for security risk auditing -17. **plan_package_migration** - Generate comprehensive package migration plan prompts -18. **generate_migration_checklist** - Generate detailed migration checklist prompts +### PyPI Publishing & Account Management (6 tools) +12. **upload_package_to_pypi** - Upload packages to PyPI with comprehensive validation +13. **check_pypi_credentials** - Validate PyPI authentication credentials +14. **get_pypi_upload_history** - Get detailed upload history and statistics +15. **delete_pypi_release** - Delete specific package releases from PyPI +16. **manage_pypi_maintainers** - Add/remove package maintainers +17. **get_pypi_account_info** - Get comprehensive PyPI account information -### Environment Analysis Templates -19. **analyze_environment_dependencies** - Generate prompts for analyzing current environment dependencies -20. **check_outdated_packages** - Generate prompts for checking outdated packages with update priorities -21. **generate_update_plan** - Generate prompts for creating comprehensive package update plans +### Package Metadata & Management (4 tools) +18. **update_package_metadata** - Update package descriptions, keywords, and metadata +19. **manage_package_urls** - Update project URLs and documentation links +20. **set_package_visibility** - Control package visibility and access +21. **manage_package_keywords** - Add/remove package keywords and tags -### Trending Analysis Templates -22. **analyze_daily_trends** - Generate prompts for analyzing daily PyPI download trends -23. **find_trending_packages** - Generate prompts for discovering trending packages over time periods -24. **track_package_updates** - Generate prompts for tracking recent package updates and releases +### Analytics & Insights (4 tools) +22. **get_pypi_package_analytics** - Comprehensive package analytics and metrics +23. **get_pypi_security_alerts** - Security vulnerability alerts and advisories +24. **get_pypi_package_rankings** - Package popularity rankings and comparisons +25. **analyze_pypi_competition** - Competitive analysis with similar packages + +### Discovery & Monitoring (4 tools) +26. **monitor_pypi_new_releases** - Monitor new package releases and updates +27. **get_pypi_trending_today** - Get trending packages with growth metrics +28. **search_pypi_by_maintainer** - Find packages by maintainer or organization +29. **get_pypi_package_recommendations** - Get intelligent package recommendations + +### Development Workflow (4 tools) +30. **validate_pypi_package_name** - Validate package names and availability +31. **preview_pypi_package_page** - Preview package page before publishing +32. **check_pypi_upload_requirements** - Validate package before upload +33. **get_pypi_build_logs** - Retrieve build logs and debugging information + +### 🔒 Security Analysis (2 tools) +34. **scan_pypi_package_security** - Comprehensive security vulnerability scanning with OSV database and GitHub advisories +35. **bulk_scan_package_security** - Bulk security scanning for multiple packages with consolidated reporting + +### 📄 License & Compliance (2 tools) +36. **analyze_pypi_package_license** - License compatibility analysis with SPDX normalization and risk assessment +37. **check_bulk_license_compliance** - Bulk license compliance checking with comprehensive compatibility matrix + +### 🏥 Package Health Assessment (2 tools) +- **assess_package_health_score** - Package health scoring across 7 categories (maintenance, popularity, documentation, testing, security, compatibility, metadata) +- **compare_packages_health_scores** - Comparative health analysis between multiple packages with GitHub metrics integration + +### 📋 Requirements Analysis (2 tools) +- **analyze_requirements_file_tool** - Requirements file analysis supporting multiple formats (requirements.txt, pyproject.toml, setup.py, Pipfile, conda.yml) +- **compare_multiple_requirements_files** - Multi-file comparison for requirements analysis across different environments + +### MCP Prompt Templates (12 tools) +- **analyze_package_quality** - Generate comprehensive package quality analysis prompts +- **compare_packages** - Generate detailed package comparison prompts +- **suggest_alternatives** - Generate prompts for finding package alternatives +- **resolve_dependency_conflicts** - Generate prompts for resolving dependency conflicts +- **plan_version_upgrade** - Generate prompts for planning package version upgrades +- **audit_security_risks** - Generate prompts for security risk auditing +- **plan_package_migration** - Generate comprehensive package migration plan prompts +- **generate_migration_checklist** - Generate detailed migration checklist prompts +- **analyze_environment_dependencies** - Generate prompts for analyzing current environment dependencies +- **check_outdated_packages** - Generate prompts for checking outdated packages with update priorities +- **generate_update_plan** - Generate prompts for creating comprehensive package update plans +- **analyze_daily_trends** - Generate prompts for analyzing daily PyPI download trends > 📖 **Learn more about prompt templates**: See [PROMPT_TEMPLATES.md](PROMPT_TEMPLATES.md) for detailed documentation and examples. @@ -276,6 +340,30 @@ Once configured in your MCP client (Claude Desktop, Cline, Cursor, Windsurf), yo - "Track recent security updates and new package releases" - "Find rising packages in web development that I should consider" +### Security Analysis +- "Scan Django for security vulnerabilities using OSV database" +- "Check my requirements.txt file for packages with known security issues" +- "Bulk scan all packages in my project for security vulnerabilities" +- "What security advisories exist for numpy version 1.21.0?" + +### License Analysis & Compliance +- "Analyze the license compatibility of MIT, Apache-2.0, and GPL-3.0 licenses" +- "Check if all packages in my requirements.txt are compatible with my MIT license" +- "What are the licensing risks of using this package in a commercial project?" +- "Bulk check license compliance for my entire dependency tree" + +### Package Health Assessment +- "Assess the overall health score of the requests package" +- "Compare the health scores of Django vs FastAPI vs Flask for a new project" +- "Which package has better maintenance: numpy or pandas?" +- "Score this package across maintenance, popularity, and security metrics" + +### Requirements File Analysis +- "Analyze my requirements.txt file for outdated packages and security issues" +- "Compare my development and production requirements files" +- "Parse my pyproject.toml file and suggest package updates" +- "What dependencies in my Pipfile need security updates?" + ### Example Conversations **User**: "Check if Django 4.2 is compatible with Python 3.9"