MCP Vector Knowledge Engine with Qdrant Persistence

This service furnishes a robust knowledge graph infrastructure, featuring graph-based data modeling enhanced by Qdrant's high-performance vector database capabilities.

Core Capabilities

• Structuring data via interconnected entities and relationships.
• Persistent storage solution employing both local file system (memory.json) and Qdrant.
• Enabling semantic querying through vector similarity against OpenAI-derived embeddings.
• Full compliance for secure transport via HTTPS (suitable for reverse proxy setups).
• Containerized deployment readiness using Docker images.

Configuration Variables

The following environmental inputs are mandatory for operation:

bash

API credential for OpenAI embedding generation

OPENAI_API_KEY=your-openai-api-key

Address for the Qdrant vector store endpoint (accepts HTTP/S)

QDRANT_URL=https://your-qdrant-server

Authentication token for secured Qdrant instances

QDRANT_API_KEY=your-qdrant-api-key

Designated Qdrant index/collection name

QDRANT_COLLECTION_NAME=your-collection-name

Deployment Guide

Local Initialization

1. Acquire necessary package dependencies: bash npm install

2. Compile the server source code: bash npm run build

Containerized Deployment (Docker)

1. Build the executable image: bash docker build -t mcp-vector-engine .

2. Initiate the container, supplying all necessary secrets and configurations: bash docker run -d \ -e OPENAI_API_KEY=your-openai-api-key \ -e QDRANT_URL=http://your-qdrant-server:6333 \ -e QDRANT_COLLECTION_NAME=your-collection-name \ -e QDRANT_API_KEY=your-qdrant-api-key \ --name knowledge-server mcp-vector-engine

MCP Integration Block

To expose this functionality within the MCP framework:

{ "mcpServers": { "vector_memory": { "command": "/bin/zsh", "args": ["-c", "cd /path/to/server && node dist/index.js"], "env": { "OPENAI_API_KEY": "your-openai-api-key", "QDRANT_API_KEY": "your-qdrant-api-key", "QDRANT_URL": "http://your-qdrant-server:6333", "QDRANT_COLLECTION_NAME": "your-collection-name" }, "alwaysAllow": [ "create_entities", "create_relations", "add_observations", "delete_entities", "delete_observations", "delete_relations", "read_graph", "search_similar" ] } } }

Available Operations

Graph Manipulation

• create_entities: Provision new conceptual nodes.
• create_relations: Define connections between existing entities.
• add_observations: Append contextual data to specific entities.
• delete_entities: Remove nodes and associated links.
• delete_observations: Purge isolated contextual records.
• delete_relations: Disconnect specific entity pairings.
• read_graph: Retrieve the entire graph topology.

Semantic Retrieval

• search_similar: Perform proximity search based on conceptual meaning. typescript interface SimilarityQuery { query: string; // Text input for the conceptual search limit?: number; // Maximum number of results returned (default is 10) }

Internal Architecture

The system maintains dual persistence layers to optimize access and search precision:

1. File System (memory.json): Stores the canonical, full graph schema for rapid structural lookups.

2. Qdrant Vector Index: Hosts high-dimensional vector representations (embeddings) of graph elements, facilitating rapid semantic proximity determination.

State Synchronization

Modification events (creation, update, deletion) trigger a sequence: 1. Persistence update in memory.json. 2. OpenAI utility generates the required vector representation. 3. The new vector is committed to the Qdrant index. 4. Consistency is actively maintained across both storage modules.

Retrieval Workflow

Query execution follows this path: 1. Input query text is transformed into its corresponding vector embedding. 2. Qdrant executes a nearest-neighbor search using this vector. 3. Results, encompassing both entities and relationships, are returned. 4. Results are ordered based on their semantic distance scores.

Practical Application Example

typescript // Registering new structured data points await client.callTool("create_entities", { entities: [{ name: "System Update", entityType: "Maintenance", observations: ["Scheduled patch deployment"] }] });

// Executing a conceptual search const searchOutcomes = await client.callTool("search_similar", { query: "system maintenance schedule", limit: 5 });

Secure Transport (HTTPS/Proxy Setup)

This engine is fully compatible with secure connections to Qdrant, essential when deploying behind edge termination points like Nginx or using private certificate authorities.

Reverse Proxy Configuration Example (Nginx)

1. Configure the ingress controller to handle SSL termination: nginx server { listen 443 ssl; server_name qdrant.internal-net;

   ssl_certificate /etc/nginx/ssl/server.pem; ssl_certificate_key /etc/nginx/ssl/server.key;

   location / { proxy_pass http://localhost:6333; / Targetting internal Qdrant instance / proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }

2. Adjust the connectivity setting in the environment: bash QDRANT_URL=https://qdrant.internal-net

Security Hardening Measures

Key features for secure operation include: - Support for custom TLS/SSL policies. - Rigorous certificate validation protocols. - Optimized connection handling (pooling, keepalive). - Resilient connection restoration mechanisms (exponential backoff retries). - Configurable operational timeouts.

Connection Diagnosis

If secure communication fails:

1. Validate certificate chain integrity: bash openssl s_client -connect qdrant.internal-net:443 -showcerts

2. Test endpoint responsiveness directly: bash curl -v https://qdrant.internal-net/collections

3. Inspect active proxy settings on the host machine: bash env | grep -i proxy

Collaboration

1. Initiate a project fork.
2. Branch for new features.
3. Implement desired changes.
4. Submit a formal Pull Request for review.

Licensing

Released under the MIT License.