KnowledgeGraph MCP Server

Permite armazenamento persistente de conhecimento para Claude usando um grafo de conhecimento com múltiplos backends de banco de dados como PostgreSQL e SQLite.

GitHub
26
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

AVISO

Fiquei desiludido com ferramentas automatizadas de gerenciamento de contexto como esta, pois é quase impossível controlá-las. Depois de um tempo, sempre tenho que limpar manualmente a bagunça ou corrigir anotações inadequadas do LLM. Em vez disso, criei uma ferramenta que dá ao agente LLM acesso a contexto carregado dinamicamente. No entanto, o contexto em si é criado pelo usuário: https://github.com/n-r-w/agent-standards-mcp

KnowledgeGraph MCP Server

Uma maneira simples de dar aos LLMs memória persistente entre conversas. Este servidor permite que o Claude ou o vscode lembrem informações sobre você, seus projetos e suas preferências usando um grafo de conhecimento.

Principais recursos:

  • Múltiplos backends de armazenamento: PostgreSQL (recomendado) ou SQLite (arquivo local)
  • Separação de projetos: Mantenha diferentes projetos isolados (detecção automática usando prompts)
  • Melhor busca: Encontre informações com busca difusa e paginação

Guia de Configuração Completo

Siga estes passos em ordem para fazer o grafo de conhecimento funcionar com o Claude:

Passo 1: Escolha seu Método de Instalação

Opção A: NPX (Mais fácil - sem necessidade de download)

# Test that it works
npx knowledgegraph-mcp --help

Opção B: Docker

# Clone and build
git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
docker build -t knowledgegraph-mcp .

Passo 2: Escolha seu Banco de Dados

SQLite (Padrão - sem configuração necessária):

  • Nenhuma instalação de banco de dados necessária
  • Arquivo de banco de dados criado automaticamente em [you home folder]/.knowledge-graph/
  • Perfeito para uso pessoal e na maioria dos cenários
  • Este é o backend padrão

PostgreSQL (Para usuários avançados):

  • Instale o PostgreSQL no seu sistema
  • Crie um banco de dados: CREATE DATABASE knowledgegraph;
  • Melhor para uso em produção com múltiplos usuários simultâneos

Passo 3: Configure o cliente

Claude Desktop

Edite seu arquivo de configuração do Claude Desktop:

Encontre seu arquivo de configuração:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Se você escolheu NPX + SQLite (padrão e mais fácil):

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"]
    }
  }
}

Nota: O SQLite criará automaticamente o banco de dados em [you home folder]/.knowledge-graph/knowledgegraph.db. Para usar um local personalizado, adicione: "KNOWLEDGEGRAPH_SQLITE_PATH": "/path/to/your/database.db"

Se você escolheu Docker + SQLite (padrão):

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "[you home folder]/.knowledge-graph:/app/.knowledge-graph",
        "knowledgegraph-mcp"
      ]
    }
  }
}

Nota: A montagem de volume garante que seus dados persistam entre execuções do Docker. Para caminhos personalizados, adicione: -e KNOWLEDGEGRAPH_SQLITE_PATH=/app/.knowledge-graph/custom.db

Se você escolheu PostgreSQL:

{
  "mcpServers": {
    "Knowledge Graph": {
      "command": "npx",
      "args": ["-y", "knowledgegraph-mcp"],
      "env": {
        "KNOWLEDGEGRAPH_STORAGE_TYPE": "postgresql",
        "KNOWLEDGEGRAPH_CONNECTION_STRING": "postgresql://postgres:yourpassword@localhost:5432/knowledgegraph"
      }
    }
  }
}

VS Code

Se você também quiser usar isso com o VS Code, adicione isto às suas Configurações do Usuário (JSON) ou crie .vscode/mcp.json:

Usando NPX + SQLite (padrão):

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "npx",
        "args": ["-y", "knowledgegraph-mcp"],
      }
    }
  }
}

Usando Docker (SQLite padrão):

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=sqlite://./knowledgegraph.db",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Usando Docker + PostgreSQL:

Primeiro, certifique-se de que seu banco de dados PostgreSQL esteja configurado:

# Create the database (run this once)
psql -h 127.0.0.1 -p 5432 -U postgres -c "CREATE DATABASE knowledgegraph;"

Depois configure o VS Code:

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--network", "host",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@127.0.0.1:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Alternativa Docker + PostgreSQL (se --network host não funcionar):

{
  "mcp": {
    "servers": {
      "Knowledge Graph": {
        "command": "docker",
        "args": [
          "run", "-i", "--rm",
          "--add-host", "host.docker.internal:host-gateway",
          "-e", "KNOWLEDGEGRAPH_STORAGE_TYPE=postgresql",
          "-e", "KNOWLEDGEGRAPH_CONNECTION_STRING=postgresql://postgres:yourpassword@host.docker.internal:5432/knowledgegraph",
          "knowledgegraph-mcp"
        ]
      }
    }
  }
}

Notas Importantes:

  • Substitua yourpassword pela sua senha real do PostgreSQL
  • Certifique-se de que o banco de dados knowledgegraph exista antes de iniciar
  • Se você receber erros de conexão, tente a configuração alternativa acima
  • Para solucionar problemas com Docker + PostgreSQL, consulte a seção Problemas Comuns

Passo 4: Escolha os Prompts de Sistema do seu LLM

Personalização:

  • Modifique os tipos de entidade com base no seu domínio
  • Ajuste as estratégias de busca para seus padrões de dados
  • Adicione tags e tipos de relação específicos do domínio

Compatibilidade com LLM:

  • Todos os LLMs se comportam de maneira diferente. Para alguns, instruções gerais são suficientes, enquanto outros precisam descrever tudo em detalhes
  • Use o LLM para explicar por que ele não usou o grafo de conhecimento. Pergunte a Explain STEP-BY-STEP why you didn't use the knowledge graph? DO NOT DO ANYTHING ELSE para obter um relatório detalhado e identificar problemas com as instruções.

Prompts Disponíveis:

Passo 5: Reinicie o Claude Desktop (ou VS Code)

Feche e reabra o Claude Desktop. Você agora deve ver "Knowledge Graph" nas suas ferramentas disponíveis.

Passo 6: Teste se Funciona

Comandos de Teste Rápidos para LLMs:

  1. "Lembre-se de que prefiro reuniões pela manhã" → Cria entidade de preferência
  2. "John Smith trabalha no Google como engenheiro de software" → Cria pessoa + empresa + relação
  3. "Encontre todas as pessoas que trabalham no Google" → Testa busca e relações
  4. "Marque a preferência de reuniões pela manhã como urgente" → Testa tags

Nota: O serviço inclui validação abrangente de entrada para evitar erros. Se você encontrar algum problema, consulte o Guia de Solução de Problemas para soluções comuns.

Como Funciona - Recursos Avançados do LLM

O grafo de conhecimento permite consultas poderosas através de quatro conceitos interconectados:

1. Entidades - Seus Nós de Conhecimento

Armazene pessoas, projetos, empresas, tecnologias como entidades pesquisáveis.

Exemplo Real - Gerenciamento de Projetos:

{
  "name": "Sarah_Chen",
  "entityType": "person",
  "observations": ["Senior React developer", "Leads frontend team", "Available for urgent tasks"],
  "tags": ["developer", "team-lead", "available"]
}

Benefício para o LLM: Encontre "todos os líderes de equipe disponíveis" instantaneamente com busca por tags.

2. Relações - Habilite Consultas de Descoberta

Conecte entidades para responder perguntas complexas como "Quem trabalha em quê?"

Exemplo Real - Estrutura de Equipe:

{
  "from": "Sarah_Chen",
  "to": "Project_Alpha",
  "relationType": "leads"
}

Benefício para o LLM: Consulte "Encontre todos os projetos liderados por Sarah" ou "Quem lidera o Projeto Alpha?"

3. Observações - Fatos Atômicos

Armazene fatos específicos e pesquisáveis sobre entidades.

Exemplos Reais - Informações Acionáveis:

  • "Disponível para tarefas urgentes" → Encontre pessoas disponíveis
  • "Usa React 18.2" → Encontre projetos com tecnologia específica
  • "Prazo: 15 de março de 2024" → Encontre prazos futuros

4. Tags - Filtragem Instantânea

Habilite buscas imediatas por status e categoria.

Exemplos Reais - Fluxo de Trabalho de Projetos:

  • ["urgent", "in-progress", "frontend"] → Encontre tarefas urgentes de frontend
  • ["completed", "bug-fix"] → Acompanhe correções de bugs concluídas
  • ["available", "senior"] → Encontre funcionários seniores disponíveis

Opções de Configuração

Variáveis de Ambiente

O servidor suporta várias variáveis de ambiente para personalização:

