# SemVer Version Manager MCP

> SemVer Version Manager gives your AI client absolute authority over software versions. Stop relying on large language models to guess dependency compatibility or sort release tags. This MCP deterministically evaluates semantic version ranges and orders messy arrays of releases, making your CI/CD pipeline mathematically perfect every time.

## Overview
- **Category:** productivity
- **Price:** Free
- **Tags:** semantic-versioning, dependency-management, software-lifecycle, version-control, parsing

## Description

When working with package files like `package.json`, LLMs frequently mess up the math. They might hallucinate that a version satisfies a peer dependency range (like `>=1.4.0 <2.0.0`), or they'll fail to sort release tags correctly, especially when pre-releases are involved. This MCP bypasses those guesswork moments by connecting directly to the official NPM SemVer engine. It lets your AI client run real version checks—the kind that keep production builds from failing due to faulty logic. Whether you're validating a specific version against a complex range or need to reliably sort dozens of release candidates, this tool handles all the heavy lifting with true determinism. Because Vinkius hosts this MCP, you get access to mathematically sound dependency resolution right where you need it.

## Tools

### check_semver_compatibility
Checks if a given software version fits within a defined semantic version range, like `^1.4.2`.

### sort_semver_list
Takes an array of mixed release tags and correctly sorts them according to official semantic versioning rules.

## Prompt Examples

**Prompt:** 
```
Verify deterministically if version `2.4.1` satisfies the peer dependency range `^2.0.0`.
```

**Response:** 
```
✅ **SemVer Result:** Satisfied. `2.4.1` is safely within the `^2.0.0` caret constraints.
```

**Prompt:** 
```
Sort this array of 12 release tags (including `-rc.1` and `-beta`) in descending order.
```

**Response:** 
```
✅ **Sorted Order:**
1. `v2.0.0`
2. `v2.0.0-rc.1`
3. `v2.0.0-beta.2`
...
```

**Prompt:** 
```
What is the result of applying a 'minor' bump to version `1.4.3-alpha`?
```

**Response:** 
```
✅ **New Version:** `1.5.0`. The alpha pre-release tag is dropped during a standard minor bump.
```

## Capabilities

### Check version compatibility
It checks if a given software version satisfies a specific semantic version range (e.g., `^1.4.2`).

### Sort release versions
It takes an unordered list of different software tags and sorts them correctly according to semantic rules.

## Use Cases

### Validating a new package dependency
A developer needs to confirm if their current app version (`2.4.1`) satisfies the peer dependency range of an old library (`^2.0.0`). They use `check_semver_compatibility` and instantly get confirmation, knowing they won't deploy a broken build.

### Preparing release notes for documentation
The Release Manager pulls in 50 version tags from Jira—a mix of major, minor, patch, and beta releases. They use `sort_semver_list` to generate the exact chronological list needed for the official changelog.

### Troubleshooting CI/CD build failures
A developer's agent keeps failing because it thinks a version is compatible when it isn't. They use `check_semver_compatibility` to run a deterministic test, proving the dependency failure and fixing the underlying configuration.

### Comparing multiple component versions
An agent needs to compare three different library tags (`v1.0.0`, `v2.0.0-beta`, `v1.9.5`) to decide which one to use in a new module. They pass them through `sort_semver_list` for accurate comparison.

## Benefits

- Eliminate dependency guessing: Instead of hoping the AI client gets version math right, use `check_semver_compatibility` to confirm if a specific package version fits its required range. This stops build failures cold.
- Perfect release ordering: If you have a mix of versions (like `v2.0.0`, `v2.0.0-rc.1`, and `v1.5.0`), the `sort_semver_list` tool delivers them in the correct, deterministic sequence every time.
- Absolute determinism: This MCP uses the official NPM SemVer engine, meaning your version logic is based on established standards, not general LLM knowledge. You get reliable results for critical CI/CD steps.
- Reduced debugging time: By offloading complex version checks, you cut down hours spent manually verifying which libraries are compatible with each other across different environments.
- Handles pre-releases properly: It correctly handles complicated tags like alpha and beta versions, ensuring that your release notes or build order is perfectly accurate.

## How It Works

The bottom line is you get reliable version math that doesn't rely on guesswork.

1. You tell your agent exactly what you need: either a specific version check against a range, or an unsorted array of release versions.
2. The MCP sends the data to the underlying NPM SemVer engine for calculation and verification.
3. Your client gets back a definitive answer—a clear pass/fail on compatibility, or a perfectly ordered list.

## Frequently Asked Questions

**Does SemVer Version Manager handle pre-release tags?**
Yes, absolutely. It uses the official NPM engine, so it correctly handles complex pre-release tags like `-rc.1` and `alpha`, ensuring proper sorting and compatibility checks.

**How do I use SemVer Version Manager to check dependency ranges?**
You call the `check_semver_compatibility` tool. You provide two inputs: the version you want to test, and the required range (like `^2.0.0`). It returns a clear 'Satisfied' or 'Not satisfied' status.

**Can SemVer Version Manager sort versions from different years?**
Yes. The `sort_semver_list` tool is designed to handle full semantic versioning logic, ensuring that the order remains correct even when mixing major, minor, and patch releases across large time gaps.

**Is SemVer Version Manager only for JavaScript projects?**
No. While it uses NPM's engine as its backend source of truth, the MCP provides deterministic semantic versioning logic that applies to any software project using standard semver guidelines.

**What is the difference between this and writing a regex?**
A regex can validate a format (e.g., 'does it look like X.Y.Z'), but `check_semver_compatibility` performs actual mathematical logic on version constraints, which is far more reliable for dependency management.