Gremlin

Servidor MCP de Gremlin

¡Conecta agentes de IA como Claude, Cursor y Windsurf a tus bases de datos de grafos!

Un servidor MCP (Protocolo de Contexto de Modelo) que permite a los asistentes de IA interactuar con cualquier base de datos de grafos compatible con Gremlin mediante lenguaje natural. Consulta tus datos, descubre esquemas, analiza relaciones y gestiona datos de grafos usando conversaciones simples.

✨ Lo que puedes hacer

Habla con tu base de datos de grafos de forma natural:

• 🔍 "¿Cuál es la estructura de mi grafo?" - Descubrimiento automático de esquemas
• 📊 "Muéstrame todos los usuarios mayores de 30 y sus conexiones" - Consultas complejas de grafos
• 🔗 "Encuentra la ruta más corta entre Alice y Bob" - Análisis de relaciones
• 📈 "Dame estadísticas y métricas del grafo" - Información de datos
• 📥 "Importa estos datos GraphSON" - Carga de datos
• 📤 "Exporta datos de usuarios como CSV" - Extracción de datos
• 🧠 Descubrimiento inteligente de enums - La IA aprende los valores válidos de tus datos automáticamente

🛠️ Herramientas disponibles

Tu asistente de IA tiene acceso a estas potentes herramientas:

Herramienta	Propósito	Qué hace
🔍 get_graph_status	Verificación de salud	Verifica la conectividad de la base de datos y el estado del servidor
📋 get_graph_schema	Descubrimiento de esquemas	Obtén la estructura completa del grafo con nodos, aristas y relaciones
⚡ run_gremlin_query	Ejecución de consultas	Ejecuta cualquier consulta de recorrido Gremlin con soporte completo de sintaxis
🔄 refresh_schema_cache	Gestión de caché	Fuerza la actualización inmediata de la información de esquema en caché
📥 import_graph_data	Importación de datos	Carga datos desde GraphSON, CSV o JSON con procesamiento por lotes
📤 export_subgraph	Exportación de datos	Extrae subgrafos a formatos JSON, GraphSON o CSV

🚀 Configuración rápida

Paso 1: Instalación

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

Alternativa: Compilar desde el código fuente

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

Paso 2: Configura tu cliente de IA

Añade esto a la configuración de tu cliente MCP:

Claude Desktop / Cursor / Windsurf

Usando el paquete publicado (recomendado):

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

Desde el código fuente:

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

Con autenticación

{
  "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"
      }
    }
  }
}

Paso 3: Inicia tu servidor Gremlin

Asegúrate de que tu base de datos compatible con Gremlin esté en ejecución:

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

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

Paso 4: Prueba la conexión

Reinicia tu cliente de IA e intenta preguntar:

"¿Puedes verificar si mi base de datos de grafos está conectada y mostrarme su esquema?"

💡 Ejemplos de uso

Exploración de esquemas

Tú preguntas: "¿Cuál es la estructura de mi base de datos de grafos?"

Respuesta de la IA: La IA llama a get_graph_schema y te informa sobre tus tipos de nodos, tipos de aristas y cómo están conectados.

Análisis de datos

Tú preguntas: "Muéstrame todas las personas mayores de 30 y sus relaciones"

Respuesta de la IA: La IA ejecuta g.V().hasLabel('person').has('age', gt(30)).out().path() y explica los resultados en lenguaje natural.

Métricas del grafo

Tú preguntas: "Dame algunas estadísticas sobre mi grafo"

Respuesta de la IA: La IA ejecuta múltiples consultas para contar nodos, aristas y analizar la distribución, luego presenta un resumen.

Importación de datos

Tú preguntas: "Carga estos datos GraphSON en mi base de datos"

Respuesta de la IA: La IA usa import_graph_data para procesar tus datos en lotes e informa el estado de la importación.

🧠 Descubrimiento automático de enums

Por qué es importante: Los agentes de IA funcionan mejor cuando conocen los valores válidos exactos de las propiedades. En lugar de adivinar o hacer consultas inválidas, pueden usar valores precisos y reales de tus datos.

Una de las características más potentes de este servidor MCP es el Descubrimiento automático de enums: analiza inteligentemente los datos de tu grafo para descubrir valores de propiedad válidos y los proporciona como enums a los agentes de IA.

🤔 El problema que resuelve

Sin descubrimiento 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')

Con descubrimiento 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

💡 Cómo funciona

El servidor escanea automáticamente las propiedades de tu grafo y:

1. Identifica propiedades de baja cardinalidad - Propiedades con un número razonable de valores distintos
2. Extrae valores reales - Muestrea datos reales de tu grafo
3. Los proporciona como enums - Incluye valores válidos en el esquema para los agentes de IA

Ejemplo de salida:

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

🎯 Beneficios para los agentes de IA

• 🎯 Consultas precisas - La IA usa valores reales en lugar de adivinar
• ⚡ Resultados más rápidos - Sin prueba y error con valores inválidos
• 🧠 Mejor comprensión - La IA aprende el vocabulario de tus datos
• 📊 Analítica más inteligente - Permite agrupar y filtrar con categorías reales

⚙️ Opciones de configuración

Ajusta el descubrimiento de enums para que coincida con tus datos:

# 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 propiedades

Algunas propiedades nunca deben tratarse como enums:

Excluidas automáticamente:

• Propiedades de alta cardinalidad (> valor umbral de valores únicos)
• IDs numéricos y UUIDs
• Marcas de tiempo y fechas
• Campos de texto largo

Exclusión manual:

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

