Onedrive MCP Server Spring

🚀 MCP Server for Microsoft OneDrive

An MCP server that enables AI agents to search and navigate files and folders in Microsoft OneDrive, built with Spring Boot and Spring AI.

🚀 Quick Start

This is an MCP server implementing the Model Context Protocol (MCP), enabling AI agents to search and navigate files and folders in Microsoft OneDrive. It's built using Spring Boot and Spring AI.

✨ Features

• 🔍 Search for files in OneDrive with optional folder filtering.
• 📁 Search and navigate the folder structure.
• 🔗 Get direct web links to files and folders.
• 🤖 MCP-compatible interface for integration with AI agents.
• 🔒 Secure access using the Microsoft Graph API.

📦 Installation

Prerequisites

• Java 21 or higher.
• Maven 3.6+.
• Docker (optional, for containerized deployment).
• A Microsoft OneDrive account and access token.

Obtaining a Microsoft OneDrive Access Token

You can obtain an access token for OneDrive in two ways:

Method 1: Logging in with a Microsoft Account

1. Open your browser and visit https://onedrive.live.com.
2. Log in with your Microsoft account.
3. After logging in, you'll see a link ending with .access in the browser address bar. For example: https://account.microsoft.com/onedrive/authorize?response_type=code&client_id=your_client_id&redirect_uri=your_redirect_uri&scope=files.readwrite
4. Copy this link to your clipboard.
5. Run the following command in your terminal, pasting the .access link at the end:

   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. Press Enter, and you'll receive a JSON response containing the access token. You can extract the access token from the access_token field.

Method 2: Creating an Application in the Azure Portal and Obtaining a Token

1. Visit the Azure portal.
2. Log in with your Microsoft account.
3. In the left-hand menu, select “Enterprise application registration”.
4. Follow the prompts to fill in the application's name, description, and other necessary information, then complete the registration.
5. After registration, find the application you just created in the Azure portal and go to its “Settings” section.
6. Under “OAuth2 token endpoint authorization”, record your client ID and client secret.
7. Use the following command to obtain an access token via client credentials:

   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. Press Enter, and you'll receive a JSON response containing the access token. You can extract the access token from the access_token field.

Configuration

Environment Variable Configuration

Before running the MCP server, ensure you've set the following environment variables:

• ONEDRIVE_CLIENT_ID: Your application's client ID.
• ONEDRIVE_CLIENT_SECRET: Your application's client secret.
• ONEDRIVE_REDIRECT_URI: Your application's redirect URI.

Text File Configuration

You can also write these values to a text file (e.g., .env):

ONEDRIVE_CLIENT_ID=your_client_id
ONEDRIVE_CLIENT_SECRET=your_client_secret
ONEDRIVE_REDIRECT_URI=your_redirect_uri

Running the Server

Direct Run

Run the following command in your terminal to start the MCP server:

mvn spring-boot:run

Docker Deployment

1. Build the Docker image:

   mvn spring-boot:build-image
   

2. This will create an image named karthik20/onedrive-mcp-server:0.0.1.
3. Run the container:

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

💻 Usage Examples

Testing with an MCP Client

GitHub Copilot

1. Install GitHub Copilot in VS Code.
2. Configure your AI settings to use the MCP server:

   {
       "mcp.server.url": "http://localhost:8080"
   }
   

Other Microsoft Tools

1. Open the Claude Desktop settings.
2. Add a new MCP server with the URL set to http://localhost:8080.
3. Use the built-in file browser to access OneDrive files.

Available MCP Tools

Searching for Files

Search for files in OneDrive with optional folder filtering:

public String searchFiles(String fileName, String folder)

Searching for Folders

Navigate and search the folder structure:

public String searchFolderPath(String folderName)

Listing Folder Contents

List all files and folders in a specific folder path:

public String listFolderContents(String folderPath)

This returns a JSON array containing information about files and folders.

Test Code Examples

Java Example

The following is a simple Java example demonstrating how to use the API provided by the MCP server:

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";
        
        // Search for files
        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();
        }
        
        // Search for folders
        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();
        }
        
        // List folder contents
        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 Example

The following is a simple Python example demonstrating how to use the API provided by the MCP server:

import requests

server_url = "http://localhost:8080"

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

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

# List folder contents
try:
    response = requests.get(f"{server_url}/api/list_contents/folder?path=/")
    print(response.json())
except Exception as e:
    print(str(e))

📚 Documentation

Project Structure

Root Directory

• src/main/java/com/example/onedrive/OAuth2TokenProvider.java: Implements the OAuth 2.0 token provider.
• src/main/java/com/example/onedrive/OneDriveService.java: Defines the core service interface for interacting with OneDrive.
• src/main/java/com/example/mcp/MCPController.java: Handles API requests for the MCP server.

Resources

• /api/search/files: Search for files.
• /api/search/folders: Search for folders.
• /api/list_contents/folder: List the contents of a folder at a specified path.

Notes

1. Permission Management: Ensure your application has the appropriate permissions to access OneDrive resources.
2. Error Handling: In a production environment, it's recommended to add appropriate error handling mechanisms and logging.
3. Security: Don't store sensitive information (such as client secrets) in plain text in your code. It's recommended to use environment variables or secure configuration management tools.

Dependencies

• Spring Boot
• Java HTTP client library
• JSON processing library

Building and Running

Using Maven

1. In the project's root directory, run the following command to build the project:

   mvn clean install
   

2. Run the MCP server:

   mvn spring-boot:run
   

Manual Deployment

1. Copy the MCP server JAR file to the target server.
2. Run the following in the terminal:

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

Monitoring and Logging

It's recommended to integrate the following tools for monitoring and logging:

• Prometheus and Grafana: For metrics and visualization.
• ELK Stack (Elasticsearch, Logstash, Kibana): For log management and analysis.

Troubleshooting

1. Unable to start the MCP server
   • Check if the port is occupied. The default port is 8080. If it conflicts with other services, change the port.
2. Unable to access OneDrive resources
   • Ensure your application has the appropriate permissions and that the environment variables are configured correctly.
3. API requests fail
   • Check if the request URL is correct, and review the returned status code and response content.

Appendix

REST API Documentation

• Search for files:

  GET /api/search/files?name=<filename>
  
  Returns all matches for the specified file name.
  

• Search for folders:

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