mcp-package-hero 1.2.0

MCP server for package version checking, quality rating, and llms.txt documentation across PyPI, npm, and pub.dev

🦸 MCP Package Hero

A comprehensive Model Context Protocol (MCP) server for checking package versions and rating package quality across Python (PyPI), JavaScript/TypeScript (npm), and Dart (pub.dev).

🎯 Purpose

MCP Package Hero helps you make informed decisions about packages by providing:

• Version Information: Get the latest stable version of any package
• Quality Ratings: Comprehensive quality analysis across multiple dimensions
• llms.txt Documentation: Fetch and generate LLM-friendly documentation files

Package Hero focuses on three major ecosystems:

• ✅ Python packages on PyPI
• ✅ JavaScript/TypeScript packages on npm
• ✅ Dart/Flutter packages on pub.dev

🚀 Features

Version Checking

• Simple API: Get latest version for one or multiple packages
• Fast: Sub-second response times with async operations
• Batch Support: Check up to 10 packages at once

Quality Rating (v1.1.0+)

• Comprehensive Analysis: Multi-dimensional package quality scoring
  • 🔧 Maintenance Health (35%): Release frequency, issue resolution, PR activity
  • 📊 Popularity (25%): Downloads, GitHub stars, community adoption
  • ✨ Quality Metrics (40%): Documentation (35%), license (25%), tests (25%), llms.txt (15%)
• Letter Grades: A+ to F rating system for quick assessment
• Actionable Insights: Key strengths and red flags for each package
• Ecosystem Integration: Leverages native scores (pub.dev pub points, npms.io scores)
• llms.txt Bonus (v1.2.0+): Packages with llms.txt get bonus points (70 for llms.txt, 100 for both llms.txt + llms-full.txt)

llms.txt Support (v1.2.0+)

• Fetch llms.txt: Get LLM-friendly documentation from package repositories
• Generate llms.txt: Create standardized documentation for your projects
• Multi-Source: Searches GitHub, homepages, and documentation sites
• Validation: Parses and validates llms.txt format compliance
• Smart Scanning: Automatically discovers documentation files in projects

Technical Excellence

• LLM-Friendly: Designed specifically for AI assistants and agents
• Type-Safe: Full type hints, Pydantic validation, and mypy compliance
• Well-Tested: Comprehensive coverage for all features
• Production-Ready: Modern Python best practices, timezone-aware, Pydantic V2

📦 Installation

Using uv (Recommended)

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/moinsen-dev/mcp-package-hero.git
cd mcp-package-hero

# Install dependencies
uv sync

# Install the package
uv pip install -e .

Using pip

git clone https://github.com/moinsen-dev/mcp-package-hero.git
cd mcp-package-hero
pip install -e .

🔧 Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cline, etc.):

Claude Desktop

Option 1: Run directly from GitHub (Recommended)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "package-hero": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/moinsen-dev/mcp-package-hero.git",
        "mcp-package-hero"
      ]
    }
  }
}

Option 2: Run from local directory

{
  "mcpServers": {
    "package-hero": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-package-hero",
        "mcp-package-hero"
      ]
    }
  }
}

Cline VSCode Extension

Edit ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

Option 1: Run directly from GitHub (Recommended)

{
  "mcpServers": {
    "package-hero": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/moinsen-dev/mcp-package-hero.git",
        "mcp-package-hero"
      ]
    }
  }
}

Option 2: Run from local directory

{
  "mcpServers": {
    "package-hero": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-package-hero",
        "mcp-package-hero"
      ]
    }
  }
}

Claude Code

Add the server globally to Claude Code using the CLI:

Option 1: Run directly from GitHub (Recommended)

claude mcp add-json package-hero '{"type":"stdio","command":"uvx","args":["--from","git+https://github.com/moinsen-dev/mcp-package-hero.git","mcp-package-hero"]}'

Option 2: Run from local directory

claude mcp add-json package-hero '{"type":"stdio","command":"uv","args":["run","--directory","/path/to/mcp-package-hero","mcp-package-hero"]}'

