Documentation Index Fetch the complete documentation index at: https://mintlify.com/tobi/qmd/llms.txt
Use this file to discover all available pages before exploring further.
Overview The query tool is the primary search interface for QMD’s MCP server. It accepts a query document — an array of typed sub-queries that are executed in parallel and combined using Reciprocal Rank Fusion (RRF).
Array of 1-10 typed sub-queries. First sub-query gets 2× weight. Query type: lex (BM25), vec (semantic), or hyde (hypothetical document)
The query text. Format depends on type:
lex : Keywords, "quoted phrases", -negationvec : Natural language questionhyde : 50-100 word passage describing the ideal answer Maximum number of results to return
Minimum relevance score (0-1). Filters out low-confidence results.
Filter to specific collections (OR match). If omitted, uses default collections from config.
Query Types lex — BM25 Keyword Search Full-text search using SQLite FTS5. Fast, exact, no LLM required.
Syntax:
term — Prefix match (“perf” matches “performance”)"exact phrase" — Phrase must appear verbatim-term or -"phrase" — Exclude documents containing this
Examples: { "type" : "lex" , "query" : "error handling" } { "type" : "lex" , "query" : " \" connection pool \" timeout -redis" } { "type" : "lex" , "query" : "handleError async typescript" }
vec — Semantic Vector Search Find documents by meaning, not exact keywords. Requires embeddings (run qmd embed).
Format: Natural language questionExamples: { "type" : "vec" , "query" : "how does the rate limiter handle burst traffic?" } { "type" : "vec" , "query" : "what is the tradeoff between consistency and availability?" }
hyde — Hypothetical Document Embeddings Write a 50-100 word passage that looks like the ideal answer. Often the most powerful for nuanced topics.
Examples: { "type" : "hyde" , "query" : "The rate limiter uses a token bucket algorithm. When a client exceeds 100 req/min, subsequent requests return 429 until the window resets." }
Search Strategy Combine multiple query types for best recall:
Goal Strategy Known exact term lex onlyConcept search vec onlyBest recall lex + vecComplex/nuanced lex + vec + hyde
The first sub-query gets 2× weight — put your strongest signal first.Array with a single text element containing a human-readable summary Summary like: Found 3 results for "error handling":\n\n#abc123 92% src/errors.ts - Error utilities
Machine-readable results Show structuredContent.results
Array of search result objects Short document ID with # prefix (e.g., #abc123). Use with get.
File path relative to collection (e.g., docs/errors.md)
Document title from frontmatter or first heading
Relevance score (0-1), rounded to 2 decimals
Context metadata from qmd context add, or null
Best matching chunk (300 chars) with line numbers
Examples Simple Keyword Lookup { "searches" : [ { "type" : "lex" , "query" : "CAP theorem" } ] }
Best Recall on Technical Topic { "searches" : [ { "type" : "lex" , "query" : " \" connection pool \" timeout -redis" }, { "type" : "vec" , "query" : "why do database connections time out under load" }, { "type" : "hyde" , "query" : "Connection pool exhaustion occurs when all connections are in use and new requests must wait. This typically happens under high concurrency when queries run longer than expected." } ], "limit" : 5 , "minScore" : 0.5 }
{ "searches" : [ { "type" : "lex" , "query" : " \" C++ performance \" optimization -sports -athlete" }, { "type" : "vec" , "query" : "how to optimize C++ program performance" } ] }
Collection-Scoped Search { "searches" : [ { "type" : "vec" , "query" : "meeting notes from last week" } ], "collections" : [ "journals" ], "limit" : 10 }
Response Example { "content" : [ { "type" : "text" , "text" : "Found 2 results for \" error handling \" : \n\n #abc123 92% src/errors.ts - Error handling utilities \n #def456 87% docs/errors.md - Error handling guide" } ], "structuredContent" : { "results" : [ { "docid" : "#abc123" , "file" : "src/errors.ts" , "title" : "Error handling utilities" , "score" : 0.92 , "context" : "Source code for error utilities" , "snippet" : "1: export function handleError(err: Error) { \n 2: logger.error(err.message); \n 3: return { success: false, error: err.message }; \n 4: }" }, { "docid" : "#def456" , "file" : "docs/errors.md" , "title" : "Error handling guide" , "score" : 0.87 , "context" : "Documentation for error handling patterns" , "snippet" : "15: ## Best Practices \n 16: \n 17: Always catch errors at the boundary and log them. \n 18: Return structured error objects with codes." } ] } }
CLI Equivalent The query tool corresponds to the qmd query CLI command:
qmd query "error handling" --limit 5 --min-score 0.5
The CLI uses automatic query expansion, while the MCP tool gives you explicit control over sub-query types.
get Tool Retrieve documents from search results
status Tool Check if embeddings are available for vec/hyde
