README.md•24.1 kB
# MCP Cut-Copy-Paste Clipboard Server
[](https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp/actions/workflows/ci.yml)
[](https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
[](LICENSE)
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](docs/PATH_ACCESS_CONTROL.md))
- 🔒 **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)
```bash
npx cut-copy-paste-mcp
```
### Via NPM
```bash
npm install -g cut-copy-paste-mcp
cut-copy-paste-mcp
```
### Local Development
```bash
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:
```json
{
"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`](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:**
```json
{
"tool": "copy_lines",
"arguments": {
"file_path": "src/utils/helpers.ts",
"start_line": 10,
"end_line": 25
}
}
```
**Returns:**
```json
{
"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:**
```json
{
"tool": "cut_lines",
"arguments": {
"file_path": "src/legacy/old-module.ts",
"start_line": 50,
"end_line": 75
}
}
```
**Returns:**
```json
{
"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):**
```json
{
"tool": "paste_lines",
"arguments": {
"targets": [
{
"file_path": "src/components/NewComponent.tsx",
"target_line": 20
}
]
}
}
```
**Example (multiple targets):**
```json
{
"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:**
```json
{
"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:**
```json
{
"tool": "show_clipboard",
"arguments": {}
}
```
**Returns:**
```json
{
"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:**
```json
{
"tool": "undo_last_paste",
"arguments": {}
}
```
**Returns:**
```json
{
"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:**
```json
{
"tool": "get_operation_history",
"arguments": {
"limit": 5
}
}
```
**Returns:**
```json
{
"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
```bash
# 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`
```json
{
"mcpServers": {
"clipboard": {
"command": "npx",
"args": ["cut-copy-paste-mcp"]
}
}
}
```
For local development (not yet published to npm):
```json
{
"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`
```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:
```json
{
"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`](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
```bash
# 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
```bash
# 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](docs/PATH_ACCESS_CONTROL.md))
- ✅ **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](docs/PATH_ACCESS_CONTROL.md).
## License
MIT License - see [LICENSE](LICENSE) file for details
## Support
- 📖 [Documentation](https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp)
- 🐛 [Issue Tracker](https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp/issues)
- 💬 [Discussions](https://github.com/Pr0j3c7t0dd-Ltd/cut-copy-paste-mcp/discussions)
## Acknowledgments
- Built with [Model Context Protocol SDK](https://modelcontextprotocol.io/)
- Inspired by clipboard operations in modern code editors
- Motivated by Kix Panganiban's article ["Two things LLM coding agents are still bad at"](https://kix.dev/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](docs/PATH_ACCESS_CONTROL.md) 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](docs/PATH_ACCESS_CONTROL.md) for more examples and best practices.