Configuração do Banco de Dados

  • KNOWLEDGEGRAPH_STORAGE_TYPE: Tipo de banco de dados (sqlite ou postgresql, padrão: sqlite)
  • KNOWLEDGEGRAPH_CONNECTION_STRING: String de conexão do banco de dados
  • KNOWLEDGEGRAPH_SQLITE_PATH: Caminho personalizado do banco de dados SQLite (opcional)
  • KNOWLEDGEGRAPH_PROJECT: Identificador do projeto para isolamento de dados (padrão: knowledgegraph_default_project)

Configuração de Busca

  • KNOWLEDGEGRAPH_SEARCH_MAX_RESULTS: Número máximo de resultados a retornar das buscas no banco de dados (padrão: 100, máximo: 1000)
  • KNOWLEDGEGRAPH_SEARCH_BATCH_SIZE: Tamanho do lote para processar grandes arrays de consulta (padrão: 10, máximo: 50)
  • KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES: Número máximo de entidades a carregar para busca no lado do cliente (padrão: 10000, máximo: 100000)
  • KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE: Tamanho do bloco para processar grandes conjuntos de dados na busca no lado do cliente (padrão: 1000, máximo: 10000)

Nota: Os limites de busca são automaticamente validados e limitados a faixas seguras para evitar problemas de desempenho.

Otimização de Desempenho

O sistema de busca inclui várias otimizações de desempenho:

Limites de Carregamento de Entidades:

  • KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES limita quantas entidades são carregadas para busca no lado do cliente
  • Previne problemas de memória com grandes conjuntos de dados
  • Aviso registrado quando o limite é atingido
  • Aplica-se aos backends SQLite e PostgreSQL

Processamento em Blocos:

  • KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE controla o tamanho do bloco para grandes conjuntos de entidades
  • Usado automaticamente quando a contagem de entidades excede o tamanho do bloco
  • Melhora o uso de memória e o desempenho da busca
  • Mantém a precisão dos resultados com deduplicação

Valores Recomendados por Tamanho do Conjunto de Dados:

  • Pequeno (< 1.000 entidades): Os valores padrão funcionam bem
  • Médio (1.000 - 10.000 entidades): Considere KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=5000, KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=500
  • Grande (> 10.000 entidades): Use busca no nível do banco de dados quando possível, ou KNOWLEDGEGRAPH_SEARCH_MAX_CLIENT_ENTITIES=2000, KNOWLEDGEGRAPH_SEARCH_CLIENT_CHUNK_SIZE=200

Monitoramento de Desempenho:

  • Avisos registrados quando os limites são aplicados
  • Divisão em blocos registrada automaticamente para transparência
  • A validação de configuração previne configurações abaixo do ideal

Ferramentas Disponíveis

O servidor fornece estas ferramentas para gerenciar seu grafo de conhecimento:

Ferramentas de Criação de Dados

create_entities

CRIE novas entidades (pessoas, conceitos, objetos) no grafo de conhecimento.

  • QUANDO: Use para entidades que ainda não existem
  • RESTRIÇÃO: Cada entidade DEVE ter ≥1 observação não vazia
  • COMPORTAMENTO: Ignora entidades com nomes existentes (use add_observations para atualizar)

Entrada:

  • entities (Entity[]): Array de objetos de entidade. Cada um REQUER:
    • name (string): Identificador único, não vazio
    • entityType (string): Categoria (ex.: 'person', 'project'), não vazia
    • observations (string[]): Fatos sobre a entidade, DEVE conter ≥1 string não vazia
    • tags (string[], opcional): Rótulos de correspondência exata para filtragem
  • project_id (string, opcional): Nome do projeto para isolar dados

create_relations

CONECTE entidades para habilitar consultas poderosas e descoberta.

  • BENEFÍCIOS IMEDIATOS: Encontre todas as pessoas em uma empresa, todos os projetos que usam uma tecnologia, todas as dependências
  • CRÍTICO PARA: Estruturas de equipe, dependências de projetos, pilhas de tecnologia
  • EXEMPLOS: 'John works_at Google', 'React depends_on JavaScript', 'Project_Alpha managed_by Sarah'

Entrada:

  • relations (Relation[]): Array de objetos de relacionamento. Cada um REQUER:
    • from (string): Nome da entidade de origem (deve existir)
    • to (string): Nome da entidade de destino (deve existir)
    • relationType (string): Tipo de relacionamento na voz ativa (works_at, manages, depends_on, uses)
  • project_id (string, opcional): Nome do projeto para isolar dados

add_observations

ADICIONE observações factuais a entidades existentes.

  • REQUISITO: A entidade de destino deve existir, ≥1 observação não vazia por atualização
  • MELHOR PRÁTICA: Mantenha as observações atômicas e específicas