Patrones comunes de lista negra:

• id,uuid,guid - Identificadores únicos
• timestamp,createdAt,updatedAt,lastModified - Campos de tiempo
• description,notes,comment,content,text - Campos de texto libre
• email,url,phone,address - Datos personales/de contacto
• hash,token,key,secret - Campos relacionados con seguridad

🛠️ Ejemplos del mundo real

Grafo de comercio electró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 red social:

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

🔧 Ajuste para tus datos

Para conjuntos de datos grandes:

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

Para datos categóricos ricos:

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

Para entornos críticos de rendimiento:

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

¡Este descubrimiento inteligente de enums transforma cómo los agentes de IA interactúan con tus datos de grafos, haciendo las consultas más precisas y los conocimientos más significativos! 🎯

🗄️ Bases de datos compatibles

Funciona con cualquier base de datos de grafos compatible con Gremlin:

Base de datos	Estado	Notas
🟢 Apache TinkerPop	✅ Probado	Desarrollo local y pruebas de CI
🟡 Amazon Neptune	🔧 Compatible	Diseñado para, aún no probado
🟡 JanusGraph	🔧 Compatible	Diseñado para, aún no probado
🟡 Azure Cosmos DB	🔧 Compatible	Con API de Gremlin
🟡 ArcadeDB	🔧 Compatible	Con soporte de Gremlin

⚙️ Opciones de configuración

Configuración 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

Configuración avanzada

# 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)

🔐 Consideraciones de seguridad

⚠️ Importante: Este servidor está diseñado para entornos de desarrollo y de confianza.

Limitaciones actuales

• Sanitización básica de entrada (protección avanzada contra inyección en desarrollo)
• Sin agrupación de conexiones ni limitación de velocidad
• Toda la sintaxis de Gremlin está permitida
• Sin registro de auditoría para monitoreo de seguridad

Prácticas de seguridad recomendadas

• 🔒 Usar detrás de un firewall en producción
• 🔑 Habilitar autenticación fuerte en tu servidor Gremlin
• 📊 Monitorear patrones de consulta y uso de recursos
• 🛡️ Considerar un proxy de consultas para controles de seguridad adicionales
• 🔄 Mantener las dependencias actualizadas

🆘 Solución de problemas

Problemas de conexión

Problema	Solución
"Conexión rechazada"	Verifica que el servidor Gremlin esté en ejecución: curl http://localhost:8182/
"Autenticación fallida"	Verifica GREMLIN_USERNAME y GREMLIN_PASSWORD
"Endpoint inválido"	Usa el formato host:port o host:port/g para la fuente de recorrido

Mensajes de error comunes

• "Fallo en la caché del esquema" - El servidor no pudo descubrir la estructura del grafo (¿base de datos vacía?)
• "Sintaxis de consulta inválida" - La consulta Gremlin tiene errores de sintaxis
• "Tiempo de espera agotado" - La consulta tardó demasiado, verifica GREMLIN_IDLE_TIMEOUT

Probando tu configuración

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

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

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

---

🔧 Documentación para desarrolladores

Las siguientes secciones son para desarrolladores que quieran contribuir o modificar el servidor.

Configuración de desarrollo

# 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

Arquitectura

• Seguridad total de tipos: TypeScript + patrones de programación funcional de Effect
• Arquitectura basada en Effect: Usa Effect.ts para operaciones componibles y seguras en tipos
• Diseño orientado a servicios: Dependencias gestionadas mediante patrones Context.Tag de Effect
• Composición basada en capas: Aplicación construida usando Effect.Layer para resolución de dependencias
• Pruebas exhaustivas: Pruebas unitarias + de integración con patrones de prueba de Effect
• Gestión de errores: Gestión de errores basada en Effect con tipos de error personalizados

Estructura del proyecto

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 disponibles

Comando	Propósito
npm run build	Compilar TypeScript a JavaScript
npm run dev	Modo de desarrollo con recarga automática
npm test	Ejecutar la suite de pruebas unitarias
npm run lint	Linting de código con ESLint
npm run format	Formateo de código con Prettier
npm run validate	Ejecutar todas las verificaciones (formato, lint, verificación de tipos, pruebas)

Descubrimiento inteligente de esquemas

El servidor implementa descubrimiento inteligente de esquemas con detección de enumeraciones:

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

Contribuciones

1. Sigue las reglas en RULES.md
2. Ejecuta npm run validate antes de hacer commit
3. Añade pruebas para nuevas funcionalidades
4. Actualiza la documentación para cambios visibles al usuario
5. Asegúrate de que todas las pruebas pasen

Estrategia de pruebas

• Pruebas unitarias (tests/): Pruebas de componentes individuales
  • Aislamiento de componentes con mocking exhaustivo
  • Validación de seguridad de tipos con esquemas Zod
  • Ejecución rápida sin dependencias externas
• Pruebas de integración (tests/integration/): Pruebas de flujo de trabajo completo
  • Conexiones reales al servidor Gremlin mediante Docker
  • Validación de extremo a extremo del protocolo MCP
  • Operaciones de base de datos y ejecución de consultas
• Pruebas de CI: Pruebas automatizadas en GitHub Actions
  • Las pruebas unitarias se ejecutan en cada commit
  • Las pruebas de integración se ejecutan con el servidor Gremlin de Docker
  • Ambas son necesarias para los lanzamientos

📄 Licencia

Licencia MIT: ¡siéntete libre de usarlo en tus proyectos!

---

¿Preguntas? Consulta la guía de solución de problemas o abre un problema.