Skip to main content

​
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).

​
Input Schema

​
searches
array
required
Array of 1-10 typed sub-queries. First sub-query gets 2× weight.
​
limit
number
default:"10"
Maximum number of results to return
​
minScore
number
default:"0"
Minimum relevance score (0-1). Filters out low-confidence results.
​
collections
string[]
Filter to specific collections (OR match). If omitted, uses default collections from config.

​
Query Types

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" }
Find documents by meaning, not exact keywords. Requires embeddings (run qmd embed). Format: Natural language question Examples: 
{ "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:
GoalStrategy
Known exact termlex only
Concept searchvec only
Best recalllex + vec
Complex/nuancedlex + vec + hyde
The first sub-query gets 2× weight — put your strongest signal first.

​
Response Format

​
content
array
Array with a single text element containing a human-readable summary
​
structuredContent
object
Machine-readable results

​
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
}

​
Intent-Aware Search (C++ Performance, Not Sports)

{
  "searches": [
    { "type": "lex", "query": "\"C++ performance\" optimization -sports -athlete" },
    { "type": "vec", "query": "how to optimize C++ program performance" }
  ]
}

{
  "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) {\n2:   logger.error(err.message);\n3:   return { success: false, error: err.message };\n4: }"
      },
      {
        "docid": "#def456",
        "file": "docs/errors.md",
        "title": "Error handling guide",
        "score": 0.87,
        "context": "Documentation for error handling patterns",
        "snippet": "15: ## Best Practices\n16: \n17: Always catch errors at the boundary and log them.\n18: 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

Build docs developers (and LLMs) love

Get started for freeTalk to us