README.md•5.72 kB
# 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:**
```bash
git clone <repository-url>
cd clipboard-mcp
npm install
npm run build
```
2. **Configure MCP server:**
Add to your Claude Code MCP configuration:
```json
{
"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:
```typescript
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:**
```javascript
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:**
```javascript
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
```bash
npm test # Run all tests
npm run test:watch # Run tests in watch mode
```
### Development Mode
```bash
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:
```bash
# 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