Clipboard MCP Server

⚠️ SECURITY WARNING ⚠️

🔒 CRITICAL NOTICE: FILE SYSTEM ACCESS
Installing this MCP server will allow AI agents to READ and modify files on your system without explicit user confirmation for each operation. Only install if you trust the AI system and understand the security implications.

⚠️ Version 0.0.1 - Experimental Release
This is an early experimental version that may contain bugs, incomplete features, and breaking changes. Use at your own risk and expect frequent updates.

🎯 Overview

Context-efficient file editing MCP server using pattern-based copy/paste operations. Provides an alternative to traditional exact-string editing tools by using text patterns and markers for content manipulation.

🚀 Quick Start

Prerequisites

Node.js 18+
Claude Code with MCP support

Installation

Clone and build:

git clone <repository-url>
cd clipboard-mcp
npm install
npm run build

Configure MCP server:

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "clipboard": {
      "command": "node",
      "args": ["<absolute-path-to-project>/dist/server.js"],
      "env": {}
    }
  }
}

Restart Claude Code or run /mcp reconnect

🛠️ Usage

The server provides a single copy_paste method for pattern-based file operations:

copy_paste({
  source: {
    file: string,                  // Path to source file
    start_pattern: string,         // Text pattern to find start of content
    end_pattern?: string,          // Optional: end pattern (if not provided, uses line_count)
    line_count?: number            // Optional: number of lines from start_pattern
  },
  target: {
    file: string,                  // Path to target file
    marker: string,                // Text pattern to find insertion point
    position: 'before' | 'after' | 'replace',  // Where to insert relative to marker
    replace_pattern?: string       // Optional: specific pattern to replace (when position='replace')
  },
  cut?: boolean                    // Optional: true to cut (move) instead of copy
})

Examples

Copy a function:

copy_paste({
  source: { 
    file: '/path/to/source.js', 
    start_pattern: 'function processData',
    end_pattern: '^}'
  },
  target: { 
    file: '/path/to/target.js', 
    marker: '// Insert utilities here',
    position: 'after' 
  }
})

Move a code block:

copy_paste({
  source: { 
    file: '/path/to/old.js', 
    start_pattern: '// Helper functions',
    line_count: 10
  },
  target: { 
    file: '/path/to/new.js', 
    marker: '// TODO: Add helpers',
    position: 'replace'
  },
  cut: true  
})

🧪 Development

Running Tests

npm test                # Run all tests
npm run test:watch      # Run tests in watch mode

Development Mode

npm run dev             # MCP server with file watching
npm run dev:http        # HTTP server for testing (localhost:3000)

HTTP Testing

For debugging, you can test the server logic via HTTP:

# Start HTTP server
npm run dev:http

# Test with curl
curl -X POST http://localhost:3000/copy_paste \
  -H "Content-Type: application/json" \
  -d '{
    "source": {
      "file": "/path/to/source.js",
      "start_pattern": "function test",
      "line_count": 5
    },
    "target": {
      "file": "/path/to/target.js",
      "marker": "// Insert here",
      "position": "after"
    }
  }'

📚 Why Pattern-Based?

Traditional file editing tools require exact string matching, which:

Consumes large amounts of context tokens
Fails on whitespace differences
Requires precise text copying

Pattern-based approach:

Uses familiar text landmarks (function name, // comments)
Significantly reduces context consumption
More robust to formatting variations
Leverages natural code structure

🔧 Technical Details

Architecture

MCP Server (src/server.ts) - Protocol compliance and request routing
Copy/Paste Handler (src/handlers/) - Core business logic
File System Storage (src/services/) - File operations and pattern matching
Utilities (src/utils/) - Helper functions for position calculations

Error Handling

Pattern not found in source file
Marker not found in target file
File permission and existence checks
Invalid parameter validation

Testing

15 unit tests covering core functionality
Snapshot testing for regression protection
Fixture-based testing with cleanup automation
Edge case coverage (special characters, empty content, etc.)

⚠️ Known Limitations (v0.0.1)

Security Limitations

No file access restrictions - agents can access any readable file
No operation confirmation - file modifications happen immediately
No audit logging - operations are not logged for review
No rollback protection - file changes are permanent

Technical Limitations

Pattern matching is case-sensitive
No regex pattern support yet (only literal text)
Limited to single file operations per call
No undo/rollback functionality
File size limits not enforced
No concurrent operation protection

🛣️ Roadmap

Regex pattern support
Batch operations (multiple files)
Operation history and undo
Performance optimizations
Better error messages
Configuration options

📄 License

MIT License

🤝 Contributing

This is experimental software. Issues and feedback welcome, but expect frequent breaking changes in early versions.

Version 0.0.1 - Initial experimental release

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Enables pattern-based file editing operations using copy/paste functionality with text landmarks instead of exact string matching. Allows AI agents to efficiently manipulate file content by identifying code patterns and insertion points without consuming large amounts of context tokens.

⚠️ SECURITY WARNING ⚠️

Related MCP Servers

CodeSavant
twolven
-
security
A
license
-
quality
Provides code manipulation, execution, and version control capabilities. It allows AI assistants to read, write, and execute code while maintaining a history of changes.
Last updated -
9
MIT License
MCP File Server
codyde
A
security
F
license
A
quality
Enables AI models to perform file system operations (reading, creating, and listing files) on a local file system through a standardized Model Context Protocol interface.
Last updated -
3
Edit-MCP
mixelpixx
A
security
A
license
A
quality
A Model Context Protocol server that integrates with Microsoft's Edit tool, allowing AI systems to perform file operations from simple reads/writes to complex code editing and refactoring.
Last updated -
9
3
MIT License
MCP SmallEdit
MikeyBeez
A
security
F
license
A
quality
Provides tools for making small, targeted edits to files using stream editors like sed and awk, enabling efficient modifications without full file replacement.
Last updated -
10
1

View all related MCP servers

Clipboard MCP Server