dbx-mcp-server

一个提供与Dropbox集成的模型上下文协议（MCP）服务器，通过一组强大的工具实现MCP兼容客户端与Dropbox之间的交互。

重要免责声明： 此项目未获得Dropbox的 affiliation、endorsement 或 sponsorship。它是一个独立的整合，使用Dropbox的公共API工作。

目录

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

快速开始

1. 克隆仓库
2. 运行 npm install 安装依赖项
3. 运行 npm run build 构建项目
4. 在 Dropbox 应用控制台 创建一个新应用：
   • 生成应用密钥
5. 将应用密钥配置到环境变量中：
   • DROPBOX_APP_KEY
   • DROPBOX_APP_SECRET
6. 运行项目：

   npm run start
   

安装

要安装项目并运行示例，请执行以下步骤：

1. 克隆仓库：

   git clone [仓库地址]
   cd dbx-mcp-server
   

2. 安装依赖项：

   npm install
   

3. 配置环境变量：
   • DROPBOX_APP_KEY：你的 Dropbox 应用密钥
   • DROPBOX_APP_SECRET：你的 Dropbox 应用秘密
4. 运行项目：

   npm run start
   

身份验证

此服务器使用基于OAuth 2.0的PKCE（行业标准）进行身份验证。以下是主要的身份验证步骤：

1. 客户端请求授权URL：

   GET https://accounts.dropbox.com/oauth2/authorize?client_id=APP_KEY&response_type=code&redirect_uri=REDIRECT_URI
   

2. 用户授权应用后，服务器会重定向到指定的回调URL，并附带一个授权码。
3. 客户端使用授权码请求访问令牌：

   POST https://api.dropbox.com/oauth2/token
   Content-Type: application/x-www-form-urlencoded
   
   grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI
   

4. 服务器返回访问令牌和刷新令牌：

   {
     "access_token": "ACCESS_TOKEN",
     "token_type": "Bearer",
     "expires_in": 3600,
     "refresh_token": "REFRESH_TOKEN"
   }
   

可用工具

以下是此服务器提供的主要功能：

文件操作

1. 上传文件：

   POST /files/upload
   Content-Type: multipart/form-data
   
   file=@/path/to/file
   

2. 下载文件：

   GET /files/download?file_id=FILE_ID
   

3. 列出文件：

   GET /files/list?directory=DIRECTORY_ID
   

元数据搜索

1. 搜索文件和目录：

   POST /metadata/search
   Content-Type: application/json
   
   {
     "query": "SEARCH_TERM"
   }
   

2. 获取文件元数据：

   GET /metadata/file?file_id=FILE_ID
   

目录管理

1. 创建目录：

   POST /directories/create
   Content-Type: application/json
   
   {
     "name": "DIRECTORY_NAME",
     "parent_id": "PARENT_DIRECTORY_ID"
   }
   

2. 删除目录：

   DELETE /directories/delete?directory_id=DIRECTORY_ID
   

配置

要在服务器上配置环境变量，请添加以下变量：

• DROPBOX_APP_KEY：你的 Dropbox 应用密钥
• DROPBOX_APP_SECRET：你的 Dropbox 应用秘密
• PORT：可选，默认为3000，指定服务器运行的端口。

使用示例

示例1：上传和下载文件

1. 上传文件：

   curl -X POST http://localhost:3000/files/upload \
    -F "file=@/path/to/file.txt"
   

2. 下载文件：

   curl http://localhost:3000/files/download?file_id=FILE_ID
   

示例2：搜索文件

curl -X POST http://localhost:3000/metadata/search \
  -H "Content-Type: application/json" \
  -d '{"query": "search_term"}'

测试

概述

为了测试服务器功能，请运行以下命令：

npm test

详细步骤

1. 克隆仓库并安装依赖项：

   git clone [仓库地址]
   cd dbx-mcp-server
   npm install
   

2. 运行测试：

   npm test
   

自定义测试

要运行特定测试或测试组，请使用以下命令：

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

错误处理

服务器返回以下错误码：

• 401 Unauthorized：无效或过期令牌
• 403 Forbidden：被阻止的操作
• 404 Not Found：资源未找到
• 500 Internal Server Error：服务器内部错误

依赖项

项目依赖以下库：

• express：Web 框架
• multer：文件上传处理
• dotenv：环境变量加载

许可证

项目使用 MIT 许可证。

贡献者

感谢所有贡献者！

问题报告

如遇问题，请在 GitHub Issues/issues 提交问题。

参考资料

• Dropbox API 文档
• Express 官方文档
• Multer 官方文档

注意：此示例代码旨在提供一个起点，具体实现可能需要根据实际需求调整。