同步-mcp

Name: 同步-mcp
Author: william-garden

作者：william-garden42 星标更新：2025-11-06

安装使用来源：spider==github.com

项目介绍

技术文档摘要

sync-mcp

一键式MCP配置同步工具。中文

1. 概述

sync-mcp 是一个基于Node.js的命令行工具，旨在解决手动在多个IDE、代码编辑器和CLI工具之间同步通用MCP配置的痛点。用户可以使用简单的命令安全地将一个工具（源）的配置文件同步到另一个工具（目标），从而实现统一和自动化的配置管理。

2. 技术规格

环境：Node.js 18+（需要ESM支持和现代API）。
发布方式：通过npm发布，支持直接执行 npx sync-mcp 或全局安装 npm i -g sync-mcp。
运行依赖：仅依赖跨平台文件系统和CLI交互库；无需本地编译环境。
支持平台：稳定运行于Linux、Windows和macOS。

3. 使用方法

3.1. 直接同步

通过提供源和目标工具的关键字来直接执行同步。

npx -y sync-mcp <source_keyword> <target_keyword>

3.2. 交互式同步

当命令没有参数时，进入交互模式。

npx -y sync-mcp

操作流程：

选择源：

? 选择配置源文件：(使用箭头键)  
> 1. VS Code (~/.vscode/mcp.json)  
    2. Cursor (~/.cursor/mcp.json)  
    3. GitHub Copilot CLI (~/.copilot/mcp-config.json)  
    4. 自定义

选择目标：

? 选择配置目标文件：(使用箭头键)  
> 1. VS Code (~/.vscode/mcp.json)  
    2. Cursor (~/.cursor/mcp.json)  
    3. GitHub Copilot CLI (~/.copilot/mcp-config.json)  
    4. 自定义 (选择一个目标工具或创建新的配置)

4. 工具匹配关键字

工具名称	支持的关键字
Codex	`codex`, `openai`, `codex cli`
Claude Code	`claude`, `claude-code`, `claude code`, `anthropic`
Cursor	`cursor`, `cursor ide`
Gemini CLI	`gemini`, `gemini cli`, `google`, `gcloud`
GitHub Copilot CLI	`copilot`, `copilot cli`, `github`, `gh`
Visual Studio Code	`vscode`, `vs code`, `vs-code`, `code`

5. 支持的工具及其配置路径

工具名称	Linux/macOS 路径	Windows 路径	文档链接
Codex	`~/.codex/config.toml`	`%USERPROFILE%\.codex\config.toml`	Codex 配置
Claude Code	`~/.claude.json`	`%USERPROFILE%\.claude.json`	Claude Code MCP指南
Cursor	`~/.cursor/mcp.json`	`%APPDATA%\Cursor\mcp.json`	Cursor MCP指南
Gemini CLI (gcloud)	`~/.gemini/settings.json`	`%APPDATA%\.gemini\settings.json`	Gemini CLI MCP服务器
GitHub Copilot CLI	`~/.copilot/mcp-config.json`	`%USERPROFILE%\.copilot\mcp-config.json`	Copilot CLI MCP使用
Visual Studio Code	`~/.vscode/mcp.json`	`%APPDATA%\Roaming\Code\User\mcp.json`	VS Code MCP服务器

5.1. Codex

默认配置文件：~/.codex/config.toml

# ~/.codex/config.toml  
[mcp_servers.context7]  
command ="cmd"  
args = [  
    "/c", "npx", "-y",  
    "@upstash/context7-mcp",  
    "--api-key="YOUR_API_KEY",  
    "--stdio"  
]  
env = { SystemRoot="C:\\Windows", PROGRAMFILES="C:\\Program Files" }  
startup_timeout_ms = 60_000

5.2. Claude Code

默认配置文件：~/.claude.json

{  
  "mcpServers": {  
    "context7": {  
        "type": "stdio",  
        "command": "npx",  
        "args": [  
            "-y",  
            "@upstash/context7-mcp",  
            "--api-key",  
            "YOUR_API_KEY"  
        ],  
        "env": {}  
    }  
  }  
}

5.3. Cursor

默认配置文件：~/.cursor/mcp.json

{  
    "mcpServers": {  
        "context7": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
    }  
}

5.4. Gemini CLI (gcloud)

默认配置文件：~/.gemini/settings.json

{  
    "mcpServers": {  
        "context7": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
    }  
}

5.5. GitHub Copilot CLI

默认配置文件：~/.copilot/mcp-config.json

{  
  "mcpServers": {  
        "docs": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
  }  
}

5.6. Visual Studio Code

默认配置文件：~/.vscode/mcp.json

{  
    "servers": {  
        "context7": {  
            "command": "npx",  
            "args": ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]  
        }  
    }  
}

6. 核心功能

双模式操作：支持快速直接单行命令同步和引导式交互模式。
模糊参数匹配：用户不需要记住确切的工具名称；工具会自动匹配常见关键字。
跨平台兼容性：完美支持Linux、Windows和macOS环境，自动处理不同操作系统路径格式。
自动路径检测：内置主流开发工具的默认配置路径，自动发现本地存在的配置文件。
安全备份机制：在执行任何覆盖操作前，自动备份目标配置文件，确保操作可逆并防止意外数据丢失。
自定义与扩展：支持手动指定配置文件路径，并能自动创建不存在的目标文件。

7. 文件备份机制

安全性是此工具的核心原则之一。在任何同步操作（即覆盖目标文件）发生之前，必须执行以下备份过程：

安全原则：在任何操作写入目标文件之前，必须完成备份以确保操作可逆。
默认位置：在用户的主目录中创建一个 ~/.sync-mcp/backup/ 目录。如果不存在，则自动创建。
备份内容：当前目标文件的完整副本。
备份路径：
- 根目录：~/.sync-mcp/backup/
- 子目录结构：/<时间戳>/<原始目录结构>/<原始文件名>
- <时间戳>：执行同步操作时的Unix时间戳（毫秒），例如 1677619200000
示例：
- 操作：npx sync-mcp vscode cursor
- 时间：2025-10-24 18:00:00（假设时间戳为 1761319200000）
- 目标文件：Linux上的 ~/.cursor/mcp.json
- 动作：程序将 ~/.cursor/mcp.json 复制到 ~/.sync-mcp/backup/1761319200000/.cursor/mcp.json
- 这样可以防止备份文件被覆盖，并保留原始文件的路径结构，便于查找和恢复。

8. 平台兼容性

操作系统：必须在主流Linux发行版（如Ubuntu、CentOS等）、Windows 10/11和macOS上稳定运行。
路径处理：内部逻辑必须使用Node.js path模块中的函数（如path.join()和path.resolve()）来处理文件路径。禁止硬编码/或\。