Onedrive MCP Server Spring

🚀 適用於 Microsoft OneDrive 的 MCP 服務器

這是一個實現 Model Context Protocol (MCP) 協議的服務器，能讓 AI 代理搜索和導航 Microsoft OneDrive 中的文件與文件夾。它基於 Spring Boot 和 Spring AI 構建，為用戶提供便捷的 OneDrive 訪問體驗。

🚀 快速開始

在使用本服務器之前，你需要完成一些準備工作，包括獲取訪問令牌和進行相關配置。具體步驟請參考後續的“獲取 Microsoft OneDrive 訪問令牌”和“配置”章節。

✨ 主要特性

• 🔍 在 OneDrive 中搜索文件，支持可選的文件夾過濾。
• 📁 可搜索和導航文件夾結構。
• 🔗 能獲取文件和文件夾的直接網絡鏈接。
• 🤖 具備與 AI 代理集成的 MCP 兼容接口。
• 🔒 使用 Microsoft Graph API 實現安全訪問。

📦 安裝指南

先決條件

• Java 21 或更高版本
• Maven 3.6+
• Docker（可選，用於容器化部署）
• Microsoft OneDrive 賬戶和訪問令牌

獲取 Microsoft OneDrive 訪問令牌

方法一：使用 Microsoft 帳戶登錄

1. 打開瀏覽器，訪問 https://onedrive.live.com。
2. 使用您的 Microsoft 帳戶登錄。
3. 登錄後，您可以在瀏覽器地址欄中看到一個以 .access 結尾的鏈接。例如：https://account.microsoft.com/onedrive/authorize?response_type=code&client_id=your_client_id&redirect_uri=your_redirect_uri&scope=files.readwrite
4. 將此鏈接複製到剪貼板。
5. 在終端中運行以下命令，將 .access 鏈接粘貼到最後：

   curl -X POST https://login.microsoftonline.com/common/oauth2/v2.0/token -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "client_id=your_client_id&redirect_uri=your_redirect_uri&code=<paste-your-code>&grant_type=authorization_code"
   

6. 按下回車，您將獲得一個包含訪問令牌的 JSON 響應。您可以從 access_token 字段中提取訪問令牌。

方法二：使用 Azure 門戶創建應用程序並獲取令牌

1. 訪問 Azure 門戶網站。
2. 登錄您的 Microsoft 帳戶。
3. 在左側菜單中，選擇 “註冊企業應用”。
4. 按照提示填寫應用程序的名稱、描述和其他必要信息，然後完成註冊。
5. 註冊完成後，在 Azure 門戶中找到您剛創建的應用程序，並轉到其 “設置” 部分。
6. 在 “OAuth2 令牌端點授權” 下，記錄您的客戶端 ID 和客戶端密鑰。
7. 使用以下命令通過客戶端憑據獲取訪問令牌：

   curl -X POST https://login.microsoftonline.com/common/oauth2/v2.0/token -H "Content-Type: application/x-www-form-urlencoded" --data-urlencode "client_id=your_client_id&client_secret=your_client_secret&grant_type=client_credentials"
   

8. 按下回車，您將獲得一個包含訪問令牌的 JSON 響應。您可以從 access_token 字段中提取訪問令牌。

配置

環境變量配置

在運行 MCP 服務器之前，請確保已設置以下環境變量：

• ONEDRIVE_CLIENT_ID: 您的應用程序客戶端 ID。
• ONEDRIVE_CLIENT_SECRET: 您的應用程序客戶端密鑰。
• ONEDRIVE_REDIRECT_URI: 您應用的重定向 URI。

文本文件配置

您也可以將這些值寫入一個文本文件（例如 .env）：

ONEDRIVE_CLIENT_ID=your_client_id
ONEDRIVE_CLIENT_SECRET=your_client_secret
ONEDRIVE_REDIRECT_URI=your_redirect_uri

運行

直接運行

在終端中運行以下命令來啟動 MCP 服務器：

mvn spring-boot:run

Docker 部署

1. 構建 Docker 映像：

   mvn spring-boot:build-image
   

2. 這將創建一個名為 karthik20/onedrive-mcp-server:0.0.1 的映像。
3. 運行容器：

   docker run -p 8080:8080 -e ONEDRIVE_ACCESS_TOKEN=your-token karthik20/onedrive-mcp-server:0.0.1
   

