Clipboard To Supabase MCP Helper

🚀 Clipboard to Supabase MCP Helper

このローカルエージェントは、システムのクリップボードを監視し、コピーされた画像をSupabase Storageにアップロードし、公開（または署名付き）のURLをクリップボードに書き戻します。

✨ 主な機能

• ゼロクリックでの画像ホスティング：画像をコピーするとすぐにURLが取得できます
• 低遅延：コピーからURL取得まで800ms以内
• クロスプラットフォーム：macOS、Windows、Linuxで動作します
• MCP統合：クリップボード画像のアップロードをMCPエンドポイントとして公開します
• 自動起動：システム起動時に自動で実行するように設定できます
• 効率的な検出：ハッシュベースの重複排除で、CPU使用率が低く抑えられます

📦 インストール

前提条件

• Node.js 18+
• Storageが有効なSupabaseアカウント
• プラットフォーム固有の依存関係:
  • macOS: pngpaste (brew install pngpaste)
  • Windows/Linux: ネイティブOSのクリップボードアクセス

インストール手順

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

💻 使用例

基本的な使用法

インストールして実行すると、このヘルパーは以下のことを行います：

1. クリップボードの画像変更を監視します（300msごとにポーリング）
2. コピーされた画像をSupabaseのバケットにアップロードします
3. 公開URLをクリップボードに戻し、貼り付け可能な状態にします

サービスの実行

クリップボードヘルパーは2つのモードで実行できます：

Stdioモード（デフォルト）

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. 変更検出：300msごとにクリップボードをポーリングし、画像データのSHA-1ハッシュを計算します
2. 重複排除：ハッシュ比較に基づいて、新しいまたは変更された画像のみを処理します
3. プラットフォーム適応：プラットフォーム固有の方法を使用してクリップボード画像を取得します
4. Supabase統合：画像を一意のUUIDでSupabaseのバケットにアップロードします
5. MCPエンドポイント：Model Context Protocolを介してAIエージェントに機能を公開します
6. 自動クリーンアップ：定期的に設定された保持期間（デフォルト: 30日）より古い画像を削除します

プラットフォーム固有の注意事項

macOS

• pngpasteが必要です：brew install pngpasteでインストールしてください
• LaunchAgentsを使用して自動起動します

Windows

• PowerShellのSystem.Windows.Forms.Clipboardを使用して画像を取得します
• Windowsレジストリを使用して自動起動します

Linux

• xclip (X11) または wl-paste (Wayland) を使用してクリップボードにアクセスします
• systemdを使用して自動起動します

開発

# ライブリロードで実行（stdioモード）
npm run dev

# ライブリロードで実行（HTTPモード）
npm run dev:http

# 本番用にビルド
npm run build

# stdioバージョンを実行
npm start

# HTTPバージョンを実行
npm run start:http

📄 ライセンス

MIT