Cut Copy Paste MCP

🚀 MCP 剪切-複製-粘貼剪貼板服務器

MCP 剪切-複製-粘貼剪貼板服務器是一個基於模型上下文協議（MCP）的服務器，它為 AI 輔助編碼代理提供了類似剪貼板的操作。藉助該服務器，你可以跨文件進行代碼塊的剪切、複製、粘貼和撤銷操作，同時還具備完整的審計跟蹤和會話管理功能。

🚀 快速開始

針對 Claude Code / Claude Desktop 用戶

1. 配置 MCP 服務器：
   • 打開 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）。
   • 或者打開 %APPDATA%\Claude\claude_desktop_config.json（Windows）。
   • 添加以下配置：

{
    "mcpServers": {
        "clipboard": {
            "command": "npx",
            "args": ["cut-copy-paste-mcp"]
        }
    }
}

2. 重啟 Claude Desktop/Code 以加載 MCP 服務器。
3. 驗證工具是否可用：
   • 在對話中，你應該能看到剪貼板工具。
   • 嘗試輸入：“Show me the available clipboard tools”。
4. 開始使用剪貼板：
   • “Copy lines 10 - 25 from src/utils.ts”。
   • “Show me what's in the clipboard”。
   • “Paste the clipboard to line 5 in src/helpers.ts”。

針對其他 MCP 客戶端

1. 安裝服務器（參見下面的“📦 安裝指南”）。
2. 配置你的 MCP 客戶端，使其連接到 cut - copy - paste - mcp。
3. 配置 AI 代理指令（可選但推薦）：
   • 將使用指南從 複製到你的代理指令文件中：
     • Claude Desktop/Code：添加到項目根目錄的 CLAUDE.md 中。
     • Cursor IDE：添加到項目的 .cursorrules 或 AGENTS.md 中。
     • 其他代理：添加到你的代理的自定義規則/指令文件中。
   • 這些指南有助於 AI 理解何時以及如何有效地使用剪貼板操作。
4. 在你的 AI 編碼工作流程中開始使用剪貼板操作。

示例工作流程

你/AI: "I need to refactor the authentication logic.
      Copy lines 45 - 80 from src/auth/old - auth.ts"

AI: [使用 copy_lines 工具]
    ✓ 從 src/auth/old - auth.ts:45 - 80 複製了 36 行

你/AI: "Now paste this into a new file src/auth/token - handler.ts at line 1"

AI: [使用 paste_lines 工具]
    ✓ 粘貼到 src/auth/token - handler.ts:1

你/AI: "Actually, I want to undo that and paste it somewhere else"

AI: [使用 undo_last_paste 工具]
    ✓ 撤銷粘貼操作，恢復了 1 個文件

✨ 主要特性

• 🎯 6 種 MCP 工具：copy_lines、cut_lines、paste_lines、show_clipboard、undo_last_paste、get_operation_history。
• 📋 基於會話的剪貼板：每個會話都維護獨立的剪貼板狀態。
• ↩️ 智能撤銷支持：通過完整的文件快照撤銷粘貼操作，自動恢復被剪切的源文件。
• 📊 審計跟蹤：基於 SQLite 的操作日誌，便於調試。
• 🔐 加密的剪貼板存儲：使用 AES - 256 - GCM 加密有效負載，每個安裝的密鑰存儲在 SQLite 數據庫旁邊。
• 🛡️ 路徑訪問控制：可選的 .gitignore 風格的允許列表，用於限制文件系統訪問（文檔）。
• 🔒 會話管理：自動清理，24 小時超時。
• 🚀 NPX 就緒：通過 npm 輕鬆安裝和更新。
• 🌍 Unicode 支持：全面支持國際字符和表情符號。
• 🛡️ 二進制文件檢測：自動拒絕 PNG、PDF、JPEG、GIF 等二進制格式。
• 📏 靈活的行插入：支持粘貼到第 0 行（文件開頭）。

📦 安裝指南

通過 NPX（推薦）

npx cut - copy - paste - mcp

通過 NPM

npm install -g cut - copy - paste - mcp
cut - copy - paste - mcp

本地開發