📖 Usage

Tool 1: Get Latest Version

Check the latest version of a single package:

# Example queries for your LLM:
"What's the latest version of requests in Python?"
"Check the current version of react"
"Show me the latest version of the http package for Dart"

Tool Name: get_latest_version

Parameters:

• package_name (string): Name of the package
• ecosystem (string): One of "python", "javascript", or "dart"

Example Response:

{
  "package_name": "requests",
  "ecosystem": "python",
  "latest_version": "2.31.0",
  "registry_url": "https://pypi.org/project/requests/",
  "checked_at": "2025-10-06T10:30:00Z",
  "status": "success"
}

Tool 2: Batch Version Check

Check multiple packages at once (max 10):

# Example query:
"Check the latest versions of requests (python), react (javascript), and http (dart)"

Tool Name: get_latest_versions_batch

Parameters:

• packages (array): List of objects with package_name and ecosystem
• max_packages (integer, optional): Limit (default: 10)

Example Response:

{
  "results": [
    {
      "package_name": "requests",
      "ecosystem": "python",
      "latest_version": "2.31.0",
      "status": "success"
    },
    {
      "package_name": "nonexistent-pkg",
      "ecosystem": "python",
      "latest_version": null,
      "status": "not_found"
    }
  ],
  "checked_at": "2025-10-06T10:30:00Z"
}

Tool 3: Rate Package Quality (v1.1.0+)

Get comprehensive quality rating for a package:

# Example queries:
"Rate the quality of the requests package"
"How good is the react package?"
"Give me a quality assessment of flutter_bloc"

Tool Name: rate_package

Parameters:

• package_name (string): Name of the package
• ecosystem (string): One of "python", "javascript", or "dart"

Example Response:

{
  "package_name": "requests",
  "ecosystem": "python",
  "overall_score": 86.6,
  "letter_grade": "A-",
  "maintenance": {
    "score": 78.8,
    "last_release_days": 48,
    "release_frequency_score": 80.0,
    "issue_resolution_score": 100.0,
    "pr_merge_score": 44.2
  },
  "popularity": {
    "score": 100.0,
    "downloads": 855587647,
    "stars": 53340,
    "downloads_score": 100.0,
    "stars_score": 100.0
  },
  "quality": {
    "score": 85.0,
    "has_documentation": true,
    "has_license": true,
    "has_tests": null,
    "documentation_score": 100.0,
    "license_score": 100.0,
    "test_score": 50.0
  },
  "repository_url": "https://github.com/psf/requests",
  "license": "Apache-2.0",
  "description": "Python HTTP for Humans.",
  "insights": [
    "Strong issue resolution track record",
    "Highly popular with 100K+ monthly downloads",
    "Well-starred project (1000+ stars)",
    "High quality package with good documentation and license"
  ],
  "red_flags": [],
  "status": "success"
}

Tool 4: Get llms.txt (v1.2.0+)

Fetch llms.txt documentation file for a package:

# Example queries:
"Get the llms.txt file for fasthtml"
"Show me the documentation structure for react"
"Fetch llms.txt and llms-full.txt for flutter_bloc"

Tool Name: get_llms_txt

Parameters:

• package_name (string): Name of the package
• ecosystem (string): One of "python", "javascript", or "dart"
• include_full (boolean, optional): Also fetch llms-full.txt (default: false)

Example Response:

{
  "package_name": "fasthtml",
  "ecosystem": "python",
  "llms_txt_content": {
    "project_name": "FastHTML",
    "summary": "FastHTML is a python library which brings together Starlette, Uvicorn, HTMX, and fastcore's FT FastTags",
    "sections": [
      {
        "title": "Docs",
        "links": [
          {
            "title": "FastHTML quick start",
            "url": "https://fastht.ml/docs/tutorials/quickstart_for_web_devs.html.md",
            "description": "Overview of features"
          }
        ]
      }
    ],
    "raw_content": "# FastHTML\n\n> FastHTML is a python library...",
    "is_valid": true,
    "validation_warnings": []
  },
  "source_url": "https://raw.githubusercontent.com/AnswerDotAI/fasthtml/main/llms.txt",
  "source_type": "github_main",
  "repository_url": "https://github.com/AnswerDotAI/fasthtml",
  "status": "success"
}

