diff --git a/README.md b/README.md index b4267e5..f2f9ee9 100644 --- a/README.md +++ b/README.md @@ -1,45 +1,174 @@ -# PyPI Query MCP Server +# 🎤 mcpypi 🥧 +### *Your Master of Ceremonies for PyPI* -[![PyPI version](https://img.shields.io/pypi/v/mcpypi.svg)](https://pypi.org/project/mcpypi/) +
-A Model Context Protocol (MCP) server for querying PyPI package information, dependencies, and compatibility checking. +[![PyPI version](https://img.shields.io/pypi/v/mcpypi.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/mcpypi/) +[![Python versions](https://img.shields.io/pypi/pyversions/mcpypi.svg?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/mcpypi/) +[![Downloads](https://img.shields.io/pypi/dm/mcpypi.svg?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/mcpypi/) +[![License](https://img.shields.io/pypi/l/mcpypi.svg?style=for-the-badge)](https://github.com/loonghao/pypi-query-mcp-server/blob/main/LICENSE) + +
+ +--- + +> **mcpypi** (pronounced "MC-py-pie") is your **Master of Ceremonies** for PyPI! 🎤 +> +> *The ultimate PyPI package intelligence platform, now available through Model Context Protocol* + +Just like a world-class DJ or MC controls the music and keeps the party flowing, **mcpypi** orchestrates your entire Python package ecosystem. It's the perfect fusion of "**MCP**" + "**PyPI**" + the Python community's beloved tradition of naming everything with "**pie**" 🥧 (NumPy, SciPy, SymPy... you get it!). + +Think of mcpypi as your **intelligent package DJ** - it knows all the tracks (packages), their dependencies, security vulnerabilities, licenses, and can help you mix the perfect environment for your Python projects! + +## 🌟 Why mcpypi? + + + + + + +
+ +### 🎯 **37 Powerful Tools** +Complete PyPI analysis suite across 8 categories + +### 🔒 **Security First** +OSV database integration + GitHub advisories + +### 📊 **Real-time Analytics** +Live download stats, trends, and rankings + +### 🏥 **Health Scoring** +7-category package quality assessment + + + +### 📄 **License Intelligence** +SPDX compatibility analysis + risk assessment + +### 🔍 **Deep Analysis** +Dependency trees, requirements parsing, bulk operations + +### ⚡ **Lightning Fast** +Async operations with intelligent caching + +### 🎤 **MCP Integration** +Works with Claude Code, Claude Desktop, Cursor, and more! + +
## Features -- 📦 Query PyPI package information (name, version, description, dependencies) -- 🐍 Python version compatibility checking -- 🔍 **Advanced dependency analysis and recursive resolution** -- 📥 **Package download with dependency collection** -- 📊 **Download statistics and popularity analysis** -- 🏆 **Top packages ranking and trends** -- 🎯 **MCP prompt templates for guided analysis and decision-making** -- 🏢 Private PyPI repository support -- ⚡ Fast async operations with caching -- 🛠️ Easy integration with MCP clients +Your MC knows how to drop the beats! 🎵 -## Installation +- 📦 **Track Info** - Get the full story on any PyPI package (metadata, versions, dependencies) +- 🐍 **Compatibility Check** - Know which Python versions can handle your tracks +- 🔍 **Deep Mixing** - Advanced dependency analysis and recursive resolution to avoid conflicts +- 📥 **Collection Building** - Download packages with all their dependencies for offline mixing +- 📊 **Chart Analysis** - Real-time download statistics and popularity trends +- 🏆 **Top 40** - Discover the hottest packages trending right now +- 🔒 **Security Scanning** - Keep your playlist safe from vulnerable packages +- 📄 **License Mixing** - Ensure your package mix is legally compatible +- 🏥 **Health Check** - Assess package quality across 7 key metrics +- 📋 **Setlist Analysis** - Parse and analyze requirements files in any format +- 🎯 **Smart Prompts** - MCP templates for guided decision-making +- 🏢 **Private Venues** - Support for private PyPI repositories +- ⚡ **Live Performance** - Fast async operations with intelligent caching +- 🛠️ **Universal Mixer** - Easy integration with all MCP clients -### Using uvx (recommended) +## 🚀 Quick Start + +Ready to get your MC on the decks? Here's how to book mcpypi for your next Python party! 🎉 + +### Option 1: Lightning Setup ⚡ (Recommended) ```bash -# Run directly with uvx +# One-liner - Run immediately with uvx uvx mcpypi - -# Or install and run with specific script -uvx --from mcpypi mcpypi ``` -### Using pip +### Option 2: Traditional Install 📦 ```bash # Install from PyPI pip install mcpypi -# Run the server +# Run the server python -m pypi_query_mcp.server ``` -### From source +### Option 3: Claude Code Integration 🎤 + +```bash +# Connect directly to Claude Code +claude mcp add mcpypi -- uvx mcpypi +``` + +
+ +### 🎊 **That's it! Your MC is now live and ready to rock!** 🎊 + +
+ +--- + +## 🎭 Live Demo + +Here's what your MC can do for you: + + + + + + + + + + +
+ +### 🔍 **Package Intelligence** +```python +"What are the security vulnerabilities +in Django 4.1?" +``` +*Get real-time security analysis with OSV database* + + + +### 📊 **Trend Analysis** +```python +"Show me the top 10 trending +ML packages this week" +``` +*Live PyPI download trends and rankings* + +
+ +### 🏥 **Health Scoring** +```python +"Compare the health scores of +FastAPI vs Django vs Flask" +``` +*7-category quality assessment with GitHub metrics* + + + +### 📄 **License Compliance** +```python +"Check if my requirements.txt +is MIT license compatible" +``` +*SPDX normalization with risk assessment* + +
+ +--- + +### 🛠️ Advanced Installation + +
+Development Setup ```bash git clone https://github.com/loonghao/pypi-query-mcp-server.git @@ -48,9 +177,24 @@ uv sync uv run pypi-query-mcp ``` -## Configuration +
-### Claude Desktop +--- + +## 🎛️ Configuration + +
+ +**mcpypi works with ALL major MCP clients!** + +[![Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Ready-blue?style=for-the-badge&logo=anthropic)](https://claude.ai/desktop) +[![Claude Code](https://img.shields.io/badge/Claude_Code-Ready-blue?style=for-the-badge&logo=anthropic)](https://claude.ai/code) +[![Cursor](https://img.shields.io/badge/Cursor-Ready-blue?style=for-the-badge&logo=cursor)](https://cursor.sh/) +[![Windsurf](https://img.shields.io/badge/Windsurf-Ready-blue?style=for-the-badge)](https://codeium.com/windsurf) + +
+ +### 🖥️ Claude Desktop Add to your Claude Desktop configuration file: