Qdrant Memory

Uma implementação de grafo de conhecimento com busca semântica alimentada pelo banco de dados vetorial Qdrant.

GitHub
24
Experimente este MCPPatrocinado

Documentação

Servidor de Memória MCP com Persistência Qdrant

smithery badge

Este servidor MCP fornece uma implementação de grafo de conhecimento com recursos de busca semântica alimentados pelo banco de dados vetorial Qdrant.

Recursos

  • Representação de conhecimento baseada em grafo com entidades e relações
  • Persistência baseada em arquivos (memory.json)
  • Busca semântica usando o banco de dados vetorial Qdrant
  • Embeddings OpenAI para similaridade semântica
  • Suporte a HTTPS com compatibilidade com proxy reverso
  • Suporte a Docker para implantação fácil

Variáveis de Ambiente

As seguintes variáveis de ambiente são necessárias:

# 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

Configuração

Configuração Local

  1. Instale as dependências:
npm install
  1. Compile o servidor:
npm run build

Configuração Docker

  1. Compile a imagem Docker:
docker build -t mcp-qdrant-memory .
  1. Execute o contêiner Docker com as variáveis de ambiente necessárias:
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

Adicionar às configurações do 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"
      ]
    }
  }
}

Ferramentas

Gerenciamento de Entidades

  • create_entities: Criar múltiplas novas entidades
  • create_relations: Criar relações entre entidades
  • add_observations: Adicionar observações às entidades
  • delete_entities: Excluir entidades e suas relações
  • delete_observations: Excluir observações específicas
  • delete_relations: Excluir relações específicas
  • read_graph: Obter o grafo de conhecimento completo

Busca Semântica

  • search_similar: Buscar entidades e relações semanticamente semelhantes 
    interface SearchParams {
  query: string;     // Search query text
  limit?: number;    // Max results (default: 10)
}

Detalhes de Implementação

O servidor mantém duas formas de persistência:

  1. Baseada em arquivos (memory.json):

    • Estrutura completa do grafo de conhecimento
    • Acesso rápido ao grafo completo
    • Usada para operações de grafo

  2. Qdrant Vector DB:

    • Embeddings semânticos de entidades e relações
    • Permite busca por similaridade
    • Sincronizado automaticamente com o armazenamento de arquivos

Sincronização

Quando entidades ou relações são modificadas:

  1. As alterações são gravadas em memory.json
  2. Os embeddings são gerados usando OpenAI
  3. Os vetores são armazenados no Qdrant
  4. Ambos os sistemas de armazenamento permanecem consistentes

Processo de Busca

Ao buscar:

  1. O texto da consulta é convertido em embedding
  2. O Qdrant realiza a busca por similaridade
  3. Os resultados incluem entidades e relações
  4. Os resultados são classificados por similaridade semântica

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

Configuração de HTTPS e Proxy Reverso

O servidor suporta conexão ao Qdrant por HTTPS e proxies reversos. Isso é particularmente útil quando:

  • Executando o Qdrant atrás de um proxy reverso como Nginx ou Apache
  • Usando certificados autoassinados
  • Exigindo configurações personalizadas de SSL/TLS

Configuração com um Proxy Reverso

  1. Configure seu proxy reverso (exemplo 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;
    }
}
  1. Atualize suas variáveis de ambiente:
QDRANT_URL=https://qdrant.yourdomain.com

Considerações de Segurança

O servidor implementa tratamento HTTPS robusto com:

  • Configuração personalizada de SSL/TLS
  • Opções adequadas de verificação de certificados
  • Pooling de conexões e keepalive
  • Repetição automática com backoff exponencial
  • Timeouts configuráveis

Solução de Problemas de Conexões HTTPS

Se você tiver problemas de conexão:

  1. Verifique seus certificados:
openssl s_client -connect qdrant.yourdomain.com:443
  1. Teste a conectividade direta:
curl -v https://qdrant.yourdomain.com/collections
  1. Verifique se há configurações de proxy:
env | grep -i proxy

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de recurso
  3. Faça suas alterações
  4. Envie um pull request

Licença

MIT