┌──────────────────────────────────────────────────────────┐
│                    MCP Client                            │
│        (Claude Desktop / Claude Code / Custom Agent)     │
└────────────────────┬─────────────────────────────────────┘
                     │  HTTP  port 38080  →  /mcp
                     ▼
┌──────────────────────────────────────────────────────────┐
│              RAG MCP Server  (Hono)                      │
│                                                          │
│  ┌──────────────────┐  ┌─────────────────┐  ┌────────┐   │
│  │  index_document  │  │ semantic_search │  │  list  │   │
│  └────────┬─────────┘  └────────┬────────┘  └───┬────┘   │
│           │                     │               │        │
│  ┌────────▼─────────────────────▼───────────────▼──────┐ │
│  │          FastEmbed  —  BAAI/bge-small-en-v1.5       │ │
│  │               384 dims · local ONNX                 │ │
│  └──────────────────────────┬──────────────────────────┘ │
└─────────────────────────────┼────────────────────────────┘
                              │  REST  port 39333
                              ▼
┌──────────────────────────────────────────────────────────┐
│                      Qdrant                              │
│                  Vector database                         │
│             collection: rag_documents                    │
│             volume: qdrant_storage (persistent)          │
└──────────────────────────────────────────────────────────┘

WITHOUT RAG  —  Full document as context
────────────────────────────────────────────────────────────
┌─────────┐     ┌──────────────────────────────────────┐     ┌─────┐
│  Query  │────►│  Entire book  (~150 000 tokens)      │────►│ LLM │
└─────────┘     │  ⚠ May exceed the context window     │     └─────┘
                │  ⚠ High cost proportional to size    │
                │  ⚠ Model gets distracted by noise    │
                └──────────────────────────────────────┘

WITH RAG  —  Only relevant chunks
────────────────────────────────────────────────────────────
┌─────────┐     ┌────────────┐     ┌───────────────────────┐     ┌─────┐
│  Query  │────►│   Qdrant   │────►│  Top-k chunks         │────►│ LLM │
└─────────┘     │ (semantic  │     │  (~5 000–8 000 tokens)│     └─────┘
                │  search)   │     │  ✓ Only what matters  │
                └────────────┘     └───────────────────────┘

rag-demo/
└── .docs/
    └── my-document.pdf

docker compose up -d

[+] Running 2/2
 ✔ Container rag-qdrant  Started
 ✔ Container rag-mcp     Started

curl http://localhost:38080/health

{
  "status": "ok",
  "sessions": 0,
  "qdrant": "http://qdrant:6333",
  "collection": "rag_documents"
}

http://localhost:38080/mcp

{
  "mcpServers": {
    "rag": {
      "type": "http",
      "url": "http://localhost:38080/mcp"
    }
  }
}

claude mcp add rag --transport http http://localhost:38080/mcp

# Start only Qdrant
docker compose up qdrant -d

# Configure environment
cp .env.example .env

# Install and run
npm install
npm run dev

PDF on disk
    │
    ▼
index_document
    │
    ├─► Extract full text        (pdf-parse)
    │
    ├─► Split into chunks        (512 chars · 64 overlap)
    │
    ├─► Generate embeddings      (FastEmbed · 384 dims)
    │
    └─► Store in Qdrant          (vectors + metadata)

Natural language query
    │
    ▼
semantic_search
    │
    ├─► Embed the query          (FastEmbed)
    │
    ├─► Cosine similarity search (Qdrant)
    │
    └─► Return top-k chunks with similarity score
            │
            ▼
       LLM (Claude)
            │
            └─► Generate answer grounded in the retrieved chunks

Tool: index_document
path: .docs/the-7-habits-of-highly-effective-people.pdf

╔══════════════════════════════════════╗
║   Document indexed successfully      ║
╚══════════════════════════════════════╝

  File    : the-7-habits-of-highly-effective-people.pdf
  Chunks  : 1823
  Vectors : 1823 × 384 dims
  Time    : 47.3s

Ready for semantic search.

Tool: list_indexed_documents

Indexed documents (1):

1. the-7-habits-of-highly-effective-people.pdf

semantic_search: "habit 1 be proactive personal vision"
semantic_search: "habit 2 begin with the end in mind personal mission"
semantic_search: "habit 3 put first things first quadrant II time management"
semantic_search: "habit 4 think win-win mutual benefit agreements"
semantic_search: "habit 5 seek first to understand empathic listening"
semantic_search: "habit 6 synergize creative cooperation"
semantic_search: "habit 7 sharpen the saw balanced renewal"

[1] score=0.8205  source="the-7-habits-..."  chunk=261
    "Habit 1 says: You are the creator. You are in charge.
     It is based on the four human endowments — self-awareness,
     imagination, conscience, and independent will..."

[2] score=0.8100  ...
[3] score=0.8095  ...

http://localhost:38080/mcp        (Docker)
http://localhost:3000/mcp         (local dev)

{ "path": "/absolute/path/to/file.pdf" }

{ "path": ".docs/my-book.pdf" }

{
  "query": "What are the principles of the Private Victory?",
  "limit": 5,
  "source": "the-7-habits-of-highly-effective-people.pdf"
}

{}

npm run dev              # development with hot-reload (tsx watch)
npm run build            # production build (tsup → dist/)
npm start                # run production build
npm run typecheck        # type check without emitting
npm run test             # unit tests (vitest)
npm run test:integration # integration tests (requires Qdrant)
npm run test:all         # unit + integration