Gremlin

Interaja com qualquer banco de dados gráfico compatível com Gremlin usando linguagem natural, com suporte para descoberta de esquemas, consultas complexas e importação/exportação de dados.

GitHub

Documentação

Servidor MCP Gremlin

Conecte agentes de IA como Claude, Cursor e Windsurf aos seus bancos de dados de grafos!

Um servidor MCP (Model Context Protocol) que permite a assistentes de IA interagir com qualquer banco de dados de grafos compatível com Gremlin por meio de linguagem natural. Consulte seus dados, descubra esquemas, analise relacionamentos e gerencie dados de grafos usando conversas simples.

✨ O que você pode fazer

Fale com seu banco de dados de grafos naturalmente:

🔍 "Qual é a estrutura do meu grafo?" - Descoberta automática de esquema
📊 "Mostre-me todos os usuários com mais de 30 anos e suas conexões" - Consultas complexas de grafos
🔗 "Encontre o caminho mais curto entre Alice e Bob" - Análise de relacionamentos
📈 "Dê-me estatísticas e métricas do grafo" - Insights de dados
📥 "Importe estes dados GraphSON" - Carregamento de dados
📤 "Exporte dados de usuários como CSV" - Extração de dados
🧠 Descoberta inteligente de enums - A IA aprende os valores válidos dos seus dados automaticamente

🛠️ Ferramentas disponíveis

Seu assistente de IA tem acesso a estas ferramentas poderosas:

Ferramenta	Finalidade	O que faz
🔍 get_graph_status	Verificação de saúde	Verifica a conectividade do banco de dados e o status do servidor
📋 get_graph_schema	Descoberta de esquema	Obtém a estrutura completa do grafo com nós, arestas e relacionamentos
⚡ run_gremlin_query	Execução de consultas	Executa qualquer consulta de travessia Gremlin com suporte completo de sintaxe
🔄 refresh_schema_cache	Gerenciamento de cache	Força a atualização imediata das informações de esquema em cache
📥 import_graph_data	Importação de dados	Carrega dados de GraphSON, CSV ou JSON com processamento em lote
📤 export_subgraph	Exportação de dados	Extrai subgrafos para os formatos JSON, GraphSON ou CSV

🚀 Configuração rápida

Passo 1: Instalação

# The npx command will automatically install the package if needed
# No separate installation step required

Alternativa: Compilar a partir do código-fonte

# Clone and setup
git clone https://github.com/kpritam/gremlin-mcp.git
cd gremlin-mcp
npm install
npm run build

Passo 2: Configurar seu cliente de IA

Adicione isso à configuração do seu cliente MCP:

Claude Desktop / Cursor / Windsurf

Usando o pacote publicado (recomendado):

{
  "mcpServers": {
    "gremlin": {
      "command": "npx",
      "args": ["@kpritam/gremlin-mcp"],
      "env": {
        "GREMLIN_ENDPOINT": "localhost:8182",
        "LOG_LEVEL": "info"
      }
    }
  }
}

A partir do código-fonte:

