Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

fix(versions): deterministic meta.fastmcp.versions ordering (#4880)

feie15fc44bd53c
diff --git a/fastmcp_slim/fastmcp/utilities/versions.py b/fastmcp_slim/fastmcp/utilities/versions.py
index a8a7a898b..fc7c2d91e 100644
--- a/fastmcp_slim/fastmcp/utilities/versions.py
+++ b/fastmcp_slim/fastmcp/utilities/versions.py
@@ -327,9 +327,12 @@ def dedupe_with_versions(
for versions in by_key.values():
highest: C = max(versions, key=version_sort_key)
if any(c.version is not None for c in versions):
+ # Mirror version_sort_key's (VersionKey, raw) tuple so PEP 440-
+ # equivalent spellings ("1" vs "1.0") order by raw string instead
+ # of registration order β€” same determinism rule as selection.
all_versions = sorted(
[c.version for c in versions if c.version is not None],
- key=parse_version_key,
+ key=lambda v: (parse_version_key(v), v),
reverse=True,
)
meta = highest.meta or {}
diff --git a/tests/server/versioning/test_versioning.py b/tests/server/versioning/test_versioning.py
index 3e2355a37..6405e0d8b 100644
--- a/tests/server/versioning/test_versioning.py
+++ b/tests/server/versioning/test_versioning.py
@@ -14,6 +14,7 @@ from fastmcp.utilities.versions import (
VersionKey,
VersionSpec,
compare_versions,
+ dedupe_with_versions,
is_version_greater,
version_sort_key,
)
@@ -415,3 +416,56 @@ class TestVersionValidation:
"""FastMCP(version=False) should raise TypeError, not coerce to 'False'."""
with pytest.raises(TypeError, match="got bool"):
FastMCP(version=cast(str, False))
+
+
+class TestDedupeVersionMetadataDeterminism:
+ """The meta.fastmcp.versions list injected by dedupe_with_versions must
+ not depend on registration order.
+
+ Regression (issue #4867): the list was sorted with parse_version_key
+ alone, and sorted() is stable, so PEP 440-equivalent spellings ("1" vs
+ "1.0") kept their input order. The raw-string tie-breaker from #4058
+ (version_sort_key) now applies here too.
+ """
+
+ def _tool(self, version: str | None) -> Tool:
+ return Tool.from_function(lambda: None, name="demo", version=version)
+
+ def test_equivalent_spellings_order_independent(self):
+ forward = dedupe_with_versions(
+ [self._tool("1"), self._tool("1.0")], key_fn=lambda c: c.name
+ )
+ reverse = dedupe_with_versions(
+ [self._tool("1.0"), self._tool("1")], key_fn=lambda c: c.name
+ )
+ assert forward[0].meta is not None
+ assert forward[0].meta["fastmcp"]["versions"] == ["1.0", "1"]
+ assert reverse[0].meta is not None
+ assert reverse[0].meta["fastmcp"]["versions"] == ["1.0", "1"]
+
+ def test_primary_version_order_still_descending(self):
+ result = dedupe_with_versions(
+ [self._tool("1"), self._tool("2.0"), self._tool("1.10")],
+ key_fn=lambda c: c.name,
+ )
+ assert result[0].meta is not None
+ assert result[0].meta["fastmcp"]["versions"] == ["2.0", "1.10", "1"]
+
+ def test_unversioned_components_excluded_from_list(self):
+ result = dedupe_with_versions(
+ [self._tool(None), self._tool("1")], key_fn=lambda c: c.name
+ )
+ assert result[0].meta is not None
+ assert result[0].meta["fastmcp"]["versions"] == ["1"]
+
+ def test_malformed_versions_tiebreak_lexicographically(self):
+ forward = dedupe_with_versions(
+ [self._tool("latest"), self._tool("LATEST")], key_fn=lambda c: c.name
+ )
+ reverse = dedupe_with_versions(
+ [self._tool("LATEST"), self._tool("latest")], key_fn=lambda c: c.name
+ )
+ assert forward[0].meta is not None
+ assert forward[0].meta["fastmcp"]["versions"] == ["latest", "LATEST"]
+ assert reverse[0].meta is not None
+ assert reverse[0].meta["fastmcp"]["versions"] == ["latest", "LATEST"]