MCP Cut-Copy-Paste Clipboard Server

A Model Context Protocol (MCP) server that provides clipboard-style operations for AI-assisted coding agents. Cut, copy, paste, and undo code blocks across files with full audit trail and session management.

Features

• 🎯 6 MCP Tools: copy_lines, cut_lines, paste_lines, show_clipboard, undo_last_paste, get_operation_history
• 📋 Session-Based Clipboard: Each session maintains independent clipboard state
• ↩️ Smart Undo Support: Revert paste operations with complete file snapshots - automatically restores cut source files
• 📊 Audit Trail: SQLite-based operation logging for debugging
• 🔐 Encrypted Clipboard Storage: AES-256-GCM encrypted payloads with per-installation keys stored beside the SQLite DB
• 🛡️ Path Access Control: Optional .gitignore-style allowlist to restrict filesystem access (docs)
• 🔒 Session Management: Automatic cleanup with 24-hour timeout
• 🚀 NPX Ready: Easy installation and updates via npm
• 🌍 Unicode Support: Full support for international characters and emoji
• 🛡️ Binary File Detection: Automatically rejects PNG, PDF, JPEG, GIF, and other binary formats
• 📏 Flexible Line Insertion: Supports paste at line 0 (beginning of file)

Installation

Via NPX (Recommended)

npx cut-copy-paste-mcp

Via NPM

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

Local Development

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

Quick Start

For Claude Code / Claude Desktop Users

1. Configure the MCP server:

   • Open ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
   • Or %APPDATA%\Claude\claude_desktop_config.json (Windows)
   • Add the configuration:

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

2. Restart Claude Desktop/Code to load the MCP server

3. Verify the tools are available:

   • In your conversation, you should see clipboard tools available
   • Try: "Show me the available clipboard tools"

4. Start using the clipboard:

   • "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"

For Other MCP Clients

1. Install the server (see Installation above)
2. Configure your MCP client to connect to cut-copy-paste-mcp
3. Configure AI agent instructions (optional but recommended):
   • Copy the usage guidelines from docs/AGENTIC_USAGE.md into your agent's instruction files:
     • Claude Desktop/Code: Add to CLAUDE.md in your project root
     • Cursor IDE: Add to .cursorrules or AGENTS.md in your project
     • Other agents: Add to your agent's custom rules/instructions file
   • These guidelines help the AI understand when and how to use clipboard operations effectively
4. Start using clipboard operations in your AI coding workflow

Example Workflow

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

AI: [Uses copy_lines tool]
    ✓ Copied 36 lines from src/auth/old-auth.ts:45-80

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

AI: [Uses paste_lines tool]
    ✓ Pasted to src/auth/token-handler.ts:1

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

AI: [Uses undo_last_paste tool]
    ✓ Undone paste operation, restored 1 file(s)

MCP Tools Reference

1. copy_lines

Copy lines from a file to session clipboard without modifying the source.

Parameters:

• file_path (string, required): Path to source file
• start_line (number, required): Starting line number (1-indexed)
• end_line (number, required): Ending line number (inclusive)

Example:

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

Returns:

{
  "success": true,
  "content": "...",
  "lines": ["..."],
  "message": "Copied 16 line(s) from src/utils/helpers.ts:10-25"
}

2. cut_lines

Cut lines from a file (removes from source, saves to clipboard).

Parameters:

• file_path (string, required): Path to source file
• start_line (number, required): Starting line number (1-indexed)
• end_line (number, required): Ending line number (inclusive)

Example:

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

Returns:

{
  "success": true,
  "content": "...",
  "lines": ["..."],
  "message": "Cut 26 line(s) from src/legacy/old-module.ts:50-75"
}

3. paste_lines

Paste clipboard content to one or more locations.

Parameters:

• targets (array, required): Array of paste targets
  • file_path (string): Target file path
  • target_line (number): Line number to paste at (1-indexed)

Example (single target):

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

Example (multiple targets):

{
  "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
      }
    ]
  }
}

Returns:

{
  "success": true,
  "pastedTo": [
    { "file": "src/components/NewComponent.tsx", "line": 20 }
  ],
  "message": "Pasted to 1 location(s)"
}

4. show_clipboard

Display current clipboard contents with metadata.

Parameters: None

Example:

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

Returns:

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

5. undo_last_paste

Undo the most recent paste operation. If the paste came from a cut operation, both the paste target(s) AND the cut source are restored to their original state.

