feat(mcp): expose explain parameter for retrieval score traces

[fxstein]

Problem

The CLI qmd query --explain flag includes detailed retrieval score traces per result — FTS scores, vector scores, RRF fusion breakdown, reranker blend weights, and per-source contributions. This is a shipped v2.0.1 feature.

However, the MCP query tool does not expose this option. MCP clients cannot debug query quality, understand score composition, or tune search parameters without dropping to the CLI.

Fix

Add an optional explain boolean parameter to the MCP query tool (default: false). When enabled, pass explain: true through to structuredSearch() and include the HybridQueryExplain object on each result.

Changes:

• Extend SearchResultItem type with optional explain field
• Add explain to MCP tool input schema
• Pass explain through in both MCP tool handler and REST /query endpoint
• Conditionally include explain data in results (only when present, keeps response compact by default)

Testing

Built and tested locally against a 7,665 document index:

Query	explain	Result
searches: [{type: "lex", query: "boot gate"}]	true	ftsScores, rrf breakdown, rerankScore, blendedScore all present
searches: [{type: "lex", query: "boot gate"}]	false	Standard result, no explain field
searches: [{type: "lex", query: "boot gate"}]	omitted	Same as false (default)

Example explain output:

{
  "ftsScores": [0.88],
  "vectorScores": [],
  "rrf": { "rank": 1, "totalScore": 0.083, "contributions": [{"source": "fts", "rank": 1, "weight": 2}] },
  "rerankScore": 0.502,
  "blendedScore": 0.875
}

Existing queries without explain return results unchanged — no breaking changes.

Environment

• QMD: v2.0.1
• Platform: macOS (Apple Silicon)
• Node: v24.2.0