git clone https://github.com/Pr0j3c7t0dd - Ltd/cut - copy - paste - mcp.git
cd cut - copy - paste - mcp
npm install
npm run build
node dist/cli.js

💻 使用示例

基礎用法

以下是使用 copy_lines 工具的示例：

{
    "tool": "copy_lines",
    "arguments": {
        "file_path": "src/utils/helpers.ts",
        "start_line": 10,
        "end_line": 25
    }
}

高級用法

以下是使用 paste_lines 工具進行多目標粘貼的示例：

{
    "tool": "paste_lines",
    "arguments": {
        "targets": [
            {
                "file_path": "src/services/auth.ts",
                "target_line": 5
            },
            {
                "file_path": "src/services/api.ts",
                "target_line": 8
            },
            {
                "file_path": "src/services/storage.ts",
                "target_line": 3
            }
        ]
    }
}

📚 詳細文檔

MCP 工具參考

1. copy_lines

將文件中的行復制到會話剪貼板，不修改源文件。 參數：

• file_path（字符串，必需）：源文件路徑。
• start_line（數字，必需）：起始行號（從 1 開始索引）。
• end_line（數字，必需）：結束行號（包含）。 示例：

{
    "tool": "copy_lines",
    "arguments": {
        "file_path": "src/utils/helpers.ts",
        "start_line": 10,
        "end_line": 25
    }
}

返回值：

{
    "success": true,
    "content": "...",
    "lines": ["..."],
    "message": "從 src/utils/helpers.ts:10 - 25 複製了 16 行"
}

2. cut_lines

從文件中剪切行（從源文件中移除，保存到剪貼板）。 參數：

• file_path（字符串，必需）：源文件路徑。
• start_line（數字，必需）：起始行號（從 1 開始索引）。
• end_line（數字，必需）：結束行號（包含）。 示例：

{
    "tool": "cut_lines",
    "arguments": {
        "file_path": "src/legacy/old - module.ts",
        "start_line": 50,
        "end_line": 75
    }
}

返回值：

{
    "success": true,
    "content": "...",
    "lines": ["..."],
    "message": "從 src/legacy/old - module.ts:50 - 75 剪切了 26 行"
}

3. paste_lines

將剪貼板內容粘貼到一個或多個位置。 參數：

• targets（數組，必需）：粘貼目標數組。
  • file_path（字符串）：目標文件路徑。
  • target_line（數字）：粘貼的行號（從 1 開始索引）。 示例（單目標）：

{
    "tool": "paste_lines",
    "arguments": {
        "targets": [
            {
                "file_path": "src/components/NewComponent.tsx",
                "target_line": 20
            }
        ]
    }
}

示例（多目標）：

{
    "tool": "paste_lines",
    "arguments": {
        "targets": [
            {
                "file_path": "src/services/auth.ts",
                "target_line": 5
            },
            {
                "file_path": "src/services/api.ts",
                "target_line": 8
            },
            {
                "file_path": "src/services/storage.ts",
                "target_line": 3
            }
        ]
    }
}

返回值：

{
    "success": true,
    "pastedTo": [
        { "file": "src/components/NewComponent.tsx", "line": 20 }
    ],
    "message": "粘貼到 1 個位置"
}

4. show_clipboard

顯示當前剪貼板內容及其元數據。 參數：無 示例：

{
    "tool": "show_clipboard",
    "arguments": {}
}

返回值：

{
    "hasContent": true,
    "content": "...",
    "sourceFile": "src/utils/helpers.ts",
    "startLine": 10,
    "endLine": 25,
    "operationType": "copy",
    "copiedAt": 1699564800000
}

5. undo_last_paste

撤銷最近的粘貼操作。如果粘貼來自剪切操作，則粘貼目標和剪切源都將恢復到原始狀態。 參數：無 示例：

{
    "tool": "undo_last_paste",
    "arguments": {}
}

返回值：

{
    "success": true,
    "restoredFiles": [
        { "file": "src/components/NewComponent.tsx", "line": 20 },
        { "file": "src/legacy/old - module.ts", "line": 0 }
    ],
    "message": "撤銷粘貼操作，恢復了 2 個文件"
}

行為：

• 複製 → 粘貼 → 撤銷：僅恢復粘貼目標文件。
• 剪切 → 粘貼 → 撤銷：恢復粘貼目標和剪切源文件。

