# No installation needed! Just use uvx to run it directly
uvx mcp-package-hero

# Or install it as a tool for repeated use
uv tool install mcp-package-hero

# 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 in editable mode
uv pip install -e .

{
  "mcpServers": {
    "package-hero": {
      "command": "uvx",
      "args": ["mcp-package-hero"]
    }
  }
}

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

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

{
  "mcpServers": {
    "package-hero": {
      "command": "uvx",
      "args": ["mcp-package-hero"]
    }
  }
}

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

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

claude mcp add-json package-hero '{"type":"stdio","command":"uvx","args":["mcp-package-hero"]}'

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"]}'

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

# 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"
"What's the latest version of serde in Rust?"

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

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

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

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

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

# 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"
"Get the llms.txt for tokio"

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

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

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

# 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

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

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