Metadata-Version: 2.4
Name: bibliocommons-mcp-package-version-check
Version: 1.0.0
Summary: MCP server for checking latest package versions across 14 ecosystems
Author-email: Cody Lusk <cody.lusk@bibliocommons.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastmcp>=3.2.4
Requires-Dist: httpx>=0.28.1
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=7.1.0; extra == "dev"

# Package Version Check MCP Server

MCP server for checking latest stable package versions across 14 ecosystems. Supports Docker tag hints for suffix matching (e.g., `3.12-alpine`), Helm OCI registries, and GitHub Actions metadata lookup with optional README inclusion.

## Configuration

No authentication required for most registries. Optional `GITHUB_PAT` for higher GitHub API rate limits (Swift packages, GitHub Actions).

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GITHUB_PAT` | _(none)_ | GitHub personal access token for higher rate limits |
| `PACKAGE_VERSION_TIMEOUT` | `15` | HTTP request timeout in seconds |
| `PACKAGE_VERSION_TRANSPORT` | `stdio` | Transport mode: `stdio` or `http` |
| `PACKAGE_VERSION_PORT` | `8000` | Port for HTTP transport mode |

## Installation

### Option 1: Using uvx (Recommended)

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

No additional installation needed — `uvx` handles dependencies automatically.

### Option 2: Using pip

```bash
pip install bibliocommons-mcp-package-version-check
# or for development
pip install -e ".[dev]"
```

### Option 3: Docker

```bash
cd .. && docker build -f package-version-check/Dockerfile -t package-version-check-mcp:latest .
docker run --rm package-version-check-mcp:latest
```

## AI Client Setup

**Quick Links**: [Amazon Q](#amazon-q-developer-vs-code) | [Claude Desktop](#claude-desktop) | [VS Code](#vs-code-with-mcp-extension) | [GitHub Copilot](#github-copilot-vs-code) | [Cline](#cline-vs-code-extension) | [Zed](#zed-editor) | [Cursor](#cursor-ide) | [Kiro IDE](#kiro-ide) | [Kiro CLI](#kiro-cli)

### Amazon Q Developer (VS Code)

```json
{
  "amazonQ.mcp.servers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### VS Code (with MCP Extension)

```json
{
  "mcp.servers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### GitHub Copilot (VS Code)

```json
{
  "github.copilot.chat.mcp.servers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Cline (VS Code Extension)

```json
{
  "cline.mcpServers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Zed Editor

```json
{
  "mcpServers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Cursor IDE

```json
{
  "mcp.servers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Kiro IDE

```json
{
  "mcpServers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Kiro CLI

Create or edit `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "package-version-check": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/package-version-check", "bibliocommons-mcp-package-version-check"]
    }
  }
}
```

### Configuration Notes

- Replace `/absolute/path/to/package-version-check/` with the actual path to your server directory
- Set `GITHUB_PAT` environment variable for higher GitHub API rate limits
- After adding the configuration, restart your AI client for changes to take effect

## Supported Ecosystems

| Ecosystem | Registry | Package Format |
|-----------|----------|----------------|
| `npm` | npmjs.org | `express`, `@angular/core` |
| `pypi` | pypi.org | `requests`, `django` |
| `nuget` | nuget.org | `Newtonsoft.Json` |
| `maven_gradle` | Maven Central / Google Maven | `group:artifact` or `google:group:artifact` |
| `go` | proxy.golang.org | `golang.org/x/net` |
| `php` | packagist.org | `laravel/framework` |
| `rubygems` | rubygems.org | `rails` |
| `rust` | crates.io | `serde` |
| `swift` | GitHub tags | `github.com/owner/repo` |
| `dart` | pub.dev | `flutter` |
| `docker` | Docker Hub / any registry | `python`, `ghcr.io/org/image` |
| `helm` | ChartMuseum / OCI | `https://repo/chart` or `oci://registry/chart` |
| `terraform_provider` | Terraform Registry | `hashicorp/aws` |
| `terraform_module` | Terraform Registry | `hashicorp/consul/aws` |

## Examples

### Check package versions

```json
{
  "tool": "get_latest_package_versions",
  "arguments": {
    "packages": [
      {"ecosystem": "npm", "package_name": "express"},
      {"ecosystem": "pypi", "package_name": "django"},
      {"ecosystem": "docker", "package_name": "python", "version_hint": "3.12-alpine"},
      {"ecosystem": "helm", "package_name": "oci://ghcr.io/org/charts/app"},
      {"ecosystem": "terraform_provider", "package_name": "hashicorp/aws"}
    ]
  }
}
```

### Check GitHub Actions

```json
{
  "tool": "get_github_action_versions",
  "arguments": {
    "action_names": ["actions/checkout", "docker/login-action"],
    "include_readme": false
  }
}
```

## Standalone MCP Server

```bash
python -m bibliocommons_mcp_package_version_check
# or with HTTP transport
python -m bibliocommons_mcp_package_version_check --transport http --port 8000
```

## Security Notes

- No credentials required for public registries
- `GITHUB_PAT` is optional and only needed for higher rate limits
- All requests use HTTPS
- Docker registry auth tokens are ephemeral (per-request)
