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 官方文檔

💡 使用建議

此示例代碼旨在提供一個起點，具體實現可能需要根據實際需求調整。