mcp-qdrant 1.0.0__tar.gz

mcp_qdrant-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adrián
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_qdrant-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.3
+Name: mcp-qdrant
+Version: 1.0.0
+Summary: MCP server that wraps the Qdrant vector database API as tools.
+Author: Adrián
+Author-email: Adrián <adrianvazvaz.2117@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 Adrián
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: mcp==2.1.1
+Requires-Dist: qdrant-client==1.19.0
+Requires-Dist: pydantic>=2.12.0,<3
+Requires-Dist: tenacity>=9.1.4,<10
+Requires-Dist: uvicorn>=0.52.4,<1
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/avaazquezz/Qdrant-MCP
+Description-Content-Type: text/markdown
+
+# Qdrant-MCP
+
+MCP server that wraps the Qdrant vector database API as tools. See [ROADMAP.md](ROADMAP.md).
+
+## Tools
+
+Generated from the live tool registry — run `uv run python scripts/gen_tools_doc.py` after adding or changing a tool.
+
+<!-- TOOLS_TABLE_START -->
+| Tool | Toolset | Read-only | Destructive | Idempotent | Description |
+|---|---|---|---|---|---|
+| `qdrant_health_check` | `core` | ✅ | ❌ | ✅ | Confirm the configured Qdrant instance is reachable and responding. |
+| `qdrant_collection_create` | `core` | ❌ | ❌ | ❌ | Create a collection: either a single unnamed vector (`vector_size` + `distance`), or one or more named vectors (`vectors`, each a full `VectorParams` — size, distance, and optionally its own `multivector_config` for ColBERT-style multi-vectors or `quantization_config`) — exactly one of the two. |
+| `qdrant_collection_list` | `core` | ✅ | ❌ | ✅ | List every collection name in the configured Qdrant instance. |
+| `qdrant_collection_info` | `core` | ✅ | ❌ | ✅ | Return full config and status of one collection. |
+| `qdrant_collection_update` | `core` | ❌ | ❌ | ✅ | Update optimizer/HNSW/collection/vector params on an existing collection. |
+| `qdrant_collection_delete` | `core` | ❌ | ✅ | ✅ | Delete a collection and all its points; a no-op if it doesn't exist. |
+| `qdrant_collection_exists` | `core` | ✅ | ❌ | ✅ | Check whether a collection exists, without raising if it doesn't. |
+| `qdrant_points_upsert` | `core` | ❌ | ✅ | ✅ | Insert or replace points (id + vector + payload) in a collection. |
+| `qdrant_points_get` | `core` | ✅ | ❌ | ✅ | Retrieve points by id; unknown ids are simply omitted, not an error. |
+| `qdrant_points_delete` | `core` | ❌ | ✅ | ✅ | Delete points by id list or by payload filter — exactly one of the two. |
+| `qdrant_points_scroll` | `core` | ✅ | ❌ | ✅ | Page through all points in a collection, optionally filtered. |
+| `qdrant_points_count` | `core` | ✅ | ❌ | ✅ | Count points in a collection, optionally matching a filter. |
+| `qdrant_query` | `core` | ✅ | ❌ | ✅ | Vector similarity search, with optional hybrid search over multiple prefetch stages. |
+| `qdrant_query_batch` | `search` | ✅ | ❌ | ✅ | Run multiple independent queries against one collection in a single round trip — same query shapes as `qdrant_query` (plain vector or fusion+prefetch hybrid search), one per list item. |
+| `qdrant_query_groups` | `search` | ✅ | ❌ | ✅ | Vector query grouped by a payload field, up to `group_size` hits per group — e.g. the best-matching chunks per source document. |
+| `qdrant_recommend` | `search` | ✅ | ❌ | ✅ | Find points similar to a set of positive examples and dissimilar to a set of negative ones (vectors or point ids) — Qdrant's recommendation API. |
+| `qdrant_recommend_batch` | `search` | ✅ | ❌ | ✅ | Run multiple independent recommend queries against one collection in a single round trip. |
+| `qdrant_recommend_groups` | `search` | ✅ | ❌ | ✅ | Recommend query grouped by a payload field, up to `group_size` hits per group. |
+| `qdrant_discover` | `search` | ✅ | ❌ | ✅ | Rank points by how well they fit a target within positive/negative context pairs (vectors or point ids) — Qdrant's discovery search, a finer-grained alternative to recommend. |
+| `qdrant_discover_batch` | `search` | ✅ | ❌ | ✅ | Run multiple independent discover queries against one collection in a single round trip. |
+| `qdrant_distance_matrix_pairs` | `search` | ✅ | ❌ | ✅ | Pairwise distance matrix between a random sample of points: for each of `sample` points, its `limit` closest neighbors among that same sample — returned as a flat list of (a, b, score) pairs. |
+| `qdrant_distance_matrix_offsets` | `search` | ✅ | ❌ | ✅ | Same distance matrix as `qdrant_distance_matrix_pairs`, in a column-oriented shape (offsets into a shared id list + a parallel score array) — more compact for large samples. |
+| `qdrant_payload_set` | `payload` | ❌ | ❌ | ✅ | Merge fields into the payload of selected points — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_overwrite` | `payload` | ❌ | ✅ | ✅ | Replace the entire payload of selected points with `payload` — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_delete` | `payload` | ❌ | ✅ | ✅ | Delete specific payload keys from selected points — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_clear` | `payload` | ❌ | ✅ | ✅ | Wipe the entire payload of selected points, keeping their vectors — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_facet` | `payload` | ✅ | ❌ | ✅ | Count distinct values of a payload field across the collection (or a filtered subset) — e.g. how many points per `city`. |
+| `qdrant_payload_index_create` | `payload` | ❌ | ❌ | ✅ | Create a payload index on `field_name`, speeding up filters that use it. |
+| `qdrant_payload_index_delete` | `payload` | ❌ | ✅ | ✅ | Delete the payload index on `field_name`. |
+| `qdrant_collection_vector_create` | `payload` | ❌ | ❌ | ✅ | Add a new named vector (dense or sparse) to a collection that already has points, without touching them. |
+| `qdrant_collection_vector_delete` | `payload` | ❌ | ✅ | ✅ | Remove a named vector (dense or sparse) from a collection — points keep their other vectors and payload. |
+| `qdrant_points_batch_update` | `payload` | ❌ | ✅ | ❌ | Run multiple point operations (upsert, delete, set/overwrite/delete/clear payload, update/delete vectors) atomically against one collection, in the order given. |
+| `qdrant_vectors_update` | `payload` | ❌ | ✅ | ✅ | Replace the vector(s) of existing points by id — leaves their payload untouched. |
+| `qdrant_vectors_delete` | `payload` | ❌ | ✅ | ✅ | Remove specific named vectors from selected points, keeping their payload and other vectors — exactly one of `ids`/`points_filter`. |
+| `qdrant_snapshot_create` | `snapshots` | ❌ | ❌ | ❌ | Create a snapshot of one collection's current state. |
+| `qdrant_snapshot_list` | `snapshots` | ✅ | ❌ | ✅ | List the snapshots stored for one collection. |
+| `qdrant_snapshot_delete` | `snapshots` | ❌ | ✅ | ✅ | Delete a collection snapshot, freeing its disk space on the server — does not touch the live collection. |
+| `qdrant_snapshot_recover` | `snapshots` | ❌ | ✅ | ✅ | Overwrite `collection_name` with the state captured in a snapshot — everything written since that snapshot is lost. |
+| `qdrant_snapshot_download` | `snapshots` | ✅ | ❌ | ✅ | Confirm a collection snapshot exists and return where to fetch it from — this tool does not transfer the (potentially huge) snapshot file itself; download it yourself (e.g. `curl`) from the returned `url`. |
+| `qdrant_storage_snapshot_create` | `snapshots` | ❌ | ❌ | ❌ | Create a snapshot of the whole storage (every collection and server config), not just one collection. |
+| `qdrant_storage_snapshot_list` | `snapshots` | ✅ | ❌ | ✅ | List the full-storage snapshots stored on the server. |
+| `qdrant_storage_snapshot_delete` | `snapshots` | ❌ | ✅ | ✅ | Delete a full-storage snapshot, freeing its disk space. |
+| `qdrant_storage_snapshot_download` | `snapshots` | ✅ | ❌ | ✅ | Confirm a full-storage snapshot exists and return where to fetch it from — same caveat as `qdrant_snapshot_download`: this tool does not transfer the file itself. |
+| `qdrant_telemetry` | `observability` | ✅ | ❌ | ✅ | Server-wide telemetry: build info, per-collection stats, request counters, memory and hardware usage. |
+| `qdrant_metrics_prometheus` | `observability` | ✅ | ❌ | ✅ | Return the URL where Qdrant serves Prometheus-format metrics — this tool does not fetch the metrics themselves (they're plain text, not JSON); point your Prometheus scraper at the returned `url` instead. |
+| `qdrant_quotas_get` | `observability` | ✅ | ❌ | ✅ | Current server-wide resource quotas (memory/disk limits) and actual usage. |
+| `qdrant_quotas_set` | `observability` | ❌ | ❌ | ✅ | Update server-wide resource quotas. |
+| `qdrant_issues_list` | `observability` | ✅ | ❌ | ✅ | List the issues Qdrant has detected about its own configuration (e.g. a heavily-filtered field with no payload index). |
+| `qdrant_issues_clear` | `observability` | ❌ | ✅ | ✅ | Clear all accumulated issues. |
+<!-- TOOLS_TABLE_END -->
+
+## Configuration
+
+Environment variables: `QDRANT_URL`, `QDRANT_API_KEY`, `QDRANT_LOCAL_PATH` (exactly one
+of `QDRANT_URL`/`QDRANT_LOCAL_PATH`), `QDRANT_MCP_READ_ONLY`, `QDRANT_MCP_TRANSPORT`
+(`stdio` default, or `streamable-http`), `QDRANT_MCP_TOOLSETS` (comma-separated;
+default `core` only — opt in to `search`, `payload`, `snapshots`, `observability`
+explicitly).
+
+### Claude Desktop / Claude Code (local, `stdio`)
+
+`claude_desktop_config.json` (Claude Desktop) or `.mcp.json` (Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "qdrant": {
+      "command": "uvx",
+      "args": ["mcp-qdrant"],
+      "env": {
+        "QDRANT_URL": "http://localhost:6333",
+        "QDRANT_MCP_TOOLSETS": "core,search"
+      }
+    }
+  }
+}
+```
+
+Or double-click the `.mcpb` bundle attached to a [release](https://github.com/avaazquezz/Qdrant-MCP/releases) — Claude Desktop prompts for the same settings through its own UI, no JSON to edit.
+
+### Remote (`streamable-http`) — e.g. a custom connector in Claude.ai
+
+`QDRANT_MCP_SHARED_SECRET` is **required** in this mode — the server refuses to start
+as `streamable-http` without one, to avoid serving an unauthenticated endpoint over the
+network (verified hands-on: an open `streamable-http` server is trivially usable by
+anyone with the URL).
+
+```bash
+QDRANT_URL=http://localhost:6333 \
+QDRANT_MCP_TRANSPORT=streamable-http \
+QDRANT_MCP_HTTP_HOST=0.0.0.0 \
+QDRANT_MCP_SHARED_SECRET=<a long random secret> \
+mcp-qdrant
+```
+
+In Claude.ai (**Customize → Connectors → Add custom connector**, verified hands-on
+against a real account): enter the server's HTTPS URL, then on the detected
+authentication screen choose **"None"** and add a **Request header** —
+`Authorization` → `Bearer <the same secret>`.

mcp_qdrant-1.0.0/README.md

@@ -0,0 +1,110 @@
+# Qdrant-MCP
+
+MCP server that wraps the Qdrant vector database API as tools. See [ROADMAP.md](ROADMAP.md).
+
+## Tools
+
+Generated from the live tool registry — run `uv run python scripts/gen_tools_doc.py` after adding or changing a tool.
+
+<!-- TOOLS_TABLE_START -->
+| Tool | Toolset | Read-only | Destructive | Idempotent | Description |
+|---|---|---|---|---|---|
+| `qdrant_health_check` | `core` | ✅ | ❌ | ✅ | Confirm the configured Qdrant instance is reachable and responding. |
+| `qdrant_collection_create` | `core` | ❌ | ❌ | ❌ | Create a collection: either a single unnamed vector (`vector_size` + `distance`), or one or more named vectors (`vectors`, each a full `VectorParams` — size, distance, and optionally its own `multivector_config` for ColBERT-style multi-vectors or `quantization_config`) — exactly one of the two. |
+| `qdrant_collection_list` | `core` | ✅ | ❌ | ✅ | List every collection name in the configured Qdrant instance. |
+| `qdrant_collection_info` | `core` | ✅ | ❌ | ✅ | Return full config and status of one collection. |
+| `qdrant_collection_update` | `core` | ❌ | ❌ | ✅ | Update optimizer/HNSW/collection/vector params on an existing collection. |
+| `qdrant_collection_delete` | `core` | ❌ | ✅ | ✅ | Delete a collection and all its points; a no-op if it doesn't exist. |
+| `qdrant_collection_exists` | `core` | ✅ | ❌ | ✅ | Check whether a collection exists, without raising if it doesn't. |
+| `qdrant_points_upsert` | `core` | ❌ | ✅ | ✅ | Insert or replace points (id + vector + payload) in a collection. |
+| `qdrant_points_get` | `core` | ✅ | ❌ | ✅ | Retrieve points by id; unknown ids are simply omitted, not an error. |
+| `qdrant_points_delete` | `core` | ❌ | ✅ | ✅ | Delete points by id list or by payload filter — exactly one of the two. |
+| `qdrant_points_scroll` | `core` | ✅ | ❌ | ✅ | Page through all points in a collection, optionally filtered. |
+| `qdrant_points_count` | `core` | ✅ | ❌ | ✅ | Count points in a collection, optionally matching a filter. |
+| `qdrant_query` | `core` | ✅ | ❌ | ✅ | Vector similarity search, with optional hybrid search over multiple prefetch stages. |
+| `qdrant_query_batch` | `search` | ✅ | ❌ | ✅ | Run multiple independent queries against one collection in a single round trip — same query shapes as `qdrant_query` (plain vector or fusion+prefetch hybrid search), one per list item. |
+| `qdrant_query_groups` | `search` | ✅ | ❌ | ✅ | Vector query grouped by a payload field, up to `group_size` hits per group — e.g. the best-matching chunks per source document. |
+| `qdrant_recommend` | `search` | ✅ | ❌ | ✅ | Find points similar to a set of positive examples and dissimilar to a set of negative ones (vectors or point ids) — Qdrant's recommendation API. |
+| `qdrant_recommend_batch` | `search` | ✅ | ❌ | ✅ | Run multiple independent recommend queries against one collection in a single round trip. |
+| `qdrant_recommend_groups` | `search` | ✅ | ❌ | ✅ | Recommend query grouped by a payload field, up to `group_size` hits per group. |
+| `qdrant_discover` | `search` | ✅ | ❌ | ✅ | Rank points by how well they fit a target within positive/negative context pairs (vectors or point ids) — Qdrant's discovery search, a finer-grained alternative to recommend. |
+| `qdrant_discover_batch` | `search` | ✅ | ❌ | ✅ | Run multiple independent discover queries against one collection in a single round trip. |
+| `qdrant_distance_matrix_pairs` | `search` | ✅ | ❌ | ✅ | Pairwise distance matrix between a random sample of points: for each of `sample` points, its `limit` closest neighbors among that same sample — returned as a flat list of (a, b, score) pairs. |
+| `qdrant_distance_matrix_offsets` | `search` | ✅ | ❌ | ✅ | Same distance matrix as `qdrant_distance_matrix_pairs`, in a column-oriented shape (offsets into a shared id list + a parallel score array) — more compact for large samples. |
+| `qdrant_payload_set` | `payload` | ❌ | ❌ | ✅ | Merge fields into the payload of selected points — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_overwrite` | `payload` | ❌ | ✅ | ✅ | Replace the entire payload of selected points with `payload` — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_delete` | `payload` | ❌ | ✅ | ✅ | Delete specific payload keys from selected points — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_clear` | `payload` | ❌ | ✅ | ✅ | Wipe the entire payload of selected points, keeping their vectors — exactly one of `ids`/`points_filter`. |
+| `qdrant_payload_facet` | `payload` | ✅ | ❌ | ✅ | Count distinct values of a payload field across the collection (or a filtered subset) — e.g. how many points per `city`. |
+| `qdrant_payload_index_create` | `payload` | ❌ | ❌ | ✅ | Create a payload index on `field_name`, speeding up filters that use it. |
+| `qdrant_payload_index_delete` | `payload` | ❌ | ✅ | ✅ | Delete the payload index on `field_name`. |
+| `qdrant_collection_vector_create` | `payload` | ❌ | ❌ | ✅ | Add a new named vector (dense or sparse) to a collection that already has points, without touching them. |
+| `qdrant_collection_vector_delete` | `payload` | ❌ | ✅ | ✅ | Remove a named vector (dense or sparse) from a collection — points keep their other vectors and payload. |
+| `qdrant_points_batch_update` | `payload` | ❌ | ✅ | ❌ | Run multiple point operations (upsert, delete, set/overwrite/delete/clear payload, update/delete vectors) atomically against one collection, in the order given. |
+| `qdrant_vectors_update` | `payload` | ❌ | ✅ | ✅ | Replace the vector(s) of existing points by id — leaves their payload untouched. |
+| `qdrant_vectors_delete` | `payload` | ❌ | ✅ | ✅ | Remove specific named vectors from selected points, keeping their payload and other vectors — exactly one of `ids`/`points_filter`. |
+| `qdrant_snapshot_create` | `snapshots` | ❌ | ❌ | ❌ | Create a snapshot of one collection's current state. |
+| `qdrant_snapshot_list` | `snapshots` | ✅ | ❌ | ✅ | List the snapshots stored for one collection. |
+| `qdrant_snapshot_delete` | `snapshots` | ❌ | ✅ | ✅ | Delete a collection snapshot, freeing its disk space on the server — does not touch the live collection. |
+| `qdrant_snapshot_recover` | `snapshots` | ❌ | ✅ | ✅ | Overwrite `collection_name` with the state captured in a snapshot — everything written since that snapshot is lost. |
+| `qdrant_snapshot_download` | `snapshots` | ✅ | ❌ | ✅ | Confirm a collection snapshot exists and return where to fetch it from — this tool does not transfer the (potentially huge) snapshot file itself; download it yourself (e.g. `curl`) from the returned `url`. |
+| `qdrant_storage_snapshot_create` | `snapshots` | ❌ | ❌ | ❌ | Create a snapshot of the whole storage (every collection and server config), not just one collection. |
+| `qdrant_storage_snapshot_list` | `snapshots` | ✅ | ❌ | ✅ | List the full-storage snapshots stored on the server. |
+| `qdrant_storage_snapshot_delete` | `snapshots` | ❌ | ✅ | ✅ | Delete a full-storage snapshot, freeing its disk space. |
+| `qdrant_storage_snapshot_download` | `snapshots` | ✅ | ❌ | ✅ | Confirm a full-storage snapshot exists and return where to fetch it from — same caveat as `qdrant_snapshot_download`: this tool does not transfer the file itself. |
+| `qdrant_telemetry` | `observability` | ✅ | ❌ | ✅ | Server-wide telemetry: build info, per-collection stats, request counters, memory and hardware usage. |
+| `qdrant_metrics_prometheus` | `observability` | ✅ | ❌ | ✅ | Return the URL where Qdrant serves Prometheus-format metrics — this tool does not fetch the metrics themselves (they're plain text, not JSON); point your Prometheus scraper at the returned `url` instead. |
+| `qdrant_quotas_get` | `observability` | ✅ | ❌ | ✅ | Current server-wide resource quotas (memory/disk limits) and actual usage. |
+| `qdrant_quotas_set` | `observability` | ❌ | ❌ | ✅ | Update server-wide resource quotas. |
+| `qdrant_issues_list` | `observability` | ✅ | ❌ | ✅ | List the issues Qdrant has detected about its own configuration (e.g. a heavily-filtered field with no payload index). |
+| `qdrant_issues_clear` | `observability` | ❌ | ✅ | ✅ | Clear all accumulated issues. |
+<!-- TOOLS_TABLE_END -->
+
+## Configuration
+
+Environment variables: `QDRANT_URL`, `QDRANT_API_KEY`, `QDRANT_LOCAL_PATH` (exactly one
+of `QDRANT_URL`/`QDRANT_LOCAL_PATH`), `QDRANT_MCP_READ_ONLY`, `QDRANT_MCP_TRANSPORT`
+(`stdio` default, or `streamable-http`), `QDRANT_MCP_TOOLSETS` (comma-separated;
+default `core` only — opt in to `search`, `payload`, `snapshots`, `observability`
+explicitly).
+
+### Claude Desktop / Claude Code (local, `stdio`)
+
+`claude_desktop_config.json` (Claude Desktop) or `.mcp.json` (Claude Code):
+
+```json
+{
+  "mcpServers": {
+    "qdrant": {
+      "command": "uvx",
+      "args": ["mcp-qdrant"],
+      "env": {
+        "QDRANT_URL": "http://localhost:6333",
+        "QDRANT_MCP_TOOLSETS": "core,search"
+      }
+    }
+  }
+}
+```
+
+Or double-click the `.mcpb` bundle attached to a [release](https://github.com/avaazquezz/Qdrant-MCP/releases) — Claude Desktop prompts for the same settings through its own UI, no JSON to edit.
+
+### Remote (`streamable-http`) — e.g. a custom connector in Claude.ai
+
+`QDRANT_MCP_SHARED_SECRET` is **required** in this mode — the server refuses to start
+as `streamable-http` without one, to avoid serving an unauthenticated endpoint over the
+network (verified hands-on: an open `streamable-http` server is trivially usable by
+anyone with the URL).
+
+```bash
+QDRANT_URL=http://localhost:6333 \
+QDRANT_MCP_TRANSPORT=streamable-http \
+QDRANT_MCP_HTTP_HOST=0.0.0.0 \
+QDRANT_MCP_SHARED_SECRET=<a long random secret> \
+mcp-qdrant
+```
+
+In Claude.ai (**Customize → Connectors → Add custom connector**, verified hands-on
+against a real account): enter the server's HTTPS URL, then on the detected
+authentication screen choose **"None"** and add a **Request header** —
+`Authorization` → `Bearer <the same secret>`.

mcp_qdrant-1.0.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "mcp-qdrant"
+version = "1.0.0"
+description = "MCP server that wraps the Qdrant vector database API as tools."
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp==2.1.1",
+    "qdrant-client==1.19.0",
+    "pydantic>=2.12.0,<3",
+    "tenacity>=9.1.4,<10",
+    "uvicorn>=0.52.4,<1",
+]
+
+[project.license]
+file = "LICENSE"
+
+[[project.authors]]
+name = "Adrián"
+email = "adrianvazvaz.2117@gmail.com"
+
+[project.scripts]
+mcp-qdrant = "mcp_qdrant.cli:main"
+
+[project.urls]
+Repository = "https://github.com/avaazquezz/Qdrant-MCP"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mcp_qdrant"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "SIM",
+    "ASYNC",
+]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = [
+    "src",
+    "tests",
+    "scripts",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--cov=src/mcp_qdrant --cov-report=term-missing"
+markers = ["integration: requires a live Qdrant instance (CI provides one as a Docker service)"]
+
+[tool.coverage.run]
+source = ["src/mcp_qdrant"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1,<3",
+    "pre-commit>=4.6.2,<5",
+    "pytest>=9.1.1,<10",
+    "pytest-asyncio>=1.4.0,<2",
+    "pytest-cov>=7.1.0,<8",
+    "ruff>=0.16.5,<0.17",
+]

mcp_qdrant-1.0.0/pyproject.toml.orig

@@ -0,0 +1,70 @@
+[project]
+name = "mcp-qdrant"
+version = "1.0.0"
+description = "MCP server that wraps the Qdrant vector database API as tools."
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Adrián", email = "adrianvazvaz.2117@gmail.com" }
+]
+requires-python = ">=3.12"
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.12",
+]
+dependencies = [
+    "mcp==2.1.1",
+    "qdrant-client==1.19.0",
+    "pydantic>=2.12.0,<3",
+    "tenacity>=9.1.4,<10",
+    "uvicorn>=0.52.4,<1",
+]
+
+[project.scripts]
+mcp-qdrant = "mcp_qdrant.cli:main"
+
+[project.urls]
+Repository = "https://github.com/avaazquezz/Qdrant-MCP"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "mcp_qdrant"
+# No /website directory exists yet (Fase 0). If docs land there later,
+# exclude it from the sdist so it never ships inside the package:
+# source-exclude = ["/website"]
+
+[dependency-groups]
+dev = [
+    "mypy>=2.3.1,<3",
+    "pre-commit>=4.6.2,<5",
+    "pytest>=9.1.1,<10",
+    "pytest-asyncio>=1.4.0,<2",
+    "pytest-cov>=7.1.0,<8",
+    "ruff>=0.16.5,<0.17",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests", "scripts"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "--cov=src/mcp_qdrant --cov-report=term-missing"
+markers = [
+    "integration: requires a live Qdrant instance (CI provides one as a Docker service)",
+]
+
+[tool.coverage.run]
+source = ["src/mcp_qdrant"]

mcp_qdrant-1.0.0/src/mcp_qdrant/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

mcp_qdrant-1.0.0/src/mcp_qdrant/cli.py

@@ -0,0 +1,35 @@
+"""CLI entrypoint: the `mcp-qdrant` console script."""
+
+from __future__ import annotations
+
+from mcp_qdrant.config import Settings
+from mcp_qdrant.http_auth import SharedSecretMiddleware
+from mcp_qdrant.logging_setup import configure_logging
+from mcp_qdrant.server import build_server
+
+
+def main() -> int:
+    # Order matters: logging must be configured before MCPServer() exists, so
+    # our stderr handler wins over the SDK's own internal logging configuration
+    # (a no-op once the root logger already has handlers).
+    configure_logging()
+    settings = Settings.from_env()
+    server = build_server(settings)
+
+    if settings.transport == "streamable-http":
+        # server.run(transport="streamable-http") builds and serves its own
+        # app with no hook for middleware, so the shared-secret auth check
+        # is wired in by building the app ourselves instead.
+        import uvicorn
+
+        assert settings.shared_secret is not None  # enforced by Settings validation
+        app = server.streamable_http_app(host=settings.http_host)
+        app.add_middleware(SharedSecretMiddleware, secret=settings.shared_secret)
+        uvicorn.run(app, host=settings.http_host, port=settings.http_port)
+    else:
+        server.run(transport=settings.transport)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcp_qdrant-1.0.0/src/mcp_qdrant/config.py

@@ -0,0 +1,87 @@
+"""Environment-driven runtime configuration for mcp_qdrant.
+
+All external configuration enters here and only here: Settings.from_env()
+reads os.environ once at startup and validates it with Pydantic so a
+misconfigured deployment fails loudly before the server starts serving
+tool calls, instead of failing obscurely on the first tool call.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Literal
+
+from pydantic import BaseModel, model_validator
+
+Transport = Literal["stdio", "streamable-http"]
+Toolset = Literal["core", "search", "payload", "snapshots", "admin", "observability"]
+
+ALL_TOOLSETS: tuple[Toolset, ...] = (
+    "core",
+    "search",
+    "payload",
+    "snapshots",
+    "admin",
+    "observability",
+)
+DEFAULT_TOOLSETS: tuple[Toolset, ...] = ("core",)
+
+
+class Settings(BaseModel):
+    """Validated process configuration, built once from environment variables."""
+
+    qdrant_url: str | None = None
+    qdrant_api_key: str | None = None
+    qdrant_local_path: str | None = None
+    read_only: bool = False
+    transport: Transport = "stdio"
+    toolsets: tuple[Toolset, ...] = DEFAULT_TOOLSETS
+    shared_secret: str | None = None
+    http_host: str = "127.0.0.1"
+    http_port: int = 8000
+
+    @model_validator(mode="after")
+    def _check_single_connection_target(self) -> Settings:
+        if self.qdrant_url and self.qdrant_local_path:
+            raise ValueError("Set only one of QDRANT_URL or QDRANT_LOCAL_PATH, not both.")
+        return self
+
+    @model_validator(mode="after")
+    def _require_shared_secret_for_streamable_http(self) -> Settings:
+        # Verified hands-on (a real public tunnel + Claude.ai's own connector
+        # UI) that an unauthenticated streamable-http server is trivially
+        # usable by anyone with the URL — refuse to start that way silently.
+        if self.transport == "streamable-http" and not self.shared_secret:
+            raise ValueError(
+                "QDRANT_MCP_SHARED_SECRET is required when "
+                "QDRANT_MCP_TRANSPORT=streamable-http, to avoid serving an "
+                "unauthenticated endpoint over the network."
+            )
+        return self
+
+    @classmethod
+    def from_env(cls, env: dict[str, str] | None = None) -> Settings:
+        e = env if env is not None else dict(os.environ)
+        raw_toolsets = e.get("QDRANT_MCP_TOOLSETS", "core")
+        toolsets = tuple(t.strip() for t in raw_toolsets.split(",") if t.strip())
+        unknown = sorted(set(toolsets) - set(ALL_TOOLSETS))
+        if unknown:
+            raise ValueError(
+                f"Unknown toolset(s) in QDRANT_MCP_TOOLSETS: {unknown}. "
+                f"Valid values: {ALL_TOOLSETS}."
+            )
+        return cls(
+            qdrant_url=e.get("QDRANT_URL") or None,
+            qdrant_api_key=e.get("QDRANT_API_KEY") or None,
+            qdrant_local_path=e.get("QDRANT_LOCAL_PATH") or None,
+            read_only=_parse_bool(e.get("QDRANT_MCP_READ_ONLY")),
+            transport=e.get("QDRANT_MCP_TRANSPORT", "stdio"),  # type: ignore[arg-type]
+            toolsets=toolsets,  # type: ignore[arg-type]
+            shared_secret=e.get("QDRANT_MCP_SHARED_SECRET") or None,
+            http_host=e.get("QDRANT_MCP_HTTP_HOST", "127.0.0.1"),
+            http_port=int(e.get("QDRANT_MCP_HTTP_PORT", "8000")),
+        )
+
+
+def _parse_bool(value: str | None) -> bool:
+    return (value or "").strip().lower() in {"1", "true", "yes", "on"}

mcp_qdrant-1.0.0/src/mcp_qdrant/http_auth.py

@@ -0,0 +1,29 @@
+"""Shared-secret auth for the `streamable-http` transport.
+
+`MCPServer.run(transport="streamable-http")` builds and serves its own
+Starlette app internally with no hook for middleware, so `cli.py` builds the
+app itself via `server.streamable_http_app(...)` and wraps it with
+`SharedSecretMiddleware` before serving it. Chosen header/scheme
+(`Authorization: Bearer <secret>`) matches one of the two header names
+Claude.ai's remote-connector "Request headers" UI sends without needing
+Anthropic's manual approval for a custom header name — verified hands-on
+against a real Claude.ai account.
+"""
+
+from __future__ import annotations
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.types import ASGIApp
+
+
+class SharedSecretMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp, *, secret: str) -> None:
+        super().__init__(app)
+        self._expected = f"Bearer {secret}"
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        if request.headers.get("authorization") != self._expected:
+            return JSONResponse({"error": "Unauthorized"}, status_code=401)
+        return await call_next(request)

mcp_qdrant-1.0.0/src/mcp_qdrant/logging_setup.py

@@ -0,0 +1,28 @@
+"""Stderr-only logging setup.
+
+MCP's stdio transport treats stdout as the JSON-RPC wire; anything else
+written there corrupts every message after it. This is the single place
+allowed to touch the root logger's handlers, and it hard-codes
+stream=sys.stderr — called before MCPServer() is constructed, so the SDK's
+own internal logging configuration (which also defaults to stderr, but we
+don't want two configurations racing) finds handlers already in place.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+
+def configure_logging(level: str = "INFO") -> None:
+    """Configure the root logger to write exclusively to stderr.
+
+    Idempotent: clears existing handlers first, so calling this twice (e.g.
+    once per test) never accumulates duplicate log lines.
+    """
+    root = logging.getLogger()
+    root.handlers.clear()
+    handler = logging.StreamHandler(stream=sys.stderr)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    root.addHandler(handler)
+    root.setLevel(level)