SyncMCP - MCP 配置同步工具 🚀

智能化的 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（推薦新手和一次性使用）

無需安裝，直接執行：

# 檢查系統
uvx syncmcp doctor

# 查看狀態
uvx syncmcp status

# 執行同步
uvx syncmcp sync

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

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

# 安裝
pip install syncmcp

# 使用
syncmcp doctor
syncmcp status
syncmcp sync

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

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

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

5 分鐘入門

# 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. 智能同步

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

# 自動同步
syncmcp sync

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

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

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

同步時會做什麼:

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

2. 配置可見性

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

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

# 列出所有 MCP
syncmcp list

# 查看配置差異
syncmcp diff

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

3. 自動備份和恢復

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

# 查看同步歷史
syncmcp history

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

# 互動式恢復備份
syncmcp restore

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

備份特性:

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

4. 系統診斷

全面的系統健康檢查。

syncmcp doctor

檢查項目:

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

5. 互動式介面 (TUI)

友善的 Terminal 選單介面。

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: [顯示詳細的配置狀態]

---

使用方法

基礎使用

# 查看幫助
syncmcp --help

# 查看版本
syncmcp --version

# 執行同步
syncmcp sync

# 查看狀態
syncmcp status

常見場景

場景 1: 新增 MCP 後同步

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

# 同步到其他客戶端
syncmcp sync

場景 2: 測試新 MCP 後回滾

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

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

場景 3: 查看配置差異

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

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

更多範例請查看 EXAMPLES.md

---

📚 文檔

完整文檔請查看 docs/ 目錄：

• 使用者指南 - 完整使用說明
• 開發者指南 - 開發與貢獻
• MCP 整合指南 - MCP Server 使用
• API 文檔 - 程式化使用
• 範例和教學 - 實際使用案例
• 變更日誌 - 版本歷史

---

⚠️ 常見問題

1. syncmcp 命令找不到

原因: 安裝後未加入 PATH

解決方案:

# 檢查安裝
pip list | grep syncmcp

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

# 使用 doctor 檢查
python3 -m syncmcp doctor

2. Python 版本過舊

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

解決方案:

# macOS
brew install python@3.12

# Ubuntu/Debian
sudo apt install python3.12

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

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

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

解決方案: 將 MCP 移到全域級別

# 在專案目錄中刪除
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

4. Claude Desktop HTTP MCP 無法同步

原因: Claude Desktop 只支援 stdio 類型

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

5. 同步失敗

檢查步驟:

# 1. 執行診斷
syncmcp doctor

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

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

# 4. 從備份恢復
syncmcp restore

更多故障排除請查看 USER-GUIDE.md

---

🗺️ 功能狀態

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

• 核心功能

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

• 使用者介面

  • 完整 CLI 工具（10+ 命令）
  • 互動式 TUI
  • Rich 彩色輸出
  • 系統診斷工具

• 開發者工具

  • MCP Server 整合（4 個工具）
  • 完整測試套件（92 個測試）
  • CI/CD Pipeline
  • Pre-commit Hooks
  • 完整文檔

🔮 未來功能

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

詳細規劃請查看 user-requirements/docs/next-requirements.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:

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

---

📄 License

MIT License - 詳見 LICENSE 文件

---

🙏 致謝

• Anthropic - Claude AI
• Model Context Protocol - MCP 規範
• 所有貢獻者

---

📞 聯絡方式

• GitHub Issues: 提交問題
• 文檔: 完整文檔

---

🌟 Star History

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

---

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

---

由 Claude 驅動開發 🤖