mcp_qrant — Vector-Store MCP Server

A Python/FastAPI MCP server (JSON-RPC 2.0) that exposes a unified interface for storing and querying vector databases. Phase 1 ships Qdrant (self-embedding, local or remote). Nine more providers are listed and will be activated in later phases.

Quick Start

# from the project root
MCPQ_PORT=8008 ./.venv/bin/python server.py

The server listens on http://127.0.0.1:8008 and handles MCP JSON-RPC at both / and /mcp.

Environment variables:

Variable	Default	Purpose
MCPQ_PORT	8008	Listening port
MCPQ_HOST	127.0.0.1	Bind address
MCPQ_PROVIDERS_DIR	./providers	Directory of provider JSON descriptors

Tools (5)

list_providers

Returns all 10 provider descriptors. Each entry includes available (bool), embeds_internally (bool), and connection_schema (field list for the UI form).

list_embeddings

Returns the embedding-model catalog (FastEmbed BGE, HuggingFace MiniLM, OpenAI small/large). Only relevant for providers where embeds_internally: false — those need a model chosen from this list to embed text before upsert/search.

test_connection

Validates a provider connection without writing data.

{"provider": "qdrant", "connection": {"mode": "local", "path": "/tmp/mydb"}}

Returns {"ok": true} or {"ok": false, "message": "..."}.

store

Embeds (if needed) and upserts text chunks into a collection.

{
  "provider": "qdrant",
  "connection": {"mode": "local", "path": "/tmp/mydb"},
  "collection": "my_docs",
  "items": [
    {"text": "solar panels convert sunlight", "metadata": {"src": "wiki"}},
    {"text": "the cat sat on the mat",       "metadata": {"src": "test"}}
  ]
}

Returns {"stored": 2, "errors": 0}.

embedding is optional; Qdrant ignores it (self-embeds). Pass an id from list_embeddings for future non-self-embedding providers.

find

Semantic search over a collection.

{
  "provider": "qdrant",
  "connection": {"mode": "local", "path": "/tmp/mydb"},
  "collection": "my_docs",
  "query": "renewable energy",
  "limit": 3
}

Returns {"results": [{"text": "...", "metadata": {...}, "score": 0.91}, ...]}.

Providers (10)

Name	Label	Available	Embeds internally
qdrant	Qdrant	yes	yes
pgvector	PostgreSQL + pgvector	coming soon	no
chroma	Chroma	coming soon	no
faiss	FAISS	coming soon	no
milvus	Milvus	coming soon	no
mongodb	MongoDB Atlas	coming soon	no
pinecone	Pinecone	coming soon	no
redis	Redis	coming soon	no
weaviate	Weaviate	coming soon	no
elasticsearch	Elasticsearch	coming soon	no

embeds_internally

• true (Qdrant): the provider does its own embedding via qdrant-client[fastembed]. Pass text in items[].text and query; the embedding field is ignored.
• false (all others, Phase 2+): the MCP will embed text using the model you select from list_embeddings before upserting or searching. Pass the model id in the embedding field.

Connection Schemas

list_providers returns a connection_schema per provider that drives the UI form. Qdrant's fields:

Field	Type	Notes
mode	select	local or remote
path	text	required when mode=local; path to the on-disk Qdrant storage directory
url	text	required when mode=remote; e.g. https://xyz.cloud.qdrant.io
api_key	password	required for Qdrant Cloud; masked in UI

Running Tests

./.venv/bin/python -m pytest tests/ -v

18 tests, all green (Tasks 1–7).

Smoke Test

cd tests && ./smoke.sh

Boots the server on port 8008, fires list_providers (10 entries), store 2 chunks into a temp local Qdrant path, and find with a semantic query — then shuts down and cleans up.

PHP Prototype (Retired)

An earlier PHP prototype (htdocs/vector/) implemented qdrant-store/qdrant-find as a thin stateless translator to Qdrant Cloud REST. That work informed the tool contract but is superseded by this Python server. The PHP files will be retired at the remote-Qdrant cutover when this MCP handles both local and remote modes end-to-end.

Architecture

server.py          FastAPI app + JSON-RPC router (_wrap envelope)
handlers.py        Handlers class — delegates to registry
stores/
  base.py          VectorStoreProvider protocol
  registry.py      build_registry + providers_payload
  qdrant.py        QdrantProvider (connect/test_connection/store/find)
providers/         10 JSON descriptor files (available, embeds_internally, connection_schema)
embedding.py       Embedding catalog (used by future non-self-embedding providers)
config.py          AppConfig (env-var driven)
tests/
  smoke.sh         Live boot + curl smoke (store/find against real local Qdrant)
  test_*.py        18 unit tests