内容
# 超越比较 MCP
<p align="center">
<a href="https://github.com/casey/just"><img src="https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white" alt="Just"></a>
<a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="Ruff"></a>
<a href="https://python.org"><img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python"></a>
<a href="https://github.com/PrefectHQ/fastmcp"><img src="https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square" alt="FastMCP"></a>
</p>
> 📖 **[安装指南](INSTALL.md)** — 快速开始，手动设置，故障排除
一款现代化的MCP服务器，提供全面的文件比较，多媒体管理和开发者工作区工具，使用Beyond Compare。具备13种强大的工具，涵盖文件比较，仓库备份和工作区分析。
## 快速开始
```powershell
git clone https://github.com/sandraschi/beyondcompare-mcp
cd beyondcompare-mcp
just
```
这将打开一个交互式仪表板，显示所有可用的命令。运行 `just bootstrap` 安装依赖，然后运行 `just serve` 或 `just dev` 启动。
### 手动设置
如果您没有安装 `just`:
## 功能
- **文件和文件夹比较**：使用Beyond Compare强大的引擎比较文件和目录
- **目录同步**：使用各种同步模式（镜像，更新，备份）保持文件夹同步
- **差异报告生成**：生成多个格式的详细比较报告
- **多媒体管理**：完整的驱动器扫描，重复检测和USB驱动器监控
- **开发者工作区工具**：智能仓库备份，健康扫描和工作区分析
- **智能清理**：自动工件清理，带有node_modules过滤和空间回收
- **代码分析**：重复代码检测和工作区快照比较
- **安全第一**：全面输入验证和安全子进程执行
- **MCP合规**：基于模型上下文协议标准，具备13种强大的工具
- **MCPB包装**：使用MCPB包轻松部署到Claude Desktop（60.4 KB）
- **跨平台**：支持Windows，macOS和Linux
## 安全与质量
**已准备好生产** - 通过了全面的安全审计
**输入验证** - 命令注入和路径遍历保护
**安全依赖** - 官方MCP SDK 2.11+，带有验证包
**测试覆盖率** - 85%+ 测试覆盖率，带有安全测试
**现代架构** - Python 3.10+，带有类型提示和异步支持
## 安装
### 先决条件
- [uv](https://docs.astral.sh/uv/) 已安装（推荐）
- Python 3.12+
### 快速开始
使用 `uvx` 立即运行：
```bash
uvx beyondcompare-mcp
```
### 克劳德桌面集成
添加到您的 `claude_desktop_config.json`：
```json
"mcpServers": {
"beyondcompare-mcp": {
"command": "uv",
"args": ["--directory", "D:/Dev/repos/beyondcompare-mcp", "run", "beyondcompare-mcp"]
}
}
```
### 先决条件
- **Python 3.10+** （MCP 2.11+ 必需）
- **Beyond Compare 4+** 已安装在您的系统上
- **克劳德桌面** 或兼容的MCP客户端
### 快速安装（推荐）
**适用于克劳德桌面用户：**
1. 下载或构建最新的 `.mcpb` 包。
2. 将 `.mcpb` 文件拖放到克劳德桌面或使用设置 > MCP > 安装扩展
3. Beyond Compare 将自动检测（或在提示时配置路径）
### 从源代码安装
```bash
git clone https://github.com/sandraschi/beyondcompare-mcp.git
cd beyondcompare-mcp
pip install -e ".[dev]"
```
## 配置
MCP服务器自动检测Beyond Compare安装（包括Beyond Compare 5），但您可以通过环境变量自定义：
```ini
# 可选：Beyond Compare可执行文件路径（如果未指定则自动检测）
BEYOND_COMPARE_PATH="C:\\Program Files\\Beyond Compare 4\\BCompare.exe"
# 可选：日志级别（DEBUG，INFO，WARNING，ERROR，CRITICAL）
LOG_LEVEL=INFO
# 可选：存储临时脚本文件的目录
BC_SCRIPTS_DIR="./bc_scripts"
# 可选：命令超时（秒）
COMMAND_TIMEOUT=30
```
## 可用工具
MCP服务器提供 **13种强大的工具** 用于文件比较，多媒体管理和开发者工作流：
### 核心比较工具
#### 1. `compare_files`
使用Beyond Compare引擎比较两个文件
```json
{
"name": "compare_files",
"arguments": {
"left_path": "/path/to/file1.txt",
"right_path": "/path/to/file2.txt",
"output_report": "/path/to/report.html"
}
}
```
#### 2. `compare_folders`
比较两个目录，可选包含子文件夹
```json
{
"name": "compare_folders",
"arguments": {
"left_path": "/path/to/folder1",
"right_path": "/path/to/folder2",
"include_subfolders": true,
"output_report": "/path/to/report.html"
}
}
```
#### 3. `sync_folders`
使用Beyond Compare同步目录
```json
{
"name": "sync_folders",
"arguments": {
"source_path": "/path/to/source",
"target_path": "/path/to/target",
"sync_mode": "mirror",
"dry_run": true
}
}
```
**同步模式：**
- `mirror`: 使目标与源相同
- `update`: 从源复制更新的文件到目标
- `backup`: 仅复制缺少的文件到目标
### 多媒体和驱动器工具
#### 4. `multimedia_drive_scanner`
扫描多媒体驱动器（E:, F:, K:, L:）以获取完整的库存，带有过滤选项
#### 5. `find_multimedia_duplicates`
使用内容哈希查找驱动器上的重复多媒体文件
#### 6. `detect_usb_drives`
检测并列出所有连接的USB驱动器，带有详细信息
### 开发者工作区工具
#### 7. `backup_dev_repositories`
智能备份开发仓库，带有智能过滤
- 排除 `node_modules`，`__pycache__`，构建工件
- 保留Git essentials和项目结构
- 支持压缩和增量备份
- 适用于备份 `D:/dev/repos`，带有空间优化
#### 8. `analyze_dev_workspace`
开发者工作区的全面分析
- 语言使用统计和仓库洞察
- 依赖分析（package.json，requirements.txt等）
- 磁盘使用分析和优化机会
- 生成详细的HTML报告
#### 9. `scan_repo_health`
扫描仓库健康状况并识别潜在问题
- 跨所有仓库的Git状态检查
- 大文件检测和安全问题识别
- 过时依赖扫描
- 常见问题的自动修复选项
#### 10. `cleanup_dev_artifacts`
清理仓库中的构建工件和临时文件
- 安全移除 `node_modules`，`__pycache__`，`.next`，`dist/` 文件夹
- 可配置的大小阈值和目标模式
- 带有安全预览的dry-run模式
- 显著的磁盘空间回收
#### 11. `find_duplicate_code`
查找仓库中的重复代码以获取重构机会
- 跨仓库的重复检测
- 可配置的相似性阈值
- 支持多种文件类型（*.py, *.js, *.ts等）
- 详细的相似性报告
#### 12. `compare_workspace_snapshots`
比较工作区快照以识别随时间的变化
- 跟踪仓库的添加，删除和修改
- 详细的变更分析，带有大小差异
- 适用于监控工作区演变
#### 13. `selective_restore`
选择性恢复备份中的特定项目或文件
- 灵活的基于模式的恢复
- 结构保留选项
- 冲突解决和覆盖控制
## 开发和测试
```bash
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试并覆盖
pytest --cov=beyondcompare_mcp --cov-report=term-missing
# 代码格式化
black src tests
isort src tests
# 类型检查
mypy src
```
## 打包和分发
该仓库符合SOTA 2026标准，并使用官方验证的`@anthropic-ai/mcpb`工作流进行分发。
### 打包扩展
生成一个带有完整源代码和自动构建排除的`.mcpb`分发包：
```bash
# SOTA 2026标准打包命令
mcpb pack . dist/beyondcompare-mcp.mcpb
```
## 安全功能
- **输入验证**：所有文件路径和参数都经过验证以防止注入攻击
- **路径安全**：通过检测`..`防止路径遍历
- **安全执行**：无shell解释，控制的子进程执行
- **临时文件安全**：安全的临时文件处理，带有唯一名称
- **依赖验证**：所有依赖都经过验证和安全审计
## 系统需求
| 组件 | 需求 |
|-----------|------------|
| Python | 3.10+ |
| Beyond Compare | 4.0+ （Beyond Compare 5 验证为可用）|
| 内存 | 100MB+ 可用 |
| 磁盘空间 | 10MB 用于DXT包 |
| 操作系统 | Windows 10+，macOS 10.15+，Linux（Ubuntu 20.04+） |
## 贡献
欢迎贡献！请参阅：
- [贡献指南](CONTRIBUTING.md)
- [行为准则](CODE_OF_CONDUCT.md)
- [安全政策](docs/SECURITY-ADVISORY.md)
## 🛡️ 工业质量栈
该项目遵循 **SOTA 14.1** 工业标准，用于高保真代理编排：
- **Python（核心）**： [Ruff](https://astral.sh/ruff) 用于 linting 和格式化。核心处理程序中对 `print` 语句的零容忍度（`T201`）。
- **Webapp（UI）**： [Biome](https://biomejs.dev/) 用于毫秒级 linting。严格的 `noConsoleLog` 强制执行。
- **协议合规**：强化 `stdout/stderr` 隔离，以确保崩溃防护的JSON-RPC通信。
- **自动化**： [Justfile](./justfile) 适用于所有舰队操作（`just lint`，`just fix`，`just dev`）。
- **安全**：通过 `bandit` 和 `safety` 进行自动审计。
## 许可证
MIT许可证 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## 链接
- **超越比较**： https://www.scootersoftware.com/
- **模型上下文协议**： https://modelcontextprotocol.io/
- **文档**： [docs/](docs/)
- **变更日志**： [CHANGELOG.md](CHANGELOG.md)
---
**已准备好生产使用，具有验证的功能，全面的安全性和完整的MCP合规性。**
## 验证状态
- **软件包安装**：DXT在克劳德桌面上干净地安装
- **服务器功能**：所有核心功能验证正常
- **超越比较集成**：与超越比较5测试通过
- **安全功能**：所有安全测试通过（14/14单元测试）
- **MCP协议**：完整的MCP合规性验证（9/9 MCP测试）
- **测试覆盖率**：61%的现实覆盖率（非膨胀声明）
- **文档**：所有声明测试和验证
*该项目优先考虑工作功能而不是营销声明。*
## Webapp 仪表板（`web_sota`）
舰队端口： **10840** （Vite前端）， **10841** （统一 **FastAPI + FastMCP** 网关：REST + MCP在 `/mcp`）。
1. 启动网关： `uv run python -m beyondcompare_mcp.server --http --port 10841`
2. 在另一个shell中： `cd web_sota` 然后 `npm run dev`
3. 打开 `http://127.0.0.1:10840` （Vite代理`/api`和`/mcp`到网关）。
操作员参考： [docs/FLEET_GATEWAY.md](docs/FLEET_GATEWAY.md)。自动化健康探测： `GET http://127.0.0.1:10841/api/v1/health`。
