{"skill":{"slug":"dropbox","displayName":"Dropbox Manager","summary":"Manage Dropbox files securely with OAuth 2.0 PKCE via CLI or MCP server, supporting upload, download, search, delete, and account info operations.","description":"# Dropbox Manager Skill\n\nManage Dropbox files via MCP server and CLI. Swift-native implementation using SwiftyDropbox SDK with OAuth 2.0 PKCE and secure Keychain token storage.\n\n## Setup\n\n### Prerequisites\n\n```bash\n# Clone and build Dropbook\ngit clone https://github.com/RyanLisse/Dropbook.git\ncd Dropbook\nmake build\n```\n\n### Authentication\n\n#### Option 1: OAuth Login with Keychain (Recommended)\n\nUse the interactive OAuth flow with secure Keychain storage:\n\n```bash\nexport DROPBOX_APP_KEY=\"your_dropbox_app_key\"\nexport DROPBOX_APP_SECRET=\"your_dropbox_app_secret\"\nmake login\n# or: swift run dropbook login\n```\n\nThis will:\n1. Generate PKCE code verifier and challenge (SHA256, RFC 7636)\n2. Open an authorization URL with state parameter (CSRF protection)\n3. Prompt you to paste the authorization code\n4. Exchange code for access and refresh tokens\n5. **Save tokens to macOS Keychain** (hardware-backed encryption)\n6. Fall back to `~/.dropbook/auth.json` if Keychain unavailable\n7. Enable automatic token refreshing\n\n**Security Features (RFC 9700 compliant):**\n- PKCE with S256 challenge method\n- State parameter for CSRF protection\n- Keychain storage with `kSecAttrAccessibleWhenUnlocked`\n- CryptoKit for cryptographic operations\n\n#### Option 2: Environment Variables (Legacy)\n\n```bash\nexport DROPBOX_APP_KEY=\"your_dropbox_app_key\"\nexport DROPBOX_APP_SECRET=\"your_dropbox_app_secret\"\nexport DROPBOX_ACCESS_TOKEN=\"your_dropbox_access_token\"\n```\n\n**Note**: Manual tokens don't support automatic refreshing. Use OAuth login for production use.\n\n### Logout\n\nClear stored tokens from both Keychain and file storage:\n\n```bash\nmake logout\n# or: swift run dropbook logout\n```\n\n## MCP Server (Recommended)\n\nStart the MCP server:\n\n```bash\nmake mcp\n# or: ./.build/debug/dropbook mcp\n```\n\n### MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_directory` | List files and folders in a Dropbox directory |\n| `search` | Search for files by name or content |\n| `upload` | Upload a file to Dropbox |\n| `download` | Download a file from Dropbox |\n| `delete` | Delete a file or folder (moves to trash) |\n| `get_account_info` | Get account name and email |\n| `read_file` | Read contents of a text file |\n\n#### list_directory\n\nList files and folders in a Dropbox directory.\n\n**Parameters:**\n- `path` (string, optional): Directory path. Default: \"/\"\n\n**Response:**\n```json\n{\n  \"files\": [\n    {\"type\": \"file\", \"name\": \"doc.pdf\", \"path\": \"/Docs/doc.pdf\", \"size\": 1024},\n    {\"type\": \"folder\", \"name\": \"Projects\", \"path\": \"/Projects\"}\n  ]\n}\n```\n\n#### search\n\nSearch for files by name or content.\n\n**Parameters:**\n- `query` (string, required): Search term\n- `path` (string, optional): Path to search within. Default: \"/\"\n\n**Response:**\n```json\n{\n  \"count\": 2,\n  \"results\": [\n    {\"matchType\": \"filename\", \"metadata\": {\"name\": \"report.pdf\", \"path\": \"/Docs/report.pdf\"}}\n  ]\n}\n```\n\n#### upload\n\nUpload a file to Dropbox.\n\n**Parameters:**\n- `localPath` (string, required): Absolute path to local file\n- `remotePath` (string, required): Destination in Dropbox\n- `overwrite` (boolean, optional): Replace if exists. Default: false\n\n**Response:**\n```json\n{\n  \"uploaded\": true,\n  \"name\": \"file.txt\",\n  \"path\": \"/Uploads/file.txt\",\n  \"size\": 5000\n}\n```\n\n#### download\n\nDownload a file from Dropbox.\n\n**Parameters:**\n- `remotePath` (string, required): File path in Dropbox\n- `localPath` (string, required): Local destination path\n\n**Response:**\n```json\n{\n  \"downloaded\": true,\n  \"to\": \"/tmp/report.pdf\"\n}\n```\n\n#### delete\n\nDelete a file or folder from Dropbox (moves to trash).\n\n**Parameters:**\n- `path` (string, required): Path to delete in Dropbox\n\n**Response:**\n```json\n{\n  \"deleted\": true,\n  \"path\": \"/Docs/old-file.pdf\"\n}\n```\n\n#### get_account_info\n\nGet Dropbox account information.\n\n**Parameters:** None\n\n**Response:**\n```json\n{\n  \"name\": \"Ryan Lisse\",\n  \"email\": \"user@example.com\"\n}\n```\n\n#### read_file\n\nRead and return the contents of a text file from Dropbox.\n\n**Parameters:**\n- `path` (string, required): Path to file in Dropbox\n\n**Response:**\nReturns the file contents as text. Only works with UTF-8 encoded text files.\n\n## CLI Commands\n\n```bash\n# Authentication\nmake login                 # OAuth login with Keychain storage\nmake logout                # Clear stored tokens\n\n# File operations\nmake list                  # List root directory\nswift run dropbook list /path\n\n# Search files\nswift run dropbook search \"query\" [path]\n\n# Upload file\nswift run dropbook upload /local/path /remote/path [--overwrite]\n\n# Download file\nswift run dropbook download /remote/path /local/path\n\n# Start MCP server\nmake mcp\n```\n\n## MCP Client Configuration\n\n### Claude Code (Project-level)\n\nThe project includes a `.mcp.json` file that configures the MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"dropbox\": {\n      \"command\": \"/path/to/Dropbook/.build/debug/dropbook\",\n      \"args\": [\"mcp\"],\n      \"env\": {\n        \"DROPBOX_APP_KEY\": \"${DROPBOX_APP_KEY}\",\n        \"DROPBOX_APP_SECRET\": \"${DROPBOX_APP_SECRET}\"\n      }\n    }\n  }\n}\n```\n\nEnable project MCP servers in Claude Code settings.json:\n```json\n{\n  \"enableAllProjectMcpServers\": true\n}\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"dropbox\": {\n      \"command\": \"/path/to/dropbook/.build/debug/dropbook\",\n      \"args\": [\"mcp\"],\n      \"env\": {\n        \"DROPBOX_APP_KEY\": \"${DROPBOX_APP_KEY}\",\n        \"DROPBOX_APP_SECRET\": \"${DROPBOX_APP_SECRET}\"\n      }\n    }\n  }\n}\n```\n\n## Error Handling\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `notConfigured` | Missing env vars | Set DROPBOX_APP_KEY, DROPBOX_APP_SECRET |\n| `invalidArguments` | Missing required params | Check tool parameters |\n| `notFound` | Path doesn't exist | Use `list_directory` to verify paths |\n| `itemNotFound` | No token in Keychain | Run `make login` to authenticate |\n\n## Architecture\n\n```\nDropbook/\n├── Sources/\n│   ├── DropbookCore/           # Business logic (actor-based)\n│   │   ├── Auth/               # Keychain & file token storage\n│   │   ├── Config/             # Configuration management\n│   │   ├── Models/             # Domain models\n│   │   └── Services/           # DropboxService actor\n│   ├── DropbookCLI/            # CLI adapter\n│   │   └── Commands/           # Login, logout, file commands\n│   └── DropbookMCP/            # MCP server\n├── dropbox-skill/              # Skill documentation\n├── Makefile                    # Build automation\n├── .mcp.json                   # MCP server configuration\n└── Package.swift\n```\n\n## Bulk Operations with rclone\n\nFor large-scale operations like backups, syncing, or bulk transfers, use [rclone](https://rclone.org/) - a powerful cloud sync tool with native Dropbox support.\n\n### Install rclone\n\n```bash\nbrew install rclone\n```\n\n### Configure rclone for Dropbox\n\n```bash\n# Interactive setup (opens browser for OAuth)\nrclone authorize dropbox\n\n# Save the token output to config\nmkdir -p ~/.config/rclone\ncat > ~/.config/rclone/rclone.conf << 'EOF'\n[dropbox]\ntype = dropbox\ntoken = {\"access_token\":\"...paste token here...\"}\nEOF\n```\n\n### Backup to Network Drive / Time Capsule\n\n```bash\n# Full backup with progress\nrclone copy dropbox: /Volumes/TimeCapsule/Dropbox-Backup \\\n    --progress \\\n    --transfers 4 \\\n    --checkers 8 \\\n    --retries 10 \\\n    --log-file /tmp/dropbox-backup.log\n\n# Sync (mirror - deletes files not in source)\nrclone sync dropbox: /Volumes/Backup/Dropbox --progress\n\n# Check what would be copied (dry run)\nrclone copy dropbox: /Volumes/Backup --dry-run\n```\n\n### Common rclone Commands\n\n```bash\n# List remote contents\nrclone lsd dropbox:              # List directories\nrclone ls dropbox:               # List all files\nrclone size dropbox:             # Calculate total size\n\n# Copy operations\nrclone copy dropbox:folder /local/path    # Download folder\nrclone copy /local/path dropbox:folder    # Upload folder\n\n# Sync (bidirectional)\nrclone bisync dropbox: /local/path --resync\n\n# Mount as filesystem (macOS - requires macFUSE)\nrclone mount dropbox: /mnt/dropbox --vfs-cache-mode full\n```\n\n### rclone Flags for Reliability\n\n| Flag | Description |\n|------|-------------|\n| `--progress` | Show real-time transfer progress |\n| `--transfers 4` | Number of parallel transfers |\n| `--checkers 8` | Number of parallel checkers |\n| `--retries 10` | Retry failed operations |\n| `--low-level-retries 20` | Retry low-level errors |\n| `--log-file path` | Write logs to file |\n| `--dry-run` | Show what would be done |\n| `--checksum` | Verify with checksums |\n\n### Rate Limiting\n\nDropbox has strict API rate limits. If you see `too_many_requests` errors:\n\n```bash\n# Use bandwidth limiting\nrclone copy dropbox: /backup --bwlimit 1M\n\n# Or add delays between operations\nrclone copy dropbox: /backup --tpslimit 2\n```\n\nrclone handles rate limits automatically with exponential backoff.\n\n## Best Practices\n\n1. **Use OAuth login** - Secure Keychain storage with automatic token refresh\n2. **Use MCP for agents** - More reliable for programmatic access\n3. **Use rclone for bulk ops** - Better for backups and large transfers\n4. **Validate paths first** - Use `list_directory` before operations\n5. **Handle errors gracefully** - Check responses for error fields\n6. **Respect rate limits** - Add delays between bulk operations\n7. **Use absolute paths** - Always provide full paths for file operations\n\n## Security\n\n- **Keychain Storage**: Tokens stored with hardware-backed encryption\n- **PKCE**: Proof Key for Code Exchange prevents authorization code interception\n- **State Parameter**: CSRF protection for OAuth flow\n- **Token Refresh**: Automatic refresh before expiration\n- **CryptoKit**: Modern Swift cryptographic library\n\n## Dependencies\n\n- **SwiftyDropbox** (v10.2.4+): Official Dropbox Swift SDK\n- **MCP (swift-sdk)**: Model Context Protocol SDK\n- **CryptoKit**: Apple's cryptographic framework\n- **rclone** (optional): For bulk operations and backups (`brew install rclone`)\n\n## See Also\n\n- [Dropbook GitHub](https://github.com/RyanLisse/Dropbook)\n- [CLAUDE.md](../CLAUDE.md) - Full project documentation\n- [Dropbox API Docs](https://www.dropbox.com/developers/documentation)\n- [rclone Dropbox Docs](https://rclone.org/dropbox/) - Bulk sync and backup\n- [RFC 7636 - PKCE](https://datatracker.ietf.org/doc/html/rfc7636)\n- [RFC 9700 - OAuth 2.0 Security Best Practices](https://datatracker.ietf.org/doc/html/rfc9700)\n","topics":["Sdk"],"tags":{"latest":"1.0.0"},"stats":{"comments":0,"downloads":3255,"installsAllTime":122,"installsCurrent":12,"stars":0,"versions":1},"createdAt":1768662689302,"updatedAt":1779076395654},"latestVersion":{"version":"1.0.0","createdAt":1768662689302,"changelog":"Initial release: MCP server + CLI for Dropbox file operations","license":null},"metadata":null,"owner":{"handle":"ryanlisse","userId":"s178s3v3th8dpnw8f083act35584pte3","displayName":"Ryan Lisse","image":"https://avatars.githubusercontent.com/u/57917217?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779915505665}}