dbx-mcp-server

一个模型上下文协议 (MCP) 服务器，提供与 Dropbox 的集成，允许 MCP 兼容的客户端通过一组强大的工具与 Dropbox 交互。

重要声明： 本项目与 Dropbox 无关，未经 Dropbox 认可或赞助。 这是一个独立集成，使用 Dropbox 的公共 API。

目录

• 快速开始
• 安装
• 身份验证
• 可用工具
• 配置
• 使用示例
• 测试
• 开发
• 许可证

快速开始

1. 克隆存储库
2. 运行 npm install 安装依赖项
3. 运行 npm run build 构建项目
4. 在 Dropbox App Console 注册一个 Dropbox 应用：
   • 选择 "Scoped access" API
   • 选择您的应用需要的访问类型
   • 命名您的应用并点击 "Create app"
   • 在 "Permissions" 下，选择所需的权限：
     • files.metadata.read
     • files.content.read
     • files.content.write
     • sharing.write
     • account_info.read
   • 添加 http://localhost:3000/callback 作为您的重定向 URI
   • 记下您的 App key 和 App secret
5. 运行设置脚本：

   npm run setup
   

6. 配置您的 MCP 客户端以使用该服务器

安装

1. 克隆存储库

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

2. 安装依赖项并构建

   npm install
   npm run build
   

3. 运行设置脚本

   npm run setup
   

4. 添加到 MCP 设置

   将以下内容添加到您的 MCP 设置文件：

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

身份验证

服务器使用带有 PKCE 的 OAuth 2.0 进行与 Dropbox 的安全身份验证。

环境变量

必需：

• DROPBOX_APP_KEY: 您的 Dropbox 应用的 key
• DROPBOX_APP_SECRET: 您的 Dropbox 应用的 secret
• DROPBOX_REDIRECT_URI: OAuth 重定向 URI
• TOKEN_ENCRYPTION_KEY: 用于令牌加密的 32+ 字符密钥

可选：

• TOKEN_REFRESH_THRESHOLD_MINUTES: 令牌过期前多少分钟刷新令牌（默认值：5）
• MAX_TOKEN_REFRESH_RETRIES: 最大刷新尝试次数（默认值：3）
• TOKEN_REFRESH_RETRY_DELAY_MS: 刷新尝试之间的延迟（毫秒）（默认值：1000）

可用工具

文件操作

• list_files: 列出目录中的文件
• upload_file: 上传文件
• download_file: 下载文件
• safe_delete_item: 安全删除，支持回收站
• create_folder: 创建新文件夹
• copy_item: 复制文件或文件夹
• move_item: 移动或重命名文件/文件夹

元数据和搜索

• get_file_metadata: 获取文件/文件夹元数据
• search_file_db: 搜索文件和文件夹
• get_sharing_link: 创建共享链接
• get_file_content: 获取文件内容

帐户操作

• get_account_info: 获取帐户信息

使用示例

// 列出根目录中的文件
await mcp.useTool("dbx-mcp-server", "list_files", { path: "" });

// 上传文件
await mcp.useTool("dbx-mcp-server", "upload_file", {
  path: "/test.txt",
  content: Buffer.from("Hello World").toString("base64"),
});

// 搜索文件
await mcp.useTool("dbx-mcp-server", "search_file_db", {
  query: "report",
  path: "/Documents",
  max_results: 10,
});

测试

运行测试套件：

npm test

测试验证所有操作，包括身份验证、文件操作和错误处理。

测试结构

测试套件组织成几个模块：

• Dropbox 操作: 基本文件操作的测试（上传、下载、列表等）
• 帐户操作: 访问帐户信息的测试
• 搜索和删除: 搜索功能和安全删除（支持回收站）的测试
• 资源系统: MCP 资源系统集成的测试

处理测试数据

测试使用基于时间戳动态生成的文件和文件夹名称，以避免冲突。 测试数据在测试执行后自动清理。

运行特定测试

要运行特定的测试文件或测试组：

npm test -- tests/dropbox/search-delete.test.ts  # 运行特定测试文件
npm test -- -t "should search for files"        # 运行与描述匹配的测试

排除测试故障

如果测试因计时或身份验证问题而失败：

1. 检查 tests/setup.ts 中的模拟实现是否与您的测试期望相符
2. 确保测试助手已正确配置
3. 对于 Jest 范围错误，避免在模拟工厂函数中引用导入的变量

开发

构建使用：

• TypeScript
• 模型上下文协议 SDK
• Dropbox SDK v10.34.0
• Dropbox API v2

许可证

MIT 许可证

版权所有 (c) 2025 MCP Server Contributors

特此授予任何人免费获得本软件及其相关文档文件（“软件”）副本的许可，不受限制地处理本软件，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或销售本软件副本的权利，并允许向其提供本软件的人员这样做，但须符合以下条件：

上述版权声明和本许可声明应包含在本软件的所有副本或主要部分中。

本软件按“原样”提供，不提供任何形式的明示或暗示的保证，包括但不限于适销性、特定用途的适用性和不侵权的保证。 在任何情况下，作者或版权持有人均不对任何索赔、损害或其他责任负责，无论是在合同诉讼、侵权诉讼或其他诉讼中，无论是由本软件或本软件的使用或其他交易引起的、与之相关的或与之相关的。