witqq/clipboard-mcp

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

1. Clone and build:

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

2. Configure MCP server:

Add to your Claude Code MCP configuration:

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

3. 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