6. get_operation_history

檢索操作歷史記錄，用於調試。 參數：

• limit（數字，可選）：返回的最大操作數（默認：10）。 示例：

{
    "tool": "get_operation_history",
    "arguments": {
        "limit": 5
    }
}

返回值：

{
    "operations": [
        {
            "operationId": 42,
            "operationType": "paste",
            "timestamp": 1699564800000,
            "details": {
                "targetFile": "src/components/NewComponent.tsx",
                "targetLine": 20
            }
        }
    ]
}

使用模式

模式 1：重構 - 提取函數

1. 確定要提取的代碼 → 分析文件並找到要移動的行
2. 剪切代碼 → 使用 cut_lines 從原始位置移除
3. 驗證剪貼板 → 使用 show_clipboard 確認內容
4. 粘貼到新位置 → 使用 paste_lines 插入到新位置
5. 驗證結果 → 檢查兩個文件的正確性

模式 2：複製樣板代碼

1. 找到源代碼 → 確定可重用的代碼模式
2. 複製模式 → 使用 copy_lines 捕獲樣板代碼
3. 確定目標 → 列出所有需要此模式的文件
4. 多目標粘貼 → 使用 paste_lines 進行多目標粘貼
5. 驗證 → 抽查粘貼的內容

模式 3：在文件之間移動代碼

1. 從源文件剪切 → 使用 cut_lines 移除代碼
2. 粘貼到目標文件 → 使用 paste_lines 插入
3. 驗證兩個文件 → 檢查源文件是否清理乾淨
4. 更新引用 → 如果需要，修復導入

模式 4：安全實驗

1. 複製代碼進行測試 → 使用 copy_lines 捕獲當前狀態
2. 粘貼到測試位置 → 創建實驗版本
3. 測試更改 → 進行修改
4. 決策 → 如果不成功，使用 undo_last_paste

模式 5：撤銷剪切操作

1. 從源文件剪切代碼 → 使用 cut_lines（從源文件移除）
2. 粘貼到目標文件 → 使用 paste_lines（添加到目標文件）
3. 意識到錯誤 → 決定撤銷移動
4. 撤銷粘貼操作 → 使用 undo_last_paste
5. 結果 → 源文件和目標文件都恢復到原始狀態

注意：當你撤銷從剪切操作進行的粘貼時，服務器會自動恢復兩個文件，即粘貼目標會被恢復，剪切源文件也會恢復被移除的行。

🔧 技術細節

工作原理

功能概述

可以將其視為 AI 助手（如 Claude）可以使用的 智能代碼剪貼板。它不是複製整個文件，而是可以：

• 從文件中複製特定的行（如第 10 - 25 行）。
• 剪切行（從原始文件中移除）。
• 將這些行粘貼到一個或多個文件中。
• 如果出錯可以撤銷操作。

通信層

• 使用 MCP（模型上下文協議），這是 AI 助手與工具進行通信的標準化方式。
• 使用 stdio（標準輸入/輸出），AI 發送 JSON 消息並接收 JSON 響應。
• 庫：@modelcontextprotocol/sdk（官方 MCP 工具包）。

存儲系統

當你複製或剪切內容時，需要將其存儲在某個地方：

• 使用 SQLite 數據庫（一個簡單的基於文件的數據庫）。
• 庫：better - sqlite3（適用於 Node.js 的快速、可靠的 SQLite 庫）。
• 存儲內容包括：
  • 你複製的內容（實際代碼）。
  • 它的來源（文件路徑、行號）。
  • 會話信息（確保多個 AI 不會相互干擾）。
  • 用於撤銷功能的歷史記錄。

文件操作

所有實際的文件讀寫操作使用：

• Node.js 內置的 fs 模塊（文件系統操作）。
• 基本的文件讀寫不需要外部庫！
• 代碼：
  • 逐行讀取文件。
  • 插入或刪除特定的行範圍。
  • 保留行尾格式（Windows 與 Unix 風格）。

操作流程示例

複製操作：

1. AI 說：“Copy lines 10 - 20 from myfile.js”
2. 服務器使用 Node 的 fs.readFileSync() 讀取文件
3. 從文件中提取第 10 - 20 行
4. 將它們保存到 SQLite 數據庫（你的“剪貼板”）
5. 將複製的文本返回給 AI

