MCP tool parity: summary of open PRs closing CLI → MCP gaps #434
Description
Overview
I've been using QMD (v2.0.1) heavily via the MCP tool interface with ~7,600 indexed documents. Several CLI features are not exposed through MCP, and a few bugs affect MCP-specific code paths. I've submitted fixes for all of them as individual PRs from my fork.
This issue is a tracking summary linking everything together.
Bug Fixes
#416 — MCP status missing collection names
The status MCP tool returns collection metadata but omits the collection name field. Clients see paths and doc counts but cannot identify collections by name.
Fix: Include name in the status response.
#418 — Hyphenated terms broken in lex search
Searching for identifiers like DEC-0054 or RFC-0011 via lex returns zero results because the hyphen is treated as a phrase separator. The CLI has the same issue.
Related issue: #417
Fix: Normalize hyphenated terms to preserve them as searchable tokens.
#431 — MCP server version hardcoded as 0.9.9
The MCP server reports version: "0.9.9" regardless of the actual installed version. This has been wrong since 1.x.
Fix: Read version from package.json at startup.
Feature Additions
#432 — Expose plain query (auto-expand) via MCP
The CLI qmd query "text" triggers the trained expansion model (GRPO), but the MCP tool only accepts pre-typed searches sub-queries. This means MCP clients cannot use the recommended search mode.
Fix: Add optional query string parameter to MCP tool, routing to store.search({ query }). Mutually exclusive with searches.
#433 — Expose --explain via MCP
The CLI --explain flag provides detailed retrieval score traces (FTS scores, vector scores, RRF fusion breakdown, reranker blend weights). Not available via MCP.
Fix: Add optional explain boolean parameter. When enabled, results include the full HybridQueryExplain object.
Context
All PRs are independent (each branched from main) and can be reviewed/merged in any order. Tested locally on macOS Apple Silicon with Node v24, ~7,600 documents across 13 collections.