Dropbox MCP Server

🚀 dbx-mcp-server

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

⚠️ 重要提示

此项目未获得 Dropbox 的关联、认可或赞助。它是一个独立的整合项目，通过使用 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 官方文档

💡 使用建议

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