Tool 5: Create llms.txt (v1.2.0+)

Generate an llms.txt file for your project:

# Example queries:
"Create an llms.txt file for my project called 'My Library'"
"Generate llms.txt documentation for this codebase"
"Create llms.txt with only documentation and examples sections"

Tool Name: create_llms_txt

Parameters:

• project_name (string): Name of your project
• description (string): Brief project description
• scan_directory (string, optional): Directory to scan (default: ".")
• sections (list, optional): Specific sections to include (e.g., ["documentation", "examples"])

Available Sections: documentation, examples, api, guides, configuration

Example Response:

{
  "content": "# My Project\n\n> A comprehensive Python library\n\n## Documentation\n\n- [README](README.md): Project overview and getting started\n- [Contributing Guide](CONTRIBUTING.md): Guidelines for contributing\n\n## Examples\n\n- [Basic Example](examples/basic.py): Example code\n",
  "discovered_files": {
    "documentation": ["README.md", "CONTRIBUTING.md"],
    "examples": ["examples/basic.py"]
  },
  "suggested_path": "./llms.txt",
  "status": "success"
}

🧪 Testing

Run the test suite:

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/mcp_package_hero --cov-report=html

# Run with coverage summary
uv run pytest --cov=src/mcp_package_hero --cov-report=term-missing

# Run specific test file
uv run pytest tests/test_registries/test_pypi.py

Test Results

• ✅ 62/62 tests passing
• ✅ Comprehensive coverage for version checking, rating, and llms.txt features
• ✅ All three ecosystems validated with live API calls

🏗️ Development

Project Structure

mcp-package-hero/
├── src/mcp_package_hero/
│   ├── __init__.py
│   ├── server.py              # Main FastMCP server
│   ├── models.py              # Pydantic models
│   ├── github_client.py       # GitHub API client
│   ├── rating_calculator.py   # Rating algorithms
│   ├── registries/            # Version checking
│   │   ├── base.py
│   │   ├── pypi.py
│   │   ├── npm.py
│   │   └── pubdev.py
│   └── raters/                # Quality rating
│       ├── python_rater.py
│       ├── javascript_rater.py
│       └── dart_rater.py
├── tests/
├── README.md
└── pyproject.toml

Code Quality

# Format code
uv run ruff format .

# Lint code
uv run ruff check .

# Auto-fix safe linting issues
uv run ruff check --fix .

# Type check
uv run mypy src/

Quality Standards

• ✅ Type Safety: Full mypy compliance with Pydantic plugin
• ✅ Code Style: Ruff linting and formatting
• ✅ Modern Python: Python 3.10+ type hints (PEP 604)
• ✅ Timezone-Aware: All timestamps use UTC timezone
• ✅ Pydantic V2: Using latest ConfigDict patterns

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FastMCP by Prefect
• Inspired by mcp-package-version by Sam McLeod
• Part of the Model Context Protocol ecosystem

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

v1.2.0 ✅ (Current)

• llms.txt support - fetch documentation from packages
• llms.txt generation - create documentation for projects
• Multi-source fetching (GitHub, homepages)
• Documentation validation and parsing

v1.1.0 ✅

• Package quality rating system
• Multi-dimensional scoring (maintenance, popularity, quality)
• GitHub integration for repository metrics
• Integration with ecosystem-native scores (pub.dev, npms.io)

v1.3.0 (Planned)

• Additional ecosystems (Rust, Go, Swift)
• Cache layer for improved performance
• Support for specific version queries

v2.0 (Future)

• Dependency tree analysis
• Version compatibility checking
• Security vulnerability detection

---

Made with ☕️ by moinsen-dev