Clipboard To Supabase MCP Helper

🚀 剪贴板到Supabase MCP助手

这是一个本地代理工具，它会监控系统剪贴板，将复制的任何图像上传到Supabase存储，然后把公共（或签名）URL写回到剪贴板。

🚀 快速开始

本工具能自动监控剪贴板中的图像变化，将复制的图像上传到你的Supabase存储桶，并把公共URL放回剪贴板，方便你随时粘贴。

✨ 主要特性

• 零点击图像托管：复制图像，立即获取URL
• 低延迟：从复制到获取URL的时间低于800ms
• 跨平台：支持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

💻 使用示例

基础用法

安装并运行后，该工具会执行以下操作：

1. 每300ms轮询一次剪贴板，监控图像变化。
2. 将复制的任何图像上传到你的Supabase存储桶。
3. 把公共URL放回剪贴板，以便粘贴。

服务运行模式

剪贴板助手可以在两种模式下运行：

标准输入输出模式（默认）

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端点：通过模型上下文协议向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许可证。