npm package: @hammadparveez/pub-dev-mcp
Description: MCP server for pub.dev package information and GitHub README access
Author: Hammad Parveez
Latest version: 1.0.0

# Pub.dev MCP Server

A Model Context Protocol (MCP) server that provides access to pub.dev package information and GitHub README files. This server can be used with MCP clients like Claude Desktop or deployed as a standalone HTTP API.

🚀 **LIVE DEMO**: https://web-production-e619b.up.railway.app

## 🚀 Features

- **📦 Package Listing**: Fetch all available pub.dev package names (50,000+ packages)
- **📋 Package Details**: Get comprehensive information about specific packages
- **📖 GitHub README**: Fetch README files from package repositories
- **🌐 HTTP API**: Deploy as a web service for broader access
- **🔧 MCP Compatible**: Works with any MCP client

## 🛠 Tools

### 1. `list_pub_packages`
Fetches all package names from pub.dev.

### 2. `get_package_details`
Gets detailed information about a specific package including version, description, homepage, and repository.

### 3. `get_github_readme`
Fetches the README file from a package's GitHub repository (supports both repository and homepage fields).

## 📋 Prerequisites

- Python 3.8+
- pip or pipenv

## 🔧 Installation

### Option 1: NPM Package (Recommended)

```json
{
  "servers": {
    "pub-dev": {
      "command": "npx",
      "args": ["@hammadparveez/pub-dev-mcp@latest"]
    }
  }
}
```

### Option 2: Manual Installation

1. **Clone the repository**:
   ```bash
   git clone https://github.com/yourusername/pub_dev_mcp.git
   cd pub_dev_mcp
   ```

2. **Create virtual environment**:
   ```bash
   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

## 🎯 Usage

### As MCP Server

1. **Start the server**:
   ```bash
   python server.py
   ```

2. **Connect with MCP Inspector**:
   ```bash
   npx @modelcontextprotocol/inspector server.py
   ```

3. **Use with Claude Desktop**:
   Add to your Claude Desktop config:
   ```json
   {
     "mcpServers": {
       "pub-dev": {
         "command": "python",
         "args": ["/path/to/pub_dev_mcp/server.py"]
       }
     }
   }
   ```

### As HTTP API

1. **Install HTTP dependencies**:
   ```bash
   pip install -r requirements-http.txt
   ```

2. **Start HTTP server**:
   ```bash
   python http_server.py
   ```

3. **API Endpoints**:
   - `GET /` - Server info
   - `GET /health` - Health check
   - `GET /tools` - List available tools
   - `GET /packages` - List all packages
   - `GET /package/{name}` - Get package details
   - `GET /readme/{name}` - Get package README
   - `POST /call` - Call MCP tools directly

## 🧪 Testing

Run the test suite:
```bash
# Test MCP functionality
python test_suite.py

# Test HTTP server (requires server running)
python test_http_server.py
```

## 🚀 Deployment

Deploy as a web service on various platforms:

### Railway
1. Connect your GitHub repo to Railway
2. Deploy automatically
3. Access at `https://yourapp.railway.app`

### Render
1. Connect repo to Render
2. Use `render.yaml` configuration
3. Deploy with zero configuration

See [DEPLOYMENT.md](DEPLOYMENT.md) for detailed deployment instructions.

## 📁 Project Structure

```
pub_dev_mcp/
├── src/                    # Source code
│   ├── config.py          # Configuration constants
│   ├── pubdev_client.py   # Pub.dev API client
│   ├── github_client.py   # GitHub API client
│   └── tools.py           # MCP tools implementation
├── server.py              # Main MCP server
├── http_server.py         # HTTP API wrapper
├── test_suite.py          # Comprehensive tests
├── requirements.txt       # MCP dependencies
├── requirements-http.txt  # HTTP server dependencies
├── Dockerfile            # Docker configuration
├── DEPLOYMENT.md         # Deployment guide
└── README.md            # This file
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🐛 Issues

Found a bug? Please [open an issue](https://github.com/yourusername/pub_dev_mcp/issues) with:
- Description of the problem
- Steps to reproduce
- Expected vs actual behavior
- Your environment details

## 🙏 Acknowledgments

- [Model Context Protocol](https://github.com/modelcontextprotocol/python-sdk) team
- [pub.dev](https://pub.dev) for the excellent package API
- [Dart/Flutter](https://dart.dev) community
├── test_suite.py          # Comprehensive test suite
├── setup.sh               # Automated setup script
└── requirements.txt       # Python dependencies
```

## Quick Start

### Automated Setup
```bash
./setup.sh
```

### Manual Setup
```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

## Testing

### Run All Tests
```bash
source venv/bin/activate
python test_suite.py
```

This comprehensive test suite validates:
- ✅ pub.dev API client functionality
- ✅ GitHub client functionality  
- ✅ MCP tools implementation
- ✅ MCP protocol communication

### Interactive Testing with MCP Inspector
```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run server with inspector
source venv/bin/activate
npx @modelcontextprotocol/inspector python server.py
```

## Available Tools

### 1. `list_pub_packages`
Fetches all package names available on pub.dev (20,000+ packages).

**Parameters:** None

**Returns:** List of package names with count information.

### 2. `get_package_details`
Gets detailed information about a specific package.

**Parameters:**
- `package_name` (string): The package name

**Returns:** JSON with package metadata including version, description, dependencies, etc.

### 3. `get_github_readme`
Fetches README.md from a package's GitHub repository.

**Parameters:**
- `package_name` (string): The package name

**Returns:** README content with source URL information.

**Features:**
- ✅ Checks `repository` field first
- 🔄 Falls back to `homepage` field if repository is null
- 📝 Clear indication of URL source used
- 🌲 Tries multiple README file names and Git branches

## Usage with Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "pub-dev-server": {
      "command": "python",
      "args": ["/path/to/pub_dev_mcp/server.py"],
      "env": {}
    }
  }
}
```

## Status

- ✅ **Production Ready**: All tests passing
- ✅ **MCP Compliant**: Follows protocol specifications
- ✅ **Well Tested**: Comprehensive test suite
- ✅ **Clean Architecture**: Modular, maintainable codebase