# Container Tag Finder

**A simple API and MCP server that helps AI agents find the latest container image tags.**

## The Problem

AI agents often struggle with container image versioning:

- Web searches return outdated or inconsistent information
- Registry APIs require authentication and specific knowledge
- The "latest" tag is ambiguous—you usually want the latest *semantic version*

This project provides a clean API that returns the actual latest version tag, making it easy for agents to pin images to specific versions.

## Quick Start

### Run with Docker Compose (Recommended)

```bash
# Start the API server
docker compose up -d

# Test it
curl http://localhost:8080/latest/nginx
```

### Run the MCP server via Docker

```bash
# Interactive mode for MCP
docker compose run --rm mcp
```

### Local Installation

```bash
# Clone and install
cd container-tag-finder
pip install -e .
```

### Run the REST API (Local)

```bash
# Start the server (with hot reload for development)
RELOAD=true container-tag-finder

# Or directly
python -m container_tag_finder.server
```

The API will be available at `http://localhost:8080`. Try:

```bash
# Get latest nginx version
curl http://localhost:8080/latest/nginx

# Get latest Redis from Bitnami
curl http://localhost:8080/latest/bitnami/redis

# Get latest KEDA from GitHub Container Registry
curl "http://localhost:8080/latest/ghcr.io/kedacore/keda"

# Get latest PostgreSQL 16.x only
curl "http://localhost:8080/latest/postgres?major=16"
```

### Use as MCP Server

Add to your MCP configuration (e.g., Claude Desktop's `claude_desktop_config.json` or Cursor's MCP settings):

```json
{
  "mcpServers": {
    "container-tags": {
      "command": "container-tag-mcp",
      "args": []
    }
  }
}
```

Or with `uv`:

```json
{
  "mcpServers": {
    "container-tags": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/container-tag-finder", "container-tag-mcp"]
    }
  }
}
```

Or via Docker:

```json
{
  "mcpServers": {
    "container-tags": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/container-tag-finder/docker-compose.yml", "run", "--rm", "-T", "mcp"]
    }
  }
}
```

## API Reference

### `GET /latest/{image}`

Get the latest semantic version tag for an image. This is the primary endpoint for agents.

**Parameters:**

- `image` (path) - Image reference (e.g., `nginx`, `ghcr.io/owner/repo`)
- `include_prerelease` (query) - Include RC/beta versions (default: `false`)
- `major` (query) - Only consider this major version (e.g., `16` for PostgreSQL 16.x)
- `pattern` (query) - Regex filter for tags

**Example Response:**

```json
{
  "image": "nginx",
  "registry": "docker.io",
  "repository": "library/nginx",
  "latest_tag": "1.27.3",
  "latest_stable": "1.27.3",
  "full_reference": "nginx:1.27.3",
  "digest": "sha256:abc123...",
  "all_semver_tags": ["1.27.3", "1.27.2", "1.27.1", "1.26.2", ...]
}
```

### `GET /tags/{image}`

List all tags for an image with semantic version analysis.

**Parameters:**

- `image` (path) - Image reference
- `pattern` (query) - Regex filter
- `limit` (query) - Max tags to return (default: 50)

### `GET /compare/{image}?current={tag}`

Check if an update is available for a given tag.

**Example:**

```bash
curl "http://localhost:8080/compare/nginx?current=1.25.0"
```

**Response:**

```json
{
  "current_tag": "1.25.0",
  "current_is_semver": true,
  "latest_tag": "1.27.3",
  "update_available": true,
  "update_type": "minor",
  "message": "Update available: 1.25.0 → 1.27.3"
}
```

## MCP Tools

The MCP server provides three tools for AI agents:

### `get_latest_image_tag`

Find the latest version of a container image.

```
Input: { "image": "nginx" }
Output: Latest stable version with full reference
```

### `list_image_tags`

List available tags for an image.

```
Input: { "image": "postgres", "pattern": "^16\\." }
Output: All PostgreSQL 16.x tags
```

### `check_image_update`

Check if an update is available.

```
Input: { "image": "nginx", "current_tag": "1.25.0" }
Output: Update status and recommendation
```

## Supported Registries

- **Docker Hub** (`docker.io`) - Official and user images
- **GitHub Container Registry** (`ghcr.io`)
- **Quay.io** (`quay.io`)
- **Google Container Registry** (`gcr.io`)
- **Any OCI-compliant registry** - Generic support via OCI Distribution API

## Image Reference Formats

The API understands these formats:

| Input | Registry | Repository |
|-------|----------|------------|
| `nginx` | docker.io | library/nginx |
| `bitnami/redis` | docker.io | bitnami/redis |
| `ghcr.io/owner/repo` | ghcr.io | owner/repo |
| `quay.io/prometheus/prometheus` | quay.io | prometheus/prometheus |
| `gcr.io/project/image` | gcr.io | project/image |

## Version Detection

The API parses semantic versions from tags intelligently:

- Standard semver: `1.2.3`, `v1.2.3`
- With prerelease: `1.2.3-rc1`, `1.2.3-beta.2`
- With build metadata: `1.2.3+build123`
- Variant suffixes: `1.2.3-alpine`, `1.2.3-slim` (treated as prerelease)
- Two-part versions: `1.2` (treated as `1.2.0`)

Non-version tags like `latest`, `edge`, `nightly`, `sha-abc123` are automatically filtered out.

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
ruff format .
ruff check --fix .
```

## Why This Exists

When working with AI coding assistants on containerized applications, I found that:

1. Asking "what's the latest nginx version?" leads to web searches with outdated results
2. Agents can't easily query container registries directly
3. The "latest" tag is what agents default to, but it's bad practice for reproducibility

This API/MCP gives agents a reliable way to find the actual latest semantic version, making it easy to write `nginx:1.27.3` instead of `nginx:latest`.

## License

MIT