# MCP Memory Server with Qdrant Persistence
[![smithery badge](https://smithery.ai/badge/@delorenj/mcp-qdrant-memory)](https://smithery.ai/server/@delorenj/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:

```bash
# 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:
```bash
npm install
```

2. Build the server:
```bash
npm run build
```

### Docker Setup

1. Build the Docker image:
```bash
docker build -t mcp-qdrant-memory .
```

2. Run the Docker container with required environment variables:
```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 mcp-qdrant-memory \
  mcp-qdrant-memory
```

### Add to MCP settings:
```json
{
  "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
  ```typescript
  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):
   - Complete knowledge graph structure
   - Fast access to full graph
   - Used for graph operations

2. Qdrant Vector DB:
   - Semantic embeddings of entities and relations
   - Enables similarity search
   - 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

```typescript
// 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):
```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:
```bash
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:
```bash
openssl s_client -connect qdrant.yourdomain.com:443
```

2. Test direct connectivity:
```bash
curl -v https://qdrant.yourdomain.com/collections
```

3. Check for any proxy settings:
```bash
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