Clipboard to Supabase MCP Helper

# Clipboard to Supabase MCP Helper A local agent that monitors the system clipboard, uploads any copied image to Supabase Storage, then writes the public (or signed) URL back to the clipboard. ## Features - Zero-click image hosting: Copy an image, get a URL instantly - Low latency: Under 800ms from copy to URL - Cross-platform: Works on macOS, Windows, and Linux - MCP integration: Expose clipboard image upload as an MCP endpoint - Auto-start: Configure to run at system startup - Efficient detection: Hash-based deduplication with low CPU usage ## Prerequisites - Node.js 18+ - Supabase account with Storage enabled - Platform-specific dependencies: - macOS: `pngpaste` (`brew install pngpaste`) - Windows/Linux: Native OS clipboard access ## Installation 1. Clone the repository: ```bash git clone https://github.com/martinbowling/clipboard-to-supabase-mcp-helper.git cd clipboard-to-supabase-mcp-helper ``` 2. Install dependencies: ```bash npm install ``` 3. Create a `.env` file based on `.env.example`: ``` SUPABASE_URL=https://<project>.supabase.co SUPABASE_SERVICE_ROLE_KEY=your-service-role-key BUCKET=media MCP_PORT=3333 ``` 4. Test your Supabase connection: ```bash npm run test:supabase ``` 5. Build the project: ```bash npm run build ``` 6. Install as a system service: For macOS: ```bash npm run install:macos ``` For Linux: ```bash npm run install:linux ``` For Windows: ```bash npm run install:windows ``` ## Usage Once installed and running, the helper will: 1. Monitor your clipboard for image changes (polling every 300ms) 2. Upload any copied images to your Supabase bucket 3. Place the public URL back in your clipboard, ready to paste ### Running the Service The clipboard helper can be run in two modes: #### Stdio Mode (Default) ```bash npm start ``` This runs the MCP server with StdioServerTransport, ideal for command-line usage. #### HTTP Mode ```bash npm run start:http ``` This runs an Express HTTP server on port 3333 (configurable) with a proper REST API endpoint. ### MCP Integration The helper exposes the following MCP endpoints: #### Upload Clipboard Image With HTTP server mode: ``` POST http://localhost:3333/mcp ``` Request body: ```json { "id": "1", "jsonrpc": "2.0", "method": "tool", "params": { "name": "upload_clipboard_image", "input": {} } } ``` Response: ```json { "id": "1", "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "https://your-project.supabase.co/storage/v1/object/public/media/clips/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.png" } ] } } ``` #### Cleanup Old Files The helper also provides an MCP endpoint to manually trigger cleanup of old files. Request body: ```json { "id": "1", "jsonrpc": "2.0", "method": "tool", "params": { "name": "cleanup_old_files", "input": { "days": 30 } } } ``` Response: ```json { "id": "1", "jsonrpc": "2.0", "result": { "content": [ { "type": "text", "text": "Cleanup completed: Deleted 5 files older than 30 days. Failed: 0." } ] } } ``` The `days` parameter is optional. If not provided, it will use the value from the `RETENTION_DAYS` environment variable. ## How It Works 1. **Change Detection**: Polls clipboard every 300ms and computes SHA-1 hash of image data 2. **Deduplication**: Only processes new or changed images based on hash comparison 3. **Platform Adaptation**: Uses platform-specific methods to capture clipboard images 4. **Supabase Integration**: Uploads images to your Supabase bucket with unique UUIDs 5. **MCP Endpoint**: Exposes functionality to AI agents via Model Context Protocol 6. **Automatic Cleanup**: Periodically removes images older than the configured retention period (default: 30 days) ## Platform-Specific Notes ### macOS - Requires `pngpaste`: Install with `brew install pngpaste` - Uses LaunchAgents for auto-start ### Windows - Uses PowerShell's System.Windows.Forms.Clipboard for image capture - Uses Windows Registry for auto-start ### Linux - Uses xclip (X11) or wl-paste (Wayland) for clipboard access - Uses systemd for auto-start ## Development ```bash # Run with live reload (stdio mode) npm run dev # Run with live reload (HTTP mode) npm run dev:http # Build for production npm run build # Run stdio version npm start # Run HTTP version npm run start:http ``` ## License MIT