dbx-mcp-server

Um servidor MCP para interagir com arquivos e serviços do Dropbox.

GitHubExperimente este MCPPatrocinado

Documentação

dbx-mcp-server

Um servidor Model Context Protocol (MCP) que fornece integração com o Dropbox, permitindo que clientes compatíveis com MCP interajam com o Dropbox por meio de um conjunto de ferramentas poderosas.

Aviso importante: Este projeto não é afiliado, endossado ou patrocinado pelo Dropbox. É uma integração independente que funciona com a API pública do Dropbox.

Sumário

Início Rápido

  1. Clone o repositório
  2. Execute npm install para instalar as dependências
  3. Execute npm run build para compilar o projeto
  4. Registre um aplicativo Dropbox no Dropbox App Console:
    • Escolha a API "Scoped access"
    • Escolha o tipo de acesso que seu aplicativo precisa
    • Dê um nome ao seu aplicativo e clique em "Create app"
    • Em "Permissions", selecione as permissões necessárias:
      • files.metadata.read
      • files.content.read
      • files.content.write
      • sharing.write
      • account_info.read
    • Adicione http://localhost:3000/callback como seu URI de redirecionamento
    • Anote sua App key e App secret
  5. Execute o script de configuração: 
    npm run setup
  6. Configure seu cliente MCP para usar o servidor

Instalação

  1. Clone o repositório

    git clone https://github.com/your-username/dbx-mcp-server.git
cd dbx-mcp-server

  2. Instale as dependências e compile

    npm install
npm run build

  3. Execute o script de configuração

    npm run setup

  4. Adicione às configurações do MCP

    Adicione o seguinte ao seu arquivo de configurações do MCP:

    {
  "mcpServers": {
    "dbx": {
      "command": "node",
      "args": ["/path/to/dbx-mcp-server/build/index.js"]
    }
  }
}

Autenticação

O servidor usa OAuth 2.0 com PKCE para autenticação segura com o Dropbox.

Variáveis de Ambiente

Obrigatórias:

  • DROPBOX_APP_KEY: A chave do seu aplicativo Dropbox
  • DROPBOX_APP_SECRET: O segredo do seu aplicativo Dropbox
  • DROPBOX_REDIRECT_URI: URI de redirecionamento OAuth
  • TOKEN_ENCRYPTION_KEY: Chave de 32+ caracteres para criptografia de tokens

Opcionais:

  • TOKEN_REFRESH_THRESHOLD_MINUTES: Minutos antes da expiração para renovar o token (padrão: 5)
  • MAX_TOKEN_REFRESH_RETRIES: Número máximo de tentativas de renovação (padrão: 3)
  • TOKEN_REFRESH_RETRY_DELAY_MS: Atraso entre tentativas de renovação em ms (padrão: 1000)

Ferramentas Disponíveis

Operações de Arquivo

  • list_files: Listar arquivos em um diretório
  • upload_file: Enviar um arquivo
  • download_file: Baixar um arquivo
  • safe_delete_item: Excluir com segurança com suporte à lixeira
  • create_folder: Criar uma nova pasta
  • copy_item: Copiar um arquivo ou pasta
  • move_item: Mover ou renomear um arquivo/pasta

Metadados e Busca

  • get_file_metadata: Obter metadados de arquivo/pasta
  • search_file_db: Buscar arquivos e pastas
  • get_sharing_link: Criar links de compartilhamento
  • get_file_content: Obter conteúdo de arquivo

Operações de Conta

  • get_account_info: Obter informações da conta

Exemplos de Uso

// List files in root directory
await mcp.useTool("dbx-mcp-server", "list_files", { path: "" });

// Upload a file
await mcp.useTool("dbx-mcp-server", "upload_file", {
  path: "/test.txt",
  content: Buffer.from("Hello World").toString("base64"),
});

// Search for files
await mcp.useTool("dbx-mcp-server", "search_file_db", {
  query: "report",
  path: "/Documents",
  max_results: 10,
});

Testes

Execute a suíte de testes:

npm test

Os testes verificam todas as operações, incluindo autenticação, operações de arquivo e tratamento de erros.

Estrutura de Testes

A suíte de testes está organizada em vários módulos:

  • Operações do Dropbox: Testes para operações básicas de arquivo (upload, download, listagem, etc.)
  • Operações de Conta: Testes para acesso a informações da conta
  • Busca e Exclusão: Testes para funcionalidade de busca e exclusão segura com suporte à lixeira
  • Sistema de Recursos: Testes para a integração do sistema de recursos do MCP

Tratamento de Dados de Teste

Os testes usam nomes de arquivos e pastas gerados dinamicamente com base em timestamps para evitar conflitos. Os dados de teste são limpos automaticamente após a execução dos testes.

Executando Testes Específicos

Para executar um arquivo de teste ou grupo de testes específico:

npm test -- tests/dropbox/search-delete.test.ts  # Run specific test file
npm test -- -t "should search for files"        # Run tests matching description

Solução de Problemas nos Testes

Se os testes falharem com problemas de tempo ou autenticação:

  1. Verifique se as implementações mock em tests/setup.ts correspondem às suas expectativas de teste
  2. Garanta que os helpers de teste estejam configurados corretamente
  3. Para erros de escopo do Jest, evite referenciar variáveis importadas em funções de fábrica mock

Desenvolvimento

Construído com:

  • TypeScript
  • Model Context Protocol SDK
  • Dropbox SDK v10.34.0
  • Dropbox API v2

Licença

Licença MIT

Copyright (c) 2025 MCP Server Contributors

A permissão é concedida, gratuitamente, a qualquer pessoa que obtenha uma cópia deste software e dos arquivos de documentação associados (o "Software"), para lidar com o Software sem restrições, incluindo, sem limitação, os direitos de usar, copiar, modificar, mesclar, publicar, distribuir, sublicenciar e/ou vender cópias do Software, e permitir que as pessoas a quem o Software é fornecido o façam, sujeitas às seguintes condições:

O aviso de direitos autorais acima e este aviso de permissão deverão ser incluídos em todas as cópias ou partes substanciais do Software.

O SOFTWARE É FORNECIDO "NO ESTADO EM QUE SE ENCONTRA", SEM GARANTIA DE QUALQUER TIPO, EXPRESSA OU IMPLÍCITA, INCLUINDO, MAS NÃO SE LIMITANDO ÀS GARANTIAS DE COMERCIALIZAÇÃO, ADEQUAÇÃO A UM FIM ESPECÍFICO E NÃO VIOLAÇÃO. EM NENHUM CASO OS AUTORES OU DETENTORES DE DIREITOS AUTORAIS SERÃO RESPONSÁVEIS POR QUALQUER RECLAMAÇÃO, DANOS OU OUTRA RESPONSABILIDADE, SEJA EM AÇÃO DE CONTRATO, ATO ILÍCITO OU OUTRA FORMA, DECORRENTE DE, FORA OU EM CONEXÃO COM O SOFTWARE OU O USO OU OUTRAS NEGOCIAÇÕES NO SOFTWARE.

smithery badge