💻 使用示例

基礎用法

以下是使用 MCP 服務器提供的 API 的簡單示例：

Java 示例

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

public class OnedriveMcpClient {
    public static void main(String[] args) {
        String serverUrl = "http://localhost:8080";
        
        // 搜索文件
        try {
            HttpClient client = HttpClient.newDefault();
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(serverUrl + "/api/search/files?name=testfile.txt"))
                .build();
            HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
        
        // 搜索文件夾
        try {
            HttpClient client = HttpClient.newDefault();
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(serverUrl + "/api/search/folders?name=Documents"))
                .build();
            HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
        
        // 列出文件夾內容
        try {
            HttpClient client = HttpClient.newDefault();
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(serverUrl + "/api/list_contents/folder?path=/"))
                .build();
            HttpResponse<String> response = client.send(request,HttpResponse.BodyHandlers.ofString());
            System.out.println(response.body());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Python 示例

import requests

server_url = "http://localhost:8080"

# 搜索文件
try:
    response = requests.get(f"{server_url}/api/search/files?name=testfile.txt")
    print(response.json())
except Exception as e:
    print(str(e))

# 搜索文件夾
try:
    response = requests.get(f"{server_url}/api/search/folders?name=Documents")
    print(response.json())
except Exception as e:
    print(str(e))

# 列出文件夾內容
try:
    response = requests.get(f"{server_url}/api/list_contents/folder?path=/")
    print(response.json())
except Exception as e:
    print(str(e))

📚 詳細文檔

可用的 MCP 工具

搜索文件

在 OneDrive 中搜索文件，可選文件夾過濾：

public String searchFiles(String fileName, String folder)

搜索文件夾

導航和搜索文件夾結構：

public String searchFolderPath(String folderName)

列出文件夾內容

列出特定文件夾路徑下的所有文件和文件夾：

public String listFolderContents(String folderPath)

返回一個 JSON 數組，包含文件和文件夾的信息。

項目結構

根目錄

• src/main/java/com/example/onedrive/OAuth2TokenProvider.java: 提供 OAuth 2.0 令牌的實現。
• src/main/java/com/example/onedrive/OneDriveService.java: 定義與 OneDrive 交互的核心服務接口。
• src/main/java/com/example/mcp/MCPController.java: 處理 MCP 服務器的 API 請求。

資源

• /api/search/files: 搜索文件
• /api/search/folders: 搜索文件夾
• /api/list_contents/folder: 列出指定路徑下的文件夾內容

附錄 - REST API 文檔

• 搜索文件：

  GET /api/search/files?name=<filename>
  
  返回指定文件名的所有匹配項。
  

• 搜索文件夾：

  GET /api/search/folders?name=<foldername>
  

🔧 技術細節

依賴項

• Spring Boot
• Java HTTP 客戶端庫
• JSON 處理庫

構建和運行

使用 Maven

1. 在項目根目錄中，運行以下命令構建項目：

   mvn clean install
   

2. 運行 MCP 服務器：

   mvn spring-boot:run
   

手動部署

1. 將 MCP 服務器 JAR 文件複製到目標服務器。
2. 在終端中運行：

   java -jar onedrive-mcp-server-0.0.1.jar
   

監控和日誌

建議集成以下工具來監控和日誌記錄：

• Prometheus 和 Grafana：用於度量和可視化。
• ELK Stack（Elasticsearch, Logstash, Kibana）：用於日誌管理和分析。

故障排除

1. 無法啟動 MCP 服務器

   • 檢查端口是否被佔用。默認端口為 8080，如果與其他服務衝突，請更換端口。

2. 無法訪問 OneDrive 資源

   • 確保您的應用程序具有適當的權限，並且環境變量配置正確。

3. API 請求失敗

   • 檢查請求的 URL 是否正確，查看返回的狀態碼和響應內容。

📄 注意事項

⚠️ 重要提示

1. 權限管理：確保您的應用程序具有適當的權限來訪問 OneDrive 資源。
2. 錯誤處理：在生產環境中，建議添加適當的錯誤處理機制和日誌記錄。
3. 安全性：不要在代碼中明文存儲敏感信息（如客戶端密鑰）。建議使用環境變量或安全的配置管理工具。