{
  "mcpServers": {
    "gremlin": {
      "command": "node",
      "args": ["/path/to/gremlin-mcp/dist/server.js"],
      "env": {
        "GREMLIN_ENDPOINT": "localhost:8182",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Com autenticação

{
  "mcpServers": {
    "gremlin": {
      "command": "npx",
      "args": ["@kpritam/gremlin-mcp"],
      "env": {
        "GREMLIN_ENDPOINT": "your-server.com:8182",
        "GREMLIN_USERNAME": "your-username",
        "GREMLIN_PASSWORD": "your-password",
        "GREMLIN_USE_SSL": "true"
      }
    }
  }
}

Passo 3: Iniciar seu servidor Gremlin

Certifique-se de que seu banco de dados compatível com Gremlin está em execução:

# For Apache TinkerPop Gremlin Server
./bin/gremlin-server.sh start

# Or using Docker
docker run -p 8182:8182 tinkerpop/gremlin-server

Passo 4: Testar a conexão

Reinicie seu cliente de IA e tente perguntar:

"Você pode verificar se meu banco de dados de grafos está conectado e me mostrar o esquema dele?"

💡 Exemplos de uso

Exploração de esquema

Você pergunta: "Qual é a estrutura do meu banco de dados de grafos?"

Resposta da IA: A IA chama get_graph_schema e informa sobre seus tipos de nós, tipos de arestas e como eles estão conectados.

Análise de dados

Você pergunta: "Mostre-me todas as pessoas com mais de 30 anos e seus relacionamentos"

Resposta da IA: A IA executa g.V().hasLabel('person').has('age', gt(30)).out().path() e explica os resultados em linguagem natural.

Métricas do grafo

Você pergunta: "Dê-me algumas estatísticas sobre meu grafo"

Resposta da IA: A IA executa várias consultas para contar nós, arestas e analisar a distribuição, depois apresenta um resumo.

Importação de dados

Você pergunta: "Carregue estes dados GraphSON no meu banco de dados"

Resposta da IA: A IA usa import_graph_data para processar seus dados em lotes e relata o status da importação.

🧠 Descoberta automática de enums

Por que isso importa: Agentes de IA funcionam melhor quando conhecem os valores válidos exatos para propriedades. Em vez de adivinhar ou fazer consultas inválidas, eles podem usar valores reais e precisos dos seus dados.

Um dos recursos mais poderosos deste servidor MCP é a Descoberta automática de enums - ele analisa de forma inteligente os dados do seu grafo para descobrir valores de propriedades válidos e os fornece como enums para os agentes de IA.

🤔 O problema que ele resolve

Sem descoberta de enums:

AI: "I see this vertex has a 'status' property of type 'string'...
     Let me try querying with status='active'"
Result: ❌ No results (actual values are 'CONFIRMED', 'PENDING', 'CANCELLED')

Com descoberta de enums:

AI: "I can see the 'status' property has these exact values:
     ['CONFIRMED', 'PENDING', 'CANCELLED', 'WAITLISTED']
     Let me query with status='CONFIRMED'"
Result: ✅ Perfect results using real data values

💡 Como funciona

O servidor escaneia automaticamente as propriedades do seu grafo e:

Identifica propriedades de baixa cardinalidade - Propriedades com um número razoável de valores distintos
Extrai valores reais - Amostra dados reais do seu grafo
Fornece como enums - Inclui valores válidos no esquema para os agentes de IA

Exemplo de saída:

{
  "name": "bookingStatus",
  "type": ["string"],
  "cardinality": "single",
  "enum": ["CONFIRMED", "PENDING", "CANCELLED", "WAITLISTED"],
  "sample_values": ["CONFIRMED", "PENDING"]
}

🎯 Benefícios para agentes de IA

🎯 Consultas precisas - A IA usa valores reais em vez de adivinhar
⚡ Resultados mais rápidos - Sem tentativa e erro com valores inválidos
🧠 Melhor compreensão - A IA aprende o vocabulário dos seus dados
📊 Análises mais inteligentes - Permite agrupamento e filtragem com categorias reais

⚙️ Opções de configuração

Ajuste a descoberta de enums para corresponder aos seus dados:

# Enable/disable enum discovery
GREMLIN_ENUM_DISCOVERY_ENABLED="true"         # Default: true

# Control what gets detected as enum
GREMLIN_ENUM_CARDINALITY_THRESHOLD="10"       # Max distinct values for enum (default: 10)

# Exclude specific properties
GREMLIN_ENUM_PROPERTY_BLACKLIST="id,uuid,timestamp,createdAt,updatedAt"

# Schema optimization
GREMLIN_SCHEMA_MAX_ENUM_VALUES="10"           # Limit enum values shown (default: 10)
GREMLIN_SCHEMA_INCLUDE_SAMPLE_VALUES="false"  # Reduce schema size (default: false)

🚫 Lista negra de propriedades

Algumas propriedades nunca devem ser tratadas como enums:

Excluídas automaticamente:

Propriedades de alta cardinalidade (> limite de valores únicos)
IDs numéricos e UUIDs
Timestamps e datas
Campos de texto longo

Exclusão manual:

# Exclude specific properties by name
GREMLIN_ENUM_PROPERTY_BLACKLIST="userId,sessionId,description,notes,content"

Padrões comuns de lista negra:

id,uuid,guid - Identificadores únicos
timestamp,createdAt,updatedAt,lastModified - Campos de tempo
description,notes,comment,content,text - Campos de texto livre
email,url,phone,address - Dados pessoais/contato
hash,token,key,secret - Campos relacionados à segurança

🛠️ Exemplos do mundo real

Grafo de comércio eletrônico:

{
  "orderStatus": {
    "enum": ["PENDING", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED"]
  },
  "productCategory": {
    "enum": ["ELECTRONICS", "CLOTHING", "BOOKS", "HOME", "SPORTS"]
  },
  "paymentMethod": {
    "enum": ["CREDIT_CARD", "PAYPAL", "BANK_TRANSFER", "CRYPTO"]
  }
}

Grafo de rede social:

{
  "relationshipType": {
    "enum": ["FRIEND", "FAMILY", "COLLEAGUE", "ACQUAINTANCE"]
  },
  "privacyLevel": {
    "enum": ["PUBLIC", "FRIENDS", "PRIVATE"]
  },
  "accountStatus": {
    "enum": ["ACTIVE", "SUSPENDED", "DEACTIVATED"]
  }
}

🔧 Ajuste para seus dados

Para conjuntos de dados grandes:

GREMLIN_ENUM_CARDINALITY_THRESHOLD="5"     # Stricter enum detection
GREMLIN_SCHEMA_MAX_ENUM_VALUES="5"         # Fewer values in schema

Para dados categóricos ricos:

GREMLIN_ENUM_CARDINALITY_THRESHOLD="25"    # More permissive detection
GREMLIN_SCHEMA_MAX_ENUM_VALUES="20"        # Show more enum values

Para ambientes críticos de desempenho:

GREMLIN_ENUM_DISCOVERY_ENABLED="false"     # Disable for faster schema loading
GREMLIN_SCHEMA_INCLUDE_SAMPLE_VALUES="false" # Minimal schema size

Esta descoberta inteligente de enums transforma a forma como os agentes de IA interagem com seus dados de grafos, tornando as consultas mais precisas e os insights mais significativos! 🎯

🗄️ Bancos de dados compatíveis

Funciona com qualquer banco de dados de grafos compatível com Gremlin:

Banco de dados	Status	Notas
🟢 Apache TinkerPop	✅ Testado	Desenvolvimento local e testes de CI
🟡 Amazon Neptune	🔧 Compatível	Projetado para, ainda não testado
🟡 JanusGraph	🔧 Compatível	Projetado para, ainda não testado
🟡 Azure Cosmos DB	🔧 Compatível	Com API Gremlin
🟡 ArcadeDB	🔧 Compatível	Com suporte a Gremlin

⚙️ Opções de configuração

Configuração básica

# Required
GREMLIN_ENDPOINT="localhost:8182"

# Optional
GREMLIN_USE_SSL="true"              # Enable SSL/TLS
GREMLIN_USERNAME="username"         # Authentication
GREMLIN_PASSWORD="password"         # Authentication
GREMLIN_IDLE_TIMEOUT="300"          # Connection timeout in seconds (default: 300)
LOG_LEVEL="info"                    # Logging level: error, warn, info, debug

Configuração avançada

# Schema and performance tuning
GREMLIN_ENUM_DISCOVERY_ENABLED="true"         # Enable smart enum detection (default: true)
GREMLIN_ENUM_CARDINALITY_THRESHOLD="10"       # Max distinct values for enum detection (default: 10)
GREMLIN_ENUM_PROPERTY_BLACKLIST="id,timestamp" # Exclude specific properties from enum detection
GREMLIN_SCHEMA_INCLUDE_SAMPLE_VALUES="false"  # Include sample values in schema (default: false)
GREMLIN_SCHEMA_MAX_ENUM_VALUES="10"           # Limit enum values shown (default: 10)
GREMLIN_SCHEMA_INCLUDE_COUNTS="true"          # Include vertex/edge counts in schema (default: true)

🔐 Considerações de segurança

⚠️ Importante: Este servidor é projetado para ambientes de desenvolvimento e confiáveis.

Limitações atuais

Saneamento básico de entrada (proteção avançada contra injeção em desenvolvimento)
Sem pooling de conexões ou limite de taxa
Toda sintaxe Gremlin é permitida
Sem registro de auditoria para monitoramento de segurança

Práticas recomendadas de segurança

🔒 Use atrás de um firewall em produção
🔑 Habilite autenticação forte no seu servidor Gremlin
📊 Monitore padrões de consulta e uso de recursos
🛡️ Considere um proxy de consulta para controles adicionais de segurança
🔄 Mantenha as dependências atualizadas

🆘 Solução de problemas

Problemas de conexão

Problema	Solução
"Conexão recusada"	Verifique se o servidor Gremlin está em execução: `curl http://localhost:8182/`
"Falha na autenticação"	Verifique `GREMLIN_USERNAME` e `GREMLIN_PASSWORD`
"Endpoint inválido"	Use o formato `host:port` ou `host:port/g` para fonte de travessia

Mensagens de erro comuns

"Falha no cache de esquema" - O servidor não conseguiu descobrir a estrutura do grafo (banco de dados vazio?)
"Sintaxe de consulta inválida" - A consulta Gremlin tem erros de sintaxe
"Tempo esgotado" - A consulta demorou muito, verifique GREMLIN_IDLE_TIMEOUT

Testando sua configuração

# Test connection
curl -f http://localhost:8182/

# Check server logs
tail -f logs/gremlin-mcp.log

# Verify schema endpoint
curl http://localhost:8182/gremlin

🔧 Documentação para desenvolvedores

As seções a seguir são para desenvolvedores que desejam contribuir ou modificar o servidor.

Configuração de desenvolvimento

# Clone and install
git clone https://github.com/kpritam/gremlin-mcp.git
cd gremlin-mcp
npm install

# Development with hot reload
npm run dev

# Run tests
npm test
npm run test:coverage
npm run test:watch

# Integration tests (requires running Gremlin server)
GREMLIN_ENDPOINT=localhost:8182/g npm run test:it

# All tests together (unit + integration)
npm test && npm run test:it

Arquitetura

Segurança total de tipos: TypeScript + padrões de programação funcional com Effect
Arquitetura baseada em Effect: Usa Effect.ts para operações compostáveis e seguras quanto a tipos
Design orientado a serviços: Dependências gerenciadas através dos padrões de Context.Tag do Effect
Composição baseada em camadas: Aplicação construída usando Effect.Layer para resolução de dependências
Testes abrangentes: Testes de unidade + integração com padrões de teste do Effect
Tratamento de erros: Gerenciamento de erros baseado em Effect com tipos de erro personalizados

Estrutura do projeto

src/
├── server.ts              # Effect-based MCP server with graceful startup/shutdown
├── config.ts              # Effect.Config-based configuration validation
├── constants.ts           # Application constants integrated with Effect configuration
├── gremlin/
│   ├── service.ts         # GremlinService using Effect.Context.Tag pattern
│   ├── schema-service.ts  # SchemaService with Effect dependency injection
│   └── types.ts           # TypeScript types and schemas
├── handlers/              # Effect-based MCP request handlers
│   ├── tools.ts           # Effect-based tool handlers
│   ├── resources.ts       # Effect-based resource handlers
│   └── effect-runtime-bridge.ts # ManagedRuntime container for Effect execution
└── utils/                 # Effect-based utility modules
    ├── data-operations.ts # Effect-based graph data import/export operations
    ├── result-parser.ts   # Gremlin result parsing with metadata extraction
    └── type-guards.ts     # Runtime type checking functions

Scripts disponíveis

Comando	Finalidade
`npm run build`	Compila TypeScript para JavaScript
`npm run dev`	Modo de desenvolvimento com recarregamento automático
`npm test`	Executa a suíte de testes de unidade
`npm run lint`	Lint de código com ESLint
`npm run format`	Formatação de código com Prettier
`npm run validate`	Executa todas as verificações (formatação, lint, checagem de tipos, testes)

Descoberta inteligente de esquema

O servidor implementa descoberta de esquema inteligente com detecção de enumeração:

// Property with detected enum values
{
  "name": "status",
  "type": ["string"],
  "cardinality": "single",
  "enum": ["Confirmed", "Pending", "Cancelled", "Waitlisted"]
}

Contribuindo

Siga as regras em RULES.md
Execute npm run validate antes de commitar
Adicione testes para novas funcionalidades
Atualize a documentação para mudanças visíveis ao usuário
Garanta que todos os testes passem

Estratégia de testes

Testes de unidade (tests/): Testes de componentes individuais
- Isolamento de componentes com mocks abrangentes
- Validação de segurança de tipos com esquemas Zod
- Execução rápida sem dependências externas
Testes de integração (tests/integration/): Testes de fluxo de trabalho completo
- Conexões reais com servidor Gremlin via Docker
- Validação de ponta a ponta do protocolo MCP
- Operações de banco de dados e execução de consultas
Testes de CI: Testes automatizados no GitHub Actions
- Testes de unidade em cada commit
- Testes de integração com servidor Gremlin Docker
- Ambos necessários para lançamentos

📄 Licença

Licença MIT - sinta-se à vontade para usar em seus projetos!

Perguntas? Consulte o guia de solução de problemas ou abra uma issue.