vibe-config-sync 0.2.4 → 0.3.0

package/README.md

@@ -21,6 +21,7 @@ When using AI coding tools on multiple machines, configurations like skills, com
 | `agents/` | Agent definitions |
 | `plugins/installed_plugins.json` | Plugin registry (machine paths stripped) |
 | `plugins/known_marketplaces.json` | Plugin marketplace sources (machine paths stripped) |
+| `mcp-servers.json` | MCP server configs (extracted from `~/.claude.json`) |
 
 **Not synced** (machine-specific / ephemeral / large): `plugins/cache/`, `projects/`, `telemetry/`, `session-env/`, `plans/`, `todos/`, `debug/`, `history.jsonl`, etc.
 
@@ -82,11 +83,11 @@ vibe-sync pull
 
 ## How It Works
 
-- **Export** copies config files into `~/.vibe-sync/data/`, stripping machine-specific paths from plugin JSON files. Skills that are symlinks are resolved and their actual contents are copied.
+- **Export** copies config files into `~/.vibe-sync/data/`, stripping machine-specific paths from plugin JSON files. Skills that are symlinks are resolved and their actual contents are copied. MCP server configurations are extracted from `~/.claude.json` and saved as `mcp-servers.json` (prompts for confirmation if `env` fields containing potential secrets are detected).
 
-- **Import** restores files from `~/.vibe-sync/data/` to `~/.claude/`, validating JSON structure before overwriting. Plugin JSON files are used as a manifest only (never copied directly) — the `claude` CLI installs plugins and writes correct registry files with local paths. Already-installed plugins are detected and skipped.
+- **Import** restores files from `~/.vibe-sync/data/` to `~/.claude/`, validating JSON structure before overwriting. Plugin JSON files are used as a manifest only (never copied directly) — the `claude` CLI installs plugins and writes correct registry files with local paths. Already-installed plugins are detected and skipped. MCP servers are merged into `~/.claude.json` — only new servers are added; existing servers are never overwritten.
 
-- **Backup** is created automatically at `~/.vibe-sync/backups/claude/<timestamp>/` before every import. Use `vibe-sync restore` to list or recover from backups.
+- **Backup** is created automatically at `~/.vibe-sync/backups/claude/<timestamp>/` before every import. Both `~/.claude/` contents and `~/.claude.json` are backed up. Use `vibe-sync restore` to list or recover from backups.
 
 ## Sync Strategy
 
@@ -118,6 +119,12 @@ In short: new content is added, existing content is overwritten, but nothing is
 
 Plugin JSON files (`installed_plugins.json`, `known_marketplaces.json`) are exported with machine-specific paths stripped. On import, they are **not** copied to `~/.claude/plugins/` — instead they serve as a manifest. The `claude` CLI is invoked to install each plugin, and it writes correct registry files with local paths as a side effect. Already-installed plugins (detected by `installPath`) are skipped to avoid redundant network operations.
 
+### MCP Servers
+
+MCP server configurations live in `~/.claude.json` under the `mcpServers` key. On export, this section is extracted and saved as `mcp-servers.json` in the sync directory. If any server config contains `env` fields (which may hold secrets like API keys), the user is prompted before exporting.
+
+On import, MCP servers are **additive only** — new servers from the sync repo are added to `~/.claude.json`, but existing servers with the same name are never overwritten. This preserves any machine-specific customizations (e.g., local paths, environment variables).
+
 ### What This Means in Practice
 
 - If both machines modify different configs and then sync, the machine that runs `import` last will lose its local changes (a timestamped backup exists at `~/.vibe-sync/backups/claude/` for manual recovery)
@@ -129,6 +136,7 @@ Plugin JSON files (`installed_plugins.json`, `known_marketplaces.json`) are expo
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `CLAUDE_HOME` | Override Claude config directory | `~/.claude` |
+| `CLAUDE_JSON` | Override Claude global config file (MCP servers) | `~/.claude.json` |
 
 ## License
 

package/README.zh-CN.md

@@ -21,6 +21,7 @@
 | `agents/` | 代理定义 |
 | `plugins/installed_plugins.json` | 插件注册表（已剥离机器路径） |
 | `plugins/known_marketplaces.json` | 插件市场来源（已剥离机器路径） |
+| `mcp-servers.json` | MCP 服务器配置（从 `~/.claude.json` 提取） |
 
 **不同步**（机器特定 / 临时 / 大文件）：`plugins/cache/`、`projects/`、`telemetry/`、`session-env/`、`plans/`、`todos/`、`debug/`、`history.jsonl` 等。
 
@@ -82,11 +83,11 @@ vibe-sync pull
 
 ## 工作原理
 
