> ## Documentation Index
> Fetch the complete documentation index at: https://gofastmcp.com/docs/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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L197](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L197)</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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L209](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L209)</sup>

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

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

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

The key is a `(VersionKey, raw)` tuple. The `VersionKey` orders by PEP 440
semantics (or lexicographically for non-PEP 440 strings); the raw version
string is a deterministic tie-breaker so that two components whose versions
are PEP 440-equivalent but spelled differently (e.g. `"1"` and `"1.0"`) are
ordered reproducibly instead of by registration order. The raw tie-breaker
only affects equivalent-version ties and never the primary version order,
so range/equality matching (which uses `VersionKey` directly) is unchanged.

**Args:**

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

**Returns:**

* A deterministic, sortable `(VersionKey, raw)` tuple.

### `compare_versions` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L237](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L237)</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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L259](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L259)</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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L272](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L272)</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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L289](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L289)</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.

### `dedupe_with_versions` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L306](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L306)</sup>

```python theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
dedupe_with_versions(components: Sequence[C], key_fn: Callable[[C], str]) -> list[C]
```

Deduplicate components by key, keeping highest version.

Groups components by key, selects the highest version from each group,
and injects available versions into meta if any component is versioned.

**Args:**

* `components`: Sequence of components to deduplicate.
* `key_fn`: Function to extract the grouping key from a component.

**Returns:**

* Deduplicated list with versions injected into meta.

## Classes

### `VersionSpec` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L31](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L31)</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).
  Matching is PEP 440-normalized and `v`-prefix insensitive, so
  `eq="v1.0"` matches a component versioned `"1.0"`, and `eq="1.0"`
  matches `"1"` (PEP 440 treats `1` and `1.0` as the same version).
  If a server registers two PEP 440-equivalent spellings of the
  same component (e.g. both `"1"` and `"1.0"`), they are the same
  version under this spec; selection among them is deterministic
  (see `version_sort_key`), not registration-order dependent.

**Methods:**

#### `matches` <sup>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L55](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L55)</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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L88](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L88)</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>[https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp\_slim/fastmcp/utilities/versions.py#L124](https://github.com/PrefectHQ/fastmcp/blob/main/fastmcp_slim/fastmcp/utilities/versions.py#L124)</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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.