Metadata-Version: 2.4
Name: bibliocommons-mcp-package-version-check
Version: 1.3.5
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
Requires-Dist: python-multipart>=0.0.27
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]"
```

## AI Client Setup

### 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"]
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "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

For other AI clients (Amazon Q, GitHub Copilot, Cline, Zed, Cursor), see [docs/ai-clients.md](docs/ai-clients.md).

## Docker

```bash
# Pull from Docker Hub (private)
docker pull bibliocommons/mcp-package-version-check:latest

# Run in stdio mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-package-version-check:latest \
  --config /config.json

# Run in HTTP mode
docker run -d --rm \
  -v /path/to/config.json:/config.json:ro \
  -p 8000:8000 \
  bibliocommons/mcp-package-version-check:latest \
  --config /config.json --transport http --port 8000

# Run in expanded mode
docker run -i --rm \
  -v /path/to/config.json:/config.json:ro \
  bibliocommons/mcp-package-version-check:latest \
  --config /config.json --expanded
```

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

### CLI Flags

| Flag | Env Var | Description |
|------|---------|-------------|
| `--expanded` | `PACKAGE_VERSION_EXPANDED` | Register all tools individually instead of gateway mode |
| `--transport stdio\|http` | `PACKAGE_VERSION_TRANSPORT` | Transport mode (default: stdio) |
| `--port PORT` | `PACKAGE_VERSION_PORT` | HTTP port (default: 8000) |
| `--version` | — | Show version and exit |

## Gateway Mode (Default)

By default, the server exposes 2 tools instead of individual tools:

| Tool | Purpose |
|------|---------|
| `package_version_api` | Execute any package version action by name with a params dict |
| `package_version_help` | Search available actions, parameters, and descriptions |

The AI assistant calls `package_version_help` to discover available actions, then calls `package_version_api(action="get_latest_package_versions", params={"packages": [...]})` to execute them.

To register all individual tools (previous behavior), use `--expanded`:

```bash
python -m bibliocommons_mcp_package_version_check --expanded
```

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