Skip to content

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

fix: return current tool schemas from cached BM25 searches (#5153)

Kyubum Hwang32f981cac072
diff --git a/fastmcp_slim/fastmcp/server/transforms/search/bm25.py b/fastmcp_slim/fastmcp/server/transforms/search/bm25.py
index b08a5a963..c1f26d87f 100644
--- a/fastmcp_slim/fastmcp/server/transforms/search/bm25.py
+++ b/fastmcp_slim/fastmcp/server/transforms/search/bm25.py
@@ -1,6 +1,7 @@
"""BM25-based search transform."""
import hashlib
+import json
import math
import re
import unicodedata
@@ -81,7 +82,7 @@ class _BM25Index:
def _catalog_hash(tools: Sequence[Tool]) -> str:
"""SHA256 hash of sorted tool searchable text for staleness detection."""
- key = "|".join(sorted(_extract_searchable_text(t) for t in tools))
+ key = json.dumps(sorted(_extract_searchable_text(t) for t in tools))
return hashlib.sha256(key.encode()).hexdigest()
@@ -89,7 +90,7 @@ class BM25SearchTransform(BaseSearchTransform):
"""Search transform using BM25 Okapi relevance ranking.
Maintains an in-memory index that is lazily rebuilt when the tool
- catalog changes (detected via a hash of tool names).
+ catalog's searchable text changes.
"""
def __init__(
@@ -109,7 +110,7 @@ class BM25SearchTransform(BaseSearchTransform):
search_result_serializer=search_result_serializer,
)
self._index = _BM25Index()
- self._indexed_tools: Sequence[Tool] = ()
+ self._indexed_names: list[str] = []
self._last_hash: str = ""
def _make_search_tool(self) -> Tool:
@@ -136,11 +137,13 @@ class BM25SearchTransform(BaseSearchTransform):
documents = [_extract_searchable_text(t) for t in tools]
new_index = _BM25Index(self._index.k1, self._index.b)
new_index.build(documents)
- self._index, self._indexed_tools, self._last_hash = (
+ self._index, self._indexed_names, self._last_hash = (
new_index,
- tools,
+ [t.name for t in tools],
current_hash,
)
indices = self._index.query(query, self._max_results)
- return [self._indexed_tools[i] for i in indices]
+ # The catalog is deduplicated by name; resolve the current version's schema.
+ tools_by_name = {t.name: t for t in tools}
+ return [tools_by_name[self._indexed_names[i]] for i in indices]
diff --git a/tests/experimental/transforms/test_code_mode_discovery.py b/tests/experimental/transforms/test_code_mode_discovery.py
index 932257ccd..ae20568b1 100644
--- a/tests/experimental/transforms/test_code_mode_discovery.py
+++ b/tests/experimental/transforms/test_code_mode_discovery.py
@@ -358,6 +358,32 @@ async def test_search_full_detail_empty_results_returns_json() -> None:
assert parsed == []
+async def test_search_full_detail_returns_current_schema() -> None:
+ mcp = FastMCP("CodeMode Updated Schema")
+ mcp.add_transform(CodeMode(sandbox_provider=_UnsafeTestSandboxProvider()))
+
+ @mcp.tool(name="convert", version="1")
+ def old(value: str) -> str:
+ """Convert a value."""
+ return value
+
+ arguments = {"query": "convert", "detail": "full"}
+ await _run_tool(mcp, "search", arguments)
+
+ @mcp.tool(name="convert", version="2")
+ def new(value: int = 1) -> int:
+ """Convert a value."""
+ return value
+
+ result = await _run_tool(mcp, "search", arguments)
+ current = await mcp.get_tool("convert")
+ assert current is not None
+ (found,) = json.loads(_unwrap_string_result(result))
+ assert found["inputSchema"] == current.parameters
+ assert found["outputSchema"] == current.output_schema
+ assert found["_meta"]["fastmcp"]["version"] == "2"
+
+
async def test_get_schema_empty_tools_list() -> None:
"""get_schema with an empty tools list returns no-match message."""
mcp = FastMCP("CodeMode Empty Schema")
diff --git a/tests/server/transforms/test_search.py b/tests/server/transforms/test_search.py
index 09a822ce6..b82eb5cb7 100644
--- a/tests/server/transforms/test_search.py
+++ b/tests/server/transforms/test_search.py
@@ -3,7 +3,7 @@
from __future__ import annotations
from collections.abc import Sequence
-from typing import Any
+from typing import Any, Literal
from unittest.mock import MagicMock
import mcp_types
@@ -326,6 +326,65 @@ class TestRegexSearch:
class TestBM25Search:
+ @pytest.mark.parametrize("version", ["1", "2"], ids=["replacement", "new-version"])
+ async def test_search_returns_current_schema(self, version: str) -> None:
+ mcp = FastMCP("test", on_duplicate="replace")
+ mcp.add_transform(BM25SearchTransform())
+
+ @mcp.tool(name="job_status", version="1")
+ def old(state: Literal["queued"]) -> str:
+ """Check job status."""
+ return state
+
+ await mcp.call_tool("search_tools", {"query": "status"})
+
+ @mcp.tool(name="job_status", version=version)
+ def new(state: Literal["running"]) -> int:
+ """Check job status."""
+ return 1
+
+ result = await mcp.call_tool("search_tools", {"query": "status"})
+ current = await mcp.get_tool("job_status")
+ assert current is not None
+ (found,) = _parse_tool_result(result)
+ assert found["inputSchema"] == current.parameters
+ assert found["outputSchema"] == current.output_schema
+ assert found["_meta"]["fastmcp"]["version"] == version
+
+ async def test_cached_index_resolves_current_tools_after_reordering(self) -> None:
+ def alpha() -> str:
+ return "alpha"
+
+ def beta() -> str:
+ return "beta"
+
+ first = Tool.from_function(alpha)
+ second = Tool.from_function(beta)
+ transform = BM25SearchTransform()
+ assert await transform._search([first, second], "alpha") == [first]
+ index = transform._index
+
+ updated = first.model_copy(update={"title": "Updated alpha"})
+ results = await transform._search([second, updated], "alpha")
+ assert results == [updated]
+ assert transform._index is index
+
+ async def test_search_rebuilds_when_description_contains_catalog_delimiter(
+ self,
+ ) -> None:
+ def action() -> str:
+ return "ok"
+
+ first = Tool.from_function(action, name="get", description="user data")
+ second = Tool.from_function(action, name="list", description="orders")
+ replacement = Tool.from_function(
+ action, name="get", description="user data|list orders"
+ )
+ transform = BM25SearchTransform()
+ assert await transform._search([first, second], "orders") == [second]
+
+ assert await transform._search([replacement], "orders") == [replacement]
+
async def test_search_relevance(self):
mcp = _make_server_with_tools()
mcp.add_transform(BM25SearchTransform())