粘貼操作：

1. AI 說：“Paste to line 5 in otherfile.js”
2. 服務器從 SQLite 數據庫中檢索剪貼板內容
3. 對目標文件進行快照（以便稍後撤銷）
4. 讀取文件，在第 5 行插入行
5. 使用 fs.writeFileSync() 將修改後的文件寫回
6. 將撤銷信息保存到數據庫

撤銷操作：

1. AI 說：“Undo that paste”
2. 服務器在數據庫中查找最後一次粘貼操作
3. 找到粘貼前保存的快照
4. 將文件恢復到原始狀態
5. 如果是“剪切”操作，還會恢復源文件！

關鍵庫

巧妙之處

1. 會話隔離：每個 AI 助手都有自己的剪貼板，不會相互干擾。
2. 完整快照：在粘貼之前，保存整個文件，使撤銷操作非常可靠。
3. 逐行處理：使用行號（如“第 10 - 20 行”）進行操作，符合開發者對代碼的思考方式。
4. 二進制檢測：拒絕處理圖像/PDF 文件，僅處理文本文件。

獨特之處

與普通剪貼板不同：

• ✅ 記住代碼的來源。
• ✅ 可以同時粘貼到多個文件。
• ✅ 具有可靠的撤銷功能（即使是剪切操作）。
• ✅ 跨文件和項目工作。
• ✅ 保留所有操作的歷史記錄。

從本質上講，它是一個複雜的剪貼板，使用 AI 的語言（MCP），使用數據庫（SQLite）來記住所有內容，並使用基本的 Node.js 工具進行所有文件讀寫操作。其神奇之處在於如何協調這些部分，為 AI 編碼助手提供可靠的剪切/複製/粘貼/撤銷操作！

架構

核心組件

1. MCP 服務器：處理協議通信和工具註冊。
2. 會話管理器：管理會話狀態和剪貼板緩衝區。
3. 文件處理程序：支持按行號進行文件讀寫操作。
4. 操作記錄器：基於 SQLite 的操作歷史記錄，用於撤銷功能。
5. 剪貼板管理器：管理每個會話的剪貼板緩衝區。

數據庫架構

服務器使用 SQLite，有 4 個主要表：

• sessions：會話跟蹤，包含活動時間戳。
• clipboard_buffer：每個會話的剪貼板狀態。
• operations_log：所有操作的審計跟蹤。
• paste_history：支持撤銷功能。

數據目錄

默認情況下，數據庫存儲在：

• macOS/Linux：~/.mcp - clipboard/clipboard.db。
• Windows：%USERPROFILE%\.mcp - clipboard\clipboard.db。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

配置

Claude Desktop / Claude Code

添加到你的 MCP 配置文件中： macOS/Linux：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "clipboard": {
            "command": "npx",
            "args": ["cut - copy - paste - mcp"]
        }
    }
}

對於本地開發（尚未發佈到 npm）：

{
    "mcpServers": {
        "clipboard": {
            "command": "node",
            "args": ["/absolute/path/to/cut - copy - paste - mcp/dist/cli.js"]
        }
    }
}

Cursor IDE

添加到你的 Cursor MCP 設置文件中： macOS/Linux：~/.cursor/mcp_config.json Windows：%USERPROFILE%\.cursor\mcp_config.json

{
    "mcpServers": {
        "clipboard": {
            "command": "npx",
            "args": ["cut - copy - paste - mcp"]
        }
    }
}

Cline（VS Code 擴展）

添加到你的 Cline MCP 設置中：

1. 打開 VS Code 設置。
2. 搜索 “Cline: MCP Settings”。
3. 添加以下配置：

{
    "mcpServers": {
        "clipboard": {
            "command": "npx",
            "args": ["cut - copy - paste - mcp"]
        }
    }
}

會話超時

會話在 24 小時不活動後自動過期。過期會話在服務器啟動時清理。

AI 代理配置

為了幫助你的 AI 編碼助手有效地使用這個 MCP 服務器，你可以為它提供使用指南和最佳實踐。

設置代理指令

文件包含了 AI 代理的全面指南，包括：

