Sparkle MCP Server

A powerful Model Context Protocol (MCP) server that provides secure file access and clipboard history management for Claude AI and other MCP-compatible clients.

Features

• Secure File Access: Restricted to ~/Sparkle folder for safe AI file operations
• Advanced File Search: Pattern matching, content search, and relevance scoring
• Clipboard History: Search and query clipboard history from ~/Sparkle/Pasteboard/
• Binary File Support: Handles PDFs, images, and other binary files (up to 100MB)
• Smart File Indexing: Automatic file indexing with 50KB content sampling for search
• Multiple File Operations: Read, write, move, create directories, and get file info

Installation

Option 1: NPM Install (Recommended)

npm install -g @every-env/sparkle-mcp-server

Option 2: From Source

git clone https://github.com/EveryInc/sparkle-mcp-server.git
cd sparkle-mcp-server
npm install
npm run build
npm link

Quick Setup

Option 1: Zero Install (Recommended) 🚀

Just add this to your Claude Desktop config (~/.config/claude/config.json):

{
  "mcpServers": {
    "sparkle": {
      "command": "npx",
      "args": ["-y", "@every-env/sparkle-mcp-server"]
    }
  }
}

That's it! Restart Claude Desktop and you're done. No installation needed!

Option 2: Traditional Install

If you prefer a local installation:

npm install -g @every-env/sparkle-mcp-server

Then use this config:

{
  "mcpServers": {
    "sparkle": {
      "command": "sparkle-mcp"
    }
  }
}

Available Tools

File Operations

• list_directory - List files and directories
• search_files - Search with glob patterns (*, *.txt, etc.)
• get_relevant_files - AI-powered file search and ranking
• read_file - Read file contents (text and binary)
• write_file - Create or overwrite files
• move_file - Move or rename files
• create_directory - Create directories
• get_file_info - Get file metadata

Clipboard History

• search_clipboard - Search clipboard history with filters
• get_clipboard_by_date - Get clipboard entries for a specific date
• get_recent_clipboard - Get recent clipboard entries
• clipboard_stats - Usage statistics and analytics

System

• health_check - Server status and diagnostics

Usage Examples

Basic File Operations

// List all files in Sparkle folder
list_directory({ path: "" })

// Search for all text files
search_files({ path: "", pattern: "*.txt" })

// Find relevant files with AI
get_relevant_files({ query: "my tax documents", maxFiles: 5 })

Clipboard History

// Search clipboard for specific text
search_clipboard({ query: "password", limit: 20 })

// Get today's clipboard
get_clipboard_by_date({ date: "2025-08-05" })

// Recent clipboard history
get_recent_clipboard({ days: 7, limit: 50 })

Directory Structure

~/Sparkle/                    # Main Sparkle directory
├── README.txt               # Welcome file (auto-created)
├── Pasteboard/              # Clipboard history
│   ├── 2025-08-05/         # Daily clipboard folders
│   │   ├── clipboard.json  # Clipboard entries
│   │   └── ...
├── Documents/              # Your documents
├── Images/                 # Your images
└── ...                     # Any other files/folders

Clipboard History Format

The server supports multiple clipboard storage formats:

JSON Format (clipboard.json)

[
  {
    "timestamp": "2025-08-05T10:30:00Z",
    "content": "Hello world",
    "type": "text",
    "metadata": {
      "app": "Safari",
      "size": 11
    }
  }
]

Text Format (clipboard.txt)

2025-08-05 10:30:00 | text | Hello world
2025-08-05 10:31:15 | url | https://example.com

Swift Integration

If you have a Swift Sparkle app, here's how to integrate:

1. MCP Server Communication

import Foundation

class SparkleManager {
    private let serverProcess: Process
    
    init() {
        serverProcess = Process()
        serverProcess.executableURL = URL(fileURLWithPath: "/usr/local/bin/sparkle-mcp")
        // Configure stdio pipes for MCP communication
    }
    
    func sendMCPRequest(_ request: MCPRequest) async throws -> MCPResponse {
        // Implement MCP protocol communication
    }
}

2. File Operations

// Search files
let searchResult = try await sparkleManager.sendMCPRequest(
    MCPRequest(method: "tools/call", params: [
        "name": "search_files",
        "arguments": ["path": "", "pattern": "*.pdf"]
    ])
)

// Read file
let fileContent = try await sparkleManager.sendMCPRequest(
    MCPRequest(method: "tools/call", params: [
        "name": "read_file", 
        "arguments": ["path": "document.txt"]
    ])
)

3. Clipboard Integration

// Save clipboard to Pasteboard folder
func saveClipboard() {
    let pasteboard = NSPasteboard.general
    if let string = pasteboard.string(forType: .string) {
        let clipboardEntry = ClipboardEntry(
            timestamp: Date(),
            content: string,
            type: "text"
        )
        saveToSparkleFolder(clipboardEntry)
    }
}

// Query clipboard history via MCP
let recentClipboard = try await sparkleManager.sendMCPRequest(
    MCPRequest(method: "tools/call", params: [
        "name": "get_recent_clipboard",
        "arguments": ["days": 7, "limit": 50]
    ])
)

Configuration

The server uses ~/Sparkle/.mcp-config.json for configuration:

{
  "version": "1.0.0",
  "created": "2025-08-05T10:00:00Z",
  "settings": {
    "sparkleFolder": "~/Sparkle",
    "maxFileSize": 104857600,
    "allowedExtensions": ["*"],
    "autoIndex": true,
    "watcherEnabled": true
  }
}

Security Features

• Sandboxed Access: Only ~/Sparkle folder is accessible
• File Size Limits: 100MB maximum file size
• Path Validation: Prevents directory traversal attacks
• Rate Limiting: 100 requests per minute
• Safe File Types: Blocks executable files by default

Development

# Clone and setup
git clone https://github.com/EveryInc/sparkle-mcp-server.git
cd sparkle-mcp-server
npm install

# Development mode
npm run dev

# Build
npm run build

# Test
npm test

Publishing Steps (For Maintainers)

1. Update version: npm version patch|minor|major
2. Build: npm run build
3. Publish: npm publish --access public

Troubleshooting

Server Won't Start

# Check if installed correctly
which sparkle-mcp

# Test server manually
sparkle-mcp --help

# Check logs
tail -f ~/.config/claude/logs/sparkle.log

File Access Issues

• Ensure ~/Sparkle folder exists and is writable
• Check file permissions: chmod 755 ~/Sparkle
• Verify Claude Desktop has proper permissions

Clipboard History Not Working

• Create ~/Sparkle/Pasteboard/ directory
• Ensure your clipboard app saves to the correct format
• Check folder permissions

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: https://github.com/EveryInc/sparkle-mcp-server/issues
• Documentation: https://github.com/EveryInc/sparkle-mcp-server/wiki
• Discussions: https://github.com/EveryInc/sparkle-mcp-server/discussions

---

Built with ❤️ by Every Inc