feat: built-in tool search (BM25) for large tool catalogs, like FastMCP's search_tools #1448

Is your feature request related to a problem? Please describe.

In FastMCP, in Python, we have a function called search_tools that exposes a built-in search engine (using BM25) on the MCP server's tools. Since FastMCP 3.1.0, a server can replace its full tool listing with two synthetic tools:

• search_tools, which returns the matching tools with their full definitions (including input schemas), so the LLM can call them right away;
• call_tool, which runs a discovered tool by name.

This is available as BM25SearchTransform (natural-language query, ranked with BM25 Okapi) and RegexSearchTransform (regex pattern).

There is nothing like this in rmcp today. This matters for servers that expose a large number of tools. I am building an MCP gateway in Rust that aggregates several upstream MCP servers, so it can easily expose hundreds of tools. Sending the whole catalog in tools/list:

• uses up a large part of the model's context window before the conversation even starts;
• lowers tool-selection accuracy, since models get worse at picking the right tool as the list grows;
• costs more tokens on every request.

Every Rust project in this situation currently has to write its own indexing, ranking and synthetic-tool plumbing.

Describe the solution you'd like

I would like rmcp to provide an opt-in tool search layer, similar to FastMCP's transforms, behind a cargo feature (e.g. tool-search) so it adds no dependencies for users who don't need it.

Proposed behavior:

1. A search index over tools: build an in-memory BM25 index from each tool's name, title, description and (optionally) parameter names/descriptions. Build it lazily and rebuild it when the tool list changes (e.g. on notifications/tools/list_changed).
2. A standalone search API that can be used without exposing synthetic tools, which is what a gateway needs. Something like:

   let index = ToolSearchIndex::new(tools);           // Vec<Tool>
   let hits: Vec<ToolMatch> = index.search("create a github issue", 5);

3. An optional server-side wrapper that exposes search_tools / call_tool synthetic tools in place of the full listing, integrating with ToolRouter / ServerHandler:
   • max_results (default 5);
   • always_visible: tools that stay in tools/list and are left out of search results;
   • configurable names for the synthetic tools to avoid clashes;
   • call_tool refuses to call the synthetic tools themselves;
   • original tools remain callable directly (search controls discovery, not access).
4. Optionally, a regex search mode as a deterministic alternative to BM25, with a pattern-length limit and a timeout to guard against expensive patterns.

I'm happy to discuss the API shape (naming, where it should live in the crate, trait vs. struct) before writing any code.

Describe alternatives you've considered

• Implementing it only in my gateway. This works, but every Rust MCP server or gateway with a large catalog will end up rewriting the same logic. Having it upstream also keeps behavior consistent with FastMCP, which helps users who use both SDKs.
• Using a full-text search engine such as tantivy. Too heavy for indexing a few hundred short documents in memory. A small BM25 implementation (or a lightweight crate) is enough.
• Embedding-based semantic search. Better at synonyms, but it needs a model or an external API, which doesn't fit a core SDK. The design could keep the ranking backend behind a trait so users can plug in their own (BM25 by default, embeddings or anything else if they want).
• Relying on client-side tool search (some LLM providers offer deferred tool loading). This depends on the client and the provider, while a server/gateway-side solution works with any MCP client.

Additional context

• FastMCP documentation: https://gofastmcp.com/docs/servers/transforms/tool-search
• Use case: an MCP gateway written in Rust that aggregates multiple upstream MCP servers behind a single endpoint.

I'm volunteering to implement this feature and open a PR, once maintainers agree on the scope and the general API direction. Feedback on whether this belongs in rmcp itself or in a companion crate is very welcome.