• 詳細的工具文檔和用例。
• 常見重構任務的工作流模式。
• 剪貼板操作的最佳實踐。
• 錯誤處理指南。

如何配置你的代理：

1. Claude Desktop / Claude Code 用戶：
   • 在項目根目錄創建或編輯 CLAUDE.md。
   • 將 docs/AGENTIC_USAGE.md 的內容複製到這個文件中。
   • Claude 在處理你的項目時將自動使用這些指令。
2. Cursor IDE 用戶：
   • 在項目根目錄創建或編輯 .cursorrules 或 AGENTS.md。
   • 將 docs/AGENTIC_USAGE.md 的內容複製到這個文件中。
   • Cursor 將使用這些指南進行 AI 交互。
3. 其他 MCP 客戶端：
   • 查閱你的客戶端文檔，瞭解自定義指令/規則文件的位置。
   • 將 docs/AGENTIC_USAGE.md 的內容添加到相應的配置中。

配置後的效果

配置這些指令後，你的 AI 助手將：

• 知道何時使用剪貼板操作，何時使用原生文件編輯。
• 遵循既定的重構工作流模式。
• 在粘貼前驗證剪貼板內容。
• 使用多目標粘貼來分發樣板代碼。
• 優雅地處理錯誤。

示例：當你要求 “Refactor the authentication logic into a separate module” 時，AI 將知道：

1. 使用 cut_lines 提取代碼。
2. 使用 show_clipboard 驗證捕獲的內容。
3. 使用 paste_lines 將其插入到新位置。
4. 如果結果不正確，提供 undo_last_paste 選項。

最佳實踐

1. ✅ 始終驗證剪貼板：在粘貼操作前使用 show_clipboard。
2. ✅ 對模式使用多目標粘貼：高效地將相同代碼應用到多個文件。
3. ✅ 利用撤銷功能：不要猶豫進行粘貼操作，隨時可以撤銷。
4. ✅ 檢查操作歷史記錄：使用 get_operation_history 調試問題。
5. ✅ 注意行號：記住行號是從 1 開始索引的。
6. ✅ 完成操作序列：在開始新操作之前，完成複製/剪切/粘貼/撤銷操作。

錯誤處理

服務器為常見問題提供清晰的錯誤消息：

• ❌ 文件未找到：“Copy failed: ENOENT: no such file or directory”
• ❌ 無效的行範圍：“Invalid line range: start_line must be <= end_line”
• ❌ 剪貼板為空：“Clipboard is empty”
• ❌ 沒有可撤銷的粘貼操作：“No paste operation to undo”

開發

運行測試

# 運行所有測試
npm test

# 在監視模式下運行測試
npm test -- --watch

# 運行特定的測試文件
npm test -- src/__tests__/server.test.ts

# 運行帶覆蓋率的測試
npm test:coverage

構建

# 編譯 TypeScript
npm run build

# 代碼檢查
npm run lint

# 代碼格式化
npm run format

項目結構

src/
├── lib/
│   ├── database.ts              # SQLite 初始化
│   ├── session - manager.ts       # 會話生命週期
│   ├── file - handler.ts          # 文件操作
│   ├── clipboard - manager.ts     # 剪貼板緩衝區
│   └── operation - logger.ts      # 審計跟蹤
├── tools/
│   └── clipboard - tools.ts       # 6 種 MCP 工具實現
├── config/
│   └── tools.ts                 # 工具定義
├── server.ts                    # MCP 服務器
├── cli.ts                       # CLI 入口點
└── __tests__/                   # 測試文件

測試

項目遵循嚴格的測試驅動開發（TDD）原則：

• 213 個通過的測試，分佈在 12 個測試套件中。
• 代碼覆蓋率目標超過 90%。
• 對所有核心組件進行 單元測試。
• 對完整工作流進行 集成測試。
• 對二進制文件、Unicode、大文件等進行 邊界情況測試。
• 對剪切 - 粘貼 - 撤銷工作流進行 專門測試。

設計決策

