π The fast, Pythonic way to build MCP servers and clients.
Honor Code Mode search limits after BM25 ranking (#5715)
Winorenee713912c709
diff --git a/docs/servers/transforms/code-mode.mdx b/docs/servers/transforms/code-mode.mdxindex c8108162d..74f6e833e 100644--- a/docs/servers/transforms/code-mode.mdx+++ b/docs/servers/transforms/code-mode.mdx@@ -133,7 +133,7 @@ CodeMode ships with four built-in discovery tools: `Search`, `GetSchemas`, `GetTSearch results include an annotation like `"2 of 10 tools:"` when the result set is smaller than the full catalog, so the LLM knows there are more tools to discover with different queries.-You can cap result count with `default_limit`. The LLM can also override the limit per call. This is useful for large catalogs where you want to keep search results focused:+By default, `Search` returns all matching tools (`default_limit=None`). You can cap the result count with `default_limit` to keep large catalogs focused. The LLM can override this limit per call, including requesting more results or passing `limit=None` to return all matches:```pythonSearch(default_limit=5) # return at most 5 results per searchdiff --git a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.pyindex 8ce99a591..af774e3bf 100644--- a/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py+++ b/fastmcp_slim/fastmcp/experimental/transforms/code_mode.py@@ -1,6 +1,7 @@import asyncioimport importlibimport json+import sysfrom collections.abc import Awaitable, Callable, Sequencefrom typing import TYPE_CHECKING, Annotated, Any, Literal, Protocol@@ -375,7 +376,8 @@ class Search:if search_fn is None:from fastmcp.server.transforms.search.bm25 import BM25SearchTransform- _bm25 = BM25SearchTransform(max_results=default_limit or 50)+ # Search applies the per-call limit after ranking all matches.+ _bm25 = BM25SearchTransform(max_results=sys.maxsize)search_fn = _bm25._searchself._search_fn = search_fnself._name = name@@ -421,7 +423,9 @@ class Search:]results = await search_fn(tools, query)if limit is not None:- results = results[:limit]+ # A limit is a maximum count, not a slice offset: clamp negatives+ # so ``limit=-1`` does not mean "all but the last match".+ results = results[: max(limit, 0)]rendered = _render_tools(results, detail)if len(results) < catalog_size and detail != "full":n = len(results)diff --git a/tests/experimental/transforms/test_code_mode_search_limits.py b/tests/experimental/transforms/test_code_mode_search_limits.pynew file mode 100644index 000000000..045c3a772--- /dev/null+++ b/tests/experimental/transforms/test_code_mode_search_limits.py@@ -0,0 +1,100 @@+"""Code Mode must apply result limits after ranking the complete catalog."""++import json++import pytest++from fastmcp import Client, FastMCP+from fastmcp.experimental.transforms.code_mode import CodeMode, Search+from fastmcp.tools import Tool++CATALOG_SIZE = 60+++def _ranked_catalog() -> FastMCP:+ """Build a catalog whose BM25 ranking is the reverse of its registration order.++ Every tool repeats the query token a different number of times, so no two+ scores tie. The best match is therefore registered last, which makes the+ difference between ranking-then-slicing and slicing-then-ranking visible in+ the returned names instead of hiding behind catalogue order.+ """+ server = FastMCP("Search limits")++ def add_one(x: int) -> int:+ """Add one to a number."""+ return x + 1++ for index in range(CATALOG_SIZE):+ server.add_tool(+ Tool.from_function(+ add_one,+ name=f"add_{index:02d}",+ description="Add one to a number. " + "add " * index,+ )+ )+ return server+++# Relevance rises with the registration index, so this is the ranked order.+_RANKED_NAMES = [f"add_{index:02d}" for index in range(CATALOG_SIZE - 1, -1, -1)]+++ "default_limit, override, expected_count",+ [+ (None, {}, CATALOG_SIZE),+ (None, {"limit": 55}, 55),+ (None, {"limit": 0}, 0),+ (5, {}, 5),+ (5, {"limit": 55}, 55),+ (5, {"limit": None}, CATALOG_SIZE),+ (55, {}, 55),+ ],+)+async def test_search_applies_limits_after_ranking(+ default_limit: int | None,+ override: dict[str, int | None],+ expected_count: int,+) -> None:+ server = _ranked_catalog()+ server.add_transform(+ CodeMode(discovery_tools=[Search(default_limit=default_limit)])+ )++ async with Client(server) as client:+ result = await client.call_tool(+ "search", {"query": "add", "detail": "full", **override}+ )++ matches = json.loads(result.data)+ assert [match["name"] for match in matches] == _RANKED_NAMES[:expected_count]++[email protected]("limit", [-1, -5, -60, -61])+async def test_search_reads_a_negative_limit_as_a_count(limit: int) -> None:+ """A limit is a maximum result count, so it can never be negative.++ Python's slice semantics would otherwise read ``limit=-1`` as "all but the+ last one", which is a fine reading of a slice and a wrong reading of a cap.+ """+ server = _ranked_catalog()+ server.add_transform(CodeMode(discovery_tools=[Search()]))++ async with Client(server) as client:+ result = await client.call_tool(+ "search", {"query": "add", "detail": "full", "limit": limit}+ )++ assert json.loads(result.data) == []+++async def test_search_first_result_is_the_best_match_registered_last() -> None:+ """Ranking decides what survives a small limit, not registration order."""+ server = _ranked_catalog()+ server.add_transform(CodeMode(discovery_tools=[Search(default_limit=3)]))++ async with Client(server) as client:+ result = await client.call_tool("search", {"query": "add", "detail": "full"})++ assert [match["name"] for match in json.loads(result.data)] == _RANKED_NAMES[:3]