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. 如果是“剪切”操作，还会恢复源文件！

关键库

库	用途	功能
@modelcontextprotocol/sdk	MCP 协议	处理与 AI 助手的通信
better - sqlite3	数据库	存储剪贴板、历史记录和撤销信息
fs（内置）	文件系统	读写文件
TypeScript	语言	类型安全的 JavaScript（编译为常规 JavaScript）

巧妙之处

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

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