1. ✅ 使用 SQLite 而非 JSON 文件：提供 ACID 保證，更易於查詢。
2. ✅ 使用 stdio 傳輸：更適合本地開發，對於 MCP 足夠。
3. ✅ 行號從 1 開始索引：符合編輯器約定。
4. ✅ 單級撤銷：在 v1 版本中保持複雜度可控。
5. ✅ 複製/剪切時返回內容：為大語言模型提供即時反饋。

侷限性

• 📝 僅支持文本文件：拒絕二進制文件。
• 📝 單級撤銷：只能撤銷最後一次粘貼操作。
• 📝 剪貼板最大限制為 10MB：最大剪貼板內容大小。
• 📝 僅支持 stdio 傳輸：計劃在 v2 版本中支持 HTTP 傳輸。

路線圖

v1.0（當前版本）

• ✅ 核心剪貼板操作
• ✅ 會話管理
• ✅ 撤銷支持
• ✅ 操作歷史記錄

v2.0（計劃版本）

• 🔮 支持 HTTP 傳輸
• 🔮 多級撤銷棧
• 🔮 大文件優化（流式處理）
• 🔮 認證支持

貢獻

歡迎貢獻代碼！請按照以下步驟進行：

1. 分叉倉庫。
2. 創建功能分支（git checkout -b feature/amazing - feature）。
3. 按照 TDD 原則編寫測試（紅 → 綠 → 重構）。
4. 提交更改（git commit -m 'Add amazing feature'）。
5. 推送到分支（git push origin feature/amazing - feature）。
6. 打開拉取請求。

安全

• ✅ 路徑訪問控制：可選的允許列表，用於限制文件系統操作（詳情）。
• ✅ 加密存儲：使用 AES - 256 - GCM 對靜止的剪貼板數據進行加密。
• ✅ 路徑驗證：防止目錄遍歷攻擊。
• ✅ 輸入清理：在操作前驗證所有輸入。
• ✅ 錯誤信息中不包含敏感數據：錯誤消息不會洩露文件內容。
• ✅ 文件大小限制：最大剪貼板大小為 10MB。

有關詳細的安全信息，請參閱 路徑訪問控制文檔。

支持

• 📖 [文檔](https://github.com/Pr0j3c7t0dd - Ltd/cut - copy - paste - mcp)
• 🐛 [問題跟蹤](https://github.com/Pr0j3c7t0dd - Ltd/cut - copy - paste - mcp/issues)
• 💬 [討論](https://github.com/Pr0j3c7t0dd - Ltd/cut - copy - paste - mcp/discussions)

致謝

• 基於 模型上下文協議 SDK 構建。
• 受現代代碼編輯器中的剪貼板操作啟發。
• 受 Kix Panganiban 的文章 ["Two things LLM coding agents are still bad at"](https://kix.dev/two - things - llm - coding - agents - are - still - bad - at/) 啟發，該文章強調了 AI 編碼工作流中對適當的剪切/複製/粘貼工具的需求。
• 使用嚴格的 TDD 原則開發。

為 AI 輔助編碼工作流精心打造 ❤️

安全考慮

• 加密存儲：剪貼板條目在靜止時使用 AES - 256 - GCM 加密，使用 32 字節的密鑰存儲在 ~/.mcp - clipboard/clipboard.key（或任何自定義 --db - path 旁邊）。
• 密鑰管理：服務器首次運行時自動創建密鑰；通過替換文件並清除陳舊會話來輪換密鑰。
• 文件權限：服務器對剪貼板目錄和數據庫/密鑰文件強制執行 700/600 權限；如果重新定位這些文件，請驗證權限是否仍然完整。
• 路徑訪問控制：默認情況下，服務器可以訪問所有文件系統路徑。要限制訪問，請創建 ~/.mcp - clipboard/paths.allow，幷包含允許的路徑模式。有關配置示例，請參閱 路徑訪問控制文檔。
• 數據庫位置：在未來版本中，你可以通過 DatabaseManager 構造函數或 CLI 標誌覆蓋數據庫位置（以及密鑰位置）。

受限訪問的快速設置

要將服務器限制為僅訪問當前項目，請創建 ~/.mcp - clipboard/paths.allow：

# 僅允許你的項目目錄
/Users/username/my - project/**

# 排除常見目錄
!**/node_modules/**
!**/.git/**

有關更多示例和最佳實踐，請參閱 路徑訪問控制文檔。