-- **导出**：将配置文件复制到 `~/.vibe-sync/data/`，同时从插件 JSON 文件中剥离机器特定路径。符号链接的技能会被解析并复制其实际内容。
+- **导出**：将配置文件复制到 `~/.vibe-sync/data/`，同时从插件 JSON 文件中剥离机器特定路径。符号链接的技能会被解析并复制其实际内容。MCP 服务器配置从 `~/.claude.json` 中提取并保存为 `mcp-servers.json`（如果检测到包含潜在密钥的 `env` 字段，会提示用户确认）。
 
-- **导入**：从 `~/.vibe-sync/data/` 恢复文件到 `~/.claude/`，在覆盖前验证 JSON 结构。插件 JSON 文件仅作为清单使用（不会直接复制）—— `claude` CLI 负责安装插件并写入包含本地路径的正确注册文件。已安装的插件会被检测并跳过。
+- **导入**：从 `~/.vibe-sync/data/` 恢复文件到 `~/.claude/`，在覆盖前验证 JSON 结构。插件 JSON 文件仅作为清单使用（不会直接复制）—— `claude` CLI 负责安装插件并写入包含本地路径的正确注册文件。已安装的插件会被检测并跳过。MCP 服务器以增量方式合并到 `~/.claude.json`——仅添加新服务器，已存在的服务器不会被覆盖。
 
-- **备份**：每次导入前自动在 `~/.vibe-sync/backups/claude/<timestamp>/` 创建备份。使用 `vibe-sync restore` 列出或恢复备份。
+- **备份**：每次导入前自动在 `~/.vibe-sync/backups/claude/<timestamp>/` 创建备份，同时备份 `~/.claude/` 内容和 `~/.claude.json`。使用 `vibe-sync restore` 列出或恢复备份。
 
 ## 同步策略
 
@@ -118,6 +119,12 @@ vibe-sync pull
 
 插件 JSON 文件（`installed_plugins.json`、`known_marketplaces.json`）在导出时会剥离机器特定路径。导入时**不会**复制到 `~/.claude/plugins/`——而是作为清单使用。`claude` CLI 被调用来安装每个插件，并在安装过程中写入包含本地路径的正确注册文件。已安装的插件（通过 `installPath` 检测）会被跳过，以避免冗余的网络操作。
 
+### MCP 服务器
+
+MCP 服务器配置存储在 `~/.claude.json` 的 `mcpServers` 键下。导出时，该部分被提取并保存为同步目录中的 `mcp-servers.json`。如果任何服务器配置包含 `env` 字段（可能包含 API 密钥等密钥），导出前会提示用户确认。
+
+导入时，MCP 服务器采用**仅增量**策略——同步仓库中的新服务器会被添加到 `~/.claude.json`，但同名的已有服务器不会被覆盖。这保留了机器特定的自定义配置（如本地路径、环境变量）。
+
 ### 实际影响
 
 - 如果两台机器修改了不同的配置然后同步，最后执行 `import` 的机器会丢失其本地更改（可在 `~/.vibe-sync/backups/claude/` 找到带时间戳的备份进行手动恢复）
@@ -129,6 +136,7 @@ vibe-sync pull
 | 变量 | 说明 | 默认值 |
 |------|------|--------|
 | `CLAUDE_HOME` | 覆盖 Claude 配置目录 | `~/.claude` |
+| `CLAUDE_JSON` | 覆盖 Claude 全局配置文件（MCP 服务器） | `~/.claude.json` |
 
 ## 许可证
 

package/dist/index.js

@@ -8,6 +8,7 @@ import fs from "fs-extra";
 import os from "os";
 import path from "path";
 var CLAUDE_HOME = process.env.CLAUDE_HOME ?? path.join(os.homedir(), ".claude");
