feat(mcp): expose explain parameter for retrieval score traces - #730
Open
fxstein wants to merge 1 commit into
Open
feat(mcp): expose explain parameter for retrieval score traces#730fxstein wants to merge 1 commit into
fxstein wants to merge 1 commit into
Conversation
Add an optional "explain" boolean to the MCP query tool and the REST /query (alias /search) endpoint. When enabled, each result carries the retrieval score trace the SDK already computes: per-list FTS and vector scores, the RRF fusion breakdown, and rerank blend weights. SearchOptions.explain and HybridQueryResult.explain already exist in the SDK (hybridQuery/structuredSearch compute the trace) — this only plumbs the flag through the two MCP-facing surfaces and forwards the trace into each result when present, reusing the exported HybridQueryExplain type. Default is false, so output is unchanged for existing callers. Useful for debugging query quality and tuning search ranking from MCP clients without dropping down to the SDK.
fxstein
force-pushed
the
feat/mcp-explain-param
branch
from
June 29, 2026 09:03
a7df74e to
3fa91ac
Compare
Contributor
Author
|
Rebased onto current |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds an optional
explainboolean to the MCPquerytool and the REST/query(alias/search) endpoint. When set, each result carries the retrieval score trace the SDK already computes — per-list FTS and vector scores, the RRF fusion breakdown, and rerank blend weights.Why
SearchOptions.explainandHybridQueryResult.explainalready exist in the SDK (hybridQuery()/structuredSearch()build the trace viabuildRrfTrace), but there is no way to request it from an MCP client — you have to drop down to the SDK. This plumbs the existing flag through the two MCP-facing surfaces so query quality and ranking can be inspected in place.Details
explainparam (defaultfalse) on thequerytool schema, forwarded tostore.search.explainaccepted on the REST/querybody and forwarded likewise....(r.explain ? { explain: r.explain } : {}), typed against the exportedHybridQueryExplain— no output change whenexplainis unset.tsc --noEmitclean.History
Fresh, focused resubmission of #433, which was closed on 2026-05-20 during a stale-backlog purge with the note to "open a fresh focused issue if it still reproduces on v2.5.1+". No
explainparameter exists on currentmain, so the gap remains. Rebased onto currentmain(the rerank-awarequerysignature); the change is smaller now becausemainalready exportsHybridQueryExplain.