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/**

有关更多示例和最佳实践，请参阅 路径访问控制文档。