syncmcp 2.0.0
智能 MCP 配置同步工具 - Smart MCP Configuration Sync Tool
License: MIT
Requires Python: >=3.10
Keywords: claude, configuration, gemini, mcp, model-context-protocol, sync

# SyncMCP - MCP 配置同步工具 🚀

[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)](https://github.com/yourusername/syncmcp)
[![Python](https://img.shields.io/badge/python-3.10+-brightgreen.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

智能化的 MCP (Model Context Protocol) 配置同步工具，讓您輕鬆管理多個 AI 客戶端的配置。

> 🤖 100% 由 Claude 開發，持續進化中

## ✨ 特色

- 🔄 **智能同步** - 自動選擇最新配置，一鍵同步所有客戶端
- 💾 **自動備份** - 每次同步前自動備份，安全無憂
- 🎨 **互動介面** - 友善的 Terminal UI，非技術用戶也能輕鬆使用
- 🤖 **MCP Server** - 作為 MCP Server，讓 Claude 幫您管理配置
- 🌍 **全局命令** - 安裝後可在任何位置執行
- 🔍 **差異偵測** - 智能分析配置差異，提供清晰報告
- 🛡️ **錯誤回滾** - 同步失敗時自動恢復備份

## 📖 目錄

- [問題與解決方案](#問題與解決方案)
- [快速開始](#-快速開始)
- [支援的客戶端](#支援的客戶端)
- [主要功能](#-主要功能)
- [使用方法](#使用方法)
- [文檔](#-文檔)
- [常見問題](#-常見問題)
- [開發路線圖](#-開發路線圖)
- [貢獻](#-貢獻)

---

## 問題與解決方案

### 問題

每個 AI Agent（Claude Desktop、Claude Code、Roo Code、Gemini CLI）都有各自的 MCP Server 配置文件。當您在一個客戶端安裝或修改 MCP 時，其他客戶端不會自動同步，導致：

- ❌ 配置不一致
- ❌ 需要手動複製配置
- ❌ 容易出錯且繁瑣
- ❌ 無法追蹤配置變更歷史

### 解決方案

SyncMCP 提供：

- ✅ 自動選擇最新的配置版本
- ✅ 智能處理不同客戶端的格式差異
- ✅ 自動備份所有變更，支援一鍵恢復
- ✅ 同步到所有客戶端
- ✅ 檢測配置丟失並發出警告
- ✅ 友善的互動介面

---

## 🚀 快速開始

### 安裝

SyncMCP 支援兩種安裝方式，選擇適合您的：

#### 🎯 方式 1: uvx（推薦新手和一次性使用）

無需安裝，直接執行：

```bash
# 檢查系統
uvx syncmcp doctor

# 查看狀態
uvx syncmcp status

# 執行同步
uvx syncmcp sync
```

**優點**: 無需安裝、自動隔離、更快速度

#### 📦 方式 2: pip（推薦頻繁使用）

```bash
# 安裝
pip install syncmcp

# 使用
syncmcp doctor
syncmcp status
syncmcp sync
```

**優點**: 命令更短、適合日常使用

#### 🔧 方式 3: 從原始碼安裝（開發者）

```bash
git clone https://github.com/yourusername/syncmcp.git
cd syncmcp
pip install -e .
```

### 5 分鐘入門

```bash
# 1. 檢查系統是否正常
syncmcp doctor

# 2. 查看當前配置狀態
syncmcp status

# 3. 預覽同步（不實際修改）
syncmcp sync --dry-run

# 4. 執行同步
syncmcp sync

# 5. (可選) 使用互動模式
syncmcp interactive
```

---

## 支援的客戶端

### 客戶端特性對比

| 特性 | Claude Code | Roo Code | Claude Desktop | Gemini CLI |
|------|------------|----------|----------------|------------|
| **配置層級** | | | | |
| 全域配置 | ✅ | ✅ | ✅ | ✅ |
| 專案級配置 | ✅ | ✅ | ❌ | ❌ |
| **傳輸類型** | | | | |
| `stdio` (本地) | ✅ | ✅ | ✅ | ✅ |
| `sse` (遠端) | ✅ | ⚠️ 未測試 | ❌ | ⚠️ 未測試 |
| `http` (遠端) | ✅ | ⚠️ 需轉為 `streamable-http` | ❌ | ⚠️ 未測試 |
| **特殊類型** | | | | |
| `streamable-http` | ❌ | ✅ Roo 專有 | ❌ | ❌ |

### 類型轉換規則

SyncMCP 會自動處理不同客戶端的格式差異：

| 同步方向 | 轉換規則 | 說明 |
|---------|---------|------|
| **Roo Code → Claude Code** | `streamable-http` → `sse` 或 `http` | 根據是否有 headers 決定 |
| **Claude Code → Roo Code** | `sse`/`http` → `streamable-http` | 統一轉換為 Roo 格式 |
| **任何 → Claude Desktop** | 過濾掉所有 `http`/`sse` 類型 | Desktop 僅支援 stdio |
| **任何 → Gemini** | 僅同步全域配置 | Gemini 不支援專案級別 |

> ⚠️ **重要提示**:
> - Claude Code 中出現 `streamable-http` 表示同步錯誤
> - Roo Code 中的 `http` 必須是 `streamable-http`
> - Claude Desktop 無法使用遠端 MCP（http/sse）

### 配置文件位置

| 客戶端 | 配置文件路徑 |
|--------|--------------|
| Claude Code | `~/.claude.json` |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) |
| Roo Code | `~/.roo-code/config.json` |
| Gemini CLI | `~/.gemini/config.json` |

---

## 💎 主要功能

### 1. 智能同步

自動選擇最新配置並同步到所有客戶端。

```bash
# 自動同步
syncmcp sync

# 預覽模式（不實際修改）
syncmcp sync --dry-run

# 手動確認每個變更
syncmcp sync --strategy manual

# 同步但不建立備份
syncmcp sync --no-backup
```

**同步時會做什麼**:
- 載入所有客戶端配置
- 自動選擇最新配置作為來源
- 分析配置差異
- 自動轉換不相容的格式
- 建立備份
- 執行同步
- 記錄歷史

### 2. 配置可見性

查看所有客戶端的配置狀態和 MCP 列表。

```bash
# 查看所有客戶端狀態
syncmcp status

# 列出所有 MCP
syncmcp list

# 查看配置差異
syncmcp diff

# 打開配置檔案
syncmcp open claude-code
```

### 3. 自動備份和恢復

所有變更自動備份，支援一鍵恢復。

```bash
# 查看同步歷史
syncmcp history

# 查看統計資訊
syncmcp history --stats

# 互動式恢復備份
syncmcp restore

# 查看最近 20 筆歷史
syncmcp history --limit 20
```

**備份特性**:
- 自動保留最新 10 個備份
- 每個備份包含所有客戶端配置
- 帶時間戳，易於識別
- 一鍵恢復

### 4. 系統診斷

全面的系統健康檢查。

```bash
syncmcp doctor
```

**檢查項目**:
- ✅ Python 版本（>= 3.10）
- ✅ syncmcp 命令是否在 PATH
- ✅ 必要依賴套件
- ✅ MCP 支援檢測
- ✅ 配置檔案位置
- ✅ 目錄結構
- ✅ 提供修復建議

### 5. 互動式介面 (TUI)

友善的 Terminal 選單介面。

```bash
syncmcp interactive
```

**功能**:
- 🔄 互動式同步 - 預覽變更 → 確認 → 執行
- 📊 配置狀態 - 表格顯示所有客戶端
- 🔍 差異分析 - 顏色標示變更
- 📜 同步歷史 - 查看過往記錄
- ⏮️ 恢復備份 - 從歷史備份恢復

**操作方式**:
- `↑/↓` 選擇選項
- `Enter` 確認
- `Ctrl+C` 退出

### 6. MCP Server 整合

讓 AI 客戶端直接調用 SyncMCP 功能。

**可用工具**:
- `sync_mcp_configs` - 同步配置
- `check_sync_status` - 檢查狀態
- `show_config_diff` - 顯示差異
- `suggest_conflict_resolution` - 建議解決方案

**使用範例**:
```
您: "幫我同步所有 MCP 配置"
Claude: [自動執行同步並報告結果]

您: "列出所有客戶端的 MCP 列表"
Claude: [顯示詳細的配置狀態]
```

---

## 使用方法

### 基礎使用

```bash
# 查看幫助
syncmcp --help

# 查看版本
syncmcp --version

# 執行同步
syncmcp sync

# 查看狀態
syncmcp status
```

### 常見場景

#### 場景 1: 新增 MCP 後同步

```bash
# 在 Claude Code 安裝 MCP
cd ~
claude mcp add github npx @modelcontextprotocol/server-github

# 同步到其他客戶端
syncmcp sync
```

#### 場景 2: 測試新 MCP 後回滾

```bash
# 安裝並測試新 MCP
claude mcp add test-mcp npx test-mcp-server
syncmcp sync

# 發現問題，恢復到之前狀態
syncmcp restore
# 選擇同步前的備份
```

#### 場景 3: 查看配置差異

```bash
# 查看所有客戶端的配置差異
syncmcp diff

# 預覽同步會做什麼
syncmcp sync --dry-run
```

更多範例請查看 [EXAMPLES.md](docs/EXAMPLES.md)

---

## 📚 文檔

完整文檔請查看 [docs/](docs/) 目錄：

- [使用者指南](docs/USER-GUIDE.md) - 完整使用說明
- [開發者指南](docs/DEVELOPER-GUIDE.md) - 開發與貢獻
- [MCP 整合指南](MCP_INTEGRATION.md) - MCP Server 使用
- [API 文檔](docs/API.md) - 程式化使用
- [範例和教學](docs/EXAMPLES.md) - 實際使用案例
- [變更日誌](CHANGELOG.md) - 版本歷史

---

## ⚠️ 常見問題

### 1. syncmcp 命令找不到

**原因**: 安裝後未加入 PATH

**解決方案**:
```bash
# 檢查安裝
pip list | grep syncmcp

# 重新安裝
pip install --force-reinstall syncmcp

# 使用 doctor 檢查
python3 -m syncmcp doctor
```

### 2. Python 版本過舊

**症狀**: `Python 3.9.0 (需要 >= 3.10)`

**解決方案**:
```bash
# macOS
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12
```

### 3. 專案級別 MCP 未同步（Bug #13）

**症狀**: MCP 在 Claude Code 存在但 syncmcp 看不到

**原因**: 目前不支援專案級別 MCP

**解決方案**: 將 MCP 移到全域級別
```bash
# 在專案目錄中刪除
cd /path/to/project
claude mcp remove mcp-name

# 切換到非專案目錄
cd ~

# 重新新增到全域
claude mcp add mcp-name npx mcp-server

# 同步
syncmcp sync
```

詳細說明: [docs/MOVE-MCP-TO-GLOBAL.md](docs/MOVE-MCP-TO-GLOBAL.md)

### 4. Claude Desktop HTTP MCP 無法同步

**原因**: Claude Desktop **只支援** `stdio` 類型

**解決方法**: 這是正常行為，SyncMCP 會自動過濾不支援的類型。

### 5. 同步失敗

**檢查步驟**:
```bash
# 1. 執行診斷
syncmcp doctor

# 2. 查看詳細錯誤
syncmcp sync --verbose

# 3. 檢查配置檔案權限
ls -la ~/.claude.json

# 4. 從備份恢復
syncmcp restore
```

更多故障排除請查看 [USER-GUIDE.md](docs/USER-GUIDE.md#故障排除)

---

## 🗺️ 功能狀態

### ✅ v2.0 已完成（當前版本）

- [x] **核心功能**
  - [x] 智能配置同步
  - [x] 自動類型轉換（http/sse/streamable-http）
  - [x] 差異偵測引擎
  - [x] 自動備份和恢復
  - [x] 配置驗證

- [x] **使用者介面**
  - [x] 完整 CLI 工具（10+ 命令）
  - [x] 互動式 TUI
  - [x] Rich 彩色輸出
  - [x] 系統診斷工具

- [x] **開發者工具**
  - [x] MCP Server 整合（4 個工具）
  - [x] 完整測試套件（92 個測試）
  - [x] CI/CD Pipeline
  - [x] Pre-commit Hooks
  - [x] 完整文檔

### 🔮 未來功能

- [ ] **Doctor Mode** - MCP 健康檢查與自動修復
- [ ] **背景監控** - Daemon 模式自動同步
- [ ] **AI 協助** - 複雜問題診斷
- [ ] **專案級別支援** - 支援專案級別 MCP
- [ ] **Web UI** - 圖形化介面
- [ ] **雲端備份** - 配置雲端同步

詳細規劃請查看 [user-requirements/docs/next-requirements.md](user-requirements/docs/next-requirements.md)

---

## 🤝 貢獻

歡迎貢獻！請查看 [開發者指南](docs/DEVELOPER-GUIDE.md) 了解如何參與開發。

### 貢獻方式

1. Fork 專案
2. 建立功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交變更 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 建立 Pull Request

### 程式碼風格

- 遵循 PEP 8
- 使用 Black 格式化
- 使用 Ruff 檢查
- 完整的型別標註
- 撰寫測試

### Commit 訊息格式

遵循 [Conventional Commits](https://www.conventionalcommits.org/):

```
feat: 新功能
fix: Bug 修復
docs: 文檔更新
style: 程式碼格式
refactor: 重構
test: 測試相關
chore: 建置工具
```

---

## 📄 License

MIT License - 詳見 [LICENSE](LICENSE) 文件

---

## 🙏 致謝

- [Anthropic](https://www.anthropic.com/) - Claude AI
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP 規範
- 所有貢獻者

---

## 📞 聯絡方式

- **GitHub Issues**: [提交問題](https://github.com/yourusername/syncmcp/issues)
- **文檔**: [完整文檔](https://github.com/yourusername/syncmcp/tree/main/docs)

---

## 🌟 Star History

如果這個專案對您有幫助，請給我們一個 Star ⭐️

---

**版本**: 2.0.0
**狀態**: ✅ 所有核心功能完成（15/15 任務）
**最後更新**: 2025-10-28

---

**由 Claude 驅動開發** 🤖