Sparkle MCP Server

Sparkle MCP服务器

一个强大的模型上下文协议（MCP）服务器，为Claude AI和其他兼容MCP的客户端提供安全的文件访问和剪贴板历史管理。

特性

• 安全文件访问：仅限于 ~/Sparkle 用于安全AI文件操作的文件夹
• 高级文件搜索：模式匹配、内容搜索和相关性评分
• 剪贴板历史：从以下位置搜索和查询剪贴板历史记录 ~/Sparkle/Pasteboard/
• 二进制文件支持：处理PDF、图像和其他二进制文件（最大100MB）
• 智能文件索引：自动文件索引，50KB内容采样用于搜索
• 多个文件操作：读取、写入、移动、创建目录和获取文件信息

安装

选项1:NPM安装（推荐）

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

选项2：来源

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

快速设置

选项1：零安装（推荐）🚀

只需将此添加到您的Claude Desktop配置中(~/.config/claude/config.json):

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

就是这样！重新启动Claude Desktop，就完成了。无需安装！

选项2：传统安装

如果您更喜欢本地安装：

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

然后使用此配置：

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

可用工具

文件操作

• list_directory -列出文件和目录
• search_files -使用球形图案搜索(*, *.txt等等）
• get_relevant_files -基于人工智能的文件搜索和排名
• read_file -读取文件内容（文本和二进制）
• write_file -创建或覆盖文件
• move_file -移动或重命名文件
• create_directory -创建目录
• get_file_info -获取文件元数据

剪贴板历史

• search_clipboard -使用筛选器搜索剪贴板历史记录
• get_clipboard_by_date -获取特定日期的剪贴板条目
• get_recent_clipboard -获取最近的剪贴板条目
• clipboard_stats -使用统计和分析

系统

• health_check -服务器状态和诊断

使用示例

基本文件操作

// 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 })

剪贴板历史

// 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 })

目录结构

~/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

剪贴板历史记录格式

服务器支持多种剪贴板存储格式：

JSON格式(clipboard.json)

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

文本格式(clipboard.txt)

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

快速集成

如果你有一个Swift Sparkle应用程序，以下是如何集成：

1.MCP服务器通信

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.文件操作

// 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.剪贴板集成

// 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]
    ])
)

配置

服务器使用 ~/Sparkle/.mcp-config.json 配置：

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

安全功能

• 沙盒访问：只有 ~/Sparkle 文件夹可访问
• 文件大小限制：最大文件大小为100MB
• 路径验证：防止目录遍历攻击
• 速率限制：每分钟100个请求
• 安全文件类型：默认情况下阻止可执行文件

发展

# 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

发布步骤（适用于维护人员）

1. 更新版本: npm version patch|minor|major
2. 构建: npm run build
3. 发布: npm publish --access public

故障排除

服务器无法启动

# Check if installed correctly
which sparkle-mcp

# Test server manually
sparkle-mcp --help

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

文件访问问题

• 确保 ~/Sparkle 文件夹存在并且可写
• 检查文件权限： chmod 755 ~/Sparkle
• 验证Claude Desktop是否具有适当的权限

剪贴板历史记录不起作用

• 创建 ~/Sparkle/Pasteboard/ 目录
• 确保剪贴板应用程序保存为正确的格式
• 检查文件夹权限

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

支持

• 问题: https://github.com/EveryInc/sparkle-mcp-server/issues
• 文档: https://github.com/EveryInc/sparkle-mcp-server/wiki
• 讨论: https://github.com/EveryInc/sparkle-mcp-server/discussions

______________________________________________________________________

内置于❤️ 靠近 每家公司