Clipboard To Supabase MCP Helper

🚀 剪貼板到Supabase MCP助手

這是一個本地代理工具，它會監控系統剪貼板，將複製的任何圖像上傳到Supabase存儲，然後把公共（或帶簽名）的URL寫回到剪貼板。

🚀 快速開始

本工具安裝運行後，將執行以下操作：

1. 監控剪貼板的圖像變化（每300毫秒輪詢一次）。
2. 將複製的圖像上傳到你的Supabase存儲桶。
3. 將公共URL放回剪貼板，以便隨時粘貼。

✨ 主要特性

• 零點擊圖像託管：複製圖像，立即獲得URL。
• 低延遲：從複製到獲取URL，耗時低於800毫秒。
• 跨平臺：支持macOS、Windows和Linux系統。
• MCP集成：將剪貼板圖像上傳功能作為MCP端點暴露。
• 自動啟動：可配置為系統啟動時自動運行。
• 高效檢測：基於哈希的去重機制，CPU使用率低。

📦 安裝指南

前提條件

• Node.js 18+
• 啟用了存儲功能的Supabase賬戶
• 特定平臺依賴：
  • macOS：pngpaste（使用brew install pngpaste安裝）
  • Windows/Linux：具備原生操作系統剪貼板訪問權限

安裝步驟

1. 克隆倉庫：

git clone https://github.com/martinbowling/clipboard-to-supabase-mcp-helper.git
cd clipboard-to-supabase-mcp-helper

2. 安裝依賴：

npm install

3. 根據.env.example創建.env文件：

SUPABASE_URL=https://<project>.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
BUCKET=media
MCP_PORT=3333

4. 測試Supabase連接：

npm run test:supabase

5. 構建項目：

npm run build

6. 作為系統服務安裝：

• macOS：

npm run install:macos

• Linux：

npm run install:linux

• Windows：

npm run install:windows

💻 使用示例

運行服務

剪貼板助手可以在兩種模式下運行：

標準輸入輸出模式（默認）

npm start

此模式使用StdioServerTransport運行MCP服務器，適合命令行使用。

HTTP模式

npm run start:http

此模式在端口3333（可配置）上運行一個Express HTTP服務器，並提供一個合適的REST API端點。

MCP集成

該助手提供以下MCP端點：

上傳剪貼板圖像

在HTTP服務器模式下：

POST http://localhost:3333/mcp

請求體：

{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "tool",
  "params": {
    "name": "upload_clipboard_image",
    "input": {}
  }
}

響應：

{
  "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"
      }
    ]
  }
}

清理舊文件

該助手還提供一個MCP端點，用於手動觸發清理舊文件操作。 請求體：

{
  "id": "1",
  "jsonrpc": "2.0",
  "method": "tool",
  "params": {
    "name": "cleanup_old_files",
    "input": {
      "days": 30
    }
  }
}

響應：

{
  "id": "1",
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Cleanup completed: Deleted 5 files older than 30 days. Failed: 0."
      }
    ]
  }
}

days參數是可選的。如果未提供，將使用RETENTION_DAYS環境變量中的值。

🔧 技術細節

1. 變化檢測：每300毫秒輪詢一次剪貼板，並計算圖像數據的SHA - 1哈希值。
2. 去重處理：根據哈希比較結果，僅處理新的或有變化的圖像。
3. 平臺適配：使用特定平臺的方法來捕獲剪貼板圖像。
4. Supabase集成：將圖像以唯一的UUID上傳到你的Supabase存儲桶。
5. MCP端點：通過模型上下文協議將功能暴露給AI代理。
6. 自動清理：定期刪除超過配置保留期（默認：30天）的圖像。

📚 詳細文檔

特定平臺注意事項

macOS

• 需要pngpaste：使用brew install pngpaste進行安裝。
• 使用LaunchAgents實現自動啟動。

Windows

• 使用PowerShell的System.Windows.Forms.Clipboard進行圖像捕獲。
• 使用Windows註冊表實現自動啟動。

Linux

• 使用xclip（X11）或wl - paste（Wayland）進行剪貼板訪問。
• 使用systemd實現自動啟動。

開發相關

# 以實時重新加載模式運行（標準輸入輸出模式）
npm run dev

# 以實時重新加載模式運行（HTTP模式）
npm run dev:http

# 為生產環境構建
npm run build

# 運行標準輸入輸出版本
npm start

# 運行HTTP版本
npm run start:http

📄 許可證

本項目採用MIT許可證。