Entrada:

  • observations (ObservationUpdate[]): Array de atualizações de observação. Cada uma REQUER:
    • entityName (string): Nome da entidade de destino (deve existir)
    • observations (string[]): Novos fatos a adicionar, DEVE conter ≥1 string não vazia
  • project_id (string, opcional): Nome do projeto para isolar dados

add_tags

ADICIONE tags de status/categoria para filtragem INSTANTÂNEA.

  • BENEFÍCIO IMEDIATO: Encontre entidades por status (urgente, concluído, em andamento) ou tipo (técnico, pessoal)
  • REQUERIDO: Para gerenciamento eficiente de projetos e recuperação rápida
  • EXEMPLOS: ['urgent', 'completed', 'bug', 'feature', 'personal']

Entrada:

  • updates (TagUpdate[]): Array de atualizações de tags. Cada uma REQUER:
    • entityName (string): Nome da entidade de destino (deve existir)
    • tags (string[]): Tags de status/categoria a adicionar (correspondência exata, sensível a maiúsculas/minúsculas)
  • project_id (string, opcional): Nome do projeto para isolar dados

Ferramentas de Recuperação de Dados

read_graph

RECUPERE o grafo de conhecimento completo com todas as entidades e relacionamentos.

  • CASO DE USO: Visão geral completa, compreensão do estado atual, visualização de todas as conexões
  • ESCOPO: Retorna tudo no projeto especificado

Entrada:

  • project_id (string, opcional): Nome do projeto para isolar dados

search_knowledge

BUSQUE entidades por texto ou tags. SUPORTA MÚLTIPLAS CONSULTAS para busca em lote.

  • ESTRATÉGIA OBRIGATÓRIA: 1) Tente searchMode='exact' primeiro 2) Se não houver resultados, use searchMode='fuzzy' 3) Se ainda estiver vazio, reduza fuzzyThreshold para 0.1
  • MODO EXATO: Correspondências perfeitas de substring (rápido, preciso)
  • MODO DIFUSO: Termos semelhantes/com erros de digitação (mais lento, mais amplo)
  • BUSCA POR TAGS: Use exactTags para filtragem precisa por categoria
  • MÚLTIPLAS CONSULTAS: Busque múltiplos objetos em uma única chamada com deduplicação automática Entrada:
  • query (string | string[], opcional): Consulta de busca para pesquisa de texto. Pode ser uma única string ou um array de strings para busca de múltiplos objetos. OPCIONAL quando exactTags é fornecido para buscas apenas por tags.
  • searchMode (string, opcional): "exact" ou "fuzzy" (padrão: "exact"). Use fuzzy apenas se exact não retornar resultados
  • fuzzyThreshold (number, opcional): Limiar de similaridade fuzzy. 0.3=padrão, 0.1=muito amplo, 0.7=muito estrito. Valores menores encontram mais resultados
  • exactTags (string[], opcional): Tags para busca por correspondência exata (sensível a maiúsculas/minúsculas). Use para filtragem por categoria
  • tagMatchMode (string, opcional): Para exactTags: "any"=entidades com QUALQUER tag, "all"=entidades com TODAS as tags (padrão: "any")
  • page (number, opcional): Número da página para paginação (baseado em 0, padrão: 0)
  • pageSize (number, opcional): Número de resultados por página (1-1000, padrão: 50)
  • project_id (string, opcional): Nome do projeto para isolar dados

Exemplos:

  • Busca básica: search_knowledge(query="JavaScript", searchMode="exact")
  • Busca paginada: search_knowledge(query="React", page=0, pageSize=20)
  • Conjunto de dados grande: search_knowledge(query="components", page=2, pageSize=100)
  • Múltiplas consultas: search_knowledge(query=["JavaScript", "React"], page=0, pageSize=30)
  • Tag + paginação: search_knowledge(query="React", exactTags=["frontend"], page=1, pageSize=25)
  • Busca apenas por tag: search_knowledge(exactTags=["urgent", "bug"], tagMatchMode="all") - NENHUMA CONSULTA NECESSÁRIA

Benefícios da Paginação:

  • Desempenho: Paginação em nível de banco de dados com OFFSET/LIMIT para manipulação eficiente de grandes conjuntos de dados
  • Memória: Reduz o uso de memória limitando os resultados por solicitação
  • Navegação: Os metadados de paginação fornecem totalPages, currentPage e dicas de navegação
  • Escalabilidade: Manipula grafos de conhecimento com milhares de entidades de forma eficiente

open_nodes

