ArangoDB

Un servidor para interactuar con ArangoDB, un sistema de base de datos nativo multimodelo.

Documentación

Servidor MCP para ArangoDB

Un servidor de Protocolo de Contexto de Modelo para ArangoDB

Este es un servidor MCP basado en TypeScript que proporciona capacidades de interacción con bases de datos a través de ArangoDB. Implementa operaciones básicas de base de datos y permite una integración perfecta con ArangoDB mediante herramientas MCP. Puedes usarlo con la aplicación Claude y también con la extensión para VSCode que funciona con MCP como Cline.

Características

Herramientas

Herramienta	Categoría	Solo lectura	Modifica datos/esquema	Propósito
`arango_query`	Consulta	No	Quizás	Ejecutar AQL general con variables de enlace, resultados limitados y salvaguardas de consulta.
`arango_read_query`	Consulta	Sí	No	Ejecutar AQL de solo lectura y rechazar palabras clave de escritura/DDL.
`arango_validate_query`	Consulta	Sí	No	Analizar y validar AQL sin ejecutarlo.
`arango_explain_query`	Consulta	Sí	No	Inspeccionar planes de ejecución de AQL, uso de índices y salida del optimizador.
`arango_describe_database`	Descubrimiento	Sí	No	Resumir colecciones, conteos, índices y campos de muestra.
`arango_list_collections`	Descubrimiento	Sí	No	Listar colecciones en la base de datos configurada.
`arango_get_collection`	Descubrimiento	Sí	No	Devolver propiedades de colección, conteo e índices.
`arango_create_collection`	Colección	No	Sí	Crear colecciones de documentos o aristas.
`arango_drop_collection`	Colección	No	Sí	Eliminar una colección, requiriendo `confirm: true`.
`arango_get_document`	Documento	Sí	No	Obtener un documento por colección y `_key`.
`arango_list_documents`	Documento	Sí	No	Listar documentos con paginación `limit` y `offset`.
`arango_count_documents`	Documento	Sí	No	Contar documentos en una colección.
`arango_sample_documents`	Documento	Sí	No	Devolver una pequeña muestra aleatoria para descubrimiento de esquema.
`arango_insert`	Documento	No	Sí	Insertar un documento en una colección.
`arango_bulk_insert`	Documento	No	Sí	Insertar hasta 1000 documentos en una sola solicitud.
`arango_update`	Documento	No	Sí	Actualizar parcialmente un documento por `_key`.
`arango_bulk_update`	Documento	No	Sí	Aplicar parches a hasta 1000 documentos por `_key` o `_id`.
`arango_remove`	Documento	No	Sí	Eliminar un documento por `_key`.
`arango_list_indexes`	Índice	Sí	No	Listar índices para una colección.
`arango_create_index`	Índice	No	Sí	Crear índices persistentes, geo, TTL o invertidos.
`arango_list_views`	ArangoSearch	Sí	No	Listar Vistas de ArangoSearch y de alias de búsqueda.
`arango_create_search_view`	ArangoSearch	No	Sí	Crear una Vista de ArangoSearch vinculada a una colección.
`arango_search`	ArangoSearch	Sí	No	Buscar en una Vista de ArangoSearch con clasificación BM25 consciente del analizador.
`arango_list_analyzers`	Analizador	Sí	No	Listar Analizadores de ArangoSearch.
`arango_create_analyzer`	Analizador	No	Sí	Crear un Analizador de ArangoSearch.
`arango_list_graphs`	Grafo	Sí	No	Listar grafos nombrados.
`arango_create_graph`	Grafo	No	Sí	Crear un grafo nombrado con una definición de arista.
`arango_insert_edge`	Grafo	No	Sí	Insertar un documento de arista con `_from` y `_to`.
`arango_traverse`	Grafo	Sí	No	Recorrer aristas desde un vértice inicial usando una colección de aristas o un grafo nombrado.
`arango_shortest_path`	Grafo	Sí	No	Encontrar la ruta más corta entre dos vértices usando una colección de aristas o un grafo nombrado.
`arango_backup`	Respaldo	No	Sistema de archivos	Respaldar colecciones a archivos JSON bajo `ARANGO_BACKUP_ROOT`.

Todas las herramientas devuelven texto JSON y structuredContent cuando tienen éxito. Las herramientas con mucha lectura exponen parámetros limit limitados para mantener respuestas amigables para agentes. Las herramientas de consulta también admiten salvaguardas como memoryLimit, maxRuntime y failOnWarning cuando corresponde.

Instalación

Instalación mediante NPM

Para instalar arango-server globalmente mediante NPM, ejecuta el siguiente comando:

npm install -g arango-server

Ejecución mediante NPX

Para ejecutar arango-server directamente sin instalación, usa el siguiente comando:

npx -y arango-server

Configuración para el Agente de VSCode

Para usar arango-server con el agente Copilot de VSCode, debes tener al menos VSCode 1.99.0 instalado y seguir estos pasos:

Crear o editar el archivo de configuración de MCP:
- Configuración específica del espacio de trabajo: Crea o edita el archivo .vscode/mcp.json en tu espacio de trabajo.
- Configuración específica del usuario: Opcionalmente, especifica el servidor en la configuración (mcp) de configuración de usuario de VS Code para habilitar el servidor MCP en todos los espacios de trabajo.
  
  Consejo: Puedes consultar aquí la documentación de configuración de MCP de VSCode para obtener más detalles sobre cómo configurar el archivo de configuración.

Agrega la siguiente configuración:

{
  "servers": {
    "arango-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "arango-server"],
      "env": {
        "ARANGO_URL": "http://localhost:8529",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

Inicia el servidor MCP:
- Abre la Paleta de Comandos en VSCode (Ctrl+Shift+P o Cmd+Shift+P en Mac).
- Ejecuta el comando MCP: Start Server y selecciona arango-mcp de la lista.
Verifica el servidor:
- Abre la vista de Chat en VSCode y cambia al modo Agente.
- Usa el botón Tools para verificar que las herramientas arango-server estén disponibles.

Para usar con Claude Desktop

Ve a: Settings > Developer > Edit Config o

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

También puedes consultar la documentación de MCP para configurarlo.

Para usar con OpenCode

Agrega la siguiente configuración a tu archivo de configuración de OpenCode, como opencode.json o opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "arango": {
      "type": "local",
      "command": ["npx", "-y", "arango-server"],
      "enabled": true,
      "environment": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

Después de reiniciar OpenCode, pídele que use las herramientas MCP arango para tareas de ArangoDB.

Para usar con la extensión Cline de VSCode

Ve a: Cline Extension > MCP Servers > Edit Configuration o

MacOS: ~/Library/Application Support/Code/User/globalStorage/cline.cline/config.json
Windows: %APPDATA%/Code/User/globalStorage/cline.cline/config.json

Agrega la siguiente configuración a la sección mcpServers:

{
  "mcpServers": {
    "arango": {
      "command": "npx",
      "args": ["-y", "arango-server"],
      "env": {
        "ARANGO_URL": "your_database_url",
        "ARANGO_DB": "your_database_name",
        "ARANGO_USERNAME": "your_username",
        "ARANGO_PASSWORD": "your_password"
      }
    }
  }
}

También puedes usar la configuración anterior para que este servidor funcione con WARP

Variables de Entorno

El servidor requiere las siguientes variables de entorno:

ARANGO_URL - URL del servidor de ArangoDB (nota: 8529 es el puerto predeterminado de ArangoDB para desarrollo local)
ARANGO_DB - Nombre de la base de datos
ARANGO_USERNAME - Usuario de la base de datos
ARANGO_PASSWORD - Contraseña de la base de datos
ARANGO_BACKUP_ROOT - Directorio raíz opcional para la salida de arango_backup. El valor predeterminado es ./backups.

Uso

Puedes proporcionar prácticamente cualquier indicación significativa y Claude intentará ejecutar la función adecuada.

Algunos ejemplos de indicaciones:

"Lista todas las colecciones en la base de datos"
"Consulta todos los usuarios"
"Inserta un nuevo documento con nombre 'John Doe' y correo electrónico "john@example.com' en la colección 'users'"
"Actualiza el documento con clave '123456' o nombre 'Jane Doe' para cambiar la edad a 48"
"Crea una nueva colección llamada 'products'"

Uso con la aplicación Claude

Demo of using ArangoDB MCP server with Claude App

Uso con la extensión Cline de VSCode

Demo of using ArangoDB MCP server with Cline VSCode extension

Consultar todos los usuarios:

{
  "query": "FOR user IN users RETURN user",
  "limit": 100
}

Insertar un nuevo documento:

{
  "collection": "users",
  "document": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Actualizar un documento:

{
  "collection": "users",
  "key": "123456",
  "update": {
    "name": "Jane Doe"
  }
}

Eliminar un documento:

{
  "collection": "users",
  "key": "123456"
}

Listar todas las colecciones:

{
} // No parameters required

Respaldar colecciones de la base de datos:

{
  "outputDir": "nightly_1", // Safe subdirectory name under ARANGO_BACKUP_ROOT. Absolute paths and slashes are rejected.
  "collection": "users", // Optional. If omitted, all collections are backed up.
  "docLimit": 1000 // Optional. Maximum documents per collection. Defaults to 1000 and is capped at 10000.
}

Establece ARANGO_BACKUP_ROOT para elegir dónde se almacenan los respaldos. El servidor rechaza el recorrido de rutas, rutas absolutas, escapes de enlaces simbólicos y archivos de salida existentes para mitigar los riesgos de escritura arbitraria de archivos.

Crear una nueva colección:

{
  "name": "products",
  "type": "document", // "document" or "edge" (optional, defaults to "document")
  "waitForSync": false // Optional, defaults to false
}

Eliminar una colección:

{
  "name": "products",
  "confirm": true
}

Nota: El servidor es agnóstico a la estructura de la base de datos y puede funcionar con cualquier nombre o estructura de colección siempre que sigan los modelos de colección de documentos y aristas de ArangoDB.

Descargo de responsabilidad

Solo para uso en desarrollo

Esta herramienta está diseñada únicamente para entornos de desarrollo local. Aunque técnicamente podría conectarse a una base de datos de producción, esto crearía riesgos de seguridad significativos y se desaconseja explícitamente. Lo usamos exclusivamente con nuestras bases de datos de desarrollo para mantener la separación de preocupaciones y proteger los datos de producción.

Desarrollo

Las contribuciones son bienvenidas. Por favor, lee CONTRIBUTING.md antes de abrir una solicitud de extracción.

Clona el repositorio
Instala las dependencias:
```
npm run build
```
Para desarrollo con reconstrucción automática:
```
npm run watch
```

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser desafiante. Se recomienda usar MCP Inspector para el desarrollo:

npm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en tu navegador.

Pruebas

npm test

El conjunto de pruebas incluye cobertura de regresión para el manejo de rutas arango_backup que previene rutas absolutas, recorridos y escapes de enlaces simbólicos.

Para ejecutar la prueba de humo de integración con una instancia local de ArangoDB en Docker:

npm run test:integration

La prueba de integración inicia una instancia temporal de ArangoDB en Docker, inicia el servidor MCP a través de stdio, lista herramientas, verifica outputSchema, crea una colección temporal, inserta documentos, consulta con limit, verifica que la salida del respaldo permanezca bajo ARANGO_BACKUP_ROOT, rechaza una ruta de respaldo absoluta, limpia la colección y detiene el contenedor.

El contenedor de prueba usa el puerto de host 18529 por defecto para evitar conflictos con un ArangoDB local en 8529. Sobrescríbelo con ARANGO_PORT si es necesario.

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.