Graphiti MCP Server

Graphiti MCP Server

O Graphiti MCP Server é um backend de gráfico de conhecimento multi-projeto, controlado por CLI, para agentes de IA, construído sobre um fork do getzep/graphiti. Ele permite o rápido gerenciamento de gráficos de conhecimento temporais, isolamento de projetos e integração fluida com IDE/agentes. Tudo isso é alimentado pelo Protocolo de Contexto do Modelo (MCP) e suportado por uma única instância do Neo4j. Cada projeto obtém seu próprio servidor MCP isolado e namespace de gráfico, permitindo extração flexível de entidades, recarregamento quente e contenção robusta de falhas, tornando-o ideal para fluxos de trabalho de IA escaláveis.

Author: rawr-ai


Ver Protocolo

O que é o Graphiti MCP Server?

O Graphiti MCP Server é uma camada de gerenciamento de código aberto para construir, executar e isolar backends de gráfico de conhecimento em vários projetos, usando um banco de dados Neo4j unificado. Ele estende o servidor Graphiti MCP upstream, permitindo múltiplos servidores MCP com escopo de projeto, cada um com sua própria configuração, namespace de grupo, regras de extração de entidades e modelo LLM, mas compartilhando a infraestrutura comum. Seu CLI automatizado gera arquivos de configuração do Docker Compose e da IDE, garantindo uma fácil configuração multi-projeto e integração fluida com ferramentas populares de desenvolvimento de IA e editores que suportam MCP.

Como Configurar

  1. Clone o repositório:
    git clone https://github.com/rawr-ai/mcp-graphiti.git && cd mcp-graphiti
  2. Configure o ambiente:
    Copie .env.example para .env, e forneça uma senha segura do Neo4j e a chave do OpenAI.
    Nota: O servidor se recusa a inicializar com a senha padrão, a menos que esteja sendo executado em modo de desenvolvimento explícito (GRAPHITI_ENV=dev).
  3. Instale o CLI:
    Instale globalmente via pipx install . --include-deps (usuarios), ou configure um virtualenv local (colaboradores).
  4. Configure projetos:
    Edite ou crie mcp-projects.yaml na raiz do repositório. Defina as entradas do projeto com seus diretórios principais e quaisquer configurações específicas do projeto.
  5. (Opcional) Gerencie a integração da IDE:
    O CLI gera automaticamente .cursor/mcp.json para cada projeto e mapeamento de porta, garantindo que seu editor possa descobrir automaticamente os endpoints do MCP.

Como Usar

  1. Gere o Docker Compose e a configuração do MCP:
    Na raiz do repositório, execute graphiti compose para escanear mcp-projects.yaml e gerar docker-compose.yml além das configurações do editor.
  2. Inicie todos os serviços:
    Execute graphiti up -d para começar o Neo4j e um servidor MCP por projeto (nas portas 8000, 8001, ...).
  3. Inicialize novos projetos:
    Na raiz do repositório do seu projeto, execute graphiti init [seu-projeto] para criar as configurações e os YAMLs de extração de entidades.
  4. Recarregue ou atualize um projeto em execução:
    Após editar as definições de entidades ou configurações de modelo, execute graphiti reload mcp-[projeto] para aplicar as mudanças sem afetar outros projetos.
  5. Acesse os endpoints:
    • Status do MCP: http://localhost:800X/status
    • Endpoint SSE para agentes: http://localhost:800X/sse
    • Navegador Neo4j: http://localhost:7474
  6. Mantenha isolamento de projetos:
    Cada servidor é nomeado via group_id, mantendo dados e contextos de LLM separados e resistentes a falhas.

Principais Funcionalidades

  • Suporte a múltiplos projetos: Inicie e isole vários servidores MCP (um por projeto) compartilhando uma única instância do Neo4j para eficiência de custo e manutenção.
  • Gráficos de conhecimento temporais: Constrói e versiona automaticamente gráficos de entidades/relações ao longo do tempo, permitindo que agentes acessem dados históricos e contextos versionados.
  • Fluxos de trabalho de CLI automatizados: Escaneia as configurações do projeto, gera todas as composições/configurações da IDE e suporta recarregamento quente com mínima fricção.
  • Isolamento de falhas e dependências: Cada projeto obtém seu próprio contêiner e group_id — prompts ou configurações incorretas são contidas.
  • Extração intercambiável: Recarregue YAMLs de entidades ou modelos LLM por projeto sem afetar outros ou exigir reinícios completos da pilha.
  • Descoberta automática de editores e agentes: Endpoints do MCP são adicionados automaticamente a .cursor/mcp.json, para que ferramentas como VS Code, Cursor, LangGraph, Autogen ou Claude Desktop possam acessar imediatamente as ferramentas do projeto.
  • Segurança de nível profissional: Verificações de senha rigorosas para Neo4j; ações destrutivas exigem confirmação explícita baseada no ambiente.

Casos de Uso

  • Sistemas corporativos multi-agente: Suporte seguro para várias equipes ou agentes de IA colaborando em gráficos de conhecimento isolados, mas co-hospedados (por exemplo, conhecimento de produto, bots de suporte, auditorias de conformidade).
  • Ferramentas de pesquisa impulsionadas por LLM: Permitir que pesquisadores ingestem continuamente literatura ou dumps de recursos em gráficos de conhecimento versionados e consultáveis, por tópico ou subsídio.
  • Assistentes IDE plugáveis: Fornecer inteligência de projeto sempre sincronizada e ciente do contexto para assistentes de codificação de IA, sem risco de vazamentos de dados ou colisões de projeto.
  • Rastreamento de experimentos: Manter gráficos separados e com timestamp para cada experimento de ML/RAG, com rollback e auditoria para cada alteração.
  • Paralelização de desenvolvimento/teste: Teste novos modelos de extração de entidades e lógica atualizada em paralelo, sem downtime ou risco para os gráficos de conhecimento em produção.

FAQ

Q: Posso executar apenas um servidor MCP (projeto único)?
A: Sim. Apague todos os outros projetos de mcp-projects.yaml ou defina MCP_SINGLE_SERVER=true em seu ambiente, então execute novamente graphiti compose. Todas as requisições irão passar por um único contêiner e porta.

Q: Como é aplicado o isolamento de projetos — por portas ou de outra forma?
A: Ambos. Cada servidor MCP é executado em sua porta única, mas o isolamento a nível de dados é aplicado por meio de um parâmetro group_id necessário em cada leitura/gravação, de modo que as consultas e gráficos nunca cruzem fronteiras.

Q: Posso adicionar um proxy reverso ou um API gateway na frente?
A: Absolutamente. Você pode direcionar todo o tráfego dos agentes através de um único endpoint, injetando group_id como uma reivindicação ou cabeçalho, e fazer o servidor root se ramificar conforme necessário.

Q: O que acontece se eu precisar alterar uma regra de extração de entidades ou trocar modelos LLM?
A: Basta atualizar o YAML ou configuração relevante na pasta do seu projeto, depois execute graphiti reload mcp-[projeto]; nenhum reinício ou downtime para outros projetos é necessário.

Q: Como eu apago completamente o gráfico do Neo4j?
A: Defina NEO4J_DESTROY_ENTIRE_GRAPH=true em seu .env, depois execute graphiti up — isso irá deletar IRREVERSIVELMENTE todos os dados do projeto. Use apenas quando tiver certeza.