RECUPERA entidades específicas por nomes exatos com suas interconexões.

  • RETORNA: Entidades solicitadas mais relacionamentos entre elas
  • CASO DE USO: Quando você sabe os nomes exatos das entidades e deseja informações detalhadas

Entrada:

  • names (string[]): Array de nomes de entidades para recuperar
  • project_id (string, opcional): Nome do projeto para isolar dados

Ferramentas de Gerenciamento de Dados

delete_entities

EXCLUI PERMANENTEMENTE entidades e todos os seus relacionamentos.

  • AVISO: Não pode ser desfeito, cascateia para remover todas as conexões
  • CASO DE USO: Entidades que não são mais relevantes ou criadas por engano

Entrada:

  • entityNames (string[]): Array de nomes de entidades para excluir
  • project_id (string, opcional): Nome do projeto para isolar dados

delete_observations

REMOVE observações específicas das entidades mantendo as entidades intactas.

  • CASO DE USO: Corrigir informações incorretas ou remover detalhes obsoletos
  • PRESERVAÇÃO: A entidade e outras observações permanecem inalteradas

Entrada:

  • deletions (ObservationDeletion[]): Array de solicitações de exclusão. Cada uma REQUER:
    • entityName (string): Nome da entidade alvo
    • observations (string[]): Observações específicas para remover
  • project_id (string, opcional): Nome do projeto para isolar dados

delete_relations

ATUALIZA a estrutura de relacionamentos quando as conexões mudam.

  • CRÍTICO PARA: Mudanças de emprego (remover 'works_at' antigo), conclusão de projetos (remover 'assigned_to'), migração de tecnologia (remover 'uses' antigo)
  • MANTÉM: Estrutura de rede precisa e evita confusão
  • FLUXO DE TRABALHO: Sempre remova relações desatualizadas ao criar novas

Entrada:

  • relations (Relation[]): Array de relações para excluir. Cada uma REQUER:
    • from (string): Nome da entidade de origem
    • to (string): Nome da entidade de destino
    • relationType (string): Tipo exato de relacionamento para remover
  • project_id (string, opcional): Nome do projeto para isolar dados

remove_tags

ATUALIZA o status da entidade removendo tags desatualizadas.

  • CRÍTICO: Para rastreamento de status - remova 'in-progress' quando concluído, 'urgent' quando resolvido
  • MANTÉM: Resultados de busca limpos e status preciso
  • FLUXO DE TRABALHO: Sempre remova tags de status antigas ao adicionar novas

Entrada:

  • updates (TagUpdate[]): Array de solicitações de remoção de tags. Cada uma REQUER:
    • entityName (string): Nome da entidade alvo
    • tags (string[]): Tags desatualizadas para remover (correspondência exata, sensível a maiúsculas/minúsculas)
  • project_id (string, opcional): Nome do projeto para isolar dados

Desenvolvimento e Testes

Testes Multi-Backend

Este projeto inclui testes multi-backend abrangentes para garantir compatibilidade com SQLite e PostgreSQL:

Execute testes contra ambos os backends:

npm run test:multi-backend

Execute todos os testes (original + multi-backend):

npm run test:all-backends

Usando Taskfile (se instalado):

task test:multi-backend
task test:comprehensive

Configuração de Desenvolvimento

Clone e configure:

git clone https://github.com/n-r-w/knowledgegraph-mcp.git
cd knowledgegraph-mcp
npm install
npm run build

Execute testes:

npm test                    # All tests including multi-backend
npm run test:unit          # Unit tests only
npm run test:performance   # Performance benchmarks

Solução de Problemas

Se você encontrar qualquer problema durante a configuração ou uso, consulte nosso abrangente Guia de Solução de Problemas, que cobre:

  • Erros de validação de entrada
  • Problemas de conexão com banco de dados
  • Problemas de configuração
  • Desafios relacionados a Docker
  • Falhas na execução de testes
  • Otimização de desempenho

O guia inclui soluções passo a passo para problemas comuns e comandos de diagnóstico para ajudar a identificar problemas.

Baseado no MCP Memory Server

Esta é uma versão aprimorada do MCP Memory Server oficial com recursos adicionais:

  • Múltiplas Opções de Armazenamento: PostgreSQL (recomendado) ou SQLite (arquivo local)
  • Separação de Projetos: Mantenha diferentes projetos isolados
  • Melhor Busca: Encontre informações com busca difusa
  • Configuração Fácil: Suporte a Docker e instalação simples

Licença

Licença MIT - Sinta-se à vontade para usar, modificar e distribuir este software.