Servidor de memoria MCP con persistencia Qdrant

Este servidor MCP proporciona una implementación de gráfico de conocimiento con capacidades de búsqueda semántica impulsadas por la base de datos vectorial Qdrant.

Características

Representación de conocimiento basada en gráficos con entidades y relaciones
Persistencia basada en archivos (memory.json)
Búsqueda semántica utilizando la base de datos vectorial Qdrant
Integraciones de OpenAI para similitud semántica
Compatibilidad con HTTPS y proxy inverso
Compatibilidad con Docker para una implementación sencilla

Variables de entorno

Se requieren las siguientes variables de entorno:

# 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

Configuración

Configuración local

Instalar dependencias:

npm install

Construir el servidor:

npm run build

Configuración de Docker

Construya la imagen de Docker:

docker build -t mcp-qdrant-memory .

Ejecute el contenedor Docker con las variables de entorno requeridas:

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

Agregar a la configuración de MCP:

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

Herramientas

Gestión de entidades

create_entities : Crea múltiples entidades nuevas
create_relations : Crea relaciones entre entidades
add_observations : Agregar observaciones a las entidades
delete_entities : Eliminar entidades y sus relaciones
delete_observations : Eliminar observaciones específicas
delete_relations : Eliminar relaciones específicas
read_graph : Obtenga el gráfico de conocimiento completo

Búsqueda semántica

search_similar : Busca entidades y relaciones semánticamente similares
interface SearchParams { query: string; // Search query text limit?: number; // Max results (default: 10) }

Detalles de implementación

El servidor mantiene dos formas de persistencia:

Basado en archivos (memory.json):
- Estructura completa del gráfico de conocimiento
- Acceso rápido al gráfico completo
- Se utiliza para operaciones gráficas
Base de datos vectorial de Qdrant:
- Incrustaciones semánticas de entidades y relaciones
- Permite la búsqueda de similitud
- Sincronizado automáticamente con el almacenamiento de archivos

Sincronización

Cuando se modifican entidades o relaciones:

Los cambios se escriben en memory.json
Las incrustaciones se generan utilizando OpenAI
Los vectores se almacenan en Qdrant
Ambos sistemas de almacenamiento se mantienen consistentes

Proceso de búsqueda

Al buscar:

El texto de la consulta se convierte en incrustación
Qdrant realiza una búsqueda de similitud
Los resultados incluyen tanto entidades como relaciones
Los resultados se clasifican por similitud semántica.

Ejemplo de uso

// 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
});

Configuración de HTTPS y proxy inverso

El servidor admite la conexión a Qdrant mediante HTTPS y proxies inversos. Esto resulta especialmente útil cuando:

Ejecutar Qdrant detrás de un proxy inverso como Nginx o Apache
Uso de certificados autofirmados
Requerir configuraciones SSL/TLS personalizadas

Configuración con un proxy inverso

Configure su proxy inverso (ejemplo usando 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;
    }
}

Actualice sus variables de entorno:

QDRANT_URL=https://qdrant.yourdomain.com

Consideraciones de seguridad

El servidor implementa un manejo robusto de HTTPS con:

Configuración personalizada de SSL/TLS
Opciones adecuadas de verificación de certificados
Agrupación de conexiones y keepalive
Reintento automático con retroceso exponencial
Tiempos de espera configurables

Solución de problemas de conexiones HTTPS

Si experimenta problemas de conexión:

Verifique sus certificados:

openssl s_client -connect qdrant.yourdomain.com:443

Pruebe la conectividad directa:

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

Verifique si hay alguna configuración de proxy:

env | grep -i proxy

Contribuyendo

Bifurcar el repositorio
Crear una rama de características
Realiza tus cambios
Enviar una solicitud de extracción

Licencia

Instituto Tecnológico de Massachusetts (MIT)

MCP Memory Server with Qdrant Persistence

Integrations