mcp qdrant memory

This MCP server provides a knowledge graph implementation with semantic search capabilities powered by Qdrant vector database.

Features

• Graph-based knowledge representation with entities and relations
• File-based persistence (memory.json)
• Semantic search using Qdrant vector database
• OpenAI embeddings for semantic similarity
• HTTPS support with reverse proxy compatibility
• Docker support for easy deployment

Environment Variables

The following environment variables are required:

# OpenAI API key for generating embeddings
OPENAI_API_KEY=your-openai-api-key

# Qdrant server URL (supports both HTTP and HTTPS)
QDRANT_URL=https://your-qdrant-server

# Qdrant API key (if authentication is enabled)
QDRANT_API_KEY=your-qdrant-api-key

# Name of the Qdrant collection to use
QDRANT_COLLECTION_NAME=your-collection-name

Setup

Local Setup

1. Install dependencies:

   npm install

2. Build the server:

   npm run build

Docker Setup

1. Build the Docker image:

   docker build -t mcp-qdrant-memory .

2. Run the Docker container with required environment variables:

   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 mcp-qdrant-memory 
     mcp-qdrant-memory

Add to MCP settings:

{
  "mcpServers": {
    "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"
      ]
    }
  }
}

Tools

Entity Management

• create_entities: Create multiple new entities
• create_relations: Create relations between entities
• add_observations: Add observations to entities
• delete_entities: Delete entities and their relations
• delete_observations: Delete specific observations
• delete_relations: Delete specific relations
• read_graph: Get the full knowledge graph

Semantic Search

• search_similar: Search for semantically similar entities and relations

  interface SearchParams {
    query: string;     // Search query text
    limit?: number;    // Max results (default: 10)
  }

Implementation Details

The server maintains two forms of persistence:

1. File-based (memory.json):
2. Complete knowledge graph structure
3. Fast access to full graph

4. Used for graph operations

5. Qdrant Vector DB:

6. Semantic embeddings of entities and relations
7. Enables similarity search
8. Automatically synchronized with file storage

Synchronization

When entities or relations are modified: 1. Changes are written to memory.json 2. Embeddings are generated using OpenAI 3. Vectors are stored in Qdrant 4. Both storage systems remain consistent

Search Process

When searching: 1. Query text is converted to embedding 2. Qdrant performs similarity search 3. Results include both entities and relations 4. Results are ranked by semantic similarity

Example Usage

// Create entities
await client.callTool("create_entities", {
  entities: [{
    name: "Project",
    entityType: "Task",
    observations: ["A new development project"]
  }]
});

// Search similar concepts
const results = await client.callTool("search_similar", {
  query: "development tasks",
  limit: 5
});

HTTPS and Reverse Proxy Configuration

The server supports connecting to Qdrant through HTTPS and reverse proxies. This is particularly useful when: - Running Qdrant behind a reverse proxy like Nginx or Apache - Using self-signed certificates - Requiring custom SSL/TLS configurations

Setting up with a Reverse Proxy

1. Configure your reverse proxy (example using Nginx):

   server {
       listen 443 ssl;
       server_name qdrant.yourdomain.com;
   
       ssl_certificate /path/to/cert.pem;
       ssl_certificate_key /path/to/key.pem;
   
       location / {
           proxy_pass http://localhost:6333;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

2. Update your environment variables:

   QDRANT_URL=https://qdrant.yourdomain.com

Security Considerations

The server implements robust HTTPS handling with: - Custom SSL/TLS configuration - Proper certificate verification options - Connection pooling and keepalive - Automatic retry with exponential backoff - Configurable timeouts

Troubleshooting HTTPS Connections

If you experience connection issues:

1. Verify your certificates:

   openssl s_client -connect qdrant.yourdomain.com:443

2. Test direct connectivity:

   curl -v https://qdrant.yourdomain.com/collections

3. Check for any proxy settings:

   env | grep -i proxy

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT