ArangoDB

Um servidor para interagir com o ArangoDB, um sistema de banco de dados nativo multi-modelo.

GitHub
47
Experimente este MCPPatrocinado

Documentação

Servidor MCP para ArangoDB

ArangoDB MCP Server

Um servidor Model Context Protocol para ArangoDB

Este é um servidor MCP baseado em TypeScript que fornece capacidades de interação com banco de dados através do ArangoDB. Ele implementa operações básicas de banco de dados e permite integração perfeita com o ArangoDB através de ferramentas MCP. Você pode usá-lo com o aplicativo Claude e também com a extensão para VSCode que funciona com MCP, como o Cline!

Recursos

Ferramentas

FerramentaCategoriaSomente leituraModifica dados/esquemaPropósito
arango_queryConsultaNãoTalvezExecutar AQL geral com variáveis de ligação, resultados limitados e proteções de consulta.
arango_read_queryConsultaSimNãoExecutar AQL somente leitura e rejeitar palavras-chave de escrita/DDL.
arango_validate_queryConsultaSimNãoAnalisar e validar AQL sem executá-lo.
arango_explain_queryConsultaSimNãoInspecionar planos de execução AQL, uso de índices e saída do otimizador.
arango_describe_databaseDescobertaSimNãoResumir coleções, contagens, índices e campos de amostra.
arango_list_collectionsDescobertaSimNãoListar coleções no banco de dados configurado.
arango_get_collectionDescobertaSimNãoRetornar propriedades da coleção, contagem e índices.
arango_create_collectionColeçãoNãoSimCriar coleções de documentos ou arestas.
arango_drop_collectionColeçãoNãoSimRemover uma coleção, exigindo confirm: true.
arango_get_documentDocumentoSimNãoBuscar um documento por coleção e _key.
arango_list_documentsDocumentoSimNãoListar documentos com paginação limit e offset.
arango_count_documentsDocumentoSimNãoContar documentos em uma coleção.
arango_sample_documentsDocumentoSimNãoRetornar uma pequena amostra aleatória para descoberta de esquema.
arango_insertDocumentoNãoSimInserir um documento em uma coleção.
arango_bulk_insertDocumentoNãoSimInserir até 1000 documentos em uma única solicitação.
arango_updateDocumentoNãoSimAtualizar parcialmente um documento por _key.
arango_bulk_updateDocumentoNãoSimAplicar patch em até 1000 documentos por _key ou _id.
arango_removeDocumentoNãoSimRemover um documento por _key.
arango_list_indexesÍndiceSimNãoListar índices de uma coleção.
arango_create_indexÍndiceNãoSimCriar índices persistentes, geo, TTL ou invertidos.
arango_list_viewsArangoSearchSimNãoListar Views ArangoSearch e de alias de busca.
arango_create_search_viewArangoSearchNãoSimCriar uma View ArangoSearch vinculada a uma coleção.
arango_searchArangoSearchSimNãoPesquisar em uma View ArangoSearch com classificação BM25 ciente de analisador.
arango_list_analyzersAnalisadorSimNãoListar Analisadores ArangoSearch.
arango_create_analyzerAnalisadorNãoSimCriar um Analisador ArangoSearch.
arango_list_graphsGrafoSimNãoListar grafos nomeados.
arango_create_graphGrafoNãoSimCriar um grafo nomeado com uma definição de aresta.
arango_insert_edgeGrafoNãoSimInserir um documento de aresta com _from e _to.
arango_traverseGrafoSimNãoPercorrer arestas a partir de um vértice inicial usando uma coleção de arestas ou grafo nomeado.
arango_shortest_pathGrafoSimNãoEncontrar o caminho mais curto entre dois vértices usando uma coleção de arestas ou grafo nomeado.
arango_backupBackupNãoSistema de arquivosFazer backup de coleções em arquivos JSON em ARANGO_BACKUP_ROOT.

Todas as ferramentas retornam texto JSON e structuredContent quando bem-sucedidas. Ferramentas com muita leitura expõem parâmetros limit limitados para manter as respostas amigáveis ao agente. Ferramentas de consulta também suportam proteções como memoryLimit, maxRuntime e failOnWarning quando aplicável.

Instalação

Instalando via NPM

Para instalar arango-server globalmente via NPM, execute o seguinte comando:

npm install -g arango-server

Executando via NPX

Para executar arango-server diretamente sem instalação, use o seguinte comando:

npx -y arango-server

Configurando para o Agente VSCode

Para usar arango-server com o agente Copilot do VSCode, você deve ter pelo menos VSCode 1.99.0 instalado e seguir estes passos:

  1. Crie ou edite o arquivo de configuração MCP:

    • Configuração específica do workspace: Crie ou edite o arquivo .vscode/mcp.json no seu workspace.

    • Configuração específica do usuário: Opcionalmente, especifique o servidor na configuração(mcp) das configurações do usuário do VS Code para habilitar o servidor MCP em todos os workspaces.

      Dica: Você pode consultar aqui a documentação de configuração MCP do VSCode para mais detalhes sobre como configurar o arquivo de configuração.

  2. Adicione a seguinte configuração:

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

  3. Inicie o servidor MCP:

    • Abra a Paleta de Comandos no VSCode (Ctrl+Shift+P ou Cmd+Shift+P no Mac).
    • Execute o comando MCP: Start Server e selecione arango-mcp na lista.

  4. Verifique o servidor:

    • Abra a visualização de Chat no VSCode e mude para o modo Agente.
    • Use o botão Tools para verificar se as ferramentas arango-server estão disponíveis.

Para usar com Claude Desktop

Vá para: Settings > Developer > Edit Config ou

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

Você também pode consultar a documentação do mcp para configurá-lo.

Para usar com OpenCode

Adicione a seguinte configuração ao seu arquivo de configuração do OpenCode, como opencode.json ou 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"
      }
    }
  }
}

Após reiniciar o OpenCode, peça para ele usar as ferramentas MCP arango para tarefas do ArangoDB.

Para usar com a Extensão Cline do VSCode

Vá para: Cline Extension > MCP Servers > Edit Configuration ou

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

Adicione a seguinte configuração à seção 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"
      }
    }
  }
}

Você também pode usar a configuração acima para fazer este servidor funcionar com WARP

Variáveis de Ambiente

O servidor requer as seguintes variáveis de ambiente:

  • ARANGO_URL - URL do servidor ArangoDB (nota: 8529 é a porta padrão do ArangoDB para desenvolvimento local)
  • ARANGO_DB - Nome do banco de dados
  • ARANGO_USERNAME - Usuário do banco de dados
  • ARANGO_PASSWORD - Senha do banco de dados
  • ARANGO_BACKUP_ROOT - Diretório raiz opcional para saída de arango_backup. O padrão é ./backups.

Uso

Você pode fornecer praticamente qualquer prompt significativo e o Claude tentará executar a função apropriada.

Alguns exemplos de prompts:

  • "Listar todas as coleções no banco de dados"
  • "Consultar todos os usuários"
  • "Inserir um novo documento com nome 'John Doe' e email "john@example.com' na coleção 'users'"
  • "Atualizar o documento com chave '123456' ou nome 'Jane Doe' para mudar a idade para 48"
  • "Criar uma nova coleção chamada 'products'"

Uso com o Aplicativo Claude

Demo of using ArangoDB MCP server with Claude App

Uso com a extensão Cline do VSCode

Demo of using ArangoDB MCP server with Cline VSCode extension

Consultar todos os usuários:

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

Inserir um novo documento:

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

Atualizar um documento:

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

Remover um documento:

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

Listar todas as coleções:

{
} // No parameters required

Fazer backup das coleções do banco de dados:

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

Defina ARANGO_BACKUP_ROOT para escolher onde os backups são armazenados. O servidor rejeita travessia de caminho, caminhos absolutos, escapes de symlink e arquivos de saída existentes para mitigar riscos de escrita arbitrária de arquivos.

Criar uma nova coleção:

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

Remover uma coleção:

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

Nota: O servidor é agnóstico em relação à estrutura do banco de dados e pode trabalhar com qualquer nome ou estrutura de coleção, desde que sigam os modelos de coleção de documentos e arestas do ArangoDB.

Aviso Legal

Apenas para Uso em Desenvolvimento

Esta ferramenta é projetada apenas para ambientes de desenvolvimento local. Embora tecnicamente possa se conectar a um banco de dados de produção, isso criaria riscos significativos de segurança e é explicitamente desencorajado. Nós a usamos exclusivamente com nossos bancos de dados de desenvolvimento para manter a separação de preocupações e proteger os dados de produção.

Desenvolvimento

Contribuições são bem-vindas. Por favor, leia CONTRIBUTING.md antes de abrir um pull request.

  1. Clone o repositório

  2. Instale as dependências:

    npm run build

  3. Para desenvolvimento com recompilação automática:

    npm run watch

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. A depuração recomendada pode ser feita usando o MCP Inspector para desenvolvimento:

npm run inspector

O Inspector fornecerá uma URL para acessar as ferramentas de depuração no seu navegador.

Testes

npm test

A suíte de testes inclui cobertura de regressão para o tratamento de caminho arango_backup que previne caminhos absolutos, travessia e escapes de symlink.

Para executar o teste de fumaça de integração com uma instância local do ArangoDB via Docker:

npm run test:integration

O teste de integração inicia uma instância temporária do ArangoDB via Docker, inicia o servidor MCP via stdio, lista ferramentas, verifica outputSchema, cria uma coleção temporária, insere documentos, consulta com limit, verifica se a saída do backup permanece em ARANGO_BACKUP_ROOT, rejeita um caminho de backup absoluto, limpa a coleção e para o contêiner.

O contêiner de teste usa a porta do host 18529 por padrão para evitar conflito com um ArangoDB local na porta 8529. Substitua com ARANGO_PORT se necessário.

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.