sync-project-mcps 1.0.0

package/README.md

@@ -0,0 +1,234 @@
+# sync-project-mcps
+
+**Zero-config project-level MCP synchronization across AI coding assistants.**
+
+One command. All your project MCP servers. Every editor.
+
+```bash
+npx sync-project-mcps
+```
+
+---
+
+## The Problem
+
+You use multiple AI coding assistants - Cursor, Claude Code, Windsurf, Cline. Each has its own MCP configuration file in a different location. Adding a new MCP server means updating 3-5 config files manually. Forgetting one means inconsistent tooling across editors.
+
+## The Solution
+
+`sync-project-mcps` finds all your project MCP configurations, merges them, and writes the unified config back to all clients. **No setup required.**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                             │
+│   .cursor/mcp.json ──┐                                      │
+│                      │                                      │
+│   .mcp.json ─────────┼──► MERGE ──► Write to ALL clients    │
+│                      │                                      │
+│   .windsurf/... ─────┘                                      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start
+
+### Run Once (npx)
+
+```bash
+npx sync-project-mcps
+```
+
+### Preview Changes
+
+```bash
+npx sync-project-mcps --dry-run
+```
+
+### Verbose Output
+
+```bash
+npx sync-project-mcps -v
+```
+
+---
+
+## Supported Clients
+
+| Client | Config Location | Status |
+|--------|-----------------|--------|
+| **Cursor** | `.cursor/mcp.json` | Project |
+| **Claude Code** | `.mcp.json` | Project |
+| **Windsurf** | `.windsurf/mcp.json` | Project |
+| **Cline** | VS Code globalStorage | Global |
+| **Roo Code** | `.roo/mcp.json` | Project |
+
+---
+
+## Installation
+
+### Option 1: Run with npx (Recommended)
+
+No installation needed:
+
+```bash
+npx sync-project-mcps
+```
+
+### Option 2: Install Globally
+
+```bash
+npm install -g sync-project-mcps
+sync-project-mcps
+```
+
+---
+
+## Adding MCP Servers
+
+### For Cursor
+
+Click to install an MCP server directly:
+
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=example&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyJleGFtcGxlLW1jcCJdfQ==)
+
+Or add manually to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "command": "npx",
+      "args": ["example-mcp"]
+    }
+  }
+}
+```
+
+### For Claude Code
+
+Install globally with the Claude CLI:
+
+```bash
+claude mcp add example -s user -- npx example-mcp
+```
+
+Or add to project-level `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "command": "npx",
+      "args": ["example-mcp"]
+    }
+  }
+}
+```
+
+### Then Sync
+
+```bash
+npx sync-project-mcps
+```
+
+Your MCP server is now available in **all** your AI coding assistants.
+
+---
+
+## How It Works
+
+1. **Discovers** MCP configs from all supported clients
+2. **Merges** all `mcpServers` entries (dedupes by name)
+3. **Writes** the unified config to every client location
+
+```
+$ npx sync-project-mcps
+
+Sync MCP Configurations
+
+Found configurations:
+  + Cursor: 3 server(s)
+  + Claude Code: 2 server(s)
+
+Merged result: 4 unique server(s)
+  - context7
+  - filesystem
+  - github
+  - playwright
+
+Syncing to clients...
+  [update] Cursor (no changes)
+  [update] Claude Code (+1)
+  [create] Windsurf (+4)
+  [create] Cline (+4)
+  [create] Roo Code (+4)
+
+Done!
+```
+
+---
+
+## CLI Options
+
+```
+sync-project-mcps [options]
+
+Options:
+  --dry-run     Show what would be synced without writing files
+  -v, --verbose Show detailed information about each server
+  -h, --help    Show help message
+  --version     Show version
+```
+
+---
+
+## FAQ
+
+### Does it delete servers?
+
+No. It only adds missing servers. If a server exists in Cursor but not Claude Code, it gets added to Claude Code. Servers are never removed.
+
+### What if the same server has different configs?
+
+First occurrence wins. If `github` is configured differently in Cursor vs Claude Code, the Cursor config is used (it's checked first).
+
+### Does it support environment variables?
+
+Yes. Environment variables in configs are preserved as-is.
+
+### What about global vs project configs?
+
+Currently syncs project-level configs. Global config support is planned.
+
+---
+
+## Comparison
+
+| Feature | sync-project-mcps | sync-mcp | mcpm.sh |
+|---------|-------------------|----------|---------|
+| Scope | Project-level | Global/user | Global |
+| Zero config | Yes | No | No |
+| npx support | Yes | Yes | No |
+| Direction | Merge all | One-to-one | Manual |
+
+**sync-project-mcps** is for developers who want project MCP configs synced across all editors with zero friction.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/user/sync-project-mcps
+cd sync-project-mcps
+npm install
+npm run build
+node dist/index.js
+```
+
+---
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "sync-project-mcps",
+  "version": "1.0.0",
+  "description": "Sync project-level MCP configurations across AI coding assistants (Cursor, Claude Code, Windsurf, Cline)",
+  "type": "module",
+  "bin": {
+    "sync-project-mcps": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js"
+  },
+  "keywords": ["mcp", "cursor", "claude", "sync", "cli", "windsurf", "cline", "project"],
+  "author": "Vlad Tansky",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/clients/claude-code.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ClientConfig, McpConfig } from "../types.js";
+
+const CONFIG_PATH = ".mcp.json";
+
+export function getClaudeCodeConfig(projectRoot: string): ClientConfig {
+  const configPath = join(projectRoot, CONFIG_PATH);
+  const exists = existsSync(configPath);
+
+  if (!exists) {
+    return {
+      name: "Claude Code",
+      path: configPath,
+      config: null,
+      exists: false,
+    };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content) as McpConfig;
+    return {
+      name: "Claude Code",
+      path: configPath,
+      config,
+      exists: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Warning: Failed to parse ${configPath}: ${msg}`);
+    return {
+      name: "Claude Code",
+      path: configPath,
+      config: null,
+      exists: true,
+    };
+  }
+}

package/src/clients/cline.ts

@@ -0,0 +1,61 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ClientConfig, McpConfig } from "../types.js";
+
+function getGlobalConfigPath(): string {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return join(
+      homedir(),
+      "Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
+    );
+  } else if (platform === "win32") {
+    return join(
+      process.env.APPDATA || "",
+      "Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
+    );
+  }
+  return join(
+    homedir(),
+    ".config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
+  );
+}
+
+export function getClineConfig(projectRoot: string): ClientConfig {
+  const projectPath = join(projectRoot, ".cline/mcp.json");
+  const globalPath = getGlobalConfigPath();
+
+  // Prefer project-level config, fall back to global
+  const configPath = existsSync(projectPath) ? projectPath : globalPath;
+  const exists = existsSync(configPath);
+
+  if (!exists) {
+    return {
+      name: "Cline",
+      path: projectPath,
+      config: null,
+      exists: false,
+    };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content) as McpConfig;
+    return {
+      name: "Cline",
+      path: configPath,
+      config,
+      exists: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Warning: Failed to parse ${configPath}: ${msg}`);
+    return {
+      name: "Cline",
+      path: configPath,
+      config: null,
+      exists: true,
+    };
+  }
+}

