Versionator MCP
An MCP server that queries package registries (npm, RubyGems, PyPI, Hex.pm) for latest package versions
Installation
npx versionator-mcpAsk AI about Versionator MCP
Powered by Claude Β· Grounded in docs
I know everything about Versionator MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Versionator MCP Server
An MCP (Model Context Protocol) server that queries package registries across 19 different ecosystems to retrieve the latest release versions of packages. It follows a strict fail-hard policy and always returns current data.
Features
- 19 Package Registries: npm, RubyGems, PyPI, Hex.pm, crates.io, Bioconda, CRAN, Terraform Registry, DockerHub, CPAN, Go modules, Composer, NuGet, Homebrew, Nextflow, nf-core modules, nf-core subworkflows, Swift Package Manager, Maven Central
- Language/Ecosystem Aliases: Use familiar names like
python,rust,go, etc. - No Caching: Always returns current latest version
- Fail-Hard Error Handling: No fallbacks or stale data
- Rich Metadata: Package descriptions, homepages, and license information
- Configurable Timeouts: Adjust API request timeouts as needed
- Test Client Included:
vmcpcommand-line tool for testing and manual queries - Optimized for Claude Desktop Integration
Quick Start
Option 1: Using uvx (Recommended)
The easiest way to use Versionator with Claude Desktop is via uvx:
# Install uvx if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# Run Versionator directly with uvx
uvx versionator-mcp
Option 2: Install Locally
# Install from PyPI
pip install versionator-mcp
# Or install with pipx for isolated environment
pipx install versionator-mcp
Editor Integration
Claude Desktop
Add configuration to your Claude Desktop MCP settings:
Config Location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Recommended (uvx):
{
"mcpServers": {
"versionator": {
"command": "uvx",
"args": ["versionator-mcp"]
}
}
}
Alternative methods:
{
"mcpServers": {
"versionator": {
"command": "pipx",
"args": ["run", "versionator-mcp"]
}
}
}
Cursor
Create .cursor/mcp.json in your project root:
{
"mcpServers": {
"versionator": {
"command": "uvx",
"args": ["versionator-mcp"],
"env": {
"VERSIONATOR_REQUEST_TIMEOUT": "30"
}
}
}
}
Global configuration: ~/.cursor/mcp.json
Pro Tip: This repository includes a .cursor/mcp.json and .cursor/rules file that:
- Configures Versionator for immediate use
- Sets up rules to automatically check package versions before installations
- Ensures you always get current version information when working with dependencies
Windsurf
Edit ~/.codeium/mcp_config.json:
{
"mcpServers": {
"versionator": {
"command": "uvx",
"args": ["versionator-mcp"]
}
}
}
UI Method: Settings β Tools β Windsurf Settings β Add Server
Claude Code
Add to your Claude Code MCP configuration:
{
"mcpServers": {
"versionator": {
"command": "uvx",
"args": ["versionator-mcp"]
}
}
}
π Example configs: See
examples/directory for complete configuration files
Available Functions
1. get_package_version - Universal Package Version Query
Query the latest version from any supported registry.
Parameters:
package_manager(str): Registry name or aliaspackage_name(str): Name of the package
Supported Registries:
npm(aliases:node,nodejs) - Node.js packagesrubygems(aliases:gem,ruby) - Ruby gemspypi(aliases:pip,python) - Python packageshex(aliases:elixir,hex.pm) - Elixir packagescrates(aliases:cargo,rust) - Rust cratesbioconda(aliases:conda) - Bioconda packagescran(aliases:r) - R packagesterraform(aliases:tf) - Terraform providersdockerhub(aliases:docker) - Docker imagescpan(aliases:perl) - Perl modulesgo(aliases:golang) - Go modulescomposer(aliases:php,packagist) - PHP packagesnuget(aliases:dotnet,.net) - .NET packageshomebrew(aliases:brew) - macOS packagesnextflow(aliases:nf-core) - Nextflow pipelinesnf-core-module(aliases:nfcore-module,nf-module) - nf-core modulesnf-core-subworkflow(aliases:nfcore-subworkflow,nf-subworkflow) - nf-core subworkflowsswift(aliases:spm) - Swift packagesmaven(aliases:mvn) - Java artifacts
Examples:
# Query npm package
get_package_version("npm", "react")
# Returns: {"name": "react", "version": "19.1.1", ...}
# Query with aliases
get_package_version("python", "django")
get_package_version("rust", "serde")
get_package_version("go", "github.com/gin-gonic/gin")
get_package_version("terraform", "hashicorp/aws")
get_package_version("docker", "nginx")
get_package_version("r", "ggplot2")
get_package_version("php", "symfony/console")
get_package_version("dotnet", "Newtonsoft.Json")
get_package_version("homebrew", "git")
get_package_version("nextflow", "nf-core/rnaseq")
get_package_version("nf-core-module", "fastqc")
get_package_version("nf-core-subworkflow", "bam_sort_stats_samtools")
get_package_version("swift", "apple/swift-package-manager")
get_package_version("maven", "org.springframework:spring-core")
2. Registry-Specific Functions
get_npm_package(package_name)- NPM packagesget_ruby_gem(gem_name)- RubyGems packagesget_python_package(package_name)- PyPI packagesget_elixir_package(package_name)- Hex.pm packagesget_rust_crate(crate_name)- Rust cratesget_bioconda_package(package_name)- Bioconda packagesget_r_package(package_name)- R packagesget_terraform_provider(provider_path)- Terraform providersget_docker_image(image_name)- Docker imagesget_perl_module(module_name)- Perl modulesget_go_module(module_path)- Go modulesget_php_package(package_name)- PHP/Composer packagesget_dotnet_package(package_name)- .NET/NuGet packagesget_homebrew_formula(formula_name)- Homebrew formulasget_nextflow_pipeline(pipeline_name)- Nextflow pipelinesget_nfcore_module(module_name)- nf-core modulesget_nfcore_subworkflow(subworkflow_name)- nf-core subworkflowsget_swift_package(package_name)- Swift packagesget_maven_artifact(artifact_name)- Maven artifacts
Response Format
All functions return a PackageVersion object:
{
"name": "react",
"version": "19.1.1",
"registry": "npm",
"registry_url": "https://registry.npmjs.org/react/latest",
"query_time": "2025-08-13T10:30:00Z",
"description": "React is a JavaScript library for building user interfaces.",
"homepage": "https://react.dev/",
"license": "MIT"
}
Testing with vmcp
The project includes a command-line test client called vmcp for manual testing and verification:
Installation and Usage
# Make the vmcp script executable (if needed)
chmod +x vmcp
# Query packages from different registries
./vmcp python pandas # Query PyPI for pandas
./vmcp npm react # Query npm for react
./vmcp rust serde # Query crates.io for serde
./vmcp go github.com/gin-gonic/gin # Query Go modules
./vmcp terraform hashicorp/aws # Query Terraform registry
./vmcp docker nginx # Query DockerHub
./vmcp perl JSON # Query CPAN
./vmcp r ggplot2 # Query CRAN
./vmcp bioconda samtools # Query Bioconda
./vmcp php symfony/console # Query Packagist for PHP packages
./vmcp dotnet Newtonsoft.Json # Query NuGet for .NET packages
./vmcp homebrew git # Query Homebrew formulas
./vmcp nextflow nf-core/rnaseq # Query Nextflow pipelines
./vmcp nf-core-module fastqc # Query nf-core modules
./vmcp nf-core-subworkflow bam_sort_stats_samtools # Query nf-core subworkflows
./vmcp swift apple/swift-package-manager # Query Swift packages
./vmcp maven org.springframework:spring-core # Query Maven Central
# List all available MCP tools
./vmcp --list-tools
# Check server health
./vmcp --health
Example Output
$ ./vmcp rust serde
π Querying rust/serde...
β
serde @ v1.0.215 (crates)
π A generic serialization/deserialization framework
π https://serde.rs
The vmcp client is particularly useful for:
- Testing your MCP setup before integrating with editors
- Verifying package queries work correctly
- Debugging connection issues with the MCP server
- Exploring available tools and their capabilities
Error Handling
The server follows a strict FAIL HARD policy:
- No Fallbacks: Never returns cached or default values
- No Suppression: All errors propagate to the caller
- Clear Messages: Errors include context and details
- Input Validation: Validates before making API calls
Common errors:
ValueError: Invalid package name or unknown package managerException: Package not found or API failures
Configuration
Environment variables (optional):
VERSIONATOR_REQUEST_TIMEOUT: API request timeout in seconds (default: 30)
Troubleshooting
Common MCP Issues
- Server not starting: Check that the command path is correct in your configuration
- Permission errors: Ensure the Python executable has proper permissions
- Package not found: Verify the package is installed and accessible from the command line
- Editor not detecting server: Restart your editor after adding MCP configuration
Testing Your Setup
You can test the server directly from the command line:
# Test with uvx
uvx versionator-mcp
# Test with pipx
pipx run versionator-mcp
# Test direct installation
python -m versionator_mcp.main
The server should start and show initialization messages. Press Ctrl+C to stop.
Alternative: HTTP Server Mode
For advanced use cases, you can run Versionator as an HTTP server:
# Start HTTP server (default port 8083)
FASTMCP_PORT=8083 python -m versionator_mcp.main
# Custom port
FASTMCP_PORT=9000 python -m versionator_mcp.main
Then configure Claude Desktop with:
{
"mcpServers": {
"versionator": {
"url": "http://localhost:8083/mcp",
"transport": "http"
}
}
}
Note: HTTP mode requires manually starting the server before using Claude Desktop.
Development
Setup
# Clone the repository
git clone https://github.com/trianglegrrl/versionator-mcp.git
cd versionator-mcp
# Install in development mode with dev dependencies
pip install -e ".[dev]"
Project Structure
The project follows a clean, modular architecture:
versionator_mcp/
βββ __init__.py
βββ app.py # FastMCP app factory and configuration
βββ config.py # Environment configuration management
βββ main.py # Entry point for the MCP server
βββ models.py # Pydantic data models
βββ core/ # Core utilities and base classes
β βββ __init__.py
β βββ base_registry.py # Abstract base class for registries
β βββ http_client.py # Shared HTTP client utilities
β βββ registry_factory.py # Registry factory and mapping
βββ registries/ # Individual registry implementations
β βββ __init__.py
β βββ npm.py # NPM registry
β βββ rubygems.py # RubyGems registry
β βββ pypi.py # PyPI registry
β βββ hex.py # Hex.pm registry
β βββ crates.py # Crates.io registry
β βββ bioconda.py # Bioconda registry
β βββ cran.py # CRAN registry
β βββ terraform.py # Terraform registry
β βββ dockerhub.py # DockerHub registry
β βββ cpan.py # CPAN registry
β βββ go.py # Go modules registry
β βββ composer.py # PHP Composer registry
β βββ nuget.py # NuGet registry
β βββ homebrew.py # Homebrew registry
β βββ nextflow.py # Nextflow registry
β βββ nfcore.py # nf-core modules/subworkflows
β βββ swift.py # Swift Package Manager
β βββ maven.py # Maven Central
βββ tools/ # MCP tool registration
βββ __init__.py
βββ registry_tools.py # MCP tool definitions
Architecture Benefits
- Modular Design: Each registry is implemented in its own file with a consistent interface
- Single Responsibility: Each module has a clear, focused purpose
- Easy Extension: Adding new registries requires minimal changes to existing code
- Testability: Individual registries can be tested in isolation
- Maintainability: Changes to one registry don't affect others
- DRY Principle: Common HTTP logic is shared across all registries
Adding New Registries
To add support for a new package registry:
- Create Registry Implementation: Create a new file in
versionator_mcp/registries/(e.g.,new_registry.py) - Extend BaseRegistry: Implement the abstract methods from
BaseRegistry - Register with Factory: Call
register_registry()with your class and aliases - Add MCP Tool: Add corresponding tool function in
registry_tools.py
Example:
# versionator_mcp/registries/new_registry.py
from ..core import BaseRegistry, register_registry
from ..models import PackageVersion
class NewRegistry(BaseRegistry):
@property
def registry_name(self) -> str:
return "new_registry"
async def get_latest_version(self, package_name: str) -> PackageVersion:
package_name = self.validate_package_name(package_name)
url = f"https://api.new-registry.com/packages/{package_name}"
data = await self.http_client.get_json(url, registry_name="NewRegistry", package_name=package_name)
return PackageVersion(
name=package_name,
version=data.get("version", "unknown"),
registry="new_registry",
registry_url=url,
query_time=self.http_client.get_current_timestamp(),
description=data.get("description"),
homepage=data.get("homepage"),
license=data.get("license"),
)
# Register with aliases
register_registry(NewRegistry, ["new", "nr"])
Pre-commit Hooks (Recommended)
This project uses pre-commit hooks to ensure code quality and prevent issues:
# Install pre-commit hooks
pre-commit install
pre-commit install --hook-type pre-push
# Run hooks manually on all files
pre-commit run --all-files
Pre-commit hooks (run on git commit):
- Trailing whitespace removal, end-of-file fixing, YAML validation
- Large file detection, merge conflict detection, debug statement detection
- Black code formatting, isort import sorting, mypy type checking
Pre-push hooks (run on git push):
- pytest test suite (skips GitHub API tests to avoid rate limits)
The hooks automatically fix formatting issues when possible and prevent commits/pushes that don't meet quality standards.
Running Tests
# Run tests
pytest
# Run tests with coverage
pytest --cov=versionator_mcp
# Run linting
black --check .
isort --check-only .
mypy versionator_mcp/
Testing the MCP Server
# Test stdio transport (default)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python -m versionator_mcp.main
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes and add tests
- Run the test suite (
pytest) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Registry APIs
The server queries these endpoints:
- npm:
https://registry.npmjs.org/{package}/latest - RubyGems:
https://rubygems.org/api/v1/versions/{gem}/latest.json - PyPI:
https://pypi.org/pypi/{package}/json - Hex.pm:
https://hex.pm/api/packages/{package} - crates.io:
https://crates.io/api/v1/crates/{crate} - Bioconda:
https://api.anaconda.org/package/bioconda/{package} - CRAN:
https://crandb.r-pkg.org/{package} - Terraform:
https://registry.terraform.io/v1/providers/{provider_path} - DockerHub:
https://hub.docker.com/v2/repositories/{namespace}/{repo}/tags - CPAN:
https://fastapi.metacpan.org/v1/module/{module} - Go Modules:
https://api.github.com/repos/{owner}/{repo}/releases/latest(GitHub-hosted) - Composer:
https://packagist.org/packages/{vendor}/{package}.json - NuGet:
https://api.nuget.org/v3-flatcontainer/{package}/index.json - Homebrew:
https://formulae.brew.sh/api/formula/{formula}.json - Nextflow:
https://api.github.com/repos/nf-core/{pipeline}/releases/latest - nf-core modules:
https://api.github.com/repos/nf-core/modules/commits?path=modules/nf-core/{module} - nf-core subworkflows:
https://api.github.com/repos/nf-core/modules/commits?path=subworkflows/nf-core/{subworkflow} - Swift:
https://api.github.com/repos/{owner}/{repo}/releases/latest - Maven:
https://search.maven.org/solrsearch/select?q=g:{group}+AND+a:{artifact}
Performance Considerations
- No Caching: Each call makes a fresh API request
- Timeout: Configurable via
VERSIONATOR_REQUEST_TIMEOUT - Concurrent Requests: Async implementation allows parallel queries
- Rate Limits: Be mindful of registry rate limits
License
This project is licensed under the MIT License - see the LICENSE file for details.
Changelog
v1.3.1 (Release Process Fix)
- FIXED: GitHub Release creation process for automated PyPI publishing
- IMPROVED: Proper workflow trigger configuration for seamless releases
- MAINTAINED: All v1.3.0 features and improvements included
v1.3.0 (Refactored Architecture & Type Safety)
- REFACTORED: Complete codebase restructure for improved maintainability
- NEW: Modular registry architecture with individual files for each package manager
- NEW: Abstract base class pattern for consistent registry implementations
- NEW: Factory pattern for registry management and discovery
- NEW: Shared HTTP client utilities to eliminate code duplication
- NEW: Modular test structure mirroring the main codebase organization
- IMPROVED: 100% type safety compliance - zero mypy errors across 30 source files
- IMPROVED: Enhanced type annotations throughout the entire codebase
- IMPROVED: HTTP client return type flexibility for diverse API responses
- IMPROVED: Proper forward reference handling for type checking
- IMPROVED: Registry factory type safety with Optional parameter handling
- IMPROVED: Separation of concerns - MCP tools, registries, and core utilities
- IMPROVED: Easy extensibility - adding new registries requires minimal code changes
- IMPROVED: Better testability with isolated registry implementations
- IMPROVED: Consistent error handling across all registries
- IMPROVED: Developer experience with clear project structure and full IDE type support
- MAINTAINED: Full backward compatibility - all existing functionality preserved
- MAINTAINED: All 19 package registries with identical behavior
- MAINTAINED: Complete MCP tool compatibility
- QUALITY: 56 comprehensive tests passing with 6 appropriately skipped in CI
- QUALITY: Organized test structure with individual files per registry
v1.2.3
- FIXED: GitHub API rate limit issues in CI by skipping GitHub-dependent tests
- IMPROVED: CI reliability - 47 tests pass, 15 appropriately skipped in CI environment
- ENHANCED: Maintains full test coverage locally while ensuring green CI builds
- QUALITY: Resolves PyPI publish workflow failures caused by rate limiting
- All features from v1.2.2 included with CI reliability improvements
v1.2.2
- FIXED: Black code formatting compliance for nf-core functions
- IMPROVED: CI/CD pipeline reliability with direct test execution in publish workflow
- ENHANCED: Eliminated race condition between CI status checking and PyPI publish
- All features from v1.2.1 included with formatting fixes
v1.2.1
- NEW: Added support for nf-core modules and subworkflows:
- nf-core modules -
nf-core-module,nfcore-module,nf-module - nf-core subworkflows -
nf-core-subworkflow,nfcore-subworkflow,nf-subworkflow
- nf-core modules -
- NEW: Registry-specific MCP tools:
get_nfcore_module(module_name)for nf-core modulesget_nfcore_subworkflow(subworkflow_name)for nf-core subworkflows
- IMPROVED: Enhanced Nextflow ecosystem coverage for scientific computing
- IMPROVED: Updated documentation with nf-core module/subworkflow examples
- QUALITY: 62 comprehensive tests - all passing β
- QUALITY: Full backward compatibility maintained
v1.2.0
- NEW: Added support for 6 additional package registries:
- PHP Composer (Packagist) -
composer,php,packagist - .NET NuGet -
nuget,dotnet,.net - Homebrew -
homebrew,brew - Nextflow (nf-core) -
nextflow,nf-core - Swift Package Manager -
swift,spm - Maven Central -
maven,mvn
- PHP Composer (Packagist) -
- NEW: Registry-specific MCP tools for all new package managers
- IMPROVED: Enhanced vmcp test client with examples for all 17 registries
- IMPROVED: Comprehensive documentation updates with new API endpoints
- IMPROVED: Updated error messages and validation for new registries
- QUALITY: 56 comprehensive tests - all passing β
- QUALITY: Full backward compatibility maintained
v1.1.0
- NEW: Added support for 7 additional package registries:
- Rust (crates.io) -
rust,cargo,crates - Bioconda (anaconda.org) -
bioconda,conda - R (CRAN) -
r,cran - Terraform Registry -
terraform,tf - DockerHub -
docker,dockerhub - Perl (CPAN) -
perl,cpan - Go Modules -
go,golang
- Rust (crates.io) -
- NEW: Added
vmcpcommand-line test client - NEW: Registry-specific MCP tools for each package manager
- IMPROVED: Enhanced documentation with comprehensive examples
- IMPROVED: Updated error messages and validation
v1.0.0
- Initial release
- Support for npm, RubyGems, PyPI, and Hex.pm
- Optimized for Claude Desktop integration
- uvx and pipx support
- Comprehensive error handling
- MCP protocol compliance
