pypi-query-mcp/DOWNLOAD_STATS_FEATURE.md

PyPI Download Statistics Feature

🎉 Feature Summary

This document summarizes the new PyPI package download statistics and popularity analysis tools added to the MCP server.

🚀 New MCP Tools

1. get_download_statistics

Get comprehensive download statistics for any PyPI package.

Usage Example:

"What are the download statistics for the requests package this month?"

Returns:

• Recent download counts (last day/week/month)
• Package metadata and repository information
• Download trends and growth analysis
• Data source and timestamp information

2. get_download_trends

Analyze download trends and time series data for the last 180 days.

Usage Example:

"Show me the download trends for numpy over the last 180 days"

Returns:

• Time series data for the last 180 days
• Trend analysis (increasing/decreasing/stable)
• Peak download periods and statistics
• Average daily downloads and growth indicators

3. get_top_downloaded_packages

Get the most popular Python packages by download count.

Usage Example:

"What are the top 10 most downloaded Python packages today?"

Returns:

• Ranked list of packages with download counts
• Package metadata and repository links
• Period and ranking information
• Data source and limitations

📊 Example Questions You Can Ask

• "请帮我看看今天下载量最高的包是什么，仓库地址是什么？"
• "What are the download statistics for the requests package this month?"
• "Show me the download trends for numpy over the last 180 days"
• "What are the top 10 most downloaded Python packages today?"
• "Compare the popularity of Django vs Flask vs FastAPI"
• "Which web framework has the highest download count this week?"

🔧 Technical Implementation

Core Components

1. PyPIStatsClient - New async client for pypistats.org API integration
2. Advanced analysis functions - Download trends analysis with growth indicators
3. Repository information integration - Links to GitHub/GitLab repositories
4. Comprehensive caching - Efficient data caching for better performance

Files Added/Modified

• pypi_query_mcp/core/stats_client.py - New PyPIStatsClient for API integration
• pypi_query_mcp/tools/download_stats.py - Download statistics tools implementation
• pypi_query_mcp/server.py - New MCP tools registration
• tests/test_download_stats.py - Comprehensive test coverage
• examples/download_stats_demo.py - Demo script with examples
• README.md - Updated documentation

📈 Example Output

{
  "package": "requests",
  "downloads": {
    "last_day": 1500000,
    "last_week": 10500000,
    "last_month": 45000000
  },
  "analysis": {
    "total_downloads": 57000000,
    "highest_period": "last_month",
    "growth_indicators": {
      "daily_vs_weekly": 1.0,
      "weekly_vs_monthly": 0.93
    }
  },
  "metadata": {
    "name": "requests",
    "version": "2.31.0",
    "summary": "Python HTTP for Humans.",
    "project_urls": {
      "Repository": "https://github.com/psf/requests"
    }
  }
}

🧪 Testing

• ✅ Comprehensive unit tests with 76% coverage
• ✅ Mock-based testing for reliable CI/CD
• ✅ Integration tests for all new MCP tools
• ✅ Demo script with real-world examples

🔄 Backward Compatibility

• ✅ All existing functionality remains unchanged
• ✅ No breaking changes to existing APIs
• ✅ New features are additive only

🌟 Ready for Use

This feature is production-ready and can be used immediately after merging. The pypistats.org API is stable and widely used by the Python community.

📝 Notes

• This implementation uses the pypistats.org API which provides download statistics for the last 180 days
• For longer historical data, users can be directed to use Google BigQuery with PyPI datasets
• The top packages functionality is based on known popular packages due to API limitations

🔗 Pull Request

PR #21: https://github.com/loonghao/pypi-query-mcp-server/pull/21

---

Status: ✅ Ready for merge - All tests passing, lint checks passed, comprehensive documentation provided.