package/src/clients/cursor.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ClientConfig, McpConfig } from "../types.js";
+
+const CONFIG_PATH = ".cursor/mcp.json";
+
+export function getCursorConfig(projectRoot: string): ClientConfig {
+  const configPath = join(projectRoot, CONFIG_PATH);
+  const exists = existsSync(configPath);
+
+  if (!exists) {
+    return {
+      name: "Cursor",
+      path: configPath,
+      config: null,
+      exists: false,
+    };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content) as McpConfig;
+    return {
+      name: "Cursor",
+      path: configPath,
+      config,
+      exists: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Warning: Failed to parse ${configPath}: ${msg}`);
+    return {
+      name: "Cursor",
+      path: configPath,
+      config: null,
+      exists: true,
+    };
+  }
+}

package/src/clients/goose.ts

@@ -0,0 +1,25 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ClientConfig } from "../types.js";
+
+// Goose uses YAML config - disabled to avoid adding yaml dependency
+// TODO: Enable when yaml parsing is added
+
+function getConfigPath(): string {
+  const platform = process.platform;
+  if (platform === "win32") {
+    return join(process.env.USERPROFILE || "", ".config/goose/config.yaml");
+  }
+  return join(homedir(), ".config/goose/config.yaml");
+}
+
+export function getGooseConfig(_projectRoot: string): ClientConfig {
+  const configPath = getConfigPath();
+  return {
+    name: "Goose",
+    path: configPath,
+    config: null,
+    exists: existsSync(configPath),
+  };
+}

package/src/clients/roo-code.ts

@@ -0,0 +1,39 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ClientConfig, McpConfig } from "../types.js";
+
+const CONFIG_PATH = ".roo/mcp.json";
+
+export function getRooCodeConfig(projectRoot: string): ClientConfig {
+  const configPath = join(projectRoot, CONFIG_PATH);
+  const exists = existsSync(configPath);
+
+  if (!exists) {
+    return {
+      name: "Roo Code",
+      path: configPath,
+      config: null,
+      exists: false,
+    };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content) as McpConfig;
+    return {
+      name: "Roo Code",
+      path: configPath,
+      config,
+      exists: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Warning: Failed to parse ${configPath}: ${msg}`);
+    return {
+      name: "Roo Code",
+      path: configPath,
+      config: null,
+      exists: true,
+    };
+  }
+}

