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)

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

Option 2: Manual Installation

1. Clone the repository:

   git clone https://github.com/yourusername/pub_dev_mcp.git
   cd pub_dev_mcp

2. Create virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

🎯 Usage

As MCP Server

1. Start the server:

   python server.py

2. Connect with MCP Inspector:

   npx @modelcontextprotocol/inspector server.py

3. Use with Claude Desktop: Add to your Claude Desktop config:

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

As HTTP API

1. Install HTTP dependencies:

   pip install -r requirements-http.txt

2. Start HTTP server:

   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:

# 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 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 file for details.

🐛 Issues

Found a bug? Please open an issue with:

• Description of the problem
• Steps to reproduce
• Expected vs actual behavior
• Your environment details

🙏 Acknowledgments

• Model Context Protocol team
• pub.dev for the excellent package API
• Dart/Flutter 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

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Testing

Run All Tests

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

# 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:

{
  "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