+var CLAUDE_JSON = process.env.CLAUDE_JSON ?? path.join(os.homedir(), ".claude.json");
 var SYNC_DIR = path.join(os.homedir(), ".vibe-sync");
 var BACKUP_BASE = path.join(SYNC_DIR, "backups", "claude");
 function getConfigDir() {
@@ -19,10 +20,12 @@ function isInitialized() {
 var SYNC_FILES = ["settings.json", "CLAUDE.md"];
 var SYNC_DIRS = ["commands", "agents"];
 var PLUGIN_FILES = ["installed_plugins.json", "known_marketplaces.json"];
+var MCP_SYNC_FILE = "mcp-servers.json";
 
 // src/commands/export.ts
 import fs4 from "fs-extra";
 import path4 from "path";
+import readline from "readline/promises";
 
 // src/core/logger.ts
 import pc from "picocolors";
@@ -79,6 +82,11 @@ function writeJsonSafe(filePath, data) {
 }
 
 // src/core/sanitize.ts
+function mcpServersHaveEnv(servers) {
+  return Object.values(servers).some(
+    (config) => typeof config === "object" && config !== null && "env" in config
+  );
+}
 function sanitizePlugins(data) {
   const result = structuredClone(data);
   for (const entries of Object.values(result.plugins ?? {})) {
@@ -144,7 +152,21 @@ function importSkills(srcDir, destDir) {
 }
 
 // src/commands/export.ts
-function cmdExport() {
+async function confirmMcpExport() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  try {
+    const answer = await rl.question(
+      '[WARN] MCP server configs contain "env" fields that may include secrets (API keys, tokens).\n       Export anyway? (y/N): '
+    );
+    return answer.trim().toLowerCase() === "y";
+  } finally {
+    rl.close();
+  }
+}
+async function cmdExport() {
   if (!fs4.existsSync(CLAUDE_HOME)) {
     throw new Error(
       `Claude config directory not found: ${CLAUDE_HOME}
@@ -196,6 +218,21 @@ Make sure Claude Code has been run at least once.`
     );
     logInfo("Exported: plugins/known_marketplaces.json (sanitized)");
   }
+  const claudeJson = readJsonSafe(CLAUDE_JSON);
+  const mcpServers = claudeJson?.mcpServers;
+  if (typeof mcpServers === "object" && mcpServers !== null) {
+    const servers = mcpServers;
+    let shouldExport = true;
+    if (mcpServersHaveEnv(servers)) {
+      shouldExport = await confirmMcpExport();
+    }
+    if (shouldExport) {
+      writeJsonSafe(path4.join(configDir, MCP_SYNC_FILE), servers);
+      logInfo(`Exported: ${MCP_SYNC_FILE} (from ~/.claude.json)`);
+    } else {
+      logWarn(`Skipped: ${MCP_SYNC_FILE} (user declined due to env secrets)`);
+    }
+  }
   logOk("Export complete");
 }
 
@@ -234,6 +271,9 @@ function backupExisting() {
       fs5.copySync(src, path5.join(backupDir, "plugins", file));
     }
   }
+  if (fs5.existsSync(CLAUDE_JSON)) {
+    fs5.copySync(CLAUDE_JSON, path5.join(backupDir, ".claude.json"));
+  }
   logOk(`Backup created: ${backupDir}`);
 }
 function listBackups() {
@@ -283,6 +323,11 @@ function restoreFromBackup(backupName) {
       }
     }
   }
+  const claudeJsonSrc = path5.join(backupDir, ".claude.json");
+  if (fs5.existsSync(claudeJsonSrc)) {
+    fs5.copySync(claudeJsonSrc, CLAUDE_JSON);
+    logInfo("Restored: .claude.json");
+  }
   logOk(`Restored from backup: ${backupName}`);
 }
 
@@ -508,6 +553,49 @@ function importSyncSkills(configDir, dryRun) {
     importSkills(skillsSrc, path6.join(CLAUDE_HOME, "skills"));
   }
 }
+function readLocalMcpServers() {
+  const json = readJsonSafe(CLAUDE_JSON) ?? {};
+  const mcpServers = json.mcpServers;
+  const servers = typeof mcpServers === "object" && mcpServers !== null ? mcpServers : {};
+  return { json, servers };
+}
+function importMcpServers(configDir, dryRun) {
+  const src = path6.join(configDir, MCP_SYNC_FILE);
+  if (!fs6.existsSync(src)) return;
+  const result = validateJsonFile(src);
+  if (!result.valid) {
+    logWarn(dryRun ? `  INVALID: ${result.errors.join(", ")}` : `Skipping ${MCP_SYNC_FILE}: ${result.errors.join(", ")}`);
+    return;
+  }
+  if (dryRun) logOk(`  Validated: ${MCP_SYNC_FILE}`);
+  const syncedServers = readJsonSafe(src);
+  if (!syncedServers) return;
+  const { json: existing, servers: currentServers } = readLocalMcpServers();
+  const syncedNames = Object.keys(syncedServers);
+  const newNames = syncedNames.filter((n) => !(n in currentServers));
+  if (dryRun) {
+    const skipNames = syncedNames.filter((n) => n in currentServers);
+    if (newNames.length > 0) logInfo(`Would import MCP servers: ${newNames.join(", ")}`);
+    if (skipNames.length > 0) logWarn(`Would skip (already exist): ${skipNames.join(", ")}`);
+    if (newNames.length === 0) logInfo("No new MCP servers to import");
+    return;
+  }
+  if (newNames.length === 0) {
+    logInfo("No new MCP servers to import (all already exist locally)");
+    return;
+  }
+  for (const name of syncedNames) {
+    if (name in currentServers) {
+      logWarn(`MCP server already exists locally, skipping: ${name}`);
+    }
+  }
+  const newServers = Object.fromEntries(
+    newNames.map((name) => [name, syncedServers[name]])
+  );
+  existing.mcpServers = { ...currentServers, ...newServers };
+  fs6.writeJsonSync(CLAUDE_JSON, existing, { spaces: 2 });
+  logInfo(`Imported: ${MCP_SYNC_FILE} \u2192 ~/.claude.json (added ${newNames.length} new server(s))`);
+}
 function syncPlugins(configDir, existingState, dryRun) {
   const pluginsSrc = path6.join(configDir, "plugins");
   const hasManifest = PLUGIN_FILES.some(
@@ -559,6 +647,7 @@ Run "vibe-sync export" first or "vibe-sync pull"`
   importSyncFiles(configDir, options);
   importSyncDirs(configDir, dryRun);
   importSyncSkills(configDir, dryRun);
+  importMcpServers(configDir, dryRun);
   if (options.reinstallPlugins) {
     syncPlugins(configDir, existingState, dryRun);
   } else {
@@ -568,6 +657,8 @@ Run "vibe-sync export" first or "vibe-sync pull"`
 }
 
 // src/commands/status.ts
+import fs8 from "fs-extra";
+import os2 from "os";
 import path8 from "path";
 
 // src/core/diff.ts
@@ -665,6 +756,23 @@ function cmdStatus() {
       hasDiff = true;
     }
   }
