AI导哈

Neo4j知识图谱存储系统

一个使用Neo4j构建的持久化知识图谱存储系统，为Claude Code SDK提供全局配置的知识管理功能，支持实体创建、关系建立和全文搜索。

  • by diegofornalha
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 diegofornalha/mcp-neo4j-py

使用说明

MCP Neo4j Python - Grafo de Conhecimento Global

Sistema de memória persistente usando Neo4j para o Claude Code SDK, configurado globalmente para todos os projetos.

🚀 Quick Start

O MCP já está configurado globalmente! Use em qualquer projeto:

# Verificar status
claude mcp list

# Deve mostrar:
# neo4j-memory: /Users/2a/.claude/mcp-neo4j-py/run_mcp.sh - ✓ Connected

📚 Documentação

🛠️ Ferramentas Disponíveis

Leitura

  • read_graph - Ler grafo completo com filtro opcional
  • search_memories - Busca fulltext em memórias
  • find_memories_by_name - Buscar por nomes exatos

Escrita

  • create_entities - Criar/atualizar entidades
  • create_relations - Criar relações entre entidades
  • add_observations - Adicionar observações

Exclusão

  • delete_observations - Remover observações específicas
  • delete_entities - Deletar entidades
  • delete_relations - Deletar relações

🏗️ Arquitetura

src/mcp_neo4j/
├── core/           # Lógica de negócio
│   ├── config.py   # Configurações do servidor
│   └── memory.py   # Operações de memória
├── database/       # Camada de dados
│   └── connection.py
├── server/         # Servidor MCP
│   ├── mcp_server.py
│   └── runtime.py
└── utils/          # Utilitários
    └── logging_setup.py

⚡ Otimizações de Performance

Para evitar respostas MCP muito grandes (~10k+ tokens), o servidor aplica limites automáticos:

  • Máximo de 50 entidades por query (configurável via MEMORY_MAX_ENTITIES)
  • Máximo de 20 observações por entidade (configurável via MEMORY_MAX_OBSERVATIONS)
  • Ordenação por relevância usando scores de fulltext search

Ajustar Limites

Edite o arquivo .env para personalizar:

# Para projetos menores (respostas mais rápidas)
MEMORY_MAX_ENTITIES=25
MEMORY_MAX_OBSERVATIONS=10

# Para projetos maiores (mais contexto)
MEMORY_MAX_ENTITIES=100
MEMORY_MAX_OBSERVATIONS=30

Por que Limitar?

  • Context Window: Respostas menores consomem menos tokens
  • Performance: Queries mais rápidas
  • UX: Claude Code recebe respostas instantâneas
  • Custo: Menos tokens = menor custo de API

🔧 Desenvolvimento

Setup Local

# Clonar e entrar no diretório
cd /Users/2a/.claude/mcp-neo4j-py

# Ativar ambiente virtual
source venv/bin/activate

# Instalar em modo desenvolvimento
pip install -e .

Executar Localmente

# Via script wrapper
./run_mcp.sh

# Ou diretamente
venv/bin/python -m mcp_neo4j

Testes

# Executar testes
pytest tests/

# Com cobertura
pytest --cov=src/mcp_neo4j tests/

📊 Modelo de Dados

Entidade (Learning)

{
    "name": "Nome único da entidade",
    "type": "person | company | concept | event",
    "observations": ["Fato 1", "Fato 2", ...]
}

Relação

{
    "source": "Nome da entidade origem",
    "target": "Nome da entidade destino",
    "relationType": "WORKS_AT | USES | CONNECTS_TO"
}

🌟 Casos de Uso

1. Armazenar Conhecimento Técnico

"Crie uma entidade Learning sobre Hooks do Claude SDK"
→ Armazena conceitos, exemplos e padrões

2. Conectar Conceitos

"Conecte o conceito de Hooks com Custom Tools"
→ Cria grafo de conhecimento relacionado

3. Buscar Soluções

"Busque no conhecimento sobre async Python"
→ Encontra aprendizados anteriores

4. Aprender com Erros

"Adicione observação: erro corrigido usando context manager"
→ Registra lições aprendidas

🔐 Configuração

Variáveis de Ambiente (.env)

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=password
NEO4J_DATABASE=neo4j
MCP_LOG_LEVEL=INFO

Configuração Global MCP

# Adicionar globalmente
claude mcp add --scope user neo4j-memory \
  /Users/2a/.claude/mcp-neo4j-py/run_mcp.sh

# Remover
claude mcp remove neo4j-memory -s user

🐛 Troubleshooting

Servidor não conecta

  1. Verificar se Neo4j está rodando: neo4j status
  2. Testar conexão: cypher-shell -u neo4j -p password
  3. Ver logs: ./run_mcp.sh (modo debug)

Erro de Python

  1. Verificar versão: venv/bin/python --version (deve ser 3.11+)
  2. Reinstalar: pip install -e .

Reconfigurar do Zero

# Remover configurações
claude mcp remove neo4j-memory -s user
claude mcp remove neo4j-memory -s local

# Recriar venv
rm -rf venv
python3.11 -m venv venv
source venv/bin/activate
pip install -e .

# Adicionar globalmente
claude mcp add --scope user neo4j-memory \
  /Users/2a/.claude/mcp-neo4j-py/run_mcp.sh

🔄 Changelog

v0.1.0 (2025-10-06)

  • ✅ Configuração global do MCP
  • ✅ Correção de bug do event loop
  • ✅ Script wrapper para execução
  • ✅ Documentação completa
  • ✅ Label "Learning" como padrão

🤝 Contribuindo

  1. Fork o projeto
  2. Crie uma branch: git checkout -b feature/nova-feature
  3. Commit: git commit -am 'Adiciona nova feature'
  4. Push: git push origin feature/nova-feature
  5. Pull Request

📝 Licença

Este projeto está sob licença MIT.

🙏 Agradecimentos

📞 Suporte

相关 MCP