fix(mcp): report keyword-only and unreranked search results

Merged
LE
7d ago
+180-66

When semantic search fails or is skipped (embedding endpoint down, expired key, model/prefix/dimension mismatch), search falls back to BM25-only results; when the reranker fails it returns unreranked results. The CLI warns on stderr, but search_code discarded the timings, so MCP agents got degraded results with no signal.

  • SearchTimings and HybridTimings gain semantic_fallback: Option<String>, set on every BM25-only fallback path in SearchContext::search and when the vector arm errors. BM25-only by request (SearchContext::bm25_only()) stays None.
  • search_code merges timings across queries and adds warning: semantic search unavailable (...) and warning: reranker unavailable (...) ahead of the stale-index warning in the existing notice block. Multi-query wording says "at least one query".
  • CLI output is unchanged (default JSON is still a bare array; the reranker unavailable stderr line stays).
  • Docs: mcp.md, troubleshooting.md (new "Keyword-only results" section), whats-new.md (v2.1.1 entry, also covering #296).

Checked end to end: vera mcp against an index built with a different model now returns the notice block naming the mismatch.

Devin Review

Summary by cubic

MCP search_code results now say when they are degraded, so agents can tell keyword-only or unreranked results from a full hybrid search.

When vector search failed or was skipped (embedding endpoint down, expired key, model/prefix/dimension mismatch), search fell back to BM25-only results, and reranker failures returned unreranked results. The CLI warned on stderr, but search_code discarded the timings, so MCP agents saw no signal.

  • SearchTimings and HybridTimings now carry semantic_fallback: Option<String>, set on every BM25-only fallback path but not when BM25-only was requested.
  • search_code merges timings across queries and prepends warning: semantic search unavailable (...) or warning: reranker unavailable (...) to the existing stale-index notice block; in multi-query searches the wording notes that at least one query was degraded rather than implying all results were.
  • CLI output is unchanged; docs add a "Keyword-only results" troubleshooting section.
  • retrieval.rrf_k now applies to ordinary search as well as multi-query merging, with the default unchanged.

Summary by CodeRabbit

  • New Features
    • Search results now indicate when semantic search falls back to keyword-only results or reranking is unavailable. Multi-query searches clarify when a fallback affected at least one query.
    • The retrieval.rrf_k setting now applies to standard searches as well as multi-query result merging.
  • Documentation
    • Added guidance on interpreting search warnings and troubleshooting keyword-only results.