Metadata-Version: 2.3
Name: better-qdrant-mcp
Version: 0.2.0
Summary: Add your description here
Author: jtsang4
Author-email: jtsang4 <info@jtsang.me>
Requires-Dist: fastembed>=0.7.3
Requires-Dist: fastmcp>=2.13.1
Requires-Dist: jieba>=0.42.1
Requires-Dist: openai>=1.47.0
Requires-Dist: qdrant-client>=1.15.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# better-qdrant-mcp

A MCP server implemented with fastmcp, OpenAI embeddings, and qdrant-client. It provides three tools equivalent to the Node.js version:

- memory-store
- memory-search
- memory-debug

## Requirements

- Python 3.12+
- Qdrant reachable via HTTP

## Install deps (using uv or pip)

```bash
# using uv (recommended)
uv sync
# or with pip
pip install -e .
```

## Environment variables

- QDRANT_URL (default: http://localhost:6333)
- QDRANT_API_KEY (optional)
- COLLECTION_NAME (optional default collection)
- OPENAPI_API_KEY or OPENAI_API_KEY (required)
- OPENAI_BASE_URL (optional)
- OPENAI_EMBEDDING_MODEL (default: text-embedding-3-small)

## Run (stdio)

```bash
uvx better-qdrant-mcp
```

You can still run it via Python directly if you prefer:

```bash
python -m better_qdrant_mcp
```

Configure in MCP clients as a stdio server. Example (cursor-like):

```json
{
  "mcpServers": {
    "qdrant-mcp-python": {
      "type": "stdio",
      "command": "uvx",
      "args": ["better-qdrant-mcp"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "COLLECTION_NAME": "long_term_memory"
      }
    }
  }
}
```

## Tools

- memory-store(information, metadata?: dict, collection_name?: str) -> str
- memory-search(query, limit?: int=5, collection_name?: str) -> str
- memory-debug(collection_name?: str) -> str

`memory-search` uses hybrid search in Qdrant (dense + sparse). If the collection is configured with named vectors `dense` and `sparse`, queries are ranked by fusing dense OpenAI embeddings and sparse BM25 scores; otherwise it falls back to dense-only search.
