# 📦 PyPI Package MCP Server

[![Python](https://img.shields.io/badge/Python-3.9+-3776ab?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> A powerful Model Context Protocol (MCP) server that enables AI assistants to fetch, explore, and analyze source code from any Python package on PyPI.

## ✨ Features

- 📦 **Fetch Any PyPI Package**: Download and explore source code from millions of packages
- 🔍 **Smart File Discovery**: List and filter files with intelligent code detection
- 📄 **Selective Code Reading**: Get specific files or entire codebases
- 🏷️ **Version Control**: Support for any published package version
- 🧹 **Auto Cleanup**: Automatic temporary file management
- 🔒 **Type Safe**: Full type hints with mypy support
- ⚡ **Async First**: Modern async/await patterns throughout
- 🤖 **AI-Ready**: Perfect integration with Claude, ChatGPT, and other AI assistants

## 🎯 Use Cases

- **Code Analysis**: Analyze libraries before adopting them
- **Learning**: Study well-written open source code
- **AI Development**: Enable AI assistants to understand package internals
- **Documentation**: Generate docs by analyzing source code
- **Security Auditing**: Review dependencies for security issues
- **Migration Planning**: Understand APIs when upgrading packages

## 🚀 Installation & Setup

### Option 1: Local Development (Stdio Mode)

```bash
git clone https://github.com/Qvakk/pypi-package-mcp-server.git
cd pypi-package-mcp-server
pip install -e .
pypi-package-mcp-server
```

### Option 2: Local Development (HTTP Mode)

```bash
git clone https://github.com/Qvakk/pypi-package-mcp-server.git
cd pypi-package-mcp-server
pip install -e .
TRANSPORT_MODE=http PORT=3000 pypi-package-mcp-server
```

### Option 3: With Authentication Token

```bash
# Stdio mode with auth
AUTH_TOKEN=your-secret-token pypi-package-mcp-server

# HTTP mode with auth
TRANSPORT_MODE=http PORT=3000 AUTH_TOKEN=your-secret-token pypi-package-mcp-server
```

### Option 4: Docker (Production - HTTP Mode)

```bash
# Build Docker image
docker build -t pypi-package-mcp-server .

# Run in stdio mode (Claude Desktop)
docker run -it pypi-package-mcp-server

# Run in HTTP mode
docker run -p 3000:3000 \
  -e TRANSPORT_MODE=http \
  -e PORT=3000 \
  pypi-package-mcp-server

# Run with authentication
docker run -p 3000:3000 \
  -e TRANSPORT_MODE=http \
  -e PORT=3000 \
  -e AUTH_TOKEN=your-secret-token \
  pypi-package-mcp-server

# Use Docker Compose
docker-compose up -d
```

## 🔧 Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `TRANSPORT_MODE` | `stdio` | Transport mode: `stdio` or `http` |
| `PORT` | `3000` | HTTP server port (only used in `http` mode) |
| `AUTH_TOKEN` | (none) | Optional authentication token for API access |

### Transport Modes

#### Stdio Mode (Default)
- Best for: Claude Desktop, local development
- Connection: Standard input/output streams
- Command: `pypi-package-mcp-server`

#### HTTP Mode
- Best for: Remote servers, containerized deployments
- Connection: HTTP requests on specified port
- Health endpoint: `GET /health`
- MCP endpoint: `POST /mcp`
- Command: `TRANSPORT_MODE=http PORT=3000 pypi-package-mcp-server`

### Authentication

When `AUTH_TOKEN` environment variable is set, all HTTP requests must include the token in the `Authorization` header:

```bash
# Using Bearer token
curl -H "Authorization: Bearer your-secret-token" http://localhost:3000/health

# Or just the token
curl -H "Authorization: your-secret-token" http://localhost:3000/health
```

## 📊 Supported Packages

- ✅ All public PyPI packages
- ✅ Any published version
- ✅ Source distributions (`.tar.gz`)
- ✅ Binary wheels (`.whl`)
- ✅ Monorepo packages
- ✅ Pure Python and native extensions

## 🔥 Popular Packages to Explore

Try these commands with your AI assistant:

```
"Analyze the requests library implementation"
"Show me the Django ORM structure"
"Explore the Flask application framework"
"Review the NumPy array implementation"
"Study the pandas DataFrame code"
```

## 🛠️ Tools

### 1. `get_pypi_package_code`
Fetch source code from a Python package.

```python
# Get all source files from the latest version
pypi_server.get_pypi_package_code(package_name="requests")

# Get a specific version
pypi_server.get_pypi_package_code(package_name="django", version="4.2.0")

# Get a specific file
pypi_server.get_pypi_package_code(
    package_name="flask",
    file_path="src/flask/app.py"
)
```

### 2. `list_package_files`
List all files in a package.

```python
pypi_server.list_package_files(package_name="numpy")
pypi_server.list_package_files(package_name="pandas", version="2.0.0")
```

### 3. `get_package_info`
Get metadata about a package.

```python
pypi_server.get_package_info(package_name="requests")
```

### 4. `search_pypi_packages`
Search for packages on PyPI.

```python
pypi_server.search_pypi_packages(query="web framework", limit=20)
```


## 📋 Requirements

- Python 3.9 or higher
- `mcp` >= 0.1.0
- `requests` >= 2.31.0
- `pydantic` >= 2.0.0

## 🔒 Authentication (Optional)

Set the `AUTH_TOKEN` environment variable for API authentication:

```bash
export AUTH_TOKEN=your-secret-token
pypi-package-mcp-server
```

## 🧪 Development

### Install Development Dependencies

```bash
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Format Code

```bash
black pypi_mcp_server/
```

### Lint Code

```bash
ruff check pypi_mcp_server/
```

### Type Checking

```bash
mypy pypi_mcp_server/
```

## 🐛 Troubleshooting

### Package Not Found
- Verify the package name is correct (use lowercase, hyphens not underscores)
- Search first with `search_pypi_packages` to find the exact name

### Extraction Failed
- Some packages may not have source distributions
- Check if a wheel-only package is available

### Timeout Issues
- Large packages may take time to download
- Increase timeout values if needed

## 📚 Related Projects

- [Model Context Protocol](https://github.com/modelcontextprotocol/servers)
- [PyPI JSON API](https://warehouse.pypa.io/api-reference/json.html)
- [NPM Package MCP Server](https://github.com/Qvakk/npm-package-mcp-server)

## 📄 License

MIT License - See [LICENSE](LICENSE) file for details

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## ⭐ Credits

Inspired by the [NPM Package MCP Server](https://github.com/Qvakk/npm-package-mcp-server)

---

**Made with ❤️**