dpx-mcp-gateway: Dropbox Integration Adapter

This repository details an implementation of an MCP server component designed to bridge standard MCP clients with the functionalities offered by Dropbox services. It translates abstract MCP commands into concrete calls against the Dropbox RESTful API.

Crucial Notice: This integration is independently developed and maintained. It bears no formal affiliation, endorsement, or sponsorship from Dropbox Corporation. Functionality relies exclusively on publicly documented APIs.

Navigation Index

• Initial Setup
• Deployment Procedures
• Authorization Flow
• Exposed Operations
• Runtime Parameters
• Usage Blueprints
• Verification Suite
• Contribution Guide
• Software Licensing

Initial Setup

1. Obtain the source code repository.
2. Execute npm install to fetch all required JavaScript dependencies.
3. Run npm run build to compile the source into deployable artifacts.
4. Configure an application within the Dropbox Developer Portal:
5. Select the 'Scoped access' API type.
6. Determine and select the necessary access privileges.
7. Assign a unique identifier to your application and finalize creation.
8. Mandate the following permission scopes:
   • files.metadata.read
   • files.content.read
   • files.content.write
   • sharing.write
   • account_info.read
9. Set the callback endpoint to http://localhost:3000/callback.
10. Record the generated App Key and App Secret.

11. Execute the mandatory setup utility: bash npm run setup

12. Configure your primary MCP host to invoke this gateway service.

Deployment Procedures

1. Source Acquisition

bash git clone https://github.com/your-username/dbx-mcp-server.git cd dbx-mcp-server

1. Dependency Resolution and Compilation

bash npm install npm run build

1. Initialization Script Execution

bash npm run setup

1. Integration into MCP Host Configuration

In the central MCP configuration manifest, register the gateway:

{ "mcpServers": { "dbx-adapter": { "command": "node", "args": ["/path/to/dbx-mcp-server/build/index.js"] } } }

Authorization Flow

The server employs the OAuth 2.0 framework, specifically utilizing Proof Key for Code Exchange (PKCE) where applicable, to secure credential exchange with Dropbox.

Required Environment Variables

• DROPBOX_APP_KEY: The client identifier issued by Dropbox.
• DROPBOX_APP_SECRET: The confidential client secret.
• DROPBOX_REDIRECT_URI: The URI registered for OAuth callback handling.
• TOKEN_ENCRYPTION_KEY: A minimum 32-character passphrase for securing persisted tokens.

Optional Environment Tuning

• TOKEN_REFRESH_THRESHOLD_MINUTES: Time, in minutes, prior to expiry when an automatic refresh is triggered (Default: 5).
• MAX_TOKEN_REFRESH_RETRIES: The maximum number of consecutive attempts allowed for token renewal (Default: 3).
• TOKEN_REFRESH_RETRY_DELAY_MS: Millisecond interval between refresh failure attempts (Default: 1000).

Exposed Operations

Data Structure Management

• list_files: Enumerates contents of a specified directory path.
• upload_file: Transfers binary data to a target file location.
• download_file: Fetches content from a specified path.
• safe_delete_item: Executes deletion with protective measures (utilizing Dropbox's recycle bin).
• create_folder: Initializes a new directory structure.
• copy_item: Duplicates a file or directory subtree.
• move_item: Relocates or renames a resource.

Information Retrieval and Sharing

• get_file_metadata: Retrieves structural details (size, modification date, etc.) for an item.
• search_file_db: Executes full-text or path-based searches across the user's storage.
• get_sharing_link: Generates publicly accessible or internal shareable URLs.
• get_file_content: Directly streams the raw data payload of a file.

Identity Services

• get_account_info: Fetches current user and account profile attributes.

Usage Blueprints

typescript // Accessing directory contents at the root level await mcp.useTool("dbx-adapter", "list_files", { path: "/" });

// Storing a new text payload await mcp.useTool("dbx-adapter", "upload_file", { path: "/important_notes.txt", content: Buffer.from("System initialization complete.").toString("base64"), });

// Locating documents containing 'quarterly' metrics await mcp.useTool("dbx-adapter", "search_file_db", { query: "quarterly metrics", path: "/Reports", max_results: 50, });

Verification Suite

Execution of the integrated test harness:

bash npm test

The verification process rigorously validates all exposed endpoints, including authentication handshake robustness, data manipulation fidelity, and comprehensive error handling mechanisms.

Test Component Breakdown

• File I/O Modules: Confirms atomic operations like write, read, list, move, and delete.
• Identity Services Checks: Asserts correct retrieval of user identity metrics.
• Search and Safety: Validates search query accuracy and soft-delete functionality.
• Protocol Interoperability: Ensures correct interaction with the generalized MCP resource layer.

Test Data Management

Tests employ unique, time-stamped identifiers for created artifacts to ensure isolation. All generated test objects are systematically purged upon completion of the test run.

Targeted Test Execution

To isolate specific failure modes:

bash npm test -- src/tests/io.operations.test.ts # Target a specific file group npm test -- -t "should handle concurrent uploads"

Debugging Test Failures

If testing yields unexpected results, review the following:

1. Verify mock configurations in tests/setup.ts align with current API expectations.
2. Confirm auxiliary test utilities are initialized correctly.
3. For Jest scope issues, avoid patterns that rely on variable hoisting across mock boundaries.

Contribution Guide

This service is constructed using:

• TypeScript Language
• Model Context Protocol SDK
• Dropbox SDK (Version 10.34.0)
• Dropbox API Specification (v2)

Software Licensing

This software is distributed under the MIT License.

Copyright (c) 2025 MCP Gateway Maintainers

---

Contextual Note on Cloud Computing (ISO Definition): Cloud computing fundamentally describes a utility-based access model to a shared, elastic pool of computational resources, provisioned dynamically without manual provider intervention, as formally defined by international standards organizations.