Parameters: None

Example:

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

Returns:

{
  "success": true,
  "restoredFiles": [
    { "file": "src/components/NewComponent.tsx", "line": 20 },
    { "file": "src/legacy/old-module.ts", "line": 0 }
  ],
  "message": "Undone paste operation, restored 2 file(s)"
}

Behavior:

• Copy → Paste → Undo: Restores only the paste target file(s)
• Cut → Paste → Undo: Restores both the paste target(s) AND the cut source file

6. get_operation_history

Retrieve operation history for debugging.

Parameters:

• limit (number, optional): Max number of operations to return (default: 10)

Example:

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

Returns:

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

Usage Patterns

Pattern 1: Refactoring - Extract Function

1. Identify code to extract → Analyze file and find lines to move
2. Cut the code           → Use cut_lines to remove from original location
3. Verify clipboard       → Use show_clipboard to confirm content
4. Paste to new location  → Use paste_lines to insert at new location
5. Verify result          → Check both files for correctness

Pattern 2: Copying Boilerplate

1. Find source code       → Identify reusable code pattern
2. Copy the pattern       → Use copy_lines to capture boilerplate
3. Identify targets       → List all files needing this pattern
4. Multi-paste           → Use paste_lines with multiple targets
5. Verify                → Spot-check pasted content

Pattern 3: Moving Code Between Files

1. Cut from source       → Use cut_lines to remove code
2. Paste to destination  → Use paste_lines to insert
3. Verify both files     → Check source is cleaned up
4. Update references     → Fix imports if needed

Pattern 4: Safe Experimentation

1. Copy code for testing → Use copy_lines to capture current state
2. Paste to test location → Create experimental version
3. Test changes          → Make modifications
4. Decide                → Use undo_last_paste if unsuccessful

Pattern 5: Undoing Cut Operations

1. Cut code from source     → Use cut_lines (removes from source)
2. Paste to destination     → Use paste_lines (adds to destination)
3. Realize mistake          → Decide to revert the move
4. Undo paste operation     → Use undo_last_paste
5. Result                   → Both source AND destination restored to original state

Note: When you undo a paste from a cut operation, the server automatically restores BOTH files - the paste target(s) are restored, and the cut source is restored with the lines that were removed.

How It Works

What It Does

Think of this as a smart clipboard for code that AI assistants (like Claude) can use. Instead of copying entire files, it can:

• Copy specific lines from a file (like lines 10-25)
• Cut lines (remove them from the original file)
• Paste those lines to one or multiple files
• Undo if you made a mistake

The Communication Layer

• Uses the MCP (Model Context Protocol) - a standardized way for AI assistants to talk to tools
• Uses stdio (standard input/output) - the AI sends JSON messages and gets JSON responses back
• Library: @modelcontextprotocol/sdk (the official MCP toolkit)

The Storage System

When you copy or cut something, it needs to be stored somewhere:

