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. 安全性：不要在代码中明文存储敏感信息（如客户端密钥）。建议使用环境变量或安全的配置管理工具。