package/src/clients/vscode.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ClientConfig } from "../types.js";
+
+// VS Code MCP support is read-only for now
+// Writing would require merging into settings.json to avoid overwriting other settings
+// TODO: Implement proper merge logic before enabling write support
+
+function getConfigPath(): string {
+  const platform = process.platform;
+  if (platform === "darwin") {
+    return join(homedir(), "Library/Application Support/Code/User/settings.json");
+  } else if (platform === "win32") {
+    return join(process.env.APPDATA || "", "Code/User/settings.json");
+  }
+  return join(homedir(), ".config/Code/User/settings.json");
+}
+
+export function getVSCodeConfig(_projectRoot: string): ClientConfig {
+  const configPath = getConfigPath();
+  const exists = existsSync(configPath);
+
+  if (!exists) {
+    return {
+      name: "VS Code",
+      path: configPath,
+      config: null,
+      exists: false,
+    };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const settings = JSON.parse(content);
+    const mcpServers = settings["mcp.servers"] || settings.mcpServers || {};
+    return {
+      name: "VS Code",
+      path: configPath,
+      config: { mcpServers },
+      exists: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Warning: Failed to parse VS Code settings: ${msg}`);
+    return {
+      name: "VS Code",
+      path: configPath,
+      config: null,
+      exists: true,
+    };
+  }
+}

package/src/clients/windsurf.ts

@@ -0,0 +1,46 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import type { ClientConfig, McpConfig } from "../types.js";
+
+function getGlobalConfigPath(): string {
+  return join(homedir(), ".codeium/windsurf/mcp_config.json");
+}
+
+export function getWindsurfConfig(projectRoot: string): ClientConfig {
+  const projectPath = join(projectRoot, ".windsurf/mcp.json");
+  const globalPath = getGlobalConfigPath();
+
+  // Prefer project-level config, fall back to global
+  const configPath = existsSync(projectPath) ? projectPath : globalPath;
+  const exists = existsSync(configPath);
+
+  if (!exists) {
+    return {
+      name: "Windsurf",
+      path: projectPath, // Default to project path for creation
+      config: null,
+      exists: false,
+    };
+  }
+
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    const config = JSON.parse(content) as McpConfig;
+    return {
+      name: "Windsurf",
+      path: configPath,
+      config,
+      exists: true,
+    };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : "Unknown error";
+    console.error(`Warning: Failed to parse ${configPath}: ${msg}`);
+    return {
+      name: "Windsurf",
+      path: configPath,
+      config: null,
+      exists: true,
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { parseArgs } from "node:util";
+import { getCursorConfig } from "./clients/cursor.js";
+import { getClaudeCodeConfig } from "./clients/claude-code.js";
+import { getWindsurfConfig } from "./clients/windsurf.js";
+import { getClineConfig } from "./clients/cline.js";
+import { getRooCodeConfig } from "./clients/roo-code.js";
+import { mergeConfigs, getChanges } from "./merge.js";
+import type { ClientConfig } from "./types.js";
+
+const COLORS = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  cyan: "\x1b[36m",
+  red: "\x1b[31m",
+};
+
+function c(color: keyof typeof COLORS, text: string): string {
+  return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+
+const { values: args } = parseArgs({
+  options: {
+    "dry-run": { type: "boolean", default: false },
+    verbose: { type: "boolean", short: "v", default: false },
+    help: { type: "boolean", short: "h", default: false },
+    version: { type: "boolean", default: false },
+  },
+});
+
+function printHelp() {
+  console.log(`
+${c("bold", "sync-project-mcps")} - Sync project-level MCP configurations across AI coding assistants
+
+${c("bold", "USAGE")}
+  npx sync-project-mcps [options]
+
+${c("bold", "OPTIONS")}
+  --dry-run     Show what would be synced without writing files
+  -v, --verbose Show detailed information
+  -h, --help    Show this help message
+  --version     Show version
+
+${c("bold", "SUPPORTED CLIENTS")}
+  - Cursor      ${c("dim", ".cursor/mcp.json")}
+  - Claude Code ${c("dim", ".mcp.json")}
+  - Windsurf    ${c("dim", ".windsurf/mcp.json")}
+  - Cline       ${c("dim", ".cline/mcp.json")}
+  - Roo Code    ${c("dim", ".roo/mcp.json")}
+
+${c("bold", "EXAMPLES")}
+  npx sync-project-mcps              Sync all MCP configurations
+  npx sync-project-mcps --dry-run    Preview changes without writing
+`);
+}
+
+function run() {
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (args.version) {
+    console.log("1.0.0");
+    process.exit(0);
+  }
+
+  const projectRoot = process.cwd();
+  const dryRun = args["dry-run"];
+  const verbose = args.verbose;
+
+  console.log(c("bold", "\nSync MCP Configurations\n"));
+
+  if (dryRun) {
+    console.log(c("yellow", "DRY RUN - no files will be modified\n"));
+  }
+
+  const clients: ClientConfig[] = [
+    getCursorConfig(projectRoot),
+    getClaudeCodeConfig(projectRoot),
+    getWindsurfConfig(projectRoot),
+    getClineConfig(projectRoot),
+    getRooCodeConfig(projectRoot),
+  ];
+
+  const existingClients = clients.filter((c) => c.exists && c.config);
+  const missingClients = clients.filter((c) => !c.exists);
+
+  if (existingClients.length === 0) {
+    console.log(c("red", "No MCP configurations found.\n"));
+    console.log("Expected locations:");
+    for (const client of clients) {
+      console.log(c("dim", `  ${client.name}: ${client.path}`));
+    }
+    console.log(
+      `\nCreate at least one MCP config file to get started.`
+    );
+    process.exit(1);
+  }
+
+  console.log(c("cyan", "Found configurations:"));
+  for (const client of existingClients) {
+    const serverCount = Object.keys(client.config!.mcpServers).length;
+    console.log(`  ${c("green", "+")} ${client.name}: ${serverCount} server(s)`);
+    if (verbose) {
+      for (const name of Object.keys(client.config!.mcpServers)) {
+        console.log(c("dim", `      - ${name}`));
+      }
+    }
+  }
+
+  if (missingClients.length > 0 && verbose) {
+    console.log(c("dim", "\nNot found (will be created):"));
+    for (const client of missingClients) {
+      console.log(c("dim", `  - ${client.name}`));
+    }
+  }
+
+  const merged = mergeConfigs(existingClients);
+  const mergedCount = Object.keys(merged.mcpServers).length;
+
+  console.log(`\n${c("cyan", "Merged result:")} ${mergedCount} unique server(s)`);
+  for (const name of Object.keys(merged.mcpServers).sort()) {
+    console.log(`  ${c("blue", "-")} ${name}`);
+  }
+
+  console.log(`\n${c("cyan", "Syncing to clients...")}`);
+
+  for (const client of clients) {
+    const changes = getChanges(client, merged);
+    const parts: string[] = [];
+
+    if (changes.added.length > 0) {
+      parts.push(c("green", `+${changes.added.length}`));
+    }
+    if (changes.removed.length > 0) {
+      parts.push(c("red", `-${changes.removed.length}`));
+    }
+
+    const changeInfo = parts.length > 0 ? ` (${parts.join(", ")})` : c("dim", " (no changes)");
+    const status = client.exists ? c("green", "update") : c("yellow", "create");
+
+    console.log(`  [${status}] ${client.name}${changeInfo}`);
+
+    if (verbose && changes.added.length > 0) {
+      for (const name of changes.added) {
+        console.log(c("green", `      + ${name}`));
+      }
+    }
+
+    if (!dryRun) {
+      const dir = dirname(client.path);
+      if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+      }
+      writeFileSync(client.path, JSON.stringify(merged, null, 2) + "\n");
+    }
+  }
+
+  console.log(`\n${c("green", "Done!")} ${dryRun ? "(dry run)" : ""}\n`);
+}
+
+run();

package/src/merge.ts

@@ -0,0 +1,47 @@
+import type { ClientConfig, McpConfig, McpServer } from "./types.js";
+
+function serversEqual(a: McpServer, b: McpServer): boolean {
+  return (
+    a.command === b.command &&
+    JSON.stringify(a.args ?? []) === JSON.stringify(b.args ?? []) &&
+    JSON.stringify(a.env ?? {}) === JSON.stringify(b.env ?? {})
+  );
+}
+
+export function mergeConfigs(clients: ClientConfig[]): McpConfig {
+  const merged: Record<string, McpServer> = {};
+
+  for (const client of clients) {
+    if (!client.config?.mcpServers) continue;
+
+    for (const [name, server] of Object.entries(client.config.mcpServers)) {
+      if (!merged[name]) {
+        merged[name] = { ...server };
+        continue;
+      }
+
+      if (!serversEqual(merged[name], server)) {
+        console.log(
+          `  Warning: "${name}" differs between configs, keeping first occurrence`
+        );
+      }
+    }
+  }
+
+  return { mcpServers: merged };
+}
+
+export function getChanges(
+  client: ClientConfig,
+  merged: McpConfig
+): { added: string[]; removed: string[] } {
+  const currentServers = new Set(
+    Object.keys(client.config?.mcpServers ?? {})
+  );
+  const mergedServers = new Set(Object.keys(merged.mcpServers));
+
+  const added = [...mergedServers].filter((s) => !currentServers.has(s));
+  const removed = [...currentServers].filter((s) => !mergedServers.has(s));
+
+  return { added, removed };
+}

package/src/types.ts

@@ -0,0 +1,17 @@
+export type McpServer = {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  disabled?: boolean;
+};
+
+export type McpConfig = {
+  mcpServers: Record<string, McpServer>;
+};
+
+export type ClientConfig = {
+  name: string;
+  path: string;
+  config: McpConfig | null;
+  exists: boolean;
+};

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}