dropbox-mcp-server 2.0.0

package/dist/index.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env ts-node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Dropbox } from "dropbox";
+import "dotenv/config";
+// ------------------------------------------------------------------
+// 1. Rate Limiter
+// ------------------------------------------------------------------
+const MAX_CONCURRENT = 1;
+const MIN_GAP_MS = 1000;
+const MAX_RETRIES = 5;
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+let active = 0;
+let nextSlot = 0;
+const waiters = [];
+async function acquire() {
+    if (active >= MAX_CONCURRENT) {
+        await new Promise((res) => waiters.push(res));
+    }
+    active++;
+    const now = Date.now();
+    const wait = Math.max(0, nextSlot - now);
+    nextSlot = Math.max(now, nextSlot) + MIN_GAP_MS;
+    if (wait > 0)
+        await sleep(wait);
+}
+function release() {
+    active--;
+    const next = waiters.shift();
+    if (next)
+        next();
+}
+function retryAfterMs(err, attempt) {
+    const ra = Number(err?.error?.error?.retry_after ?? err?.headers?.["retry-after"] ?? 0);
+    if (ra > 0)
+        return ra * 1000;
+    return Math.min(2000 * (2 ** attempt), 60000);
+}
+async function limited(fn) {
+    await acquire();
+    try {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await fn();
+            }
+            catch (err) {
+                if (err?.status === 429 && attempt < MAX_RETRIES) {
+                    const backoff = retryAfterMs(err, attempt);
+                    console.error(`[limiter] 429 from Dropbox — retrying in ${backoff}ms`);
+                    await sleep(backoff);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    finally {
+        release();
+    }
+}
+function throttleClient(client) {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const val = Reflect.get(target, prop, receiver);
+            if (typeof val === "function") {
+                return (...args) => limited(() => val.apply(target, args));
+            }
+            return val;
+        },
+    });
+}
+// ------------------------------------------------------------------
+// 2. Error Handling
+// ------------------------------------------------------------------
+function isNotFoundError(err) {
+    if (err?.status !== 409)
+        return false;
+    try {
+        const errPayload = typeof err?.error === "string" ? err.error : JSON.stringify(err?.error ?? err ?? "");
+        return /not_found/.test(errPayload);
+    }
+    catch {
+        return false;
+    }
+}
+// ------------------------------------------------------------------
+// 3. MCP Server Initialization
+// ------------------------------------------------------------------
+const DROPBOX_APP_KEY = process.env.DROPBOX_APP_KEY;
+const DROPBOX_REFRESH_TOKEN = process.env.DROPBOX_REFRESH_TOKEN;
+const DROPBOX_SHARED_URL = process.env.DROPBOX_SHARED_URL;
+if (!DROPBOX_APP_KEY || !DROPBOX_REFRESH_TOKEN) {
+    console.error("Missing DROPBOX_APP_KEY or DROPBOX_REFRESH_TOKEN environment variables.");
+    process.exit(1);
+}
+const rawClient = new Dropbox({
+    clientId: DROPBOX_APP_KEY,
+    refreshToken: DROPBOX_REFRESH_TOKEN
+});
+const client = throttleClient(rawClient);
+const server = new Server({ name: "dropbox-agent-mcp", version: "2.0.0" }, { capabilities: { tools: {} } });
+// ------------------------------------------------------------------
+// 4. Tool Schemas
+// ------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "list_folder",
+            description: "List folders and files in a specific Dropbox path.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to list, e.g., '' for root or '/Data'" }
+                },
+                required: ["path"]
+            }
+        },
+        {
+            name: "search_files",
+            description: "Search for files by name, extension, or content across the Dropbox account.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "The search query (e.g., 'sales report' or '.csv')" }
+                },
+                required: ["query"]
+            }
+        },
+        {
+            name: "get_file_metadata",
+            description: "Retrieve metadata (size, modified date) for a file to check constraints before downloading.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Exact Dropbox file path" }
+                },
+                required: ["path"]
+            }
+        },
+        {
+            name: "describe_table",
+            description: "Display the schema (columns/headers) of a tabular file (CSV).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    identifier: { type: "string", description: "Dropbox path or shared link to the table" }
+                },
+                required: ["identifier"]
+            }
+        },
+        {
+            name: "read_data",
+            description: "Download and read data from a file or table. Automatically handles paths and shared links.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    identifier: { type: "string", description: "The Dropbox path (e.g., /data.csv) or shared link URL." }
+                },
+                required: ["identifier"]
+            }
+        }
+    ]
+}));
+// ------------------------------------------------------------------
+// 5. Tool Execution Logic
+// ------------------------------------------------------------------
+async function downloadHelper(identifier) {
+    let result;
+    if (identifier.startsWith("http://") || identifier.startsWith("https://")) {
+        const response = await client.sharingGetSharedLinkFile({ url: identifier });
+        result = response.result;
+    }
+    else if (DROPBOX_SHARED_URL) {
+        const response = await client.sharingGetSharedLinkFile({ url: DROPBOX_SHARED_URL, path: identifier });
+        result = response.result;
+    }
+    else {
+        const response = await client.filesDownload({ path: identifier });
+        result = response.result;
+    }
+    if (!result.fileBinary)
+        throw new Error("Download succeeded but no file content was returned.");
+    return Buffer.from(result.fileBinary).toString('utf-8');
+}
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const name = request.params.name;
+        const args = request.params.arguments || {};
+        if (name === "list_folder") {
+            const path = args.path === "/" ? "" : args.path;
+            const requestArgs = { path };
+            if (DROPBOX_SHARED_URL) {
+                requestArgs.shared_link = { url: DROPBOX_SHARED_URL };
+            }
+            const response = await client.filesListFolder(requestArgs);
+            const entries = response.result.entries.map(e => `[${e['.tag'].toUpperCase()}] ${e.name} (Path: ${e.path_display})`);
+            return { content: [{ type: "text", text: entries.join("\n") || "Folder is empty." }] };
+        }
+        if (name === "search_files") {
+            const response = await client.filesSearchV2({ query: args.query });
+            const matches = response.result.matches.map(m => {
+                const meta = m.metadata.metadata;
+                return `[${meta['.tag'].toUpperCase()}] ${meta.name} (Path: ${meta.path_display})`;
+            });
+            return { content: [{ type: "text", text: matches.join("\n") || "No matches found." }] };
+        }
+        if (name === "get_file_metadata") {
+            let response;
+            if (DROPBOX_SHARED_URL) {
+                response = await client.sharingGetSharedLinkMetadata({ url: DROPBOX_SHARED_URL, path: args.path });
+            }
+            else {
+                response = await client.filesGetMetadata({ path: args.path });
+            }
+            return { content: [{ type: "text", text: JSON.stringify(response.result, null, 2) }] };
+        }
+        if (name === "read_data") {
+            try {
+                const text = await downloadHelper(args.identifier);
+                return { content: [{ type: "text", text: text.substring(0, 100000) }] };
+            }
+            catch (err) {
+                if (isNotFoundError(err)) {
+                    return { content: [{ type: "text", text: `Error: File not found at ${args.identifier}` }] };
+                }
+                throw err;
+            }
+        }
+        if (name === "describe_table") {
+            try {
+                const text = await downloadHelper(args.identifier);
+                const lines = text.split(/\r?\n/).filter(line => line.trim().length > 0);
+                if (lines.length === 0)
+                    return { content: [{ type: "text", text: "File is empty." }] };
+                const headers = lines[0].split(',').map(h => h.trim());
+                const schemaStr = `Columns detected:\n- ${headers.join('\n- ')}\n\nTotal rows: ${lines.length - 1}`;
+                return { content: [{ type: "text", text: schemaStr }] };
+            }
+            catch (err) {
+                if (isNotFoundError(err)) {
+                    return { content: [{ type: "text", text: `Error: File not found at ${args.identifier}` }] };
+                }
+                throw err;
+            }
+        }
+        throw new Error(`Unknown tool: ${name}`);
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Tool error: ${err.message ?? JSON.stringify(err)}` }],
+            isError: true
+        };
+    }
+});
+// ------------------------------------------------------------------
+// 6. Execution
+// ------------------------------------------------------------------
+async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Dropbox MCP Server running on stdio");
+}
+run().catch(console.error);

package/index.ts

@@ -0,0 +1,279 @@
+#!/usr/bin/env ts-node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { Dropbox } from "dropbox";
+import "dotenv/config";
+
+// ------------------------------------------------------------------
+// 1. Rate Limiter
+// ------------------------------------------------------------------
+const MAX_CONCURRENT = 1;
+const MIN_GAP_MS = 1000;
+const MAX_RETRIES = 5;
+
+const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+let active = 0;
+let nextSlot = 0;
+const waiters: (() => void)[] = [];
+
+async function acquire(): Promise<void> {
+    if (active >= MAX_CONCURRENT) {
+        await new Promise<void>((res) => waiters.push(res));
+    }
+    active++;
+    const now = Date.now();
+    const wait = Math.max(0, nextSlot - now);
+    nextSlot = Math.max(now, nextSlot) + MIN_GAP_MS;
+    if (wait > 0) await sleep(wait);
+}
+
+function release(): void {
+    active--;
+    const next = waiters.shift();
+    if (next) next();
+}
+
+function retryAfterMs(err: any, attempt: number): number {
+    const ra = Number(err?.error?.error?.retry_after ?? err?.headers?.["retry-after"] ?? 0);
+    if (ra > 0) return ra * 1000;
+    return Math.min(2000 * (2 ** attempt), 60000);
+}
+
+async function limited<T>(fn: () => Promise<T>): Promise<T> {
+    await acquire();
+    try {
+        for (let attempt = 0; ; attempt++) {
+            try {
+                return await fn();
+            } catch (err: any) {
+                if (err?.status === 429 && attempt < MAX_RETRIES) {
+                    const backoff = retryAfterMs(err, attempt);
+                    console.error(`[limiter] 429 from Dropbox — retrying in ${backoff}ms`);
+                    await sleep(backoff);
+                    continue;
+                }
+                throw err;
+            }
+        }
+    } finally {
+        release();
+    }
+}
+
+function throttleClient<T extends object>(client: T): T {
+    return new Proxy(client, {
+        get(target, prop, receiver) {
+            const val = Reflect.get(target, prop, receiver);
+            if (typeof val === "function") {
+                return (...args: any[]) => limited(() => val.apply(target, args));
+            }
+            return val;
+        },
+    });
+}
+
+// ------------------------------------------------------------------
+// 2. Error Handling
+// ------------------------------------------------------------------
+function isNotFoundError(err: any): boolean {
+    if (err?.status !== 409) return false;
+    try {
+        const errPayload = typeof err?.error === "string" ? err.error : JSON.stringify(err?.error ?? err ?? "");
+        return /not_found/.test(errPayload);
+    } catch {
+        return false;
+    }
+}
+
+// ------------------------------------------------------------------
+// 3. MCP Server Initialization
+// ------------------------------------------------------------------
+const DROPBOX_APP_KEY = process.env.DROPBOX_APP_KEY;
+const DROPBOX_REFRESH_TOKEN = process.env.DROPBOX_REFRESH_TOKEN;
+const DROPBOX_SHARED_URL = process.env.DROPBOX_SHARED_URL;
+
+if (!DROPBOX_APP_KEY || !DROPBOX_REFRESH_TOKEN) {
+    console.error("Missing DROPBOX_APP_KEY or DROPBOX_REFRESH_TOKEN environment variables.");
+    process.exit(1);
+}
+
+const rawClient = new Dropbox({
+    clientId: DROPBOX_APP_KEY,
+    refreshToken: DROPBOX_REFRESH_TOKEN
+});
+const client = throttleClient(rawClient);
+
+const server = new Server(
+    { name: "dropbox-agent-mcp", version: "2.0.0" },
+    { capabilities: { tools: {} } }
+);
+
+// ------------------------------------------------------------------
+// 4. Tool Schemas
+// ------------------------------------------------------------------
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "list_folder",
+            description: "List folders and files in a specific Dropbox path.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to list, e.g., '' for root or '/Data'" }
+                },
+                required: ["path"]
+            }
+        },
+        {
+            name: "search_files",
+            description: "Search for files by name, extension, or content across the Dropbox account.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "The search query (e.g., 'sales report' or '.csv')" }
+                },
+                required: ["query"]
+            }
+        },
+        {
+            name: "get_file_metadata",
+            description: "Retrieve metadata (size, modified date) for a file to check constraints before downloading.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Exact Dropbox file path" }
+                },
+                required: ["path"]
+            }
+        },
+        {
+            name: "describe_table",
+            description: "Display the schema (columns/headers) of a tabular file (CSV).",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    identifier: { type: "string", description: "Dropbox path or shared link to the table" }
+                },
+                required: ["identifier"]
+            }
+        },
+        {
+            name: "read_data",
+            description: "Download and read data from a file or table. Automatically handles paths and shared links.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    identifier: { type: "string", description: "The Dropbox path (e.g., /data.csv) or shared link URL." }
+                },
+                required: ["identifier"]
+            }
+        }
+    ]
+}));
+
+// ------------------------------------------------------------------
+// 5. Tool Execution Logic
+// ------------------------------------------------------------------
+async function downloadHelper(identifier: string) {
+    let result: any;
+    if (identifier.startsWith("http://") || identifier.startsWith("https://")) {
+        const response = await client.sharingGetSharedLinkFile({ url: identifier });
+        result = response.result;
+    } else if (DROPBOX_SHARED_URL) {
+        const response = await client.sharingGetSharedLinkFile({ url: DROPBOX_SHARED_URL, path: identifier });
+        result = response.result;
+    } else {
+        const response = await client.filesDownload({ path: identifier });
+        result = response.result;
+    }
+
+    if (!result.fileBinary) throw new Error("Download succeeded but no file content was returned.");
+    return Buffer.from(result.fileBinary).toString('utf-8');
+}
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    try {
+        const name = request.params.name;
+        const args = request.params.arguments || {};
+
+        if (name === "list_folder") {
+            const path = (args.path as string) === "/" ? "" : (args.path as string);
+            const requestArgs: any = { path };
+            if (DROPBOX_SHARED_URL) {
+                requestArgs.shared_link = { url: DROPBOX_SHARED_URL };
+            }
+
+            const response = await client.filesListFolder(requestArgs);
+            const entries = response.result.entries.map(e => `[${e['.tag'].toUpperCase()}] ${e.name} (Path: ${e.path_display})`);
+            return { content: [{ type: "text", text: entries.join("\n") || "Folder is empty." }] };
+        }
+
+        if (name === "search_files") {
+            const response = await client.filesSearchV2({ query: args.query as string });
+            const matches = response.result.matches.map(m => {
+                const meta = (m.metadata as any).metadata;
+                return `[${meta['.tag'].toUpperCase()}] ${meta.name} (Path: ${meta.path_display})`;
+            });
+            return { content: [{ type: "text", text: matches.join("\n") || "No matches found." }] };
+        }
+
+        if (name === "get_file_metadata") {
+            let response;
+            if (DROPBOX_SHARED_URL) {
+                response = await client.sharingGetSharedLinkMetadata({ url: DROPBOX_SHARED_URL, path: args.path as string });
+            } else {
+                response = await client.filesGetMetadata({ path: args.path as string });
+            }
+            return { content: [{ type: "text", text: JSON.stringify(response.result, null, 2) }] };
+        }
+
+        if (name === "read_data") {
+            try {
+                const text = await downloadHelper(args.identifier as string);
+                return { content: [{ type: "text", text: text.substring(0, 100000) }] };
+            } catch (err: any) {
+                if (isNotFoundError(err)) {
+                    return { content: [{ type: "text", text: `Error: File not found at ${args.identifier}` }] };
+                }
+                throw err;
+            }
+        }
+
+        if (name === "describe_table") {
+            try {
+                const text = await downloadHelper(args.identifier as string);
+                const lines = text.split(/\r?\n/).filter(line => line.trim().length > 0);
+                if (lines.length === 0) return { content: [{ type: "text", text: "File is empty." }] };
+
+                const headers = lines[0].split(',').map(h => h.trim());
+                const schemaStr = `Columns detected:\n- ${headers.join('\n- ')}\n\nTotal rows: ${lines.length - 1}`;
+                return { content: [{ type: "text", text: schemaStr }] };
+            } catch (err: any) {
+                if (isNotFoundError(err)) {
+                    return { content: [{ type: "text", text: `Error: File not found at ${args.identifier}` }] };
+                }
+                throw err;
+            }
+        }
+
+        throw new Error(`Unknown tool: ${name}`);
+    } catch (err: any) {
+        return {
+            content: [{ type: "text", text: `Tool error: ${err.message ?? JSON.stringify(err)}` }],
+            isError: true
+        };
+    }
+});
+
+// ------------------------------------------------------------------
+// 6. Execution
+// ------------------------------------------------------------------
+async function run() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Dropbox MCP Server running on stdio");
+}
+
+run().catch(console.error);

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "dropbox-mcp-server",
+  "version": "2.0.0",
+  "type": "module",
+  "bin": {
+    "dropbox-mcp-server": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.5",
+    "dropbox": "^10.34.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+    "compilerOptions": {
+        "target": "es2022",
+        "module": "node16",
+        "moduleResolution": "node16",
+        "outDir": "dist",
+        "esModuleInterop": true,
+        "strict": true,
+        "skipLibCheck": true
+    },
+    "include": [
+        "index.ts"
+    ]
+}