+  const repoMcp = path8.join(configDir, MCP_SYNC_FILE);
+  const claudeJson = readJsonSafe(CLAUDE_JSON);
+  const localMcp = typeof claudeJson?.mcpServers === "object" && claudeJson.mcpServers !== null ? claudeJson.mcpServers : void 0;
+  if (localMcp || fs8.existsSync(repoMcp)) {
+    const tmpFile = path8.join(os2.tmpdir(), `vibe-sync-mcp-${Date.now()}.json`);
+    try {
+      if (localMcp) {
+        fs8.writeJsonSync(tmpFile, localMcp, { spaces: 2 });
+      }
+      const localPath = localMcp ? tmpFile : "";
+      if (showDiff(localPath, repoMcp, MCP_SYNC_FILE)) {
+        hasDiff = true;
+      }
+    } finally {
+      fs8.removeSync(tmpFile);
+    }
+  }
   if (!hasDiff) {
     logOk("No differences found");
   }
@@ -776,7 +884,7 @@ async function pullFromRemote(git) {
 
 // src/commands/push.ts
 async function cmdPush() {
-  cmdExport();
+  await cmdExport();
   const git = createGit(SYNC_DIR);
   await commitAndPush(git);
 }
@@ -810,12 +918,12 @@ async function cmdPull(options = {}) {
 }
 
 // src/commands/init.ts
-import fs8 from "fs-extra";
+import fs9 from "fs-extra";
 import path9 from "path";
-import readline from "readline/promises";
+import readline2 from "readline/promises";
 var GIT_URL_PATTERN = /^(https?:\/\/|git@|ssh:\/\/|git:\/\/).+/;
 function createReadline() {
-  return readline.createInterface({
+  return readline2.createInterface({
     input: process.stdin,
     output: process.stdout
   });
@@ -867,7 +975,7 @@ async function freshInit() {
       logError("URL cannot be empty");
       return;
     }
-    fs8.ensureDirSync(SYNC_DIR);
+    fs9.ensureDirSync(SYNC_DIR);
     const git = createGit(SYNC_DIR);
     await git.init();
     logOk("Initialized git repository");
@@ -879,8 +987,8 @@ async function freshInit() {
       logInfo("No existing data on remote (new repository)");
     }
     const gitignorePath = path9.join(SYNC_DIR, ".gitignore");
-    if (!fs8.existsSync(gitignorePath)) {
-      fs8.writeFileSync(gitignorePath, ".DS_Store\nThumbs.db\n");
+    if (!fs9.existsSync(gitignorePath)) {
+      fs9.writeFileSync(gitignorePath, ".DS_Store\nThumbs.db\n");
     }
     console.log("");
     logOk("Setup complete!");
@@ -926,7 +1034,7 @@ function cmdRestore(timestamp) {
 
 // src/index.ts
 var program = new Command();
-program.name("vibe-sync").description("Sync AI coding tool configurations across machines via git").version("0.2.4").action(async () => {
+program.name("vibe-sync").description("Sync AI coding tool configurations across machines via git").version("0.3.0").action(async () => {
   if (!isInitialized()) {
     await cmdInit();
   } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-config-sync",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "Cross-platform CLI tool to sync AI coding tool configurations across machines via git",
   "type": "module",
   "bin": {