# Source: https://gofastmcp.com/python-sdk/fastmcp-utilities-versions.md

> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# versions

# `fastmcp.utilities.versions`

Version comparison utilities for component versioning.

This module provides utilities for comparing component versions. Versions are
strings that are first attempted to be parsed as PEP 440 versions (using the
`packaging` library), falling back to lexicographic string comparison.

Examples:

* "1", "2", "10" → parsed as PEP 440, compared semantically (1 \< 2 \< 10)
* "1.0", "2.0" → parsed as PEP 440
* "v1.0" → 'v' prefix stripped, parsed as "1.0"
* "2025-01-15" → not valid PEP 440, compared as strings
* None → sorts lowest (unversioned components)

## Functions

### `parse_version_key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L187" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
parse_version_key(version: str | None) -> VersionKey
```

Parse a version string into a sortable key.

**Args:**

* `version`: The version string, or None for unversioned.

**Returns:**

* A VersionKey suitable for sorting.

### `version_sort_key` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L199" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
version_sort_key(component: FastMCPComponent) -> VersionKey
```

Get a sort key for a component based on its version.

Use with sorted() or max() to order components by version.

**Args:**

* `component`: The component to get a sort key for.

**Returns:**

* A sortable VersionKey.

### `compare_versions` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L219" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
compare_versions(a: str | None, b: str | None) -> int
```

Compare two version strings.

**Args:**

* `a`: First version string (or None).
* `b`: Second version string (or None).

**Returns:**

* -1 if a \< b, 0 if a == b, 1 if a > b.

### `is_version_greater` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L241" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
is_version_greater(a: str | None, b: str | None) -> bool
```

Check if version a is greater than version b.

**Args:**

* `a`: First version string (or None).
* `b`: Second version string (or None).

**Returns:**

* True if a > b, False otherwise.

### `max_version` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L254" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
max_version(a: str | None, b: str | None) -> str | None
```

Return the greater of two versions.

**Args:**

* `a`: First version string (or None).
* `b`: Second version string (or None).

**Returns:**

* The greater version, or None if both are None.

### `min_version` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L271" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
min_version(a: str | None, b: str | None) -> str | None
```

Return the lesser of two versions.

**Args:**

* `a`: First version string (or None).
* `b`: Second version string (or None).

**Returns:**

* The lesser version, or None if both are None.

## Classes

### `VersionSpec` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L28" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

Specification for filtering components by version.

Used by transforms and providers to filter components to a specific
version or version range. Unversioned components (version=None) always
match any spec.

**Args:**

* `gte`: If set, only versions >= this value match.
* `lt`: If set, only versions \< this value match.
* `eq`: If set, only this exact version matches (gte/lt ignored).

**Methods:**

#### `matches` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L45" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
matches(self, version: str | None) -> bool
```

Check if a version matches this spec.

**Args:**

* `version`: The version to check, or None for unversioned.
* `match_none`: Whether unversioned (None) components match. Defaults to True
  for backward compatibility with retrieval operations. Set to False
  when filtering (e.g., enable/disable) to exclude unversioned components
  from version-specific rules.

**Returns:**

* True if the version matches the spec.

#### `intersect` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L78" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python  theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
intersect(self, other: VersionSpec | None) -> VersionSpec
```

Return a spec that satisfies both this spec and other.

Used by transforms to combine caller constraints with filter constraints.
For example, if a VersionFilter has lt="3.0" and caller requests eq="1.0",
the intersection validates "1.0" is in range and returns the exact spec.

**Args:**

* `other`: Another spec to intersect with, or None.

**Returns:**

* A VersionSpec that matches only versions satisfying both specs.

### `VersionKey` <sup><a href="https://github.com/jlowin/fastmcp/blob/main/src/fastmcp/utilities/versions.py#L114" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

A comparable version key that handles None, PEP 440 versions, and strings.

Comparison order:

1. None (unversioned) sorts lowest
2. PEP 440 versions sort by semantic version order
3. Invalid versions (strings) sort lexicographically
4. When comparing PEP 440 vs string, PEP 440 comes first