atlas-mcp-doc-search

MCP server that exposes hybrid document search over the Atlas ingested corpus. Built with the official Python mcp SDK (FastMCP server interface, Streamable HTTP transport), Python 3.12 asyncio, and deployed as a standalone K8s service on AKS.

Tool Contract

doc_search

doc_search(query: str, k: int = 8) -> {chunks: [{id, text, source_id, score}]}

Returns a list of up to k chunks, each with:

Hybrid Retrieval Approach

The server implements HYBRID retrieval — combining sparse (BM25) and dense (vector) signals and fusing them with Reciprocal Rank Fusion (RRF):

1. Query embedding — the raw query string is sent to the Atlas gateway's /v1/embeddings endpoint to produce a dense vector.

2. Parallel retrieval

   • Elasticsearch BM25 keyword search over the doc_chunks index.

   • Qdrant vector similarity search over collection doc_chunks (payload fields: source_id, doc_id, chunk_idx, text).

3. Fusion — both ranked lists are merged with RRF to produce a single ranked list.

4. Return — top k results are returned with their fused scores.

Dependencies

Diagrams

• Component (C4-L3)

• Sequence — hybrid doc search

• Class diagram

Related

• atlas-docs — document ingestion pipeline that populates the corpus

• atlas-mcp-citations — citation verification MCP server