• Uses SQLite database (a simple file-based database)
• Library: better-sqlite3 (fast, reliable SQLite library for Node.js)
• Stores:
  • What you copied (the actual code)
  • Where it came from (file path, line numbers)
  • Session info (so multiple AIs don't interfere with each other)
  • History for undo functionality

The File Operations

All the actual reading and writing of files uses:

• Node.js built-in fs module (filesystem operations)
• No external libraries needed for basic file reading/writing!
• The code:
  • Reads files line by line
  • Inserts or deletes specific line ranges
  • Preserves line endings (Windows vs Unix style)

Operation Flow Examples

Copy Operation:

1. AI says: "Copy lines 10-20 from myfile.js"
2. Server reads the file using Node's fs.readFileSync()
3. Extracts lines 10-20 from the file
4. Saves them to the SQLite database (your "clipboard")
5. Returns the copied text back to the AI

Paste Operation:

1. AI says: "Paste to line 5 in otherfile.js"
2. Server retrieves clipboard from SQLite database
3. Takes a snapshot of the target file (for undo later)
4. Reads the file, inserts the lines at position 5
5. Writes the modified file back using fs.writeFileSync()
6. Saves the undo information to the database

Undo Operation:

1. AI says: "Undo that paste"
2. Server looks up the last paste in the database
3. Finds the saved snapshot from before the paste
4. Restores the file to its original state
5. If it was from a "cut", also restores the source file!

Key Libraries

Library	Purpose	What It Does
@modelcontextprotocol/sdk	MCP Protocol	Handles communication with AI assistants
better-sqlite3	Database	Stores clipboard, history, and undo info
fs (built-in)	File System	Reads and writes files
TypeScript	Language	Type-safe JavaScript (compiles to regular JavaScript)

The Clever Parts

1. Session Isolation: Each AI assistant gets its own clipboard, so they don't interfere with each other
2. Full Snapshots: Before pasting, it saves the entire file - this makes undo super reliable
3. Line-by-Line: It works with line numbers (like "line 10-20"), which matches how developers think about code
4. Binary Detection: Refuses to work with images/PDFs - only text files

What Makes It Special

Unlike a regular clipboard:

• ✅ Remembers where the code came from
• ✅ Can paste to multiple files at once
• ✅ Has reliable undo (even for cut operations)
• ✅ Works across files and projects
• ✅ Keeps a history of all operations

In essence: It's a sophisticated clipboard that speaks AI's language (MCP), uses a database to remember everything (SQLite), and does all the file reading/writing using basic Node.js tools. The magic is in how it coordinates these pieces to provide reliable cut/copy/paste/undo operations for AI coding assistants!

Architecture

Core Components

1. MCP Server - Handles protocol communication and tool registration
2. Session Manager - Manages session state and clipboard buffers
3. File Handler - Reads and writes file operations with line number support
4. Operation Logger - SQLite-based operation history for undo functionality
5. Clipboard Manager - Manages clipboard buffer per session

Database Schema

The server uses SQLite with 4 main tables:

• sessions - Session tracking with activity timestamps
• clipboard_buffer - Per-session clipboard state
• operations_log - Audit trail of all operations
• paste_history - Enables undo functionality

Data Directory

By default, the database is stored at:

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

CLI Usage

# Start the MCP server
cut-copy-paste-mcp

# Show help
cut-copy-paste-mcp --help

# Show version
cut-copy-paste-mcp --version

Configuration

Claude Desktop / Claude Code

Add to your MCP configuration file:

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"]
    }
  }
}

For local development (not yet published to npm):

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

Cursor IDE

Add to your Cursor MCP settings file:

macOS/Linux: ~/.cursor/mcp_config.json Windows: %USERPROFILE%\.cursor\mcp_config.json

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

Cline (VS Code Extension)

Add to your Cline MCP settings:

1. Open VS Code Settings
2. Search for "Cline: MCP Settings"
3. Add the configuration:

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

Session Timeout

Sessions automatically expire after 24 hours of inactivity. Expired sessions are cleaned up on server start.

AI Agent Configuration

To help your AI coding assistant use this MCP server effectively, you can provide it with usage guidelines and best practices.

Setting Up Agent Instructions

The docs/AGENTIC_USAGE.md file contains comprehensive guidelines for AI agents, including:

• Detailed tool documentation with use cases
• Workflow patterns for common refactoring tasks
• Best practices for clipboard operations
• Error handling guidance

How to configure your agent:

1. Claude Desktop / Claude Code Users:

   • Create or edit CLAUDE.md in your project root
   • Copy the contents of docs/AGENTIC_USAGE.md into this file
   • Claude will automatically use these instructions when working in your project

2. Cursor IDE Users:

   • Create or edit .cursorrules or AGENTS.md in your project root
   • Copy the contents of docs/AGENTIC_USAGE.md into this file
   • Cursor will use these guidelines for AI interactions

3. Other MCP Clients:

   • Consult your client's documentation for custom instructions/rules files
   • Add the contents of docs/AGENTIC_USAGE.md to the appropriate configuration

What This Provides

With these instructions configured, your AI assistant will:

• Know when to use clipboard operations vs. native file editing
• Follow established workflow patterns for refactoring
• Verify clipboard contents before pasting
• Use multi-target paste for boilerplate distribution
• Handle errors gracefully

Example: When you ask "Refactor the authentication logic into a separate module", the AI will know to:

1. Use cut_lines to extract the code
2. Use show_clipboard to verify what was captured
3. Use paste_lines to insert it in the new location
4. Offer to undo_last_paste if the result isn't correct

Best Practices

1. ✅ Always verify clipboard - Use show_clipboard before paste operations
2. ✅ Use multi-paste for patterns - Apply same code to multiple files efficiently
3. ✅ Leverage undo - Don't hesitate to paste; you can always undo
4. ✅ Check operation history - Use get_operation_history to debug issues
5. ✅ Mind line numbers - Remember line numbers are 1-indexed
6. ✅ Complete sequences - Finish copy/cut/paste/undo before starting new operations

Error Handling

The server provides clear error messages for common issues:

• ❌ File not found - "Copy failed: ENOENT: no such file or directory"
• ❌ Invalid line range - "Invalid line range: start_line must be <= end_line"
• ❌ Empty clipboard - "Clipboard is empty"
• ❌ No paste to undo - "No paste operation to undo"

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm test -- --watch

# Run specific test file
npm test -- src/__tests__/server.test.ts

# Run with coverage
npm test:coverage

Building

# Compile TypeScript
npm run build

# Lint code
npm run lint

# Format code
npm run format

Project Structure

src/
├── lib/
│   ├── database.ts              # SQLite initialization
│   ├── session-manager.ts       # Session lifecycle
│   ├── file-handler.ts          # File operations
│   ├── clipboard-manager.ts     # Clipboard buffer
│   └── operation-logger.ts      # Audit trail
├── tools/
│   └── clipboard-tools.ts       # 6 MCP tool implementations
├── config/
│   └── tools.ts                 # Tool definitions
├── server.ts                    # MCP server
├── cli.ts                       # CLI entry point
└── __tests__/                   # Test files

Testing

The project follows strict Test-Driven Development (TDD) with:

• 213 passing tests across 12 test suites
• 90%+ code coverage target
• Unit tests for all core components
• Integration tests for complete workflows
• Edge case tests for binary files, Unicode, large files, and more
• Dedicated tests for cut-paste-undo workflows

Design Decisions

1. ✅ SQLite over JSON files - Provides ACID guarantees, easier querying
2. ✅ stdio transport - Simpler for local development, sufficient for MCP
3. ✅ 1-indexed line numbers - Matches editor conventions
4. ✅ Single undo level - Keeps complexity manageable for v1
5. ✅ Return content on copy/cut - Provides immediate feedback to LLM

Limitations

• 📝 Text files only - Binary files are rejected
• 📝 Single undo level - Only last paste operation can be undone
• 📝 10MB clipboard limit - Maximum clipboard content size
• 📝 stdio transport only - HTTP transport planned for v2

Roadmap

v1.0 (Current)

• ✅ Core clipboard operations
• ✅ Session management
• ✅ Undo support
• ✅ Operation history

v2.0 (Planned)

• 🔮 HTTP transport support
• 🔮 Multi-level undo stack
• 🔮 Large file optimization (streaming)
• 🔮 Authentication support

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests following TDD principles (RED → GREEN → REFACTOR)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Security

• ✅ Path access control - Optional allowlist to restrict filesystem operations (details)
• ✅ Encrypted storage - AES-256-GCM encryption for clipboard data at rest
• ✅ Path validation - Prevents directory traversal attacks
• ✅ Input sanitization - All inputs validated before operations
• ✅ No sensitive data in errors - Error messages don't leak file contents
• ✅ File size limits - 10MB maximum clipboard size

For detailed security information, see Path Access Control Documentation.

License

MIT License - see LICENSE file for details

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

• Built with Model Context Protocol SDK
• Inspired by clipboard operations in modern code editors
• Motivated by Kix Panganiban's article "Two things LLM coding agents are still bad at" highlighting the need for proper cut/copy/paste tools in AI coding workflows
• Developed using strict TDD principles

---

Made with ❤️ for AI-assisted coding workflows

Security Considerations

• Encrypted Storage: Clipboard entries are encrypted at rest with AES-256-GCM using a 32-byte key stored in ~/.mcp-clipboard/clipboard.key (or alongside any custom --db-path).
• Key Management: The key is created automatically the first time the server runs; rotate it by replacing the file and clearing stale sessions.
• File Permissions: The server enforces 700/600 permissions on the clipboard directory and database/key files; verify these remain intact if you relocate them.
• Path Access Control: By default, the server can access all filesystem paths. To restrict access, create ~/.mcp-clipboard/paths.allow with allowed path patterns. See Path Access Control Documentation for configuration examples.
• Database Location: You can override the database location (and thus the key location) via the DatabaseManager constructor or CLI flag in future releases.

Quick Setup for Restricted Access

To limit the server to your current project only, create ~/.mcp-clipboard/paths.allow:

# Allow only your project directory
/Users/username/my-project/**

# Exclude common directories
!**/node_modules/**
!**/.git/**

See Path Access Control Documentation for more examples and best practices.