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

Related MCP server: Qdrant MCP Server

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

1. Instalar dependencias:

npm install

2. Construir el servidor:

npm run build

Configuración de Docker

1. Construya la imagen de Docker:

docker build -t mcp-qdrant-memory .

2. 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:

1. 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

2. 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:

1. Los cambios se escriben en memory.json

2. Las incrustaciones se generan utilizando OpenAI

3. Los vectores se almacenan en Qdrant

4. Ambos sistemas de almacenamiento se mantienen consistentes

Proceso de búsqueda

Al buscar:

1. El texto de la consulta se convierte en incrustación

2. Qdrant realiza una búsqueda de similitud

3. Los resultados incluyen tanto entidades como relaciones

4. 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

1. 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;
    }
}

2. 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:

1. Verifique sus certificados:

openssl s_client -connect qdrant.yourdomain.com:443

2. Pruebe la conectividad directa:

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

3. Verifique si hay alguna configuración de proxy:

env | grep -i proxy

Contribuyendo

1. Bifurcar el repositorio

2. Crear una rama de características

3. Realiza tus cambios

4. Enviar una solicitud de extracción

Licencia

Instituto